ITimer

The ITimer class creates and references periodic time-interval-based operations.

Timer identifiers are limited to the value 0x7FFF in all environments to allow portability to systems where where this limit is imposed by the operating system.

AIX Considerations

At the end of each interval, a notification request is registered with the system for the next interval. Because of processing delays that may occur in the operating system and applications between the time an interval expires and the next one is scheduled, some drift may occur in the timer.

OS/2 Considerations

ITimer objects use timer identifier values above 1000. Limit your use of timer identifiers to values below 1000 when directly creating or managing timers using operating system calls.

The ITimer class uses the operating system message queue for timer expiration. This can cause timer actions to be delayed if the application is currently tying up the queue. If a timer event is delayed, the next timer event still occurs at the expected interval (there should be no timer drift).

ITimer - Member Functions and Data by Group

You can construct, copy, assign, and destruct objects of this class.
Note: The ITimer class does not support user-specified timer identifier values or timers that were not created with the ITimer class.

---

~ITimer

public:
virtual ~ITimer()

The destructor does not stop the timer or deallocate resources. If you want to stop the timer and deallocate resources, call the function stop to halt the started timer.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

ITimer

---

Overload 1

public:
ITimer()

Constructs an ITimer object using the default constructor. When calling start to subsequently start the timer, you can specify a timer interval and a function for the timer to call each time it expires.

Exception

IOutOfSystemResource

The system is out of available timer identifiers.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

Overload 2

public:
ITimer(unsigned long timerIdentifier)

timerIdentifier

A value that represents the timer identifier (ID).

Constructs an ITimer object from the timer ID of an existing ITimer object.

Exception

IInvalidParameter

The timer identifier value is not valid.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

Overload 3

public:
ITimer( const ICountedPointerTo < ITimerFn >& timerFunction,
        unsigned long timerInterval = 1000 )

Constructs an ITimer object with a specification of code to be run and a time interval (in thousandths of a second).

timerFunction

A reference to an object of the ICountedPointerTo template class that was created using a class derived from ITimerFn. You must dynamically allocate the ITimerFn object using operator new.

timerInterval

A value that represents the time interval. One second (1000 milliseconds) is the default.

This constructor is equivalent to using the default constructor and calling ITimer::start. Therefore, use this form of the constructor to construct a new ITimer and immediately start it.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

Overload 4

public:
ITimer(const ITimer& timer)

timer

A reference to an existing timer object.

Constructs an ITimer object from an existing ITimer object.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

operator =

public:
ITimer& operator =(const ITimer& timer)

Assigns an ITimer object to reference an existing timer.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Use these members to compare ITimer objects.

---

operator ==

public:
bool operator ==(const ITimer timer)

Returns true if and only if the timers are identical.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Use these members for diagnostic purposes. They return IString representations of the timer diagnostics.

---

asDebugInfo

public:
virtual IString asDebugInfo() const

Returns a representation of the timer as diagnostic information.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

asString

public:
virtual IString asString() const

Returns a string of the form "ITimer(ID)", where ID is replaced by the actual identifier of the timer.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

After you start a timer, it expires each time a specified time interval passes. Use these members to access the timer expiration interval.

---

interval

public:
unsigned long interval() const

Returns the timer interval (in thousandths of a second).

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

setInterval

public:
virtual ITimer& setInterval(unsigned long interval = 1000)

Sets the timer interval (in thousandths of a second). If no interval is set for a timer, then an interval of one second is used by default.

If this member function is called for a started timer, then the timer is stopped and restarted with the new interval. The ITimerFn being used is saved and used when the timer is restarted.

An interval of 0 causes the timer to expire as quickly as possible.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

OS/2 Considerations

When you run a timer on the OS/2 operating system, an effective minimum of about 1/18 of a second exists for timer intervals.

Use these members to retrieve a timer object using the class ITimer::Cursor.

---

timerAt

public:
static ITimer timerAt(const Cursor& cursor)

Returns an ITimer object at the position indicated by cursor.

Exception

IInvalidParameter

The ITimer::Cursor is invalid.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Use these members to start and stop timers.

---

isStarted

public:
bool isStarted() const

Returns true if the timer is currently active. A timer is not active if you have stopped it or have never started it. The timer will continue to expire as long as it is active.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

start

Starts a time-interval-based operation with an arbitrary ITimerFn object. The ITimerFn is passed in using an ICountedPointerTo object so that ITimer can reference count the ITimerFn object and subsequently delete it when you stop the timer.

ITimer calls the ITimerFn object each time the timer interval expires, until you stop the timer.

---

Overload 1

public:
virtual ITimer&
  start( const ICountedPointerTo < ITimerFn >& timerFunction )

timerFunction

A reference to an object of the ICountedPointerTo template class that was created using a class derived from ITimerFn. You must dynamically allocate the ITimerFn object using operator new.

Exception

IInvalidRequest	The timer has already been started.
IAccessError	The operating system is unable to start the timer.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

Overload 2

public:
virtual ITimer&
  start( const ICountedPointerTo < ITimerFn >& timerFunction,
         unsigned long timerInterval )

timerFunction

A reference to an object of the ICountedPointerTo template class that was created using a class derived from ITimerFn. You must dynamically allocate the ITimerFn object using operator new.

timerInterval

A value that represents the timer interval.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

---

stop

public:
virtual ITimer& stop()

Stops the timer. You must stop the timer to deallocate resources used by the timer.

Exception

IAccessError

The operating system is unable to stop the timer.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

Use these members to access timer information, such as the timer identifier.

---

id

public:
unsigned long id() const

Returns the timer's identifier.

Supported Platforms

Windows	OS/2	AIX
Yes	Yes	Yes

ITimer - Inherited Member Functions and Data

• None

• None

• None

• None