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

CCallbackTimerQueueEx Class Reference
[Timer management]

Inheritance diagram for CCallbackTimerQueueEx:
Collaboration diagram for CCallbackTimerQueueEx:

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. You must manually manage the handling and processing of timeouts by calling IManageTimerQueue::BeginTimeoutHandling() every IManageTimerQueue::GetNextTimeout() milliseconds. See here for more details. Note: the maximum timeout that you can set is 4294967294ms as 0xFFFFFFF is reserved as 'INFINITE' i.e. a timer that never expires. Internally the code uses an unsigned 64 bit counter which will wrap in around 584942417.4 years from the creation of the timer queue. You cannot set a timer that crosses this wrap point and an exception will be thrown. GetMaximumTimeout() does not report the reducing maximum timeout as the wrap point approaches, it will always return 4294967294ms.


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

 CCallbackTimerQueueEx ()
 Create a timer queue.
 CCallbackTimerQueueEx (IMonitorCallbackTimerQueue &monitor)
 Create a timer queue and monitor it with the supplied monitor.
 CCallbackTimerQueueEx (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.
 CCallbackTimerQueueEx (IMonitorCallbackTimerQueue &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.
 CCallbackTimerQueueEx (const CCallbackTimerQueueEx &rhs)
 ~CCallbackTimerQueueEx () override
CCallbackTimerQueueExoperator= (const CCallbackTimerQueueEx &rhs)
Milliseconds GetNextTimeout () override
 Get the number of milliseconds until the next timer is due to fire. Or INFINITE if no timer is set.
bool BeginTimeoutHandling () override
 Returns true if timers need to be handled. You should then call HandleTimeout() to handle the timeouts and finally call EndTimeoutHandling() to tell the queue that you are done.
size_t HandleTimeout () override
 Handle the timeout for the given timer handle. Note that in an implementation that is safe for use in a multi-threaded situation it is NOT acceptable to hold a lock that will prevent concurrent calls to any of the methods on IQueueTimers.
void EndTimeoutHandling () override
 Complete the handling of a timeout that was started with BeginTimeoutHandling(). Note that in an implementation that is safe for use in a multi-threaded situation it is acceptable to hold a lock whilst this method is called to prevent concurrent calls to any of the methods on IQueueTimers.
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 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.

Classes

class  TimerDataIntrusiveMultiMapNodeAccessor
class  TimerDataIntrusiveMultiMapNodeKeyAccessor


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

Create a timer queue.

CCallbackTimerQueueEx ( IMonitorCallbackTimerQueue monitor  )  [explicit]

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

CCallbackTimerQueueEx ( 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.

CCallbackTimerQueueEx ( IMonitorCallbackTimerQueue 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.

~CCallbackTimerQueueEx (  )  [override]


Member Function Documentation

CCallbackTimerQueueEx& operator= ( const CCallbackTimerQueueEx rhs  ) 

Milliseconds GetNextTimeout (  )  [override, virtual]

Get the number of milliseconds until the next timer is due to fire. Or INFINITE if no timer is set.

Implements IManageTimerQueue.

bool BeginTimeoutHandling (  )  [override, virtual]

Returns true if timers need to be handled. You should then call HandleTimeout() to handle the timeouts and finally call EndTimeoutHandling() to tell the queue that you are done.

Implements IManageTimerQueue.

size_t HandleTimeout (  )  [override, virtual]

Handle the timeout for the given timer handle. Note that in an implementation that is safe for use in a multi-threaded situation it is NOT acceptable to hold a lock that will prevent concurrent calls to any of the methods on IQueueTimers.

Implements IManageTimerQueue.

void EndTimeoutHandling (  )  [override, virtual]

Complete the handling of a timeout that was started with BeginTimeoutHandling(). Note that in an implementation that is safe for use in a multi-threaded situation it is acceptable to hold a lock whilst this method is called to prevent concurrent calls to any of the methods on IQueueTimers.

Implements IManageTimerQueue.

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

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.


Generated on Sun Sep 12 19:08:22 2021 for The Server Framework - v7.4 by doxygen 1.5.3