Annotation of src/external/mpl/bind/dist/lib/isc/include/isc/timer.h, Revision 1.6
1.2 christos 1: /* $NetBSD: timer.h,v 1.1.1.10 2014/12/10 03:34:44 christos Exp $ */
1.1 christos 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
1.5 christos 8: * file, you can obtain one at https://mozilla.org/MPL/2.0/.
1.1 christos 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.4 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.3 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.4 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.4 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.4 christos 92: struct isc_event common;
93: isc_time_t due;
1.1 christos 94: } isc_timerevent_t;
95:
1.4 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: *** Timer and Timer Manager Functions
104: ***
105: *** Note: all Ensures conditions apply only if the result is success for
106: *** those functions which return an isc_result_t.
107: ***/
108:
109: isc_result_t
1.4 christos 110: isc_timer_create(isc_timermgr_t *manager, isc_timertype_t type,
111: const isc_time_t *expires, const isc_interval_t *interval,
112: isc_task_t *task, isc_taskaction_t action, void *arg,
1.1 christos 113: isc_timer_t **timerp);
114: /*%<
115: * Create a new 'type' timer managed by 'manager'. The timers parameters
116: * are specified by 'expires' and 'interval'. Events will be posted to
117: * 'task' and when dispatched 'action' will be called with 'arg' as the
118: * arg value. The new timer is returned in 'timerp'.
119: *
120: * Notes:
121: *
122: *\li For ticker timers, the timer will generate a 'tick' event every
123: * 'interval' seconds. The value of 'expires' is ignored.
124: *
125: *\li For once timers, 'expires' specifies the time when a life timeout
126: * event should be generated. If 'expires' is 0 (the epoch), then no life
127: * timeout will be generated. 'interval' specifies how long the timer
128: * can be idle before it generates an idle timeout. If 0, then no
129: * idle timeout will be generated.
130: *
131: *\li If 'expires' is NULL, the epoch will be used.
132: *
133: * If 'interval' is NULL, the zero interval will be used.
134: *
135: * Requires:
136: *
137: *\li 'manager' is a valid manager
138: *
139: *\li 'task' is a valid task
140: *
141: *\li 'action' is a valid action
142: *
143: *\li 'expires' points to a valid time, or is NULL.
144: *
145: *\li 'interval' points to a valid interval, or is NULL.
146: *
147: *\li type == isc_timertype_inactive ||
148: * ('expires' and 'interval' are not both 0)
149: *
150: *\li 'timerp' is a valid pointer, and *timerp == NULL
151: *
152: * Ensures:
153: *
154: *\li '*timerp' is attached to the newly created timer
155: *
156: *\li The timer is attached to the task
157: *
158: *\li An idle timeout will not be generated until at least Now + the
159: * timer's interval if 'timer' is a once timer with a non-zero
160: * interval.
161: *
162: * Returns:
163: *
164: *\li Success
165: *\li No memory
166: *\li Unexpected error
167: */
168:
169: isc_result_t
1.4 christos 170: isc_timer_reset(isc_timer_t *timer, isc_timertype_t type,
171: const isc_time_t *expires, const isc_interval_t *interval,
1.3 christos 172: bool purge);
1.1 christos 173: /*%<
174: * Change the timer's type, expires, and interval values to the given
175: * values. If 'purge' is TRUE, any pending events from this timer
176: * are purged from its task's event queue.
177: *
178: * Notes:
179: *
180: *\li If 'expires' is NULL, the epoch will be used.
181: *
182: *\li If 'interval' is NULL, the zero interval will be used.
183: *
184: * Requires:
185: *
186: *\li 'timer' is a valid timer
187: *
188: *\li The same requirements that isc_timer_create() imposes on 'type',
189: * 'expires' and 'interval' apply.
190: *
191: * Ensures:
192: *
193: *\li An idle timeout will not be generated until at least Now + the
194: * timer's interval if 'timer' is a once timer with a non-zero
195: * interval.
196: *
197: * Returns:
198: *
199: *\li Success
200: *\li No memory
201: *\li Unexpected error
202: */
203:
204: isc_result_t
205: isc_timer_touch(isc_timer_t *timer);
206: /*%<
207: * Set the last-touched time of 'timer' to the current time.
208: *
209: * Requires:
210: *
211: *\li 'timer' is a valid once timer.
212: *
213: * Ensures:
214: *
215: *\li An idle timeout will not be generated until at least Now + the
216: * timer's interval if 'timer' is a once timer with a non-zero
217: * interval.
218: *
219: * Returns:
220: *
221: *\li Success
222: *\li Unexpected error
223: */
224:
225: void
226: isc_timer_attach(isc_timer_t *timer, isc_timer_t **timerp);
227: /*%<
228: * Attach *timerp to timer.
229: *
230: * Requires:
231: *
232: *\li 'timer' is a valid timer.
233: *
234: *\li 'timerp' points to a NULL timer.
235: *
236: * Ensures:
237: *
238: *\li *timerp is attached to timer.
239: */
240:
241: void
242: isc_timer_detach(isc_timer_t **timerp);
243: /*%<
244: * Detach *timerp from its timer.
245: *
246: * Requires:
247: *
248: *\li 'timerp' points to a valid timer.
249: *
250: * Ensures:
251: *
252: *\li *timerp is NULL.
253: *
254: *\li If '*timerp' is the last reference to the timer,
255: * then:
256: *
257: *\code
258: * The timer will be shutdown
259: *
260: * The timer will detach from its task
261: *
262: * All resources used by the timer have been freed
263: *
264: * Any events already posted by the timer will be purged.
265: * Therefore, if isc_timer_detach() is called in the context
266: * of the timer's task, it is guaranteed that no more
267: * timer event callbacks will run after the call.
268: *\endcode
269: */
270:
271: isc_timertype_t
272: isc_timer_gettype(isc_timer_t *timer);
273: /*%<
274: * Return the timer type.
275: *
276: * Requires:
277: *
278: *\li 'timer' to be a valid timer.
279: */
280:
281: isc_result_t
282: isc_timermgr_create(isc_mem_t *mctx, isc_timermgr_t **managerp);
283: /*%<
1.6 ! christos 284: * Create a timer manager.
1.1 christos 285: *
286: * Notes:
287: *
288: *\li All memory will be allocated in memory context 'mctx'.
289: *
290: * Requires:
291: *
292: *\li 'mctx' is a valid memory context.
293: *
294: *\li 'managerp' points to a NULL isc_timermgr_t.
295: *
296: * Ensures:
297: *
298: *\li '*managerp' is a valid isc_timermgr_t.
299: *
300: * Returns:
301: *
302: *\li Success
303: *\li No memory
304: *\li Unexpected error
305: */
306:
307: void
308: isc_timermgr_destroy(isc_timermgr_t **managerp);
309: /*%<
310: * Destroy a timer manager.
311: *
312: * Notes:
313: *
314: *\li This routine blocks until there are no timers left in the manager,
315: * so if the caller holds any timer references using the manager, it
316: * must detach them before calling isc_timermgr_destroy() or it will
317: * block forever.
318: *
319: * Requires:
320: *
321: *\li '*managerp' is a valid isc_timermgr_t.
322: *
323: * Ensures:
324: *
325: *\li *managerp == NULL
326: *
327: *\li All resources used by the manager have been freed.
328: */
329:
1.4 christos 330: void
331: isc_timermgr_poke(isc_timermgr_t *m);
1.1 christos 332:
333: ISC_LANG_ENDDECLS
334:
335: #endif /* ISC_TIMER_H */
CVSweb <webmaster@jp.NetBSD.org>