FreeBSD Manual Pages
AG_TIMER(3) 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 object, Agar will guarantee cancellation of any callbacks if the parent object is destroyed or detached. When a timer expires, its callback routine is exe- cuted. 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 previ- ously specified in AG_AddTimer(). The current timer interval (in ticks) can be retrieved from the ival member of the AG_Timer structure. The call- back 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 execu- tion of the callback. The context of execution of the callback is plat- form-dependent. On platforms where kqueue(2) is available, the routine is executed in the event loop. On platforms where only POSIX timers are available, the routine is executed in a separate thread. On platforms which don't provide any timer interface at all, the event loop repeatedly calls AG_ProcessTimeouts() routine to process expired timers. Different objects may also manage timers differently (see "SPECIALIZED TIMERS" be- low). 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) void AG_DelTimers(void *obj) 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) Uint32 AG_ExecTimer(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 par- ent object is being detached (see AG_ObjectDe- tach(3)). AG_TIMER_AUTO_FREE Automatically free() the timer structure upon ex- piration 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 callback routine is specified as the fn() argument. Arguments to pass to the call- back may be specified under fmt (using the AG_Event(3) style of argument 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 derefer- ence this pointer unless AG_LockTimers() is in effect). On failure, AG_Ad- dTimerAuto() returns NULL. The AG_DelTimer() function cancels the execution of a timer and frees all resources allocated by it. If the given timer is not active, AG_DelTimer() does nothing. The optional obj argument specifies the timer's parent ob- ject. The timer argument does not need to point to an initialized struc- ture. 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_Reset- Timer() on a timer that is not currently running, and the call must be pro- tected by AG_LockTimers(). In the timer callback routine, it is safe to make AG_AddTimer() or AG_Del- Timer() 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); AG_ExecTimer() runs the timer's callback routine artificially and returns its return value. The caller is normally expected to use AG_DelTimer() on a return value of 0 and AG_ResetTimer() if the returned interval differs from current to->ival. 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 monotonic system clock and one "tick" is roughly equivalent to one millisecond. How- ever, it is possible for different parent objects to process time differ- ently. For example, an object in a simulation application might manage its timers using use some software-defined time, or an offline renderer might require that logic time be stopped during rendering (see AG_Time(3)). EXAMPLES The following code creates 3 one-shot and 1 regular timer: static Uint32 Timeout1(AG_Timer *to, AG_Event *event) { AG_Verbose("This message should appear first\n"); return (0); } static Uint32 Timeout2(AG_Timer *to, AG_Event *event) { AG_Verbose("This message should appear second\n"); return (0); } static Uint32 Timeout3(AG_Timer *to, AG_Event *event) { AG_Verbose("This message should appear last\n"); return (0); } static Uint32 TimeoutReg(AG_Timer *to, AG_Event *event) { AG_Verbose("Tick #%u\n", AG_GetTicks()); return (to->ival); } AG_Object obj; AG_ObjectInit(&obj, NULL, &agObjectClass); AG_AddTimerAuto(obj, 1000, Timeout1,NULL); AG_AddTimerAuto(obj, 2000, Timeout2,NULL); AG_AddTimerAuto(obj, 2100, Timeout3,NULL); AG_AddTimerAuto(obj, 1000, TimeoutReg,NULL); 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: Ef- ficient Data Structures for Implementing a Timer Facility, February 14, 1996. HISTORY The AG_Timer facility first appeared in Agar 1.0 as AG_Timeout. It is mod- eled after the OpenBSD timeout(9) API by Artur Grabowski and Thomas Nordin. Support for multiple arguments in callback routines was added in Agar 1.5. Support for kqueue(2) appeared in Agar 1.5. Agar 1.7 December 21, 2022 AG_TIMER(3)
NAME | SYNOPSIS | DESCRIPTION | INTERFACE | SPECIALIZED TIMERS | EXAMPLES | 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+Ports+15.1.quarterly>