Home --> Documentations --> PJLIB Reference

Data Structures | Typedefs | Functions
Timer Heap Management.

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). More...

Data Structures

struct  pj_timer_entry
 

Typedefs

typedef int pj_timer_id_t
 
typedef void pj_timer_heap_callback (pj_timer_heap_t *timer_heap, struct pj_timer_entry *entry)
 

Functions

pj_size_t pj_timer_heap_mem_size (pj_size_t count)
 
pj_status_t pj_timer_heap_create (pj_pool_t *pool, pj_size_t count, pj_timer_heap_t **ht)
 
void pj_timer_heap_destroy (pj_timer_heap_t *ht)
 
void pj_timer_heap_set_lock (pj_timer_heap_t *ht, pj_lock_t *lock, pj_bool_t auto_del)
 
unsigned pj_timer_heap_set_max_timed_out_per_poll (pj_timer_heap_t *ht, unsigned count)
 
pj_timer_entrypj_timer_entry_init (pj_timer_entry *entry, int id, void *user_data, pj_timer_heap_callback *cb)
 
pj_bool_t pj_timer_entry_running (pj_timer_entry *entry)
 
pj_status_t pj_timer_heap_schedule (pj_timer_heap_t *ht, pj_timer_entry *entry, const pj_time_val *delay)
 
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)
 
int pj_timer_heap_cancel (pj_timer_heap_t *ht, pj_timer_entry *entry)
 
int pj_timer_heap_cancel_if_active (pj_timer_heap_t *ht, pj_timer_entry *entry, int id_val)
 
pj_size_t pj_timer_heap_count (pj_timer_heap_t *ht)
 
pj_status_t pj_timer_heap_earliest_time (pj_timer_heap_t *ht, pj_time_val *timeval)
 
unsigned pj_timer_heap_poll (pj_timer_heap_t *ht, pj_time_val *next_delay)
 

Detailed Description

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.sch.nosp@m.midt.nosp@m.@vand.nosp@m.erbi.nosp@m.lt.ed.nosp@m.u

Examples

For some examples on how to use the timer heap, please see the link below.

Typedef Documentation

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_heapThe timer heap.
entryTimer entry which timer's has expired.
typedef int pj_timer_id_t

The type for internal timer ID.

Function Documentation

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
entryThe timer entry to be initialized.
idArbitrary 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_dataUser data to be associated with this entry. Applications normally will put the instance of object that owns the timer entry in this field.
cbCallback function to be called when the timer elapses.
Returns
The timer entry itself.
pj_bool_t pj_timer_entry_running ( pj_timer_entry entry)

Queries whether a timer entry is currently running.

Parameters
entryThe timer entry to query.
Returns
PJ_TRUE if the timer is running. PJ_FALSE if not.
int pj_timer_heap_cancel ( pj_timer_heap_t ht,
pj_timer_entry entry 
)

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.

Parameters
htThe timer heap.
entryThe 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.
int pj_timer_heap_cancel_if_active ( pj_timer_heap_t ht,
pj_timer_entry entry,
int  id_val 
)

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.

Parameters
htThe timer heap.
entryThe entry to be cancelled.
id_valValue to be set to "id"
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
htThe timer heap.
Returns
The number of timer entries.
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
poolThe 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.
countThe maximum number of timer entries to be supported initially. If the application registers more entries during runtime, then the timer heap will resize.
htPointer 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
htThe timer heap.
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
htThe timer heap.
timevalThe time deadline of the earliest timer entry.
Returns
PJ_SUCCESS, or PJ_ENOTFOUND if no entry is scheduled.
pj_size_t pj_timer_heap_mem_size ( pj_size_t  count)

Calculate memory size required to create a timer heap.

Parameters
countNumber of timer entries to be supported.
Returns
Memory size requirement in bytes.
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
htThe timer heap.
next_delayIf 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.
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
htThe timer heap.
entryThe entry to be registered.
delayThe interval to expire.
Returns
PJ_SUCCESS, or the appropriate error code.
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 
)

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.

Parameters
htThe timer heap.
entryThe entry to be registered.
id_valThe value to be set to the "id" field of the timer entry once the timer is scheduled.
delayThe interval to expire.
grp_lockThe group lock.
Returns
PJ_SUCCESS, or the appropriate error code.
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
htThe timer heap.
lockThe lock object to be used for synchronization.
auto_delIf 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
htThe timer heap.
countNumber of entries.
Returns
The old number.

 


PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.