# Poco

# class Timer

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

virtual ~Timer();

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();

See also: Poco::Runnable::run()