FreeBSD Manual Pages
AG_TIMER(3) BSD Library Functions Manual AG_TIMER(3) NAME AG_Timer -- agar timer facility SYNOPSIS #include <agar/core.h> DESCRIPTION The AG_Timer structure describes a unique timer, which may or may not be associated with some parent AG_Object(3). If a timer has a parent ob- ject, Agar will guarantee cancellation of any callbacks if the parent ob- ject is destroyed or detached. When a timer expires, its callback rou- tine is executed. Timer callback routines should be defined as: Uint32 AG_TimerFn(AG_Timer *timer, AG_Event *event) The timer argument, and the list of arguments under event are those pre- viously specified in AG_AddTimer(). The current timer interval (in ticks) can be retrieved from the ival member of the AG_Timer structure. The callback should return a new timer interval (if the timer is to be restarted), or 0 if the timer is to be cancelled. The timer's parent object is guaranteed to remain locked during the exe- cution of the callback. The context of execution of the callback is platform-dependent. On platforms where kqueue(2) is available, the rou- tine is executed in the event loop. On platforms where only POSIX timers are available, the routine is executed in a separate thread. On plat- forms which don't provide any timer interface at all, the event loop re- peatedly calls AG_ProcessTimeouts() routine to process expired timers. Different objects may also manage timers differently (see SPECIALIZED TIMERS below). INTERFACE void AG_InitTimer(AG_Timer *timer, const char *name, Uint flags) int AG_AddTimer(void *obj, AG_Timer *timer, Uint32 t, Uint32 (*fn)(AG_Timer *, AG_Event *), const char *fmt, ...) AG_Timer * AG_AddTimerAuto(void *obj, Uint32 t, Uint32 (*fn)(AG_Timer *, AG_Event *), const char *fmt, ...) void AG_DelTimer(void *obj, AG_Timer *timer) int AG_ResetTimer(void *obj, AG_Timer *timer, Uint32 t) void AG_LockTimers(void *obj) void AG_UnlockTimers(void *obj) int AG_TimerIsRunning(void *obj, AG_Timer *timer) void AG_ProcessTimeouts(Uint32 ticks) The AG_InitTimer() routine initializes a AG_Timer structure. name is an optional string identifier, useful for debugging purposes. Acceptable flags options include: AG_TIMER_SURVIVE_DETACH Don't automatically cancel the timer if its parent object is being detached (see AG_ObjectDetach(3)). AG_TIMER_AUTO_FREE Automatically free() the timer structure upon expiration or cancellation (set implicitely by AG_AddTimerAuto()). The AG_AddTimer() function starts the timer. The optional obj argument specifies a parent AG_Object(3) which will manage the timer. The call- back routine is specified as the fn() argument. Arguments to pass to the callback may be specified under fmt (using the AG_Event(3) style of argu- ment passing). The AG_AddTimer() function returns 0 on success or -1 if the timer could not be created. Timers created with AG_AddTimer() are set to expire in t ticks from now. On expiration, the timer's callback is invoked. If it returns a non-zero number of ticks, the timer is restarted, otherwise it is cancelled. The AG_AddTimerAuto() variant of AG_AddTimer() allocates an anonymous AG_Timer structure which will be freed upon cancellation. On success, a pointer to the new timer structure is returned (it is not safe to deref- erence this pointer unless AG_LockTimers() is in effect). On failure, AG_AddTimerAuto() returns NULL. The AG_DelTimer() function deletes a timer. The optional obj argument specifies the timer's parent object. The timer argument does not need to point to an initialized structure. If the timer is not running, AG_DelTimer() is a safe no-op. The AG_ResetTimer() function changes the interval of a running timer, such that it will expire in t ticks from now. It is illegal to invoke AG_ResetTimer() on a timer that is not currently running, and the call must be protected by AG_LockTimers(). In the timer callback routine, it is safe to make AG_AddTimer() or AG_DelTimer() calls. It is not safe to try and detach or destroy the timer's parent object from the callback routine. The AG_TimerIsRunning() function returns 1 if the timer is active. For thread safety, the call should be protected by AG_LockTimers(): AG_LockTimers(obj); if (AG_TimerIsRunning(obj, &timer)) { ... } AG_UnlockTimers(obj); The AG_ProcessTimeouts() function advances the timing wheel and executes the callbacks of expired timers. Normally, this function is not used di- rectly, but it can be useful on platforms without timer interfaces (i.e., AG_ProcessTimeouts() may be called repeatedly from a delay loop). The ticks argument is the monotonic time in ticks (usually obtained from AG_GetTicks(3)). For AG_ProcessTimeouts() to work as expected, the AG_SOFT_TIMERS flag must be passed to AG_InitCore(3). SPECIALIZED TIMERS The AG_Timer interface is not tied to any specific time source. A timer's parent object may influence the way timers are processed. By default, the execution of timers is based on the progress of a mono- tonic system clock and one "tick" is roughly equivalent to one millisec- ond. However, it is possible for different parent objects to process time differently. For example, an object in a simulation application might manage its timers using use some software-defined time, or an off- line renderer might require that logic time be stopped during rendering (see AG_Time(3)). SEE ALSO AG_Event(3), AG_GetTicks(3), AG_Intro(3), AG_Object(3), AG_SchedEvent(3), AG_Time(3) George Varghese and Tony Lauck, Hashed and Hierarchical Timing Wheels: Efficient Data Structures for Implementing a Timer Facility, February 14, 1996. HISTORY The AG_Timer facility first appeared in Agar 1.0 as AG_Timeout, and was modeled after the OpenBSD timeout(9) API by Artur Grabowski and Thomas Nordin. In Agar 1.5.0, callback routines were allowed to accept multiple arguments, and support for kqueue(2) was added. BSD May 9, 2004 BSD
NAME | SYNOPSIS | DESCRIPTION | INTERFACE | SPECIALIZED TIMERS | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Timer&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>