BaTimer Struct Reference

Detailed Description

Timer manager used for one-shot and periodic callbacks.

BaTimer runs its own worker thread. Timer callbacks are therefore not executed in the HTTP request thread that created the timer.

#include <BaTimer.h>

Inheritance diagram for BaTimer:

Public Member Functions
	BaTimer (ThreadMutex *mutex, int stackSize, U32 ticklen=10, ThreadPriority priority=ThreadPrioNormal, AllocatorIntf *alloc=0)
	Create a BaTimer object and its worker thread. More...
	~BaTimer ()
	Stop the worker and discard outstanding timer events without calling their callbacks. More...
size_t	set (BaTimer_CB cb, void *data, U32 milliSec)
	Create a timer event. More...
int	reset (size_t tkey, U32 milliSec)
	Resets the timer. More...
int	cancel (size_t tkey)
	Cancels the timer. More...
Public Member Functions inherited from Thread
	Thread ()
	Uninitialized storage; call Thread_constructor before use/destruction. More...
	Thread (Thread_Run r, ThreadPriority priority, int stackSize)
	Create a thread. More...
	~Thread ()
	Release platform thread resources (C: Thread_destructor). More...
void	start ()
	Release the constructed thread to run its entry point once (C: Thread_start). More...

Additional Inherited Members
Static Public Member Functions inherited from Thread
static void	sleep (unsigned int milliseconds)
	Delay the calling thread (C: Thread_sleep). More...

Constructor & Destructor Documentation

BaTimer()

BaTimer::BaTimer	(	ThreadMutex *	mutex,
		int	stackSize,
		U32	ticklen = 10,
		ThreadPriority	priority = ThreadPrioNormal,
		AllocatorIntf *	alloc = 0
	)

Create a BaTimer object and its worker thread.

Parameters

mutex	Required initialized mutex shared with the dispatcher. It is borrowed and must outlive the timer manager.
stackSize	Worker thread stack size in bytes.
ticklen	Positive timer tick interval in milliseconds; default 10 in C++. Delays are quantized to this tick and worker scheduling, so this is not an exact-deadline facility. Zero is not supported.
priority	Worker thread priority; default ThreadPrioNormal in C++.
alloc	Borrowed allocator for timer nodes, or NULL to use AllocatorIntf_getDefault(). It must outlive the timer manager. Platform thread creation has no recoverable return status. With BA_TIMER_EXT_TICK enabled, only one timer manager is supported.

~BaTimer()

BaTimer::~BaTimer

(

)

Stop the worker and discard outstanding timer events without calling their callbacks.

Call from a thread other than the timer worker and prevent new operations during destruction. Waits for the worker to finish. If the caller owns the manager mutex, it is released during the wait and reacquired before returning. User data is not freed.

Member Function Documentation

cancel()

int BaTimer::cancel

(

size_t

tkey

)

Cancels the timer.

Parameters

tkey	the timer key.

Returns

0 on cancellation, -1 if the key was not found. Cancellation does not free the application data. Internal node memory may be reclaimed later by the worker.

reset()

int BaTimer::reset	(	size_t	tkey,
		U32	milliSec
	)

Resets the timer.

Parameters

tkey	the timer key.
milliSec	New delay in milliseconds, quantized to timer ticks. The timer is reset from the time this method is called.

Returns

0 on success, -1 if tkey was not found, or -2 if allocation of the replacement node fails or shutdown has begun. A -2 result leaves the old event cancelled; it does not preserve the old timer.

set()

size_t BaTimer::set	(	BaTimer_CB	cb,
		void *	data,
		U32	milliSec
	)

Create a timer event.

Parameters

cb	Required event callback. Returning TRUE repeats the event; FALSE makes it a one-shot event.
data	Borrowed callback context; may be NULL. See BaTimer_CB.
milliSec	the timer callback function is activated in "millisecs" time, unless method "reset" or "cancelled" is called before the timer triggers. The callback runs in the timer thread, not in the web-server request thread. A zero delay still queues work; the callback is not called inline.

Returns

A nonzero event key on success, or zero if node allocation fails or shutdown has begun. The key is local to this manager.