sipxportlib
Version 3.3
|
#include <OsTimer.h>
Public Types | |
enum | OsTimerState { STOPPED, STARTED } |
The states a timer can be in. More... | |
Public Member Functions | |
virtual | ~OsTimer () |
Destructor. More... | |
virtual void | deleteAsync () |
Non-blocking asynchronous delete operation. More... | |
virtual OsStatus | stop (UtlBoolean synchronous=TRUE) |
Stop the timer if it has been started. More... | |
virtual OsNotification * | getNotifier (void) const |
Return the OsNotification object for this timer. More... | |
virtual unsigned | hash () const |
Calculate a unique hash code for this object. More... | |
virtual UtlContainableType | getContainableType () const |
Get the ContainableType for a UtlContainable derived class. More... | |
UtlBoolean | getWasFired () |
Returns TRUE if timer was fired. More... | |
virtual int | compareTo (UtlContainable const *) const |
Compare the this object to another like-objects. More... | |
virtual OsTimerState | getState () |
Return the state value for this OsTimer object. More... | |
Public Member Functions inherited from UtlContainable | |
virtual | ~UtlContainable () |
unsigned | directHash () const |
Provides a hash function that uses the object pointer as the hash value. More... | |
virtual UtlBoolean | isEqual (UtlContainable const *) const |
Test this object to another object for equality. More... | |
virtual UtlBoolean | isInstanceOf (const UtlContainableType type) const |
Determine if this object is a derivative of the specified UtlContainableType. More... | |
Static Public Attributes | |
static const UtlContainableType | TYPE = "OsTimer" |
Static Public Attributes inherited from UtlContainable | |
static const UtlContainableType | TYPE = "UtlContainable" |
Protected Member Functions | |
OsStatus | startTimer (OsTime start, UtlBoolean periodic, OsTime period) |
Start a timer. More... | |
Static Protected Member Functions | |
static UtlBoolean | isStarted (int status) |
Test whether a status indicates the timer has been started. More... | |
static UtlBoolean | isStopped (int status) |
Test whether a status indicates the timer has been stopped. More... | |
Protected Attributes | |
OsBSem | mBSem |
Semaphore to lock access to members. More... | |
unsigned int | mApplicationState |
UtlBoolean | mWasFired |
TRUE if timer is stopped because it was fired < state as seen by application methods. More... | |
unsigned int | mTaskState |
State as seen by the timer task. More... | |
UtlBoolean | mDeleting |
TRUE if timer is being deleted. More... | |
OsNotification * | mpNotifier |
Used to signal timer expiration event. More... | |
UtlBoolean | mbManagedNotifier |
TRUE if OsTimer destructor should < delete *mpNotifier. More... | |
OsTime | mExpiresAt |
Expire time of timer. More... | |
UtlBoolean | mPeriodic |
TRUE if timer fires repetitively. More... | |
OsTime | mPeriod |
Repetition time. More... | |
OsTime | mQueuedExpiresAt |
Expire time of timer (copy). More... | |
UtlBoolean | mQueuedPeriodic |
TRUE if timer fires repetitively (copy). More... | |
OsTime | mQueuedPeriod |
Repetition time (copy). More... | |
int | mOutstandingMessages |
Number of messages for this timer < in the timer task's queue. More... | |
OsTimer * | mTimerQueueLink |
To chain together timers. More... | |
Friends | |
class | OsTimerTask |
class | OsTimerTest |
Constructors | |
Constructors specify how fired timers will signal the application. The event specification does not change over the lifetime of the timer. The timer period information is specified by the start method, and can be different for different starts. | |
OsTimer (OsNotification &rNotifier) | |
OsTimer (OsMsgQ *pQueue, intptr_t userData) | |
Start methods | |
These methods start the timer. They may be called when the timer is in any state, but if the timer is already started, they have no effect. They return a value that reflects that state: OS_SUCCESS if the start operation was successful and OS_FAILED if it failed (because the timer was already started). | |
virtual OsStatus | oneshotAt (const OsDateTime &when) |
Start the timer to fire once at the indicated date/time. More... | |
virtual OsStatus | oneshotAfter (const OsTime &offset) |
Start the timer to fire once at the current time + offset. More... | |
virtual OsStatus | periodicAt (const OsDateTime &when, const OsTime &period) |
Start the timer to fire periodically starting at the indicated date/time. More... | |
virtual OsStatus | periodicEvery (const OsTime &offset, const OsTime &period) |
Start the timer to fire periodically starting at current time + offset. More... | |
Additional Inherited Members | |
Static Public Member Functions inherited from UtlContainable | |
static unsigned | stringHash (char const *value) |
Provides a hash function appropriate for null-terminated string values. More... | |
static UtlBoolean | areSameTypes (const UtlContainableType type1, const UtlContainableType type2) |
Are UtlContainable types the same. More... | |
This class implements one-shot and periodic timers.
Once a timer is created, it must be started. After the specified time, the timer expires or "fires", at which point (depending on how the timer was created) an OsNotification object is used to signal an event, or a message is posted to a specified queue.
A timer may be stopped at any time (except when the timer is being destroyed). The destructor calls stop() before freeing the timer.
If the stop() is synchronous, it may block, but it ensures that any event routine call will have finished before stop() returns. If the stop() is asynchronous, it will not block, but an event routine execution that has been previously committed may execute after stop() returns. (For one-shot timers, this can be detected by examining the return value of stop().)
Once a timer is stopped with stop() or by firing (if it is a one-shot timer), it can be started again. The time interval of a timer can be changed every time it is started, but its notification information is fixed when it is created.
All methods can be used concurrently, except that no other method may be called concurrently with the destructor (which cannot be made to work, as the destructor deletes the timer's memory). Note that a timer may fire while it is being deleted; the destructor handles this situation correctly, the timer is guaranteed to exist until after the event routine returns.
An event routine should be non-blocking, because it is called on the timer task thread. Within an event routine, all non-blocking methods may be executed on the timer. When the event routine of a one-shot timer is entered, the timer is in the stopped state. When the event routine of a periodic timer is entered, the timer is still in the running state.
(If mbManagedNotifier is set, the timer may not be destroyed (using deleteAsync, which is non-blocking), as that destroys the OsNotifier object whose method is the event notifier that is currently running. But there is no current interface for creating that situation.)
Most methods are non-blocking, except to seize the timer's mutex and to post messages to the timer task's message queue. The exceptions are the destructor and synchronous stops, which must block until they get a response from the timer task.
If VALGRIND_TIMER_ERROR is defined, additional code is created to detect and backtrace errors in timer usage. This code causes run-time errors that Valgrind can detect to produce backtraces of where the invalid method invocations were made.
If NDEBUG is defined, some checking code that is used only to trigger asserts is omitted.
enum OsTimerState |
OsTimer | ( | OsNotification & | rNotifier | ) |
Construct a timer that signals by calling
rNotifier | OsNotification object to report event |
Construct a timer that signals by calling
pQueue | Queue to send OsEventMsg::NOTIFY message |
userData | userData value to store in OsQueuedEvent |
|
virtual |
Destructor.
|
virtual |
Non-blocking asynchronous delete operation.
Stops the timer, then sends a message to the timer task, which will eventually delete it. Provides a non-blocking way to delete an OsTimer.
|
virtual |
Start the timer to fire once at the indicated date/time.
Start the timer to fire once at the current time + offset.
Start the timer to fire periodically starting at the indicated date/time.
Start the timer to fire periodically starting at current time + offset.
|
virtual |
Stop the timer if it has been started.
stop() can be called when the timer is in any state, and returns a value that reflects that state:
Thus, if it is a one-shot timer, and there are one or more calls to stop(), if the event has been signaled, all calls will return OS_FAILED. But if the event has not been signaled, exactly one call will return OS_SUCCESS. This allows the caller of stop() to know whether to clean up or not.
If synchronous is TRUE, the call will block if necessary to ensure that any event routine execution for this timer will finish before stop() returns. If synchronous is FALSE, the call will not block, but a previously committed event routine execution may happen after stop() returns.
|
virtual |
Return the OsNotification object for this timer.
If the timer was constructed with OsTimer(OsMsgQ*, const int), it returns the address of an internally allocated OsNotification.
|
virtual |
Calculate a unique hash code for this object.
If the equals operator returns true for another object, then both of those objects must return the same hashcode.
Implements UtlContainable.
|
virtual |
Get the ContainableType for a UtlContainable derived class.
Implements UtlContainable.
UtlBoolean getWasFired | ( | ) |
Returns TRUE if timer was fired.
This flag is set to FALSE when timer is first started, and also if stop operation succeeds. It is set to TRUE when timer is fired. Note that stop fails on a stopped timer.
|
virtual |
Compare the this object to another like-objects.
Results for comparing with a non-like object are undefined.
Implements UtlContainable.
|
virtual |
Return the state value for this OsTimer object.
|
protected |
Start a timer.
|
inlinestaticprotected |
Test whether a status indicates the timer has been started.
|
inlinestaticprotected |
Test whether a status indicates the timer has been stopped.
|
friend |
|
friend |
|
static |
Class type used for runtime checking
|
protected |
Semaphore to lock access to members.
|
protected |
|
protected |
TRUE if timer is stopped because it was fired < state as seen by application methods.
|
protected |
State as seen by the timer task.
|
protected |
TRUE if timer is being deleted.
|
protected |
Used to signal timer expiration event.
|
protected |
TRUE if OsTimer destructor should < delete *mpNotifier.
|
protected |
Expire time of timer.
|
protected |
TRUE if timer fires repetitively.
|
protected |
Repetition time.
|
protected |
Expire time of timer (copy).
|
protected |
TRUE if timer fires repetitively (copy).
|
protected |
Repetition time (copy).
|
protected |
Number of messages for this timer < in the timer task's queue.
|
protected |
To chain together timers.