sipxportlib  Version 3.3
Public Types | Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends | List of all members
OsTimer Class Reference

#include <OsTimer.h>

Inheritance diagram for OsTimer:
Inheritance graph
[legend]
Collaboration diagram for OsTimer:
Collaboration graph
[legend]

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 OsNotificationgetNotifier (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...
 
OsNotificationmpNotifier
 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...
 
OsTimermTimerQueueLink
 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...
 

Detailed Description

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.

Member Enumeration Documentation

The states a timer can be in.

Enumerator
STOPPED 

Timer has not been started, or has fired < or been stopped.

STARTED 

Timer is running and will fire.

Constructor & Destructor Documentation

OsTimer ( OsNotification rNotifier)

Construct a timer that signals by calling

rNotifier.signal((int) this)
Parameters
rNotifierOsNotification object to report event
OsTimer ( OsMsgQ *  pQueue,
intptr_t  userData 
)

Construct a timer that signals by calling

pQueue->doSendEventMsg(OsEventMsg::NOTIFY, (int) this)
Parameters
pQueueQueue to send OsEventMsg::NOTIFY message
userDatauserData value to store in OsQueuedEvent
~OsTimer ( )
virtual

Destructor.

Member Function Documentation

void deleteAsync ( )
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.

OsStatus oneshotAt ( const OsDateTime &  when)
virtual

Start the timer to fire once at the indicated date/time.

OsStatus oneshotAfter ( const OsTime offset)
virtual

Start the timer to fire once at the current time + offset.

OsStatus periodicAt ( const OsDateTime &  when,
const OsTime period 
)
virtual

Start the timer to fire periodically starting at the indicated date/time.

OsStatus periodicEvery ( const OsTime offset,
const OsTime period 
)
virtual

Start the timer to fire periodically starting at current time + offset.

OsStatus stop ( UtlBoolean  synchronous = TRUE)
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:

Returns
OS_SUCCESS if the timer was started and OS_FAILED if the timer was not started, was already stopped, or is a one-shot timer and has fired.

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.

OsNotification * getNotifier ( void  ) const
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.

unsigned hash ( ) const
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.

UtlContainableType getContainableType ( ) const
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.

int compareTo ( UtlContainable const *  inVal) const
virtual

Compare the this object to another like-objects.

Results for comparing with a non-like object are undefined.

Returns
0 if equal, < 0 if less-than and > 0 if greater-than.

Implements UtlContainable.

OsTimer::OsTimerState getState ( )
virtual

Return the state value for this OsTimer object.

OsStatus startTimer ( OsTime  start,
UtlBoolean  periodic,
OsTime  period 
)
protected

Start a timer.

static UtlBoolean isStarted ( int  status)
inlinestaticprotected

Test whether a status indicates the timer has been started.

static UtlBoolean isStopped ( int  status)
inlinestaticprotected

Test whether a status indicates the timer has been stopped.

Friends And Related Function Documentation

friend class OsTimerTask
friend
friend class OsTimerTest
friend

Member Data Documentation

const UtlContainableType TYPE = "OsTimer"
static

Class type used for runtime checking

OsBSem mBSem
protected

Semaphore to lock access to members.

unsigned int mApplicationState
protected
UtlBoolean mWasFired
protected

TRUE if timer is stopped because it was fired < state as seen by application methods.

unsigned int mTaskState
protected

State as seen by the timer task.

UtlBoolean mDeleting
protected

TRUE if timer is being deleted.

OsNotification* mpNotifier
protected

Used to signal timer expiration event.

UtlBoolean mbManagedNotifier
protected

TRUE if OsTimer destructor should < delete *mpNotifier.

OsTime mExpiresAt
protected

Expire time of timer.

UtlBoolean mPeriodic
protected

TRUE if timer fires repetitively.

OsTime mPeriod
protected

Repetition time.

OsTime mQueuedExpiresAt
protected

Expire time of timer (copy).

UtlBoolean mQueuedPeriodic
protected

TRUE if timer fires repetitively (copy).

OsTime mQueuedPeriod
protected

Repetition time (copy).

int mOutstandingMessages
protected

Number of messages for this timer < in the timer task's queue.

OsTimer* mTimerQueueLink
protected

To chain together timers.