Annotation of src/external/mpl/bind/dist/lib/isc/include/isc/timer.h, Revision 1.1.1.3
1.1 christos 1: /* $NetBSD$ */
2:
3: /*
4: * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
5: *
6: * This Source Code Form is subject to the terms of the Mozilla Public
7: * License, v. 2.0. If a copy of the MPL was not distributed with this
8: * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9: *
10: * See the COPYRIGHT file distributed with this work for additional
11: * information regarding copyright ownership.
12: */
13:
14: #ifndef ISC_TIMER_H
15: #define ISC_TIMER_H 1
16:
17: /*****
1.1.1.3 ! christos 18: ***** Module Info
! 19: *****/
1.1 christos 20:
21: /*! \file isc/timer.h
22: * \brief Provides timers which are event sources in the task system.
23: *
24: * Three types of timers are supported:
25: *
26: *\li 'ticker' timers generate a periodic tick event.
27: *
28: *\li 'once' timers generate an idle timeout event if they are idle for too
29: * long, and generate a life timeout event if their lifetime expires.
30: * They are used to implement both (possibly expiring) idle timers and
31: * 'one-shot' timers.
32: *
33: *\li 'limited' timers generate a periodic tick event until they reach
34: * their lifetime when they generate a life timeout event.
35: *
36: *\li 'inactive' timers generate no events.
37: *
38: * Timers can change type. It is typical to create a timer as
39: * an 'inactive' timer and then change it into a 'ticker' or
40: * 'once' timer.
41: *
42: *\li MP:
43: * The module ensures appropriate synchronization of data structures it
44: * creates and manipulates.
45: * Clients of this module must not be holding a timer's task's lock when
46: * making a call that affects that timer. Failure to follow this rule
47: * can result in deadlock.
48: * The caller must ensure that isc_timermgr_destroy() is called only
49: * once for a given manager.
50: *
51: * \li Reliability:
52: * No anticipated impact.
53: *
54: * \li Resources:
55: * TBS
56: *
57: * \li Security:
58: * No anticipated impact.
59: *
60: * \li Standards:
61: * None.
62: */
63:
64: /***
65: *** Imports
66: ***/
67:
1.1.1.2 christos 68: #include <stdbool.h>
69:
1.1 christos 70: #include <isc/event.h>
71: #include <isc/eventclass.h>
72: #include <isc/lang.h>
73: #include <isc/time.h>
1.1.1.3 ! christos 74: #include <isc/types.h>
1.1 christos 75:
76: ISC_LANG_BEGINDECLS
77:
78: /***
79: *** Types
80: ***/
81:
82: /*% Timer Type */
83: typedef enum {
1.1.1.3 ! christos 84: isc_timertype_undefined = -1, /*%< Undefined */
! 85: isc_timertype_ticker = 0, /*%< Ticker */
! 86: isc_timertype_once = 1, /*%< Once */
! 87: isc_timertype_limited = 2, /*%< Limited */
! 88: isc_timertype_inactive = 3 /*%< Inactive */
1.1 christos 89: } isc_timertype_t;
90:
91: typedef struct isc_timerevent {
1.1.1.3 ! christos 92: struct isc_event common;
! 93: isc_time_t due;
1.1 christos 94: } isc_timerevent_t;
95:
1.1.1.3 ! christos 96: #define ISC_TIMEREVENT_FIRSTEVENT (ISC_EVENTCLASS_TIMER + 0)
! 97: #define ISC_TIMEREVENT_TICK (ISC_EVENTCLASS_TIMER + 1)
! 98: #define ISC_TIMEREVENT_IDLE (ISC_EVENTCLASS_TIMER + 2)
! 99: #define ISC_TIMEREVENT_LIFE (ISC_EVENTCLASS_TIMER + 3)
! 100: #define ISC_TIMEREVENT_LASTEVENT (ISC_EVENTCLASS_TIMER + 65535)
1.1 christos 101:
102: /*%
103: * This structure is actually just the common prefix of a timer manager
104: * object implementation's version of an isc_timermgr_t.
105: * \brief
106: * Direct use of this structure by clients is forbidden. timer implementations
107: * may change the structure. 'magic' must be ISCAPI_TIMERMGR_MAGIC for any
108: * of the isc_timer_ routines to work. timer implementations must maintain
109: * all timer invariants.
110: */
111: struct isc_timermgr {
1.1.1.3 ! christos 112: unsigned int impmagic;
! 113: unsigned int magic;
1.1 christos 114: };
115:
1.1.1.3 ! christos 116: #define ISCAPI_TIMERMGR_MAGIC ISC_MAGIC('A', 't', 'm', 'g')
! 117: #define ISCAPI_TIMERMGR_VALID(m) \
! 118: ((m) != NULL && (m)->magic == ISCAPI_TIMERMGR_MAGIC)
1.1 christos 119:
120: /*%
121: * This is the common prefix of a timer object. The same note as
122: * that for the timermgr structure applies.
123: */
124: struct isc_timer {
1.1.1.3 ! christos 125: unsigned int impmagic;
! 126: unsigned int magic;
1.1 christos 127: };
128:
1.1.1.3 ! christos 129: #define ISCAPI_TIMER_MAGIC ISC_MAGIC('A', 't', 'm', 'r')
! 130: #define ISCAPI_TIMER_VALID(s) ((s) != NULL && (s)->magic == ISCAPI_TIMER_MAGIC)
1.1 christos 131:
132: /***
133: *** Timer and Timer Manager Functions
134: ***
135: *** Note: all Ensures conditions apply only if the result is success for
136: *** those functions which return an isc_result_t.
137: ***/
138:
139: isc_result_t
1.1.1.3 ! christos 140: isc_timer_create(isc_timermgr_t *manager, isc_timertype_t type,
! 141: const isc_time_t *expires, const isc_interval_t *interval,
! 142: isc_task_t *task, isc_taskaction_t action, void *arg,
1.1 christos 143: isc_timer_t **timerp);
144: /*%<
145: * Create a new 'type' timer managed by 'manager'. The timers parameters
146: * are specified by 'expires' and 'interval'. Events will be posted to
147: * 'task' and when dispatched 'action' will be called with 'arg' as the
148: * arg value. The new timer is returned in 'timerp'.
149: *
150: * Notes:
151: *
152: *\li For ticker timers, the timer will generate a 'tick' event every
153: * 'interval' seconds. The value of 'expires' is ignored.
154: *
155: *\li For once timers, 'expires' specifies the time when a life timeout
156: * event should be generated. If 'expires' is 0 (the epoch), then no life
157: * timeout will be generated. 'interval' specifies how long the timer
158: * can be idle before it generates an idle timeout. If 0, then no
159: * idle timeout will be generated.
160: *
161: *\li If 'expires' is NULL, the epoch will be used.
162: *
163: * If 'interval' is NULL, the zero interval will be used.
164: *
165: * Requires:
166: *
167: *\li 'manager' is a valid manager
168: *
169: *\li 'task' is a valid task
170: *
171: *\li 'action' is a valid action
172: *
173: *\li 'expires' points to a valid time, or is NULL.
174: *
175: *\li 'interval' points to a valid interval, or is NULL.
176: *
177: *\li type == isc_timertype_inactive ||
178: * ('expires' and 'interval' are not both 0)
179: *
180: *\li 'timerp' is a valid pointer, and *timerp == NULL
181: *
182: * Ensures:
183: *
184: *\li '*timerp' is attached to the newly created timer
185: *
186: *\li The timer is attached to the task
187: *
188: *\li An idle timeout will not be generated until at least Now + the
189: * timer's interval if 'timer' is a once timer with a non-zero
190: * interval.
191: *
192: * Returns:
193: *
194: *\li Success
195: *\li No memory
196: *\li Unexpected error
197: */
198:
199: isc_result_t
1.1.1.3 ! christos 200: isc_timer_reset(isc_timer_t *timer, isc_timertype_t type,
! 201: const isc_time_t *expires, const isc_interval_t *interval,
1.1.1.2 christos 202: bool purge);
1.1 christos 203: /*%<
204: * Change the timer's type, expires, and interval values to the given
205: * values. If 'purge' is TRUE, any pending events from this timer
206: * are purged from its task's event queue.
207: *
208: * Notes:
209: *
210: *\li If 'expires' is NULL, the epoch will be used.
211: *
212: *\li If 'interval' is NULL, the zero interval will be used.
213: *
214: * Requires:
215: *
216: *\li 'timer' is a valid timer
217: *
218: *\li The same requirements that isc_timer_create() imposes on 'type',
219: * 'expires' and 'interval' apply.
220: *
221: * Ensures:
222: *
223: *\li An idle timeout will not be generated until at least Now + the
224: * timer's interval if 'timer' is a once timer with a non-zero
225: * interval.
226: *
227: * Returns:
228: *
229: *\li Success
230: *\li No memory
231: *\li Unexpected error
232: */
233:
234: isc_result_t
235: isc_timer_touch(isc_timer_t *timer);
236: /*%<
237: * Set the last-touched time of 'timer' to the current time.
238: *
239: * Requires:
240: *
241: *\li 'timer' is a valid once timer.
242: *
243: * Ensures:
244: *
245: *\li An idle timeout will not be generated until at least Now + the
246: * timer's interval if 'timer' is a once timer with a non-zero
247: * interval.
248: *
249: * Returns:
250: *
251: *\li Success
252: *\li Unexpected error
253: */
254:
255: void
256: isc_timer_attach(isc_timer_t *timer, isc_timer_t **timerp);
257: /*%<
258: * Attach *timerp to timer.
259: *
260: * Requires:
261: *
262: *\li 'timer' is a valid timer.
263: *
264: *\li 'timerp' points to a NULL timer.
265: *
266: * Ensures:
267: *
268: *\li *timerp is attached to timer.
269: */
270:
271: void
272: isc_timer_detach(isc_timer_t **timerp);
273: /*%<
274: * Detach *timerp from its timer.
275: *
276: * Requires:
277: *
278: *\li 'timerp' points to a valid timer.
279: *
280: * Ensures:
281: *
282: *\li *timerp is NULL.
283: *
284: *\li If '*timerp' is the last reference to the timer,
285: * then:
286: *
287: *\code
288: * The timer will be shutdown
289: *
290: * The timer will detach from its task
291: *
292: * All resources used by the timer have been freed
293: *
294: * Any events already posted by the timer will be purged.
295: * Therefore, if isc_timer_detach() is called in the context
296: * of the timer's task, it is guaranteed that no more
297: * timer event callbacks will run after the call.
298: *\endcode
299: */
300:
301: isc_timertype_t
302: isc_timer_gettype(isc_timer_t *timer);
303: /*%<
304: * Return the timer type.
305: *
306: * Requires:
307: *
308: *\li 'timer' to be a valid timer.
309: */
310:
311: isc_result_t
1.1.1.3 ! christos 312: isc_timermgr_createinctx(isc_mem_t *mctx, isc_timermgr_t **managerp);
1.1 christos 313:
314: isc_result_t
315: isc_timermgr_create(isc_mem_t *mctx, isc_timermgr_t **managerp);
316: /*%<
317: * Create a timer manager. isc_timermgr_createinctx() also associates
318: * the new manager with the specified application context.
319: *
320: * Notes:
321: *
322: *\li All memory will be allocated in memory context 'mctx'.
323: *
324: * Requires:
325: *
326: *\li 'mctx' is a valid memory context.
327: *
328: *\li 'managerp' points to a NULL isc_timermgr_t.
329: *
330: *\li 'actx' is a valid application context (for createinctx()).
331: *
332: * Ensures:
333: *
334: *\li '*managerp' is a valid isc_timermgr_t.
335: *
336: * Returns:
337: *
338: *\li Success
339: *\li No memory
340: *\li Unexpected error
341: */
342:
343: void
344: isc_timermgr_destroy(isc_timermgr_t **managerp);
345: /*%<
346: * Destroy a timer manager.
347: *
348: * Notes:
349: *
350: *\li This routine blocks until there are no timers left in the manager,
351: * so if the caller holds any timer references using the manager, it
352: * must detach them before calling isc_timermgr_destroy() or it will
353: * block forever.
354: *
355: * Requires:
356: *
357: *\li '*managerp' is a valid isc_timermgr_t.
358: *
359: * Ensures:
360: *
361: *\li *managerp == NULL
362: *
363: *\li All resources used by the manager have been freed.
364: */
365:
1.1.1.3 ! christos 366: void
! 367: isc_timermgr_poke(isc_timermgr_t *m);
1.1 christos 368:
369: ISC_LANG_ENDDECLS
370:
371: #endif /* ISC_TIMER_H */
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to timer.h CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / external / mpl / bind / dist / lib / isc / include / isc