Library: Foundation
Package: Threading
Header: Poco/Timer.h
Description
This class implements a thread-based timer. A timer starts a thread that first waits for a given start interval. Once that interval expires, the timer callback is called repeatedly in the given periodic interval. If the interval is 0, the timer is only called once. The timer callback method can stop the timer by setting the timer's periodic interval to 0.
The timer callback runs in its own thread, so multithreading issues (proper synchronization) have to be considered when writing the callback method.
The exact interval at which the callback is called depends on many factors like operating system, CPU performance and system load and may differ from the specified interval.
The time needed to execute the timer callback is not included in the interval between invocations. For example, if the interval is 500 milliseconds, and the callback needs 400 milliseconds to execute, the callback function is nevertheless called every 500 milliseconds. If the callback takes longer to execute than the interval, the callback function will not be called until the next proper interval. The number of skipped invocations since the last invocation will be recorded and can be obtained by the callback by calling skipped().
The timer thread is taken from a thread pool, so there is a limit to the number of available concurrent timers.
Inheritance
Direct Base Classes: Runnable
All Base Classes: Runnable
Member Summary
Member Functions: getPeriodicInterval, getStartInterval, restart, run, setPeriodicInterval, setStartInterval, skipped, start, stop
Inherited Functions: run
Constructors
Timer
Timer(
long startInterval = 0,
long periodicInterval = 0
);
Creates a new timer object. StartInterval and periodicInterval are given in milliseconds. If a periodicInterval of zero is specified, the callback will only be called once, after the startInterval expires. To start the timer, call the Start() method.
Destructor
~Timer 
~Timer() override;
Stops and destroys the timer.
Member Functions
getPeriodicInterval
long getPeriodicInterval() const;
Returns the periodic interval.
getStartInterval
long getStartInterval() const;
Returns the start interval.
restart
void restart();
Restarts the periodic interval. If the callback method is already running, nothing will happen.
restart
void restart(
long milliseconds
);
Sets a new periodic interval and restarts the timer. An interval of 0 will stop the timer.
setPeriodicInterval
void setPeriodicInterval(
long milliseconds
);
Sets the periodic interval. If the timer is already running the new interval will be effective when the current interval expires.
setStartInterval
void setStartInterval(
long milliseconds
);
Sets the start interval. Will only be effective before start() is called.
skipped
long skipped() const;
Returns the number of skipped invocations since the last invocation. Skipped invocations happen if the timer callback function takes longer to execute than the timer interval.
start
void start(
const AbstractTimerCallback & method
);
Starts the timer. Create the TimerCallback as follows:
TimerCallback<MyClass> callback(*this, &MyClass::onTimer); timer.start(callback);
The timer thread is taken from the global default thread pool.
start
void start(
const AbstractTimerCallback & method,
Thread::Priority priority
);
Starts the timer in a thread with the given priority. Create the TimerCallback as follows:
TimerCallback<MyClass> callback(*this, &MyClass::onTimer); timer.start(callback);
The timer thread is taken from the global default thread pool.
start
void start(
const AbstractTimerCallback & method,
ThreadPool & threadPool
);
Starts the timer. Create the TimerCallback as follows:
TimerCallback<MyClass> callback(*this, &MyClass::onTimer); timer.start(callback);
start
void start(
const AbstractTimerCallback & method,
Thread::Priority priority,
ThreadPool & threadPool
);
Starts the timer in a thread with the given priority. Create the TimerCallback as follows:
TimerCallback<MyClass> callback(*this, &MyClass::onTimer); timer.start(callback);
stop
void stop();
Stops the timer. If the callback method is currently running it will be allowed to finish first. WARNING: Never call this method from within the callback method, as a deadlock would result. To stop the timer from within the callback method, call restart(0).
run 
void run() override;
See also: Poco::Runnable::run()