Alexandre Lision | 8af73cb | 2013-12-10 14:11:20 -0500 | [diff] [blame] | 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 | #include <pj/lock.h> |
| 28 | |
| 29 | PJ_BEGIN_DECL |
| 30 | |
| 31 | /** |
| 32 | * @defgroup PJ_TIMER Timer Heap Management. |
| 33 | * @ingroup PJ_MISC |
| 34 | * @brief |
| 35 | * The timer scheduling implementation here is based on ACE library's |
| 36 | * ACE_Timer_Heap, with only little modification to suit our library's style |
| 37 | * (I even left most of the comments in the original source). |
| 38 | * |
| 39 | * To quote the original quote in ACE_Timer_Heap_T class: |
| 40 | * |
| 41 | * This implementation uses a heap-based callout queue of |
| 42 | * absolute times. Therefore, in the average and worst case, |
| 43 | * scheduling, canceling, and expiring timers is O(log N) (where |
| 44 | * N is the total number of timers). In addition, we can also |
| 45 | * preallocate as many \a ACE_Timer_Nodes as there are slots in |
| 46 | * the heap. This allows us to completely remove the need for |
| 47 | * dynamic memory allocation, which is important for real-time |
| 48 | * systems. |
| 49 | * |
| 50 | * You can find the fine ACE library at: |
| 51 | * http://www.cs.wustl.edu/~schmidt/ACE.html |
| 52 | * |
| 53 | * ACE is Copyright (C)1993-2006 Douglas C. Schmidt <d.schmidt@vanderbilt.edu> |
| 54 | * |
| 55 | * @{ |
| 56 | * |
| 57 | * \section pj_timer_examples_sec Examples |
| 58 | * |
| 59 | * For some examples on how to use the timer heap, please see the link below. |
| 60 | * |
| 61 | * - \ref page_pjlib_timer_test |
| 62 | */ |
| 63 | |
| 64 | |
| 65 | /** |
| 66 | * The type for internal timer ID. |
| 67 | */ |
| 68 | typedef int pj_timer_id_t; |
| 69 | |
| 70 | /** |
| 71 | * Forward declaration for pj_timer_entry. |
| 72 | */ |
| 73 | struct pj_timer_entry; |
| 74 | |
| 75 | /** |
| 76 | * The type of callback function to be called by timer scheduler when a timer |
| 77 | * has expired. |
| 78 | * |
| 79 | * @param timer_heap The timer heap. |
| 80 | * @param entry Timer entry which timer's has expired. |
| 81 | */ |
| 82 | typedef void pj_timer_heap_callback(pj_timer_heap_t *timer_heap, |
| 83 | struct pj_timer_entry *entry); |
| 84 | |
| 85 | |
| 86 | /** |
| 87 | * This structure represents an entry to the timer. |
| 88 | */ |
| 89 | typedef struct pj_timer_entry |
| 90 | { |
| 91 | /** |
| 92 | * User data to be associated with this entry. |
| 93 | * Applications normally will put the instance of object that |
| 94 | * owns the timer entry in this field. |
| 95 | */ |
| 96 | void *user_data; |
| 97 | |
| 98 | /** |
| 99 | * Arbitrary ID assigned by the user/owner of this entry. |
| 100 | * Applications can use this ID to distinguish multiple |
| 101 | * timer entries that share the same callback and user_data. |
| 102 | */ |
| 103 | int id; |
| 104 | |
| 105 | /** |
| 106 | * Callback to be called when the timer expires. |
| 107 | */ |
| 108 | pj_timer_heap_callback *cb; |
| 109 | |
| 110 | /** |
| 111 | * Internal unique timer ID, which is assigned by the timer heap. |
| 112 | * Application should not touch this ID. |
| 113 | */ |
| 114 | pj_timer_id_t _timer_id; |
| 115 | |
| 116 | /** |
| 117 | * The future time when the timer expires, which the value is updated |
| 118 | * by timer heap when the timer is scheduled. |
| 119 | */ |
| 120 | pj_time_val _timer_value; |
| 121 | |
| 122 | /** |
| 123 | * Internal: the group lock used by this entry, set when |
| 124 | * pj_timer_heap_schedule_w_lock() is used. |
| 125 | */ |
| 126 | pj_grp_lock_t *_grp_lock; |
| 127 | |
| 128 | #if PJ_TIMER_DEBUG |
| 129 | const char *src_file; |
| 130 | int src_line; |
| 131 | #endif |
| 132 | } pj_timer_entry; |
| 133 | |
| 134 | |
| 135 | /** |
| 136 | * Calculate memory size required to create a timer heap. |
| 137 | * |
| 138 | * @param count Number of timer entries to be supported. |
| 139 | * @return Memory size requirement in bytes. |
| 140 | */ |
| 141 | PJ_DECL(pj_size_t) pj_timer_heap_mem_size(pj_size_t count); |
| 142 | |
| 143 | /** |
| 144 | * Create a timer heap. |
| 145 | * |
| 146 | * @param pool The pool where allocations in the timer heap will be |
| 147 | * allocated. The timer heap will dynamicly allocate |
| 148 | * more storate from the pool if the number of timer |
| 149 | * entries registered is more than the size originally |
| 150 | * requested when calling this function. |
| 151 | * @param count The maximum number of timer entries to be supported |
| 152 | * initially. If the application registers more entries |
| 153 | * during runtime, then the timer heap will resize. |
| 154 | * @param ht Pointer to receive the created timer heap. |
| 155 | * |
| 156 | * @return PJ_SUCCESS, or the appropriate error code. |
| 157 | */ |
| 158 | PJ_DECL(pj_status_t) pj_timer_heap_create( pj_pool_t *pool, |
| 159 | pj_size_t count, |
| 160 | pj_timer_heap_t **ht); |
| 161 | |
| 162 | /** |
| 163 | * Destroy the timer heap. |
| 164 | * |
| 165 | * @param ht The timer heap. |
| 166 | */ |
| 167 | PJ_DECL(void) pj_timer_heap_destroy( pj_timer_heap_t *ht ); |
| 168 | |
| 169 | |
| 170 | /** |
| 171 | * Set lock object to be used by the timer heap. By default, the timer heap |
| 172 | * uses dummy synchronization. |
| 173 | * |
| 174 | * @param ht The timer heap. |
| 175 | * @param lock The lock object to be used for synchronization. |
| 176 | * @param auto_del If nonzero, the lock object will be destroyed when |
| 177 | * the timer heap is destroyed. |
| 178 | */ |
| 179 | PJ_DECL(void) pj_timer_heap_set_lock( pj_timer_heap_t *ht, |
| 180 | pj_lock_t *lock, |
| 181 | pj_bool_t auto_del ); |
| 182 | |
| 183 | /** |
| 184 | * Set maximum number of timed out entries to process in a single poll. |
| 185 | * |
| 186 | * @param ht The timer heap. |
| 187 | * @param count Number of entries. |
| 188 | * |
| 189 | * @return The old number. |
| 190 | */ |
| 191 | PJ_DECL(unsigned) pj_timer_heap_set_max_timed_out_per_poll(pj_timer_heap_t *ht, |
| 192 | unsigned count ); |
| 193 | |
| 194 | /** |
| 195 | * Initialize a timer entry. Application should call this function at least |
| 196 | * once before scheduling the entry to the timer heap, to properly initialize |
| 197 | * the timer entry. |
| 198 | * |
| 199 | * @param entry The timer entry to be initialized. |
| 200 | * @param id Arbitrary ID assigned by the user/owner of this entry. |
| 201 | * Applications can use this ID to distinguish multiple |
| 202 | * timer entries that share the same callback and user_data. |
| 203 | * @param user_data User data to be associated with this entry. |
| 204 | * Applications normally will put the instance of object that |
| 205 | * owns the timer entry in this field. |
| 206 | * @param cb Callback function to be called when the timer elapses. |
| 207 | * |
| 208 | * @return The timer entry itself. |
| 209 | */ |
| 210 | PJ_DECL(pj_timer_entry*) pj_timer_entry_init( pj_timer_entry *entry, |
| 211 | int id, |
| 212 | void *user_data, |
| 213 | pj_timer_heap_callback *cb ); |
| 214 | |
| 215 | /** |
| 216 | * Queries whether a timer entry is currently running. |
| 217 | * |
| 218 | * @param entry The timer entry to query. |
| 219 | * |
| 220 | * @return PJ_TRUE if the timer is running. PJ_FALSE if not. |
| 221 | */ |
| 222 | PJ_DECL(pj_bool_t) pj_timer_entry_running( pj_timer_entry *entry ); |
| 223 | |
| 224 | /** |
| 225 | * Schedule a timer entry which will expire AFTER the specified delay. |
| 226 | * |
| 227 | * @param ht The timer heap. |
| 228 | * @param entry The entry to be registered. |
| 229 | * @param delay The interval to expire. |
| 230 | * @return PJ_SUCCESS, or the appropriate error code. |
| 231 | */ |
| 232 | #if PJ_TIMER_DEBUG |
| 233 | # define pj_timer_heap_schedule(ht,e,d) \ |
| 234 | pj_timer_heap_schedule_dbg(ht,e,d,__FILE__,__LINE__) |
| 235 | |
| 236 | PJ_DECL(pj_status_t) pj_timer_heap_schedule_dbg( pj_timer_heap_t *ht, |
| 237 | pj_timer_entry *entry, |
| 238 | const pj_time_val *delay, |
| 239 | const char *src_file, |
| 240 | int src_line); |
| 241 | #else |
| 242 | PJ_DECL(pj_status_t) pj_timer_heap_schedule( pj_timer_heap_t *ht, |
| 243 | pj_timer_entry *entry, |
| 244 | const pj_time_val *delay); |
| 245 | #endif /* PJ_TIMER_DEBUG */ |
| 246 | |
| 247 | /** |
| 248 | * Schedule a timer entry which will expire AFTER the specified delay, and |
| 249 | * increment the reference counter of the group lock while the timer entry |
| 250 | * is active. The group lock reference counter will automatically be released |
| 251 | * after the timer callback is called or when the timer is cancelled. |
| 252 | * |
| 253 | * @param ht The timer heap. |
| 254 | * @param entry The entry to be registered. |
| 255 | * @param id_val The value to be set to the "id" field of the timer entry |
| 256 | * once the timer is scheduled. |
| 257 | * @param delay The interval to expire. |
| 258 | * @param grp_lock The group lock. |
| 259 | * |
| 260 | * @return PJ_SUCCESS, or the appropriate error code. |
| 261 | */ |
| 262 | #if PJ_TIMER_DEBUG |
| 263 | # define pj_timer_heap_schedule_w_grp_lock(ht,e,d,id,g) \ |
| 264 | pj_timer_heap_schedule_w_grp_lock_dbg(ht,e,d,id,g,__FILE__,__LINE__) |
| 265 | |
| 266 | PJ_DECL(pj_status_t) pj_timer_heap_schedule_w_grp_lock_dbg( |
| 267 | pj_timer_heap_t *ht, |
| 268 | pj_timer_entry *entry, |
| 269 | const pj_time_val *delay, |
| 270 | int id_val, |
| 271 | pj_grp_lock_t *grp_lock, |
| 272 | const char *src_file, |
| 273 | int src_line); |
| 274 | #else |
| 275 | PJ_DECL(pj_status_t) pj_timer_heap_schedule_w_grp_lock( |
| 276 | pj_timer_heap_t *ht, |
| 277 | pj_timer_entry *entry, |
| 278 | const pj_time_val *delay, |
| 279 | int id_val, |
| 280 | pj_grp_lock_t *grp_lock); |
| 281 | #endif /* PJ_TIMER_DEBUG */ |
| 282 | |
| 283 | |
| 284 | /** |
| 285 | * Cancel a previously registered timer. This will also decrement the |
| 286 | * reference counter of the group lock associated with the timer entry, |
| 287 | * if the entry was scheduled with one. |
| 288 | * |
| 289 | * @param ht The timer heap. |
| 290 | * @param entry The entry to be cancelled. |
| 291 | * @return The number of timer cancelled, which should be one if the |
| 292 | * entry has really been registered, or zero if no timer was |
| 293 | * cancelled. |
| 294 | */ |
| 295 | PJ_DECL(int) pj_timer_heap_cancel( pj_timer_heap_t *ht, |
| 296 | pj_timer_entry *entry); |
| 297 | |
| 298 | /** |
| 299 | * Cancel only if the previously registered timer is active. This will |
| 300 | * also decrement the reference counter of the group lock associated |
| 301 | * with the timer entry, if the entry was scheduled with one. In any |
| 302 | * case, set the "id" to the specified value. |
| 303 | * |
| 304 | * @param ht The timer heap. |
| 305 | * @param entry The entry to be cancelled. |
| 306 | * @param id_val Value to be set to "id" |
| 307 | * |
| 308 | * @return The number of timer cancelled, which should be one if the |
| 309 | * entry has really been registered, or zero if no timer was |
| 310 | * cancelled. |
| 311 | */ |
| 312 | PJ_DECL(int) pj_timer_heap_cancel_if_active(pj_timer_heap_t *ht, |
| 313 | pj_timer_entry *entry, |
| 314 | int id_val); |
| 315 | |
| 316 | /** |
| 317 | * Get the number of timer entries. |
| 318 | * |
| 319 | * @param ht The timer heap. |
| 320 | * @return The number of timer entries. |
| 321 | */ |
| 322 | PJ_DECL(pj_size_t) pj_timer_heap_count( pj_timer_heap_t *ht ); |
| 323 | |
| 324 | /** |
| 325 | * Get the earliest time registered in the timer heap. The timer heap |
| 326 | * MUST have at least one timer being scheduled (application should use |
| 327 | * #pj_timer_heap_count() before calling this function). |
| 328 | * |
| 329 | * @param ht The timer heap. |
| 330 | * @param timeval The time deadline of the earliest timer entry. |
| 331 | * |
| 332 | * @return PJ_SUCCESS, or PJ_ENOTFOUND if no entry is scheduled. |
| 333 | */ |
| 334 | PJ_DECL(pj_status_t) pj_timer_heap_earliest_time( pj_timer_heap_t *ht, |
| 335 | pj_time_val *timeval); |
| 336 | |
| 337 | /** |
| 338 | * Poll the timer heap, check for expired timers and call the callback for |
| 339 | * each of the expired timers. |
| 340 | * |
| 341 | * Note: polling the timer heap is not necessary in Symbian. Please see |
| 342 | * @ref PJ_SYMBIAN_OS for more info. |
| 343 | * |
| 344 | * @param ht The timer heap. |
| 345 | * @param next_delay If this parameter is not NULL, it will be filled up with |
| 346 | * the time delay until the next timer elapsed, or |
| 347 | * PJ_MAXINT32 in the sec part if no entry exist. |
| 348 | * |
| 349 | * @return The number of timers expired. |
| 350 | */ |
| 351 | PJ_DECL(unsigned) pj_timer_heap_poll( pj_timer_heap_t *ht, |
| 352 | pj_time_val *next_delay); |
| 353 | |
| 354 | #if PJ_TIMER_DEBUG |
| 355 | /** |
| 356 | * Dump timer heap entries. |
| 357 | * |
| 358 | * @param ht The timer heap. |
| 359 | */ |
| 360 | PJ_DECL(void) pj_timer_heap_dump(pj_timer_heap_t *ht); |
| 361 | #endif |
| 362 | |
| 363 | /** |
| 364 | * @} |
| 365 | */ |
| 366 | |
| 367 | PJ_END_DECL |
| 368 | |
| 369 | #endif /* __PJ_TIMER_H__ */ |
| 370 | |