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