The Sequence Toolkit
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros
stk_timer_api.h File Reference
#include "stk_timer.h"
#include "stk_env.h"
#include "stk_common.h"
Include dependency graph for stk_timer_api.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


stk_timer_set_tstk_new_timer_set (stk_env_t *env, void *user_setdata, stk_uint32 max_timers, stk_bool add_to_pool)
stk_ret stk_free_timer_set (stk_timer_set_t *timer_set, stk_bool cancel_timers)
stk_timer_tstk_schedule_timer (stk_timer_set_t *timer_set, stk_timer_cb cb, stk_uint64 id, void *userdata, long ms)
stk_ret stk_reschedule_timer (stk_timer_set_t *timer_set, stk_timer_t *timer)
stk_ret stk_cancel_timer (stk_timer_set_t *timer_set, stk_timer_t *timer)
stk_ret stk_cancel_timer_id (stk_timer_set_t *timer_set, stk_uint64 id)
stk_ret stk_dispatch_timers (stk_timer_set_t *timer_set, unsigned short max_callbacks)
int stk_next_timer_ms (stk_timer_set_t *timer_set)
stk_env_tstk_env_from_timer_set (stk_timer_set_t *timer_set)

Detailed Description

This file contains the implementation of a timer management subsystem. It is based on a linked list whic could be improved performance wise but allow multiple timer sets that can be used to offset the overhead in insertions by reducing the number of timers per set.

This timer API is not thread safe at this time

Function Documentation

stk_ret stk_cancel_timer ( stk_timer_set_t timer_set,
stk_timer_t timer 

Cancel a timer using the pointer returned when scheduling the timer

The timer callback will be called with STK_TIMER_CANCELLED as the cb_type

timer_setThe timer set to be used
timerThe timer to be cancelled
Whether the timer was successfully cancelled
See Also
stk_schedule_timer() stk_timer_cb_type
stk_ret stk_cancel_timer_id ( stk_timer_set_t timer_set,
stk_uint64  id 

Cancel a timer based on ID.

Only the first instance of a timer with the ID will be cancelled. If ID's are reused

Whether the timer was successfully cancelled or STK_NOT_FOUND
See Also
stk_schedule_timer() stk_timer_cb_type STK_NOT_FOUND
stk_ret stk_dispatch_timers ( stk_timer_set_t timer_set,
unsigned short  max_callbacks 

Dispatch the timers that have expired

timer_setThe timer set to be dispatched
max_callbacksThe maximum number of callbacks to be executed (0 indicates any and all timers due, but is not recommended)
Whether dispatching timers succeeded
STK_SUCCESS if all timers due were expired
STK_MAX_TIMERS if max_callbacks is met
stk_env_t* stk_env_from_timer_set ( stk_timer_set_t timer_set)

Get the STK Environment from a timer set

timer_setThe timer set from which the STK environ,ent is desired
The environment which a timer set is associated with.
stk_ret stk_free_timer_set ( stk_timer_set_t timer_set,
stk_bool  cancel_timers 

Free a timer set.

If you have data allocated per timer, use the expire_timers to force expiration so you can free the memory.

timer_setThe timer set to be freed
cancel_timersIndicates if timers left in the set should be cancelled
Whether the set was successfully freed
See Also
stk_timer_set_t* stk_new_timer_set ( stk_env_t env,
void *  user_setdata,
stk_uint32  max_timers,
stk_bool  add_to_pool 

Allocate a new timer set.

The max_timers influences the means by which timers are managed for optimal runtime performance. A value of 0 is valid and indicates the timer set should be managed entirely dynamically, but of course, this is a little slower but much more flexible. Time vs space vs complexity!

envThe environment which this timer set should be a part of
user_setdataA user pointer passed to each call back for this set
max_timersThe maximum number of timers this set shall contain
add_to_poolIndicates if the timer should be added to the environment timer pools
A handle to the allocated timer set
See Also
stk_free_timer_set() stk_env_dispatch_timer_pools()
int stk_next_timer_ms ( stk_timer_set_t timer_set)

Returns the number of milliseconds to the next timer expiration - useful for passing to poll() etc

timer_setThe timer set being queried
milliseconds until next timer expiration (or -1 if there is no timer)
stk_ret stk_reschedule_timer ( stk_timer_set_t timer_set,
stk_timer_t timer 

Reschedule a previously scheduled timer (same ID, interval etc)

timer_setThe timer set to be used
timerThe timer (as returned by stk_schedule_timer() originally)
Whether the timer was successfully rescheduled
See Also
stk_timer_t* stk_schedule_timer ( stk_timer_set_t timer_set,
stk_timer_cb  cb,
stk_uint64  id,
void *  userdata,
long  ms 

Schedule a timer callback for ms milliseconds from now.

The timer callback will be called with STK_TIMER_EXPIRED as the cb_type

IDs may be reused in the set

timer_setThe timer set to be used
cbThe callback to be called when the timer has expired or cancelled
idA 64 bit unsigned user ID for this timer
userdataApplicstion data to be passed to callbacks when this timer expires
msThe number of milliseconds before the callback should bencalled
A timer pointer that may be used to efficiently cancel the timer
See Also
stk_cancel_timer() stk_cancel_timer_id() stk_reschedule_timer() stk_timer_cb_type