| iMatix home page | << | < | > | >>

SMT Version 2.81

The Timer Agent - SMTTIME

Generates timing events. You can request one timing event after a specific delay, or repeated timing events at regular intervals. The timer is accurate to 1/100th of a second. You specify delays as a number of days and a number of centiseconds.

To use SMTTIME, call smttime init(). This creates a single unnamed thread automatically the first time it is called, and has no effect thereafter. You can then send messages to this thread. It supports these methods:

• ALARM - send alarm event after specified delay.
• WAKEUP - send alarm event at some specific day and time.
• CLOCK - send alarm events at regular intervals.
• FLUSH - flush any requests for a client thread.

Example of initialising SMTTIME:

/*  Static data                                                 */
static QID
    timeq;                      /*  Timer agent event queue     */

    /*  In agent initialisation code                            */
    THREAD  *thread;            /*  Handle to various threads   */

    method declare (agent, "TIME_ALARM", alarm_event, 0);
    method declare (agent, "TIME_ERROR", error_event, 0);

    /*  Ensure that timer agent is running, else start it       */
    smttime init ();
    if ((thread = thread lookup (SMT_TIMER, "")) != NULL)
        timeq = thread-> queue-> qid;
    else
        return (-1);

The ALARM Method

Sends a single alarm event after some specified delay. Build the event body using exdr_write() and the message definition SMT_TIME_ALARM. The event body consists of these fields (see exdr_write() for the field types):

• [q] The delay, in days.
• [q] The delay, in 1/100th seconds.
• [mM] An argument block, returned with the alarm event. This is arbitrary data, and may be NULL.

• TIME_ALARM - the alarm went off. The event body contains the argument block, if any. Decode the event body, if you need to, using exdr_read() and the message definition SMT_TIME_REPLY. The body contains these fields: [mM] the argument block.
• TIME_ERROR - there was an error that prevented the timer from working. This can be handled as a fatal error. At present the only cause for such an error is insufficient memory. The event body contains an error message.

The ALARM method implicitly does a FLUSH before proceeding.

The WAKEUP Method

Sends a single alarm event at some specified day and time. Build the event body using exdr_write() and the message definition SMT_TIME_ALARM. The event body consists of these fields (see exdr_write() for the field types):

• [q] The alarm time in days.
• [q] The alarm time in 1/100th seconds.
• [mM] An argument block, returned with the alarm event. This is arbitrary data, and may be NULL.

• TIME_ALARM - the alarm went off. The event body contains the argument block, if any. Decode the event body, if you need to, using exdr_read() and the message definition SMT_TIME_REPLY. The body contains these fields: [mM] the argument block.
• TIME_ERROR - there was an error that prevented the timer from working. This can be handled as a fatal error. At present the only cause for such an error is insufficient memory. The event body contains an error message.

The WAKEUP method implicitly does a FLUSH before proceeding.

The CLOCK Method

Sends a repeated alarm event after some specified delay, for ever, or a specific number of times. Build the event body using exdr_write() and the message definition SMT_TIME_CLOCK. The event body consists of these fields (see exdr_write() for the field types):

• [q] The delay, in days.
• [q] The delay, in 1/100th seconds.
• [w] A number of times to cycle; zero means forever.
• [mM] An argument block, returned with the alarm event. This is arbitrary data, and may be NULL.

• TIME_ALARM - the alarm went off. The event body contains the argument block, if any. Decode the event body, if you need to, using exdr_read() and the message definition SMT_TIME_REPLY. The body contains these fields: [mM] the argument block.
• TIME_ERROR - there was an error that prevented the timer from working. This can be handled as a fatal error. At present the only cause for such an error is insufficient memory. The event body contains an error message.

The CLOCK method implicitly does a FLUSH before proceeding.

The FLUSH Method

Removes any requests sent by a particular client thread. Use this to cancel a CLOCK method, or an unexpired ALARM or WAKEUP request. You do not need to provide an event body, but you must specify your thread's QID correctly when you use event_send(). SMTTIME does not reply to a FLUSH method.

Example Of Use

The SMTTST1 test agent shows an example of using the timer agent.

SMTTIME Implementation

The hypertext view of SMTTIME's dialog and source code may help to understand how SMTTIME works.

| << | < | > | >>

Copyright © 1996-99 iMatix Corporation