CThreadedCallbackTimerQueue Class Reference
[Timer management, Win32 Threading primitives]

Inheritance diagram for CThreadedCallbackTimerQueue:

[legend]

Collaboration diagram for CThreadedCallbackTimerQueue:

[legend]

List of all members.

---

Detailed Description

A class that manages a group of timers that implement IQueueTimers::Timer and which have their IQueueTimers::Timer::OnTimer() method called when the timer expires. The class uses an implementation of IManageTimerQueue to manage the timers and then manages its own timeouts using a thread to call IManageTimerQueue::HandleTimeouts() or IManageTimerQueue::BeginTimeoutHandling() every GetNextTimeout() milliseconds. You can configure it to use CCallbackTimerQueue, CCallbackTimerQueueEx or supply your own implementation of IManageTimerQueue and you can configure either lock held timer dispatch or no locks timer dispatch. See here for more details.

Public Types
enum	TimerQueueImplementation {   BestForPlatform = 0x01, TickCount64 = 0x02, HybridTickCount64 = 0x04, DispatchTimersWithLock = 0x00,   DispatchTimersNoLock = 0x10, BestForPlatformNoLock = BestForPlatform | DispatchTimersNoLock, TickCount64NoLock = TickCount64 | DispatchTimersNoLock, HybridTickCount64NoLock = HybridTickCount64 | DispatchTimersNoLock }
typedef ULONG_PTR	UserData
	User data that can be passed to Timer via the OnTimer() call when the timeout expires.
typedef ULONG_PTR	Handle
	A handle to a timer that has been created. This can be passed to SetTimer(), CancelTimer() and DestroyTimer() and is created with CreateTimer().
Public Member Functions
	CThreadedCallbackTimerQueue (const TimerQueueImplementation timerQueueImplementation=BestForPlatform)
	Create a timer queue using the specified implementation.
	CThreadedCallbackTimerQueue (const IProvideTickCount &tickProvider, const TimerQueueImplementation timerQueueImplementation=DispatchTimersWithLock)
	Create a timer queue that uses CCallbackTimerQueue as its implementation and that uses the provdided instance of IProvideTickCount to obtain its tick counts rather than getting them directly from the system.
	CThreadedCallbackTimerQueue (const IProvideTickCount64 &tickProvider, const TimerQueueImplementation timerQueueImplementation=DispatchTimersWithLock)
	Create a timer queue that uses CCallbackTimerQueueEx as its implementation and that uses the provdided instance of IProvideTickCount64 to obtain its tick counts rather than getting them directly from the system.
	CThreadedCallbackTimerQueue (IManageTimerQueue &impl, const TimerQueueImplementation timerQueueImplementation=DispatchTimersWithLock)
	Create a timer queue that uses the supplied instance of IManageTimerQueue as its implementation. Note that we don't take ownership of the implementation, it's up to you to manage its lifetime.
	~CThreadedCallbackTimerQueue ()
void	SetThreadName (const JetByteTools::Win32::_tstring &threadName) const
	Sets the name of the timer queue thread as displayed in the Visual Studio debugger to the supplied name. By default the constructors set the name of the thread to "TimerQueue".
virtual IQueueTimers::Handle	CreateTimer ()
	Create a timer and return a Handle to it.
virtual bool	SetTimer (const IQueueTimers::Handle &handle, IQueueTimers::Timer &timer, const Milliseconds timeout, const IQueueTimers::UserData userData)
	Set a timer that was previously created with CreateTimer(). Returns true if the timer was previously pending for another timeout and false if the timer was not already pending. Note that calling SetTimer() will cause any timers that have expired to be processed before the new timer is set.
virtual bool	CancelTimer (const IQueueTimers::Handle &handle)
	Cancel a timer that was previously set with SetTimer(). Returns true if the timer was pending and false if the timer was not pending.
virtual bool	DestroyTimer (IQueueTimers::Handle &handle)
	Destroy a timer that was previously created with CreateTimer() and update the variable passed in to contain InvalidHandleValue. Note that it is not permitted to call DestroyHandle() on a handle that contains the InvalidHandleValue value and an exception is thrown in this case. Returns true if the timer was pending and false if the timer was not pending.
virtual bool	DestroyTimer (const IQueueTimers::Handle &handle)
	Destroy a timer that was previously created with CreateTimer(). Returns true if the timer was pending and false if the timer was not pending.
virtual void	SetTimer (IQueueTimers::Timer &timer, const Milliseconds timeout, const IQueueTimers::UserData userData)
	Create and set a single use timer. Note that calling SetTimer() will cause any timers that have expired to be processed before the new timer is set.
virtual Milliseconds	GetMaximumTimeout () const
	Returns the maximum timeout value that can be set. Note that this may differ between instances of the objects that implement this interface.
virtual bool	DispatchesWithoutLock () const
	Returns true if the queue dispatches timers without holding an internal lock which it also requires to manipulate timers.
virtual void	OnThreadTerminationException (const _tstring &message)
	Called when the timer queue thread is terminated due to an exception this is a BAD situation! Override this to deal with it, log the error, etc...
virtual bool	OnThreadInitialised ()
	Called on the timer thread when the timer thread is started.
virtual void	OnThreadShutdown ()
	Called on the timer thread when the thread is shutting down.
Static Public Attributes
static Handle	InvalidHandleValue = 0
	The value that represents an invalid handle that cannot be used.

---

Member Typedef Documentation

typedef ULONG_PTR UserData [inherited]

User data that can be passed to Timer via the OnTimer() call when the timeout expires.

typedef ULONG_PTR Handle [inherited]

A handle to a timer that has been created. This can be passed to SetTimer(), CancelTimer() and DestroyTimer() and is created with CreateTimer().

---

Member Enumeration Documentation

enum TimerQueueImplementation

Enumerator:

BestForPlatform	Select CCallbackTimerQueueEx as the implementation if it's available.
TickCount64	Select CCallbackTimerQueueEx as the implementation.
HybridTickCount64	Select CCallbackTimerQueue as the implementation.
DispatchTimersWithLock	Holds our internal lock when dispatching timers (potentially slightly faster).
DispatchTimersNoLock	Does not hold our internal lock when dispatching timers.
BestForPlatformNoLock
TickCount64NoLock
HybridTickCount64NoLock

---

Constructor & Destructor Documentation

CThreadedCallbackTimerQueue

(

const TimerQueueImplementation

timerQueueImplementation = BestForPlatform

)

[explicit]

Create a timer queue using the specified implementation.

Reimplemented in CThreadedCallbackTimerQueue.

CThreadedCallbackTimerQueue	(	const IProvideTickCount &	tickProvider,
		const TimerQueueImplementation	timerQueueImplementation = DispatchTimersWithLock
	)			[explicit]

Create a timer queue that uses CCallbackTimerQueue as its implementation and that uses the provdided instance of IProvideTickCount to obtain its tick counts rather than getting them directly from the system.

Reimplemented in CThreadedCallbackTimerQueue.

CThreadedCallbackTimerQueue	(	const IProvideTickCount64 &	tickProvider,
		const TimerQueueImplementation	timerQueueImplementation = DispatchTimersWithLock
	)			[explicit]

Create a timer queue that uses CCallbackTimerQueueEx as its implementation and that uses the provdided instance of IProvideTickCount64 to obtain its tick counts rather than getting them directly from the system.

Reimplemented in CThreadedCallbackTimerQueue.

CThreadedCallbackTimerQueue	(	IManageTimerQueue &	impl,
		const TimerQueueImplementation	timerQueueImplementation = DispatchTimersWithLock
	)			[explicit]

Create a timer queue that uses the supplied instance of IManageTimerQueue as its implementation. Note that we don't take ownership of the implementation, it's up to you to manage its lifetime.

Reimplemented in CThreadedCallbackTimerQueue.

~CThreadedCallbackTimerQueue

(

)

---

Member Function Documentation

void SetThreadName

(

const JetByteTools::Win32::_tstring &

threadName

)

const

Sets the name of the timer queue thread as displayed in the Visual Studio debugger to the supplied name. By default the constructors set the name of the thread to "TimerQueue".

CThreadedCallbackTimerQueue::Handle CreateTimer

(

)

[virtual]

Create a timer and return a Handle to it.

Implements IQueueTimers.

virtual bool SetTimer	(	const IQueueTimers::Handle &	handle,
		IQueueTimers::Timer &	timer,
		const Milliseconds	timeout,
		const IQueueTimers::UserData	userData
	)			[virtual]

Set a timer that was previously created with CreateTimer(). Returns true if the timer was previously pending for another timeout and false if the timer was not already pending. Note that calling SetTimer() will cause any timers that have expired to be processed before the new timer is set.

Implements IQueueTimers.

virtual bool CancelTimer

(

const IQueueTimers::Handle &

handle

)

[virtual]

Cancel a timer that was previously set with SetTimer(). Returns true if the timer was pending and false if the timer was not pending.

Implements IQueueTimers.

virtual bool DestroyTimer

(

IQueueTimers::Handle &

handle

)

[virtual]

Destroy a timer that was previously created with CreateTimer() and update the variable passed in to contain InvalidHandleValue. Note that it is not permitted to call DestroyHandle() on a handle that contains the InvalidHandleValue value and an exception is thrown in this case. Returns true if the timer was pending and false if the timer was not pending.

Implements IQueueTimers.

virtual bool DestroyTimer

(

const IQueueTimers::Handle &

handle

)

[virtual]

Destroy a timer that was previously created with CreateTimer(). Returns true if the timer was pending and false if the timer was not pending.

Implements IQueueTimers.

virtual void SetTimer	(	IQueueTimers::Timer &	timer,
		const Milliseconds	timeout,
		const IQueueTimers::UserData	userData
	)			[virtual]

Create and set a single use timer. Note that calling SetTimer() will cause any timers that have expired to be processed before the new timer is set.

Implements IQueueTimers.

Milliseconds GetMaximumTimeout

(

)

const [virtual]

Returns the maximum timeout value that can be set. Note that this may differ between instances of the objects that implement this interface.

Implements IQueueTimers.

bool DispatchesWithoutLock

(

)

const [virtual]

Returns true if the queue dispatches timers without holding an internal lock which it also requires to manipulate timers.

Implements IQueueTimers.

void OnThreadTerminationException

(

const _tstring &

message

)

[virtual]

Called when the timer queue thread is terminated due to an exception this is a BAD situation! Override this to deal with it, log the error, etc...

bool OnThreadInitialised

(

)

[virtual]

Called on the timer thread when the timer thread is started.

void OnThreadShutdown

(

)

[virtual]

Called on the timer thread when the thread is shutting down.

---

Member Data Documentation

IQueueTimers::Handle InvalidHandleValue = 0 [static, inherited]

The value that represents an invalid handle that cannot be used.

---