#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:

Functions
stk_timer_set_t *	stk_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_t *	stk_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_t *	stk_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

Parameters

timer_set	The timer set to be used
timer	The timer to be cancelled

Returns: 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

Returns: 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

Parameters

timer_set	The timer set to be dispatched
max_callbacks	The maximum number of callbacks to be executed (0 indicates any and all timers due, but is not recommended)

Returns: 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

Parameters

timer_set The timer set from which the STK environ,ent is desired

Returns: 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.

Parameters

timer_set	The timer set to be freed
cancel_timers	Indicates if timers left in the set should be cancelled

Returns: Whether the set was successfully freed

See Also: stk_new_timer_set()

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!

Parameters

env	The environment which this timer set should be a part of
user_setdata	A user pointer passed to each call back for this set
max_timers	The maximum number of timers this set shall contain
add_to_pool	Indicates if the timer should be added to the environment timer pools

Returns: 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

Parameters

timer_set The timer set being queried

Returns: 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)

Parameters

timer_set	The timer set to be used
timer	The timer (as returned by stk_schedule_timer() originally)

Returns: Whether the timer was successfully rescheduled

See Also: stk_schedule_timer()

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

Parameters

timer_set	The timer set to be used
cb	The callback to be called when the timer has expired or cancelled
id	A 64 bit unsigned user ID for this timer
userdata	Applicstion data to be passed to callbacks when this timer expires
ms	The number of milliseconds before the callback should bencalled

Returns: 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

Functions

Detailed Description

Function Documentation