Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib / include / pj / timer.h
1 /* $Id$ */
2 /* 
3  * 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
28 PJ_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.
48  *
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  *
54  * @{
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  */
67 typedef int pj_timer_id_t;
68
69 /** 
70  * Forward declaration for pj_timer_entry. 
71  */
72 struct 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  */
81 typedef 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  */
88 struct 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  */
129 PJ_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  */
146 PJ_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  */
155 PJ_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  */
167 PJ_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  */
179 PJ_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  */
198 PJ_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  */
211 PJ_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  */
224 PJ_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  */
233 PJ_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  */
245 PJ_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  * Note: polling the timer heap is not necessary in Symbian. Please see
253  * @ref PJ_SYMBIAN_OS for more info.
254  *
255  * @param ht         The timer heap.
256  * @param next_delay If this parameter is not NULL, it will be filled up with
257  *                   the time delay until the next timer elapsed, or 
258  *                   PJ_MAXINT32 in the sec part if no entry exist.
259  *
260  * @return           The number of timers expired.
261  */
262 PJ_DECL(unsigned) pj_timer_heap_poll( pj_timer_heap_t *ht, 
263                                       pj_time_val *next_delay);
264
265 /**
266  * @}
267  */
268
269 PJ_END_DECL
270
271 #endif  /* __PJ_TIMER_H__ */
272