tibrvEvent_CreateTimer()

Function

Declaration

tibrv_status tibrvEvent_CreateTimer(
    tibrvEvent*            event,
    tibrvQueue             queue,
    tibrvEventCallback     callback,
    tibrv_f64              interval,
    const void*            closure);

Purpose

Start a timer.

Parameter	Description
`event`	At each time interval, place this event on the event queue. The program supplies a location, and the function stores the new event object in that location. The event object remains valid until the program explicitly destroys it.
`queue`	At each time interval, place the event on this event queue.
`callback`	On dispatch, process the event with this callback function.
`interval`	The timer triggers its callback function at this repeating interval (in seconds).
`closure`	Store this closure data in the event object.

Remarks

All timers are repeating timers. To simulate a once-only timer, code the callback function to destroy the timer.

This function creates a timer event object, and activates the timer event—that is, it requests notification from the operating system when the timer’s interval elapses. When the interval elapses, Rendezvous software places the event object on its event queue. Dispatch removes the event object from the queue, and runs the callback function to process the timer event. On dispatch Rendezvous software also determines whether the next interval has already elapsed, and requeues the timer event if appropriate. (To stop the cycle, destroy the event object; see tibrvEvent_Destroy().)

Notice that time waiting in the event queue until dispatch can increase the effective interval of the timer. It is the programmer’s responsibility to ensure timely dispatch of events.

Timer Activation and Dispatch illustrates a sequence of timer intervals. The number of elapsed timer intervals directly determines the number of event callbacks.

At any moment the timer object appears on the event queue at most once—not several times as multiple copies. Nonetheless, Rendezvous software arranges for the appropriate number of timer event callbacks based the number of intervals that have elapsed since the timer became active or reset its interval.

Destroying or invalidating the timer object immediately halts the sequence of timer events. The timer object ceases to queue new events, and an event already in the queue does not result in a callback. (However, callback functions that are already running in other threads continue to completion.)

Resetting the timer interval immediately interrupts the sequence of timer events and begins a new sequence, counting the new interval from that moment. The reset operation is equivalent to destroying the timer and creating a new object in its place.

Figure 182: Timer Activation and Dispatch

Timer Granularity

Express the timer interval (in seconds) as a 64-bit floating point number. This representation allows microsecond granularity for intervals for over 100 years. The actual granularity of intervals depends on hardware and operating system constraints.

Zero as Interval