Group PJ_TIMER¶
-
group
PJ_TIMER
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
Typedefs
-
typedef int
pj_timer_id_t
¶ The type for internal timer ID.
-
typedef void
pj_timer_heap_callback
(pj_timer_heap_t *timer_heap, struct pj_timer_entry *entry)¶ The type of callback function to be called by timer scheduler when a timer has expired.
- Parameters
timer_heap – The timer heap.
entry – Timer entry which timer’s has expired.
Functions
-
pj_size_t
pj_timer_heap_mem_size
(pj_size_t count)¶ Calculate memory size required to create a timer heap.
- Parameters
count – Number of timer entries to be supported.
- Returns
Memory size requirement in bytes.
-
pj_status_t
pj_timer_heap_create
(pj_pool_t *pool, pj_size_t count, pj_timer_heap_t **ht)¶ Create a timer heap.
- Parameters
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.
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.
ht – Pointer to receive the created timer heap.
- Returns
PJ_SUCCESS, or the appropriate error code.
-
void
pj_timer_heap_destroy
(pj_timer_heap_t *ht)¶ Destroy the timer heap.
- Parameters
ht – The timer heap.
-
void
pj_timer_heap_set_lock
(pj_timer_heap_t *ht, pj_lock_t *lock, pj_bool_t auto_del)¶ Set lock object to be used by the timer heap. By default, the timer heap uses dummy synchronization.
- Parameters
ht – The timer heap.
lock – The lock object to be used for synchronization.
auto_del – If nonzero, the lock object will be destroyed when the timer heap is destroyed.
-
unsigned
pj_timer_heap_set_max_timed_out_per_poll
(pj_timer_heap_t *ht, unsigned count)¶ Set maximum number of timed out entries to process in a single poll.
- Parameters
ht – The timer heap.
count – Number of entries.
- Returns
The old number.
-
pj_timer_entry *
pj_timer_entry_init
(pj_timer_entry *entry, int id, void *user_data, pj_timer_heap_callback *cb)¶ 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.
- Parameters
entry – The timer entry to be initialized.
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.
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.
cb – Callback function to be called when the timer elapses.
- Returns
The timer entry itself.
-
pj_status_t
pj_timer_heap_schedule
(pj_timer_heap_t *ht, pj_timer_entry *entry, const pj_time_val *delay)¶ Schedule a timer entry which will expire AFTER the specified delay.
- Parameters
ht – The timer heap.
entry – The entry to be registered.
delay – The interval to expire.
- Returns
PJ_SUCCESS, or the appropriate error code.
-
int
pj_timer_heap_cancel
(pj_timer_heap_t *ht, pj_timer_entry *entry)¶ Cancel a previously registered timer.
- Parameters
ht – The timer heap.
entry – The entry to be cancelled.
- Returns
The number of timer cancelled, which should be one if the entry has really been registered, or zero if no timer was cancelled.
-
pj_size_t
pj_timer_heap_count
(pj_timer_heap_t *ht)¶ Get the number of timer entries.
- Parameters
ht – The timer heap.
- Returns
The number of timer entries.
-
pj_status_t
pj_timer_heap_earliest_time
(pj_timer_heap_t *ht, pj_time_val *timeval)¶ 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).
- Parameters
ht – The timer heap.
timeval – The time deadline of the earliest timer entry.
- Returns
PJ_SUCCESS, or PJ_ENOTFOUND if no entry is scheduled.
-
unsigned
pj_timer_heap_poll
(pj_timer_heap_t *ht, pj_time_val *next_delay)¶ 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 Symbian OS Specific for more info.
- Parameters
ht – The timer heap.
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.
- Returns
The number of timers expired.
-
struct
pj_timer_entry
¶ - #include <timer.h>
This structure represents an entry to the timer.
Forward declaration for timer entry.
-
typedef int