Class Timer

Nested Relationships

Nested Types

Class Documentation

class Timer

Interface for timers on POSIX operating systems. 

posix::Timer TiborTheTimer{100_ms, [&]() { fooBar++; }};

// Start a periodic timer
TiborTheTimer.start(true);
// [.. wait ..]
// Timer fires after 100_ms and calls the lambda which increments fooBar

TiborTheTimer.stop();
This class will be DEPRECATED in the near future. In its current form there may still be potential races when start/stop/restart are called concurrently (this includes the callback, which is executed in a separate thread). The implementation also has too much overhead in the callback execution (due to execution logic and potentially multiple callback threads).

It will be replaced with simpler versions for individual use cases, such as a CountdownTimer which can be used for watchdog/keepalive purposes.

Note

Can’t be copied or moved as operating system has a pointer to this object. It needs to be ensured that this object lives longer than timeToWait, otherwise the operating system will unregister the timer @concurrent not thread safe

Public Types

enum class RunMode

Values:

enumerator ONCE
enumerator PERIODIC
enum class CatchUpPolicy

defines the behavior of the timer when the callback runtime is greater than the periodic trigger time. SKIP_TO_NEXT_BEAT skip callback and call it in the next cycle IMMEDIATE call the callback right after the currently running callback is finished TERMINATE terminates the process by calling the errorHandler with POSIX_TIMER__CALLBACK_RUNTIME_EXCEEDS_RETRIGGER_TIME

Values:

enumerator SKIP_TO_NEXT_BEAT
enumerator IMMEDIATE
enumerator TERMINATE

Public Functions

Timer(const units::Duration timeToWait) noexcept

Creates a timer without an operating system callback.

Creates a light-weight timer object that can be used with

  • hasExpiredComparedToCreationTime()

  • resetCreationTime()

Todo:

refactor this cTor and its functionality to a class called StopWatch

Note

Does not set up an operating system timer, but uses CLOCK_REALTIME instead

Parameters:

timeToWait – [in] - How long should be waited?

Timer(const units::Duration timeToWait, const std::function<void()> &callback) noexcept

Creates a timer with an operating system callback.

Initially the timer is stopped.

Note

Operating systems needs a valid reference to this object, hence DesignPattern::Creation can’t be used

Parameters:

  • timeToWait – [in] - How long should be waited?

  • callback – [in] - Function called after timeToWait (User needs to ensure lifetime of function till stop() call)

Timer(const Timer &other) = delete

Move or semantics are forbidden as address of object is not allowed to change.

Timer(Timer &&other) = delete

Move or semantics are forbidden as address of object is not allowed to change.

Timer &operator=(const Timer &other) = delete

Move or semantics are forbidden as address of object is not allowed to change.

Timer &operator=(Timer &&other) = delete

Move or semantics are forbidden as address of object is not allowed to change.

virtual ~Timer() noexcept = default

D’tor.

cxx::expected<TimerError> start(const RunMode runMode, const CatchUpPolicy catchUpPolicy) noexcept

Starts the timer.

The callback is called by the operating system after the time has expired.

Note

Shall only be called when callback is given

Parameters:

  • runMode – [in] for continuous callbacks PERIODIC otherwise ONCE

  • CatchUpPolicy – [in] define behavior when callbackRuntime > timeToWait

cxx::expected<TimerError> stop() noexcept

Disarms the timer.

Note

Shall only be called when callback is given, guarantee after stop() call is callback is immediately called or never at all

cxx::expected<TimerError> restart(const units::Duration timeToWait, const RunMode runMode, const CatchUpPolicy catchUpPolicy) noexcept

Disarms the timer, assigns a new timeToWait value and arms the timer.

Note

Shall only be called when callback is given

Parameters:

  • timeToWait – [in] duration till the callback should be called

  • runMode – [in] for continuous callbacks PERIODIC otherwise ONCE

  • CatchUpPolicy – [in] define behavior when callbackRuntime > timeToWait

cxx::expected<units::Duration, TimerError> timeUntilExpiration() noexcept

Note

Shall only be called when callback is given

cxx::expected<uint64_t, TimerError> getOverruns() noexcept

In case the callback is not immediately called by the operating system, getOverruns() returns the additional overruns that happended in the delay interval.

Note

Shall only be called when callback is given

bool hasError() const noexcept

Returns true if the construction of the object was successful.

TimerError getError() const noexcept

Returns the error that occured on constructing the object.

Public Static Functions

static cxx::expected<units::Duration, TimerError> now() noexcept

creates Duration from the result of clock_gettime(CLOCK_REALTIME, …)

Todo:

maybe move this to a clock implementation?

Returns:

if the clock_gettime call failed TimerError is returned otherwise Duration