2 * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2002 Internet Software Consortium.
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: timer.h,v 1.28.12.6 2005/10/27 00:27:30 marka Exp $ */
30 * Provides timers which are event sources in the task system.
32 * Three types of timers are supported:
34 * 'ticker' timers generate a periodic tick event.
36 * 'once' timers generate an idle timeout event if they are idle for too
37 * long, and generate a life timeout event if their lifetime expires.
38 * They are used to implement both (possibly expiring) idle timers and
41 * 'limited' timers generate a periodic tick event until they reach
42 * their lifetime when they generate a life timeout event.
44 * 'inactive' timers generate no events.
46 * Timers can change type. It is typical to create a timer as
47 * an 'inactive' timer and then change it into a 'ticker' or
51 * The module ensures appropriate synchronization of data structures it
52 * creates and manipulates.
54 * Clients of this module must not be holding a timer's task's lock when
55 * making a call that affects that timer. Failure to follow this rule
56 * can result in deadlock.
58 * The caller must ensure that isc_timermgr_destroy() is called only
59 * once for a given manager.
62 * No anticipated impact.
68 * No anticipated impact.
79 #include <isc/types.h>
80 #include <isc/event.h>
81 #include <isc/eventclass.h>
91 isc_timertype_ticker = 0,
92 isc_timertype_once = 1,
93 isc_timertype_limited = 2,
94 isc_timertype_inactive = 3
97 typedef struct isc_timerevent {
98 struct isc_event common;
101 #define ISC_TIMEREVENT_FIRSTEVENT (ISC_EVENTCLASS_TIMER + 0)
102 #define ISC_TIMEREVENT_TICK (ISC_EVENTCLASS_TIMER + 1)
103 #define ISC_TIMEREVENT_IDLE (ISC_EVENTCLASS_TIMER + 2)
104 #define ISC_TIMEREVENT_LIFE (ISC_EVENTCLASS_TIMER + 3)
105 #define ISC_TIMEREVENT_LASTEVENT (ISC_EVENTCLASS_TIMER + 65535)
108 *** Timer and Timer Manager Functions
110 *** Note: all Ensures conditions apply only if the result is success for
111 *** those functions which return an isc_result_t.
115 isc_timer_create(isc_timermgr_t *manager,
116 isc_timertype_t type,
118 isc_interval_t *interval,
120 isc_taskaction_t action,
122 isc_timer_t **timerp);
124 * Create a new 'type' timer managed by 'manager'. The timers parameters
125 * are specified by 'expires' and 'interval'. Events will be posted to
126 * 'task' and when dispatched 'action' will be called with 'arg' as the
127 * arg value. The new timer is returned in 'timerp'.
131 * For ticker timers, the timer will generate a 'tick' event every
132 * 'interval' seconds. The value of 'expires' is ignored.
134 * For once timers, 'expires' specifies the time when a life timeout
135 * event should be generated. If 'expires' is 0 (the epoch), then no life
136 * timeout will be generated. 'interval' specifies how long the timer
137 * can be idle before it generates an idle timeout. If 0, then no
138 * idle timeout will be generated.
140 * If 'expires' is NULL, the epoch will be used.
142 * If 'interval' is NULL, the zero interval will be used.
146 * 'manager' is a valid manager
148 * 'task' is a valid task
150 * 'action' is a valid action
152 * 'expires' points to a valid time, or is NULL.
154 * 'interval' points to a valid interval, or is NULL.
156 * type == isc_timertype_inactive ||
157 * ('expires' and 'interval' are not both 0)
159 * 'timerp' is a valid pointer, and *timerp == NULL
163 * '*timerp' is attached to the newly created timer
165 * The timer is attached to the task
167 * An idle timeout will not be generated until at least Now + the
168 * timer's interval if 'timer' is a once timer with a non-zero
179 isc_timer_reset(isc_timer_t *timer,
180 isc_timertype_t type,
182 isc_interval_t *interval,
183 isc_boolean_t purge);
185 * Change the timer's type, expires, and interval values to the given
186 * values. If 'purge' is TRUE, any pending events from this timer
187 * are purged from its task's event queue.
191 * If 'expires' is NULL, the epoch will be used.
193 * If 'interval' is NULL, the zero interval will be used.
197 * 'timer' is a valid timer
199 * The same requirements that isc_timer_create() imposes on 'type',
200 * 'expires' and 'interval' apply.
204 * An idle timeout will not be generated until at least Now + the
205 * timer's interval if 'timer' is a once timer with a non-zero
216 isc_timer_touch(isc_timer_t *timer);
218 * Set the last-touched time of 'timer' to the current time.
222 * 'timer' is a valid once timer.
226 * An idle timeout will not be generated until at least Now + the
227 * timer's interval if 'timer' is a once timer with a non-zero
237 isc_timer_attach(isc_timer_t *timer, isc_timer_t **timerp);
239 * Attach *timerp to timer.
243 * 'timer' is a valid timer.
245 * 'timerp' points to a NULL timer.
249 * *timerp is attached to timer.
253 isc_timer_detach(isc_timer_t **timerp);
255 * Detach *timerp from its timer.
259 * 'timerp' points to a valid timer.
265 * If '*timerp' is the last reference to the timer,
268 * The timer will be shutdown
270 * The timer will detach from its task
272 * All resources used by the timer have been freed
274 * Any events already posted by the timer will be purged.
275 * Therefore, if isc_timer_detach() is called in the context
276 * of the timer's task, it is guaranteed that no more
277 * timer event callbacks will run after the call.
281 isc_timer_gettype(isc_timer_t *timer);
283 * Return the timer type.
287 *\li 'timer' to be a valid timer.
291 isc_timermgr_create(isc_mem_t *mctx, isc_timermgr_t **managerp);
293 * Create a timer manager.
297 * All memory will be allocated in memory context 'mctx'.
301 * 'mctx' is a valid memory context.
303 * 'managerp' points to a NULL isc_timermgr_t.
307 * '*managerp' is a valid isc_timermgr_t.
317 isc_timermgr_destroy(isc_timermgr_t **managerp);
319 * Destroy a timer manager.
323 * This routine blocks until there are no timers left in the manager,
324 * so if the caller holds any timer references using the manager, it
325 * must detach them before calling isc_timermgr_destroy() or it will
330 * '*managerp' is a valid isc_timermgr_t.
336 * All resources used by the manager have been freed.
339 void isc_timermgr_poke(isc_timermgr_t *m);
343 #endif /* ISC_TIMER_H */