The C++ framework for developing highly scalable, high performance servers on Windows platforms.

• Home
• What
• Why
• How
• Who
• Products
• Pricing
• Blog
• Contact

Search

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::BeginTimeoutHandling() every GetNextTimeout() milliseconds. You can configure it to use CCallbackTimerQueueEx or supply your own implementation of IManageTimerQueue. See here for more details.

Public Types
enum	SetTimerIf { SetTimerAlways, SetTimerIfNotSet }
	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. More...
enum	UpdateTimerIf { UpdateTimerIfNewTimeIsSooner, UpdateTimerIfNewTimeIsLater, UpdateAlways, UpdateAlwaysNoTimeoutChange }
	Update a timer if it is set and if the condition is true and set the timer if it is not set. Updating a timer will set the timeout, timer and user data to the newly supplied values. If the timer is not updated because the condition is false then nothing is changed. UpdateAlways will always update. UpdateAlwaysNoTimeoutChange will always update JUST timer and user data. If you supply pWasUpdated then it is set to true if anything was changed and false if not. More...
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 ()
	Create a timer queue.
	CThreadedCallbackTimerQueue (IMonitorThreadedCallbackTimerQueue &monitor)
	Create a timer queue and monitor it with the supplied monitor.
	CThreadedCallbackTimerQueue (const IProvideTickCount64 &tickProvider)
	Create a timer queue that uses the provdided instance of IProvideTickCount64 to obtain its tick counts rather than getting them directly from the system.
	CThreadedCallbackTimerQueue (IMonitorThreadedCallbackTimerQueue &monitor, const IProvideTickCount64 &tickProvider)
	Create a timer queue that uses the provdided instance of IProvideTickCount64 to obtain its tick counts rather than getting them directly from the system. Monitor it with the supplied monitor.
	CThreadedCallbackTimerQueue (IManageTimerQueue &impl)
	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 (IManageTimerQueue &impl, IMonitorThreadedCallbackTimerQueue &monitor)
	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. Monitor it with the supplied monitor.
	CThreadedCallbackTimerQueue (const CThreadedCallbackTimerQueue &rhs)
	~CThreadedCallbackTimerQueue () override
CThreadedCallbackTimerQueue &	operator= (const CThreadedCallbackTimerQueue &rhs)
void	SetThreadName (const _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".
void	BeginShutdown ()
	Starts the shutdown process and returns immediately.
bool	WaitForShutdownToComplete (Milliseconds timeout=INFINITE)
	Initiates a shutdown (if one isn't already in progresss) and then waits for it to complete. Does not return until the shutdown has completed or the timeout has expired. Returns true if the shutdown is complete.
void	DumpStats (const JetByteTools::Core::_tstring &message) const
Handle	CreateTimer () override
	Create a timer and return a Handle to it.
bool	TimerIsSet (const Handle &handle) const override
bool	SetTimer (const Handle &handle, Timer &timer, Milliseconds timeout, UserData userData, SetTimerIf setTimerIf=SetTimerAlways, bool *pOptionalFirstToExpireHasChanged=nullptr) override
bool	UpdateTimer (const Handle &handle, Timer &timer, Milliseconds timeout, UserData userData, UpdateTimerIf updateIf, bool *pWasUpdated=nullptr, bool *pOptionalFirstToExpireHasChanged=nullptr) override
bool	CancelTimer (const Handle &handle, bool *pOptionalFirstToExpireHasChanged=nullptr) override
bool	DestroyTimer (Handle &handle, bool *pOptionalFirstToExpireHasChanged=nullptr) override
void	SetTimer (Timer &timer, Milliseconds timeout, UserData userData, bool *pOptionalFirstToExpireHasChanged=nullptr) override
Milliseconds	GetMaximumTimeout () const override
	Returns the maximum timeout value that can be set. Note that this may differ between instances of the objects that implement this interface.
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.
virtual bool	TimerIsSet (const Handle &handle) const =0
	Returns true if the timer is currently set.
virtual bool	SetTimer (const Handle &handle, Timer &timer, Milliseconds timeout, UserData userData, SetTimerIf setTimerIf=SetTimerAlways, bool *pOptionalFirstToExpireHasChanged=nullptr)=0
virtual void	SetTimer (Timer &timer, Milliseconds timeout, UserData userData, bool *pOptionalFirstToExpireHasChanged=nullptr)=0
	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.
template<typename T>
bool	SetTimerWithRefCountedUserData (const Handle &handle, Timer &timer, Milliseconds timeout, T *pUserData, SetTimerIf setTimerIf=SetTimerAlways, bool *pOptionalFirstToExpireHasChanged=nullptr)
template<typename T>
bool	SetTimerWithRefCountedTimer (const Handle &handle, T &timer, Milliseconds timeout, UserData userData, SetTimerIf setTimerIf=SetTimerAlways, bool *pOptionalFirstToExpireHasChanged=nullptr)
virtual bool	UpdateTimer (const Handle &handle, Timer &timer, Milliseconds timeout, UserData userData, UpdateTimerIf updateIf, bool *pWasUpdated=nullptr, bool *pOptionalFirstToExpireHasChanged=nullptr)=0
template<typename T>
bool	UpdateTimerWithRefCountedUserData (const Handle &handle, Timer &timer, Milliseconds timeout, T *pUserData, UpdateTimerIf updateIf, bool *pWasUpdated=nullptr, bool *pOptionalFirstToExpireHasChanged=nullptr)
template<typename T>
bool	UpdateTimerWithRefCountedTimer (const Handle &handle, T &timer, Milliseconds timeout, UserData userData, UpdateTimerIf updateIf, bool *pWasUpdated=nullptr, bool *pOptionalFirstToExpireHasChanged=nullptr)
virtual bool	CancelTimer (const Handle &handle, bool *pOptionalFirstToExpireHasChanged=nullptr)=0
	Cancel a timer that was previously set with SetTimer(). Returns true if the timer was pending and false if the timer was not pending.
template<typename T>
bool	CancelTimerWithRefCountedUserData (const Handle &handle, T &userData, bool *pOptionalFirstToExpireHasChanged=nullptr)
template<typename T>
bool	CancelTimerWithRefCountedUserData (const Handle &handle, T *pUserData, bool *pOptionalFirstToExpireHasChanged=nullptr)
template<typename T>
bool	CancelTimerWithRefCountedTimer (const Handle &handle, T &timer, bool *pOptionalFirstToExpireHasChanged=nullptr)
virtual bool	DestroyTimer (Handle &handle, bool *pOptionalFirstToExpireHasChanged=nullptr)=0
	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 Handle &handle, bool *pOptionalFirstToExpireHasChanged=nullptr)
	Destroy a timer that was previously created with CreateTimer(). Returns true if the timer was pending and false if the timer was not pending.
template<typename T, typename H>
bool	DestroyTimerWithRefCountedUserData (H &handle, T &userData, bool *pOptionalFirstToExpireHasChanged=nullptr)
template<typename T, typename H>
bool	DestroyTimerWithRefCountedUserData (H &handle, T *pUserData, bool *pOptionalFirstToExpireHasChanged=nullptr)
template<typename T, typename H>
bool	DestroyTimerWithRefCountedTimer (H &handle, T &timer, bool *pOptionalFirstToExpireHasChanged=nullptr)
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 SetTimerIf [inherited]

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.

Enumerator:

SetTimerAlways
SetTimerIfNotSet

enum UpdateTimerIf [inherited]

Update a timer if it is set and if the condition is true and set the timer if it is not set. Updating a timer will set the timeout, timer and user data to the newly supplied values. If the timer is not updated because the condition is false then nothing is changed. UpdateAlways will always update. UpdateAlwaysNoTimeoutChange will always update JUST timer and user data. If you supply pWasUpdated then it is set to true if anything was changed and false if not.

Enumerator:

UpdateTimerIfNewTimeIsSooner
UpdateTimerIfNewTimeIsLater
UpdateAlways
UpdateAlwaysNoTimeoutChange

---

Constructor & Destructor Documentation

CThreadedCallbackTimerQueue

(

)

Create a timer queue.

Reimplemented in CThreadedCallbackTimerQueue.

CThreadedCallbackTimerQueue

(

IMonitorThreadedCallbackTimerQueue &

monitor

)

[explicit]

Create a timer queue and monitor it with the supplied monitor.

CThreadedCallbackTimerQueue

(

const IProvideTickCount64 &

tickProvider

)

[explicit]

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

Reimplemented in CThreadedCallbackTimerQueue.

CThreadedCallbackTimerQueue	(	IMonitorThreadedCallbackTimerQueue &	monitor,
		const IProvideTickCount64 &	tickProvider
	)

Create a timer queue that uses the provdided instance of IProvideTickCount64 to obtain its tick counts rather than getting them directly from the system. Monitor it with the supplied monitor.

CThreadedCallbackTimerQueue

(

IManageTimerQueue &

impl

)

[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	(	IManageTimerQueue &	impl,
		IMonitorThreadedCallbackTimerQueue &	monitor
	)

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. Monitor it with the supplied monitor.

CThreadedCallbackTimerQueue

(

const CThreadedCallbackTimerQueue &

rhs

)

~CThreadedCallbackTimerQueue

(

)

[override]

---

Member Function Documentation

CThreadedCallbackTimerQueue& operator=

(

const CThreadedCallbackTimerQueue &

rhs

)

void SetThreadName

(

const _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".

void BeginShutdown

(

)

Starts the shutdown process and returns immediately.

bool WaitForShutdownToComplete

(

Milliseconds

timeout = INFINITE

)

Initiates a shutdown (if one isn't already in progresss) and then waits for it to complete. Does not return until the shutdown has completed or the timeout has expired. Returns true if the shutdown is complete.

void DumpStats

(

const JetByteTools::Core::_tstring &

message

)

const

CThreadedCallbackTimerQueue::Handle CreateTimer

(

)

[override, virtual]

Create a timer and return a Handle to it.

Implements IQueueTimers.

bool TimerIsSet

(

const Handle &

handle

)

const [override]

bool SetTimer	(	const Handle &	handle,
		Timer &	timer,
		Milliseconds	timeout,
		UserData	userData,
		SetTimerIf	setTimerIf = SetTimerAlways,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[override]

bool UpdateTimer	(	const Handle &	handle,
		Timer &	timer,
		Milliseconds	timeout,
		UserData	userData,
		UpdateTimerIf	updateIf,
		bool *	pWasUpdated = nullptr,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[override]

bool CancelTimer	(	const Handle &	handle,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[override]

bool DestroyTimer	(	Handle &	handle,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[override]

void SetTimer	(	Timer &	timer,
		Milliseconds	timeout,
		UserData	userData,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[override]

Milliseconds GetMaximumTimeout

(

)

const [override, 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.

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.

virtual bool TimerIsSet

(

const Handle &

handle

)

const [pure virtual, inherited]

Returns true if the timer is currently set.

virtual bool SetTimer	(	const Handle &	handle,
		Timer &	timer,
		Milliseconds	timeout,
		UserData	userData,
		SetTimerIf	setTimerIf = SetTimerAlways,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[pure virtual, inherited]

virtual void SetTimer	(	Timer &	timer,
		Milliseconds	timeout,
		UserData	userData,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[pure virtual, inherited]

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.

bool SetTimerWithRefCountedUserData	(	const Handle &	handle,
		Timer &	timer,
		Milliseconds	timeout,
		T *	pUserData,
		SetTimerIf	setTimerIf = SetTimerAlways,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

bool SetTimerWithRefCountedTimer	(	const Handle &	handle,
		T &	timer,
		Milliseconds	timeout,
		UserData	userData,
		SetTimerIf	setTimerIf = SetTimerAlways,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

virtual bool UpdateTimer	(	const Handle &	handle,
		Timer &	timer,
		Milliseconds	timeout,
		UserData	userData,
		UpdateTimerIf	updateIf,
		bool *	pWasUpdated = nullptr,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[pure virtual, inherited]

bool UpdateTimerWithRefCountedUserData	(	const Handle &	handle,
		Timer &	timer,
		Milliseconds	timeout,
		T *	pUserData,
		UpdateTimerIf	updateIf,
		bool *	pWasUpdated = nullptr,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

bool UpdateTimerWithRefCountedTimer	(	const Handle &	handle,
		T &	timer,
		Milliseconds	timeout,
		UserData	userData,
		UpdateTimerIf	updateIf,
		bool *	pWasUpdated = nullptr,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

virtual bool CancelTimer	(	const Handle &	handle,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[pure virtual, inherited]

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

bool CancelTimerWithRefCountedUserData	(	const Handle &	handle,
		T &	userData,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

bool CancelTimerWithRefCountedUserData	(	const Handle &	handle,
		T *	pUserData,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

bool CancelTimerWithRefCountedTimer	(	const Handle &	handle,
		T &	timer,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

virtual bool DestroyTimer	(	Handle &	handle,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[pure virtual, inherited]

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 Handle &	handle,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, virtual, inherited]

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

bool DestroyTimerWithRefCountedUserData	(	H &	handle,
		T &	userData,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

bool DestroyTimerWithRefCountedUserData	(	H &	handle,
		T *	pUserData,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

bool DestroyTimerWithRefCountedTimer	(	H &	handle,
		T &	timer,
		bool *	pOptionalFirstToExpireHasChanged = nullptr
	)			[inline, inherited]

---

Member Data Documentation

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

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

---