Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 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. |
Benny Prijono | 411b2be | 2006-08-10 08:45:17 +0000 | [diff] [blame] | 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 | * |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 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 | */ |
Benny Prijono | b2c9682 | 2007-05-03 13:31:21 +0000 | [diff] [blame] | 67 | #if defined(PJ_SYMBIAN) && PJ_SYMBIAN!=0 |
| 68 | typedef void *pj_timer_id_t; |
| 69 | #else |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 70 | typedef int pj_timer_id_t; |
Benny Prijono | b2c9682 | 2007-05-03 13:31:21 +0000 | [diff] [blame] | 71 | #endif |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 72 | |
| 73 | /** |
| 74 | * Forward declaration for pj_timer_entry. |
| 75 | */ |
| 76 | struct pj_timer_entry; |
| 77 | |
| 78 | /** |
| 79 | * The type of callback function to be called by timer scheduler when a timer |
| 80 | * has expired. |
| 81 | * |
| 82 | * @param timer_heap The timer heap. |
| 83 | * @param entry Timer entry which timer's has expired. |
| 84 | */ |
| 85 | typedef void pj_timer_heap_callback(pj_timer_heap_t *timer_heap, |
| 86 | struct pj_timer_entry *entry); |
| 87 | |
| 88 | |
| 89 | /** |
| 90 | * This structure represents an entry to the timer. |
| 91 | */ |
| 92 | struct pj_timer_entry |
| 93 | { |
| 94 | /** |
| 95 | * User data to be associated with this entry. |
| 96 | * Applications normally will put the instance of object that |
| 97 | * owns the timer entry in this field. |
| 98 | */ |
| 99 | void *user_data; |
| 100 | |
| 101 | /** |
| 102 | * Arbitrary ID assigned by the user/owner of this entry. |
| 103 | * Applications can use this ID to distinguish multiple |
| 104 | * timer entries that share the same callback and user_data. |
| 105 | */ |
| 106 | int id; |
| 107 | |
| 108 | /** |
| 109 | * Callback to be called when the timer expires. |
| 110 | */ |
| 111 | pj_timer_heap_callback *cb; |
| 112 | |
| 113 | /** |
| 114 | * Internal unique timer ID, which is assigned by the timer heap. |
| 115 | * Application should not touch this ID. |
| 116 | */ |
| 117 | pj_timer_id_t _timer_id; |
| 118 | |
| 119 | /** |
| 120 | * The future time when the timer expires, which the value is updated |
| 121 | * by timer heap when the timer is scheduled. |
| 122 | */ |
| 123 | pj_time_val _timer_value; |
| 124 | }; |
| 125 | |
| 126 | |
| 127 | /** |
| 128 | * Calculate memory size required to create a timer heap. |
| 129 | * |
| 130 | * @param count Number of timer entries to be supported. |
| 131 | * @return Memory size requirement in bytes. |
| 132 | */ |
| 133 | PJ_DECL(pj_size_t) pj_timer_heap_mem_size(pj_size_t count); |
| 134 | |
| 135 | /** |
| 136 | * Create a timer heap. |
| 137 | * |
| 138 | * @param pool The pool where allocations in the timer heap will be |
| 139 | * allocated. The timer heap will dynamicly allocate |
| 140 | * more storate from the pool if the number of timer |
| 141 | * entries registered is more than the size originally |
| 142 | * requested when calling this function. |
| 143 | * @param count The maximum number of timer entries to be supported |
| 144 | * initially. If the application registers more entries |
| 145 | * during runtime, then the timer heap will resize. |
| 146 | * @param ht Pointer to receive the created timer heap. |
| 147 | * |
| 148 | * @return PJ_SUCCESS, or the appropriate error code. |
| 149 | */ |
| 150 | PJ_DECL(pj_status_t) pj_timer_heap_create( pj_pool_t *pool, |
| 151 | pj_size_t count, |
| 152 | pj_timer_heap_t **ht); |
| 153 | |
| 154 | /** |
| 155 | * Destroy the timer heap. |
| 156 | * |
| 157 | * @param ht The timer heap. |
| 158 | */ |
| 159 | PJ_DECL(void) pj_timer_heap_destroy( pj_timer_heap_t *ht ); |
| 160 | |
| 161 | |
| 162 | /** |
| 163 | * Set lock object to be used by the timer heap. By default, the timer heap |
| 164 | * uses dummy synchronization. |
| 165 | * |
| 166 | * @param ht The timer heap. |
| 167 | * @param lock The lock object to be used for synchronization. |
| 168 | * @param auto_del If nonzero, the lock object will be destroyed when |
| 169 | * the timer heap is destroyed. |
| 170 | */ |
| 171 | PJ_DECL(void) pj_timer_heap_set_lock( pj_timer_heap_t *ht, |
| 172 | pj_lock_t *lock, |
| 173 | pj_bool_t auto_del ); |
| 174 | |
| 175 | /** |
| 176 | * Set maximum number of timed out entries to process in a single poll. |
| 177 | * |
| 178 | * @param ht The timer heap. |
| 179 | * @param count Number of entries. |
| 180 | * |
| 181 | * @return The old number. |
| 182 | */ |
| 183 | PJ_DECL(unsigned) pj_timer_heap_set_max_timed_out_per_poll(pj_timer_heap_t *ht, |
| 184 | unsigned count ); |
| 185 | |
| 186 | /** |
| 187 | * Initialize a timer entry. Application should call this function at least |
| 188 | * once before scheduling the entry to the timer heap, to properly initialize |
| 189 | * the timer entry. |
| 190 | * |
| 191 | * @param entry The timer entry to be initialized. |
| 192 | * @param id Arbitrary ID assigned by the user/owner of this entry. |
| 193 | * Applications can use this ID to distinguish multiple |
| 194 | * timer entries that share the same callback and user_data. |
| 195 | * @param user_data User data to be associated with this entry. |
| 196 | * Applications normally will put the instance of object that |
| 197 | * owns the timer entry in this field. |
| 198 | * @param cb Callback function to be called when the timer elapses. |
| 199 | * |
| 200 | * @return The timer entry itself. |
| 201 | */ |
| 202 | PJ_DECL(pj_timer_entry*) pj_timer_entry_init( pj_timer_entry *entry, |
| 203 | int id, |
| 204 | void *user_data, |
| 205 | pj_timer_heap_callback *cb ); |
| 206 | |
| 207 | /** |
| 208 | * Schedule a timer entry which will expire AFTER the specified delay. |
| 209 | * |
| 210 | * @param ht The timer heap. |
| 211 | * @param entry The entry to be registered. |
| 212 | * @param delay The interval to expire. |
| 213 | * @return PJ_SUCCESS, or the appropriate error code. |
| 214 | */ |
| 215 | PJ_DECL(pj_status_t) pj_timer_heap_schedule( pj_timer_heap_t *ht, |
| 216 | pj_timer_entry *entry, |
| 217 | const pj_time_val *delay); |
| 218 | |
| 219 | /** |
| 220 | * Cancel a previously registered timer. |
| 221 | * |
| 222 | * @param ht The timer heap. |
| 223 | * @param entry The entry to be cancelled. |
| 224 | * @return The number of timer cancelled, which should be one if the |
| 225 | * entry has really been registered, or zero if no timer was |
| 226 | * cancelled. |
| 227 | */ |
| 228 | PJ_DECL(int) pj_timer_heap_cancel( pj_timer_heap_t *ht, |
| 229 | pj_timer_entry *entry); |
| 230 | |
| 231 | /** |
| 232 | * Get the number of timer entries. |
| 233 | * |
| 234 | * @param ht The timer heap. |
| 235 | * @return The number of timer entries. |
| 236 | */ |
| 237 | PJ_DECL(pj_size_t) pj_timer_heap_count( pj_timer_heap_t *ht ); |
| 238 | |
| 239 | /** |
| 240 | * Get the earliest time registered in the timer heap. The timer heap |
| 241 | * MUST have at least one timer being scheduled (application should use |
| 242 | * #pj_timer_heap_count() before calling this function). |
| 243 | * |
| 244 | * @param ht The timer heap. |
| 245 | * @param timeval The time deadline of the earliest timer entry. |
| 246 | * |
| 247 | * @return PJ_SUCCESS, or PJ_ENOTFOUND if no entry is scheduled. |
| 248 | */ |
| 249 | PJ_DECL(pj_status_t) pj_timer_heap_earliest_time( pj_timer_heap_t *ht, |
| 250 | pj_time_val *timeval); |
| 251 | |
| 252 | /** |
| 253 | * Poll the timer heap, check for expired timers and call the callback for |
| 254 | * each of the expired timers. |
| 255 | * |
Benny Prijono | 8ab968f | 2007-07-20 08:08:30 +0000 | [diff] [blame] | 256 | * Note: polling the timer heap is not necessary in Symbian. Please see |
| 257 | * @ref PJ_SYMBIAN_OS for more info. |
| 258 | * |
Benny Prijono | 9033e31 | 2005-11-21 02:08:39 +0000 | [diff] [blame] | 259 | * @param ht The timer heap. |
| 260 | * @param next_delay If this parameter is not NULL, it will be filled up with |
| 261 | * the time delay until the next timer elapsed, or -1 in |
| 262 | * the sec part if no entry exist. |
| 263 | * |
| 264 | * @return The number of timers expired. |
| 265 | */ |
| 266 | PJ_DECL(unsigned) pj_timer_heap_poll( pj_timer_heap_t *ht, |
| 267 | pj_time_val *next_delay); |
| 268 | |
| 269 | /** |
| 270 | * @} |
| 271 | */ |
| 272 | |
| 273 | PJ_END_DECL |
| 274 | |
| 275 | #endif /* __PJ_TIMER_H__ */ |
| 276 | |