appCORE - coreTimerStart()

NAME

coreTimerStart() -- start a timer.

SYNOPSIS

include "appcore.h"

corehTIMER_t coreTimerStart( unsigned int d,
                             unsigned int (*Expire)( unsigned int a ),
                             unsigned int a )

DESCRIPTION

The coreTimerStart() function starts an appCORE Timer and returns a handle to the timer. The timer delay is specified in milliseconds. Once started, a timer either expires, or is cancelled, by calling the function coreTimerCancel() with the timer handle. On timer expiration, the supplied handler routine is called by appCORE in the same thread that started the timer. It is important to remember the timer expiration routine is always executed by the thread that requested the timer. appCORE timers utilize the Thread Specific Callback (TSC) design pattern.

appCORE timers are thread specific, and of course, message based. The start function creates a timer object and forwards this object to the appCORE timer services thread. The timer services thread maintains an ordered list of timers, sorted by expiration time. When a timer expires, if it has not been canceled, the timer object is sent to the originating thread. When this timer expiration message is processed, the timer handler function is called in the context of the originating thread. If a timer is canceled, the handle is invalid, and further access is undefined.

Importantly, there is no timer cancel race condition in appCORE providing only the originating thread cancels the timer. It would be bad practice to cancel a timer from a thread other then the originating thread. This is keeping with the primary appCORE design pattern, that threads do not access data in other threads. Each timer object carries with it state and a lock. Since the timer expires in the context of the originating thread, the originating thread may cancel the timer at any time - even when the timer is already in the thread's input queue.

The number of available timers is limited only by available memory. After timer expiration, or cancellation, timer resources are reclaimed by automatically.

PARAMETERS

d
	The delay, in milliseconds, until the timer expires.
Expire
	The function that is called when the timer expires. The function is called 
	on the thread that originated the timer. If the timer is canceled, the
	function is not called.
a
	This argument is passed to the expiration handler.

RETURN VALUE

If successful, coreTimerStart() returns a handle to the timer. The handle may be used to cancel the timer at any time before expiration. On failure the functions returns the invalid handle value, CORE_INVALID_HANDLE.

errno Value	Condition
ENOTSUP	The timer feature is disabled.
EINVAL	A delay value of 0 is not permitted.
	A null expiration handler is not allowed.
ENOMEM	Unable to allocate memory for message.

MULTI-THREAD SAFETY LEVEL

MT-safe.