blob: cf3d1d79d8f85e9521672e2ed6b7f52aebcf4ba1 [file] [log] [blame]
Benny Prijono9033e312005-11-21 02:08:39 +00001/* $Id$ */
2/*
Benny Prijono9033e312005-11-21 02:08:39 +00003 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16 */
17
18#ifndef __PJ_TIMER_H__
19#define __PJ_TIMER_H__
20
21/**
22 * @file timer.h
23 * @brief Timer Heap
24 */
25
26#include <pj/types.h>
27
28PJ_BEGIN_DECL
29
30/**
31 * @defgroup PJ_TIMER Timer Heap Management.
32 * @ingroup PJ_MISC
33 * @brief
34 * The timer scheduling implementation here is based on ACE library's
35 * ACE_Timer_Heap, with only little modification to suit our library's style
36 * (I even left most of the comments in the original source).
37 *
38 * To quote the original quote in ACE_Timer_Heap_T class:
39 *
40 * This implementation uses a heap-based callout queue of
41 * absolute times. Therefore, in the average and worst case,
42 * scheduling, canceling, and expiring timers is O(log N) (where
43 * N is the total number of timers). In addition, we can also
44 * preallocate as many \a ACE_Timer_Nodes as there are slots in
45 * the heap. This allows us to completely remove the need for
46 * dynamic memory allocation, which is important for real-time
47 * systems.
Benny Prijono411b2be2006-08-10 08:45:17 +000048 *
49 * You can find the fine ACE library at:
50 * http://www.cs.wustl.edu/~schmidt/ACE.html
51 *
52 * ACE is Copyright (C)1993-2006 Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
53 *
Benny Prijono9033e312005-11-21 02:08:39 +000054 * @{
55 *
56 * \section pj_timer_examples_sec Examples
57 *
58 * For some examples on how to use the timer heap, please see the link below.
59 *
60 * - \ref page_pjlib_timer_test
61 */
62
63
64/**
65 * The type for internal timer ID.
66 */
67typedef int pj_timer_id_t;
68
69/**
70 * Forward declaration for pj_timer_entry.
71 */
72struct pj_timer_entry;
73
74/**
75 * The type of callback function to be called by timer scheduler when a timer
76 * has expired.
77 *
78 * @param timer_heap The timer heap.
79 * @param entry Timer entry which timer's has expired.
80 */
81typedef void pj_timer_heap_callback(pj_timer_heap_t *timer_heap,
82 struct pj_timer_entry *entry);
83
84
85/**
86 * This structure represents an entry to the timer.
87 */
88struct pj_timer_entry
89{
90 /**
91 * User data to be associated with this entry.
92 * Applications normally will put the instance of object that
93 * owns the timer entry in this field.
94 */
95 void *user_data;
96
97 /**
98 * Arbitrary ID assigned by the user/owner of this entry.
99 * Applications can use this ID to distinguish multiple
100 * timer entries that share the same callback and user_data.
101 */
102 int id;
103
104 /**
105 * Callback to be called when the timer expires.
106 */
107 pj_timer_heap_callback *cb;
108
109 /**
110 * Internal unique timer ID, which is assigned by the timer heap.
111 * Application should not touch this ID.
112 */
113 pj_timer_id_t _timer_id;
114
115 /**
116 * The future time when the timer expires, which the value is updated
117 * by timer heap when the timer is scheduled.
118 */
119 pj_time_val _timer_value;
120};
121
122
123/**
124 * Calculate memory size required to create a timer heap.
125 *
126 * @param count Number of timer entries to be supported.
127 * @return Memory size requirement in bytes.
128 */
129PJ_DECL(pj_size_t) pj_timer_heap_mem_size(pj_size_t count);
130
131/**
132 * Create a timer heap.
133 *
134 * @param pool The pool where allocations in the timer heap will be
135 * allocated. The timer heap will dynamicly allocate
136 * more storate from the pool if the number of timer
137 * entries registered is more than the size originally
138 * requested when calling this function.
139 * @param count The maximum number of timer entries to be supported
140 * initially. If the application registers more entries
141 * during runtime, then the timer heap will resize.
142 * @param ht Pointer to receive the created timer heap.
143 *
144 * @return PJ_SUCCESS, or the appropriate error code.
145 */
146PJ_DECL(pj_status_t) pj_timer_heap_create( pj_pool_t *pool,
147 pj_size_t count,
148 pj_timer_heap_t **ht);
149
150/**
151 * Destroy the timer heap.
152 *
153 * @param ht The timer heap.
154 */
155PJ_DECL(void) pj_timer_heap_destroy( pj_timer_heap_t *ht );
156
157
158/**
159 * Set lock object to be used by the timer heap. By default, the timer heap
160 * uses dummy synchronization.
161 *
162 * @param ht The timer heap.
163 * @param lock The lock object to be used for synchronization.
164 * @param auto_del If nonzero, the lock object will be destroyed when
165 * the timer heap is destroyed.
166 */
167PJ_DECL(void) pj_timer_heap_set_lock( pj_timer_heap_t *ht,
168 pj_lock_t *lock,
169 pj_bool_t auto_del );
170
171/**
172 * Set maximum number of timed out entries to process in a single poll.
173 *
174 * @param ht The timer heap.
175 * @param count Number of entries.
176 *
177 * @return The old number.
178 */
179PJ_DECL(unsigned) pj_timer_heap_set_max_timed_out_per_poll(pj_timer_heap_t *ht,
180 unsigned count );
181
182/**
183 * Initialize a timer entry. Application should call this function at least
184 * once before scheduling the entry to the timer heap, to properly initialize
185 * the timer entry.
186 *
187 * @param entry The timer entry to be initialized.
188 * @param id Arbitrary ID assigned by the user/owner of this entry.
189 * Applications can use this ID to distinguish multiple
190 * timer entries that share the same callback and user_data.
191 * @param user_data User data to be associated with this entry.
192 * Applications normally will put the instance of object that
193 * owns the timer entry in this field.
194 * @param cb Callback function to be called when the timer elapses.
195 *
196 * @return The timer entry itself.
197 */
198PJ_DECL(pj_timer_entry*) pj_timer_entry_init( pj_timer_entry *entry,
199 int id,
200 void *user_data,
201 pj_timer_heap_callback *cb );
202
203/**
204 * Schedule a timer entry which will expire AFTER the specified delay.
205 *
206 * @param ht The timer heap.
207 * @param entry The entry to be registered.
208 * @param delay The interval to expire.
209 * @return PJ_SUCCESS, or the appropriate error code.
210 */
211PJ_DECL(pj_status_t) pj_timer_heap_schedule( pj_timer_heap_t *ht,
212 pj_timer_entry *entry,
213 const pj_time_val *delay);
214
215/**
216 * Cancel a previously registered timer.
217 *
218 * @param ht The timer heap.
219 * @param entry The entry to be cancelled.
220 * @return The number of timer cancelled, which should be one if the
221 * entry has really been registered, or zero if no timer was
222 * cancelled.
223 */
224PJ_DECL(int) pj_timer_heap_cancel( pj_timer_heap_t *ht,
225 pj_timer_entry *entry);
226
227/**
228 * Get the number of timer entries.
229 *
230 * @param ht The timer heap.
231 * @return The number of timer entries.
232 */
233PJ_DECL(pj_size_t) pj_timer_heap_count( pj_timer_heap_t *ht );
234
235/**
236 * Get the earliest time registered in the timer heap. The timer heap
237 * MUST have at least one timer being scheduled (application should use
238 * #pj_timer_heap_count() before calling this function).
239 *
240 * @param ht The timer heap.
241 * @param timeval The time deadline of the earliest timer entry.
242 *
243 * @return PJ_SUCCESS, or PJ_ENOTFOUND if no entry is scheduled.
244 */
245PJ_DECL(pj_status_t) pj_timer_heap_earliest_time( pj_timer_heap_t *ht,
246 pj_time_val *timeval);
247
248/**
249 * Poll the timer heap, check for expired timers and call the callback for
250 * each of the expired timers.
251 *
252 * @param ht The timer heap.
253 * @param next_delay If this parameter is not NULL, it will be filled up with
254 * the time delay until the next timer elapsed, or -1 in
255 * the sec part if no entry exist.
256 *
257 * @return The number of timers expired.
258 */
259PJ_DECL(unsigned) pj_timer_heap_poll( pj_timer_heap_t *ht,
260 pj_time_val *next_delay);
261
262/**
263 * @}
264 */
265
266PJ_END_DECL
267
268#endif /* __PJ_TIMER_H__ */
269