include/isc/timer.h

18 /* $Id: timer.h,v 1.43 2009/09/02 23:48:03 tbox Exp $ */
27 /*! \file isc/timer.h
44  * Timers can change type.  It is typical to create a timer as
45  * an 'inactive' timer and then change it into a 'ticker' or
46  * 'once' timer.
51  *	Clients of this module must not be holding a timer's task's lock when
52  *	making a call that affects that timer.  Failure to follow this rule
106 /*% Timer and timer manager methods */
120 	void		(*attach)(isc_timer_t *timer, isc_timer_t **timerp);
122 	isc_result_t	(*reset)(isc_timer_t *timer, isc_timertype_t type,
125 	isc_result_t	(*touch)(isc_timer_t *timer);
129  * This structure is actually just the common prefix of a timer manager
132  * Direct use of this structure by clients is forbidden.  timer implementations
134  * of the isc_timer_ routines to work.  timer implementations must maintain
135  * all timer invariants.
148  * This is the common prefix of a timer object.  The same note as
178  * Create a new 'type' timer managed by 'manager'.  The timers parameters
181  * arg value.  The new timer is returned in 'timerp'.
185  *\li	For ticker timers, the timer will generate a 'tick' event every
190  *	timeout will be generated.  'interval' specifies how long the timer
217  *\li	'*timerp' is attached to the newly created timer
219  *\li	The timer is attached to the task
222  *	timer's interval if 'timer' is a once timer with a non-zero
233 isc_timer_reset(isc_timer_t *timer,
239  * Change the timer's type, expires, and interval values to the given
240  * values.  If 'purge' is TRUE, any pending events from this timer
251  *\li	'timer' is a valid timer
259  *	timer's interval if 'timer' is a once timer with a non-zero
270 isc_timer_touch(isc_timer_t *timer);
272  * Set the last-touched time of 'timer' to the current time.
276  *\li	'timer' is a valid once timer.
281  *	timer's interval if 'timer' is a once timer with a non-zero
291 isc_timer_attach(isc_timer_t *timer, isc_timer_t **timerp);
293  * Attach *timerp to timer.
297  *\li	'timer' is a valid timer.
299  *\li	'timerp' points to a NULL timer.
303  *\li	*timerp is attached to timer.
309  * Detach *timerp from its timer.
313  *\li	'timerp' points to a valid timer.
319  *\li	If '*timerp' is the last reference to the timer,
323  *		The timer will be shutdown
325  *		The timer will detach from its task
327  *		All resources used by the timer have been freed
329  *		Any events already posted by the timer will be purged.
331  *		of the timer's task, it is guaranteed that no more
332  *		timer event callbacks will run after the call.
337 isc_timer_gettype(isc_timer_t *timer);
339  * Return the timer type.
343  *\li	'timer' to be a valid timer.
353  * Create a timer manager.  isc_timermgr_createinctx() also associates
382  * Destroy a timer manager.
387  *	so if the caller holds any timer references using the manager, it
414  * Register a new timer management implementation and add it to the list of
422  * A short cut function that specifies the timer management module in the ISC