iceoryx_hoofs 2.0.3
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
iox::posix::Timer Class Reference

Interface for timers on POSIX operating systems. More...

#include <iceoryx_hoofs/posix_wrapper/timer.hpp>

Public Types

enum class  RunMode { ONCE , PERIODIC }
 
enum class  CatchUpPolicy { SKIP_TO_NEXT_BEAT , IMMEDIATE , TERMINATE }
 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
 

Public Member Functions

 Timer (const units::Duration timeToWait) noexcept
 Creates a timer without an operating system callback. More...
 
 Timer (const units::Duration timeToWait, const std::function< void()> &callback) noexcept
 Creates a timer with an operating system callback. More...
 
 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.
 
Timeroperator= (const Timer &other)=delete
 Move or semantics are forbidden as address of object is not allowed to change.
 
Timeroperator= (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. More...
 
cxx::expected< TimerError > stop () noexcept
 Disarms the timer. More...
 
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. More...
 
cxx::expected< units::Duration, TimerError > timeUntilExpiration () noexcept
 
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. More...
 
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.
 

Static Public Member Functions

static cxx::expected< units::Duration, TimerError > now () noexcept
 creates Duration from the result of clock_gettime(CLOCK_REALTIME, ...) More...
 

Detailed Description

Interface for timers on POSIX operating systems.

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
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();
Interface for timers on POSIX operating systems.
Definition: timer.hpp:82
cxx::expected< TimerError > start(const RunMode runMode, const CatchUpPolicy catchUpPolicy) noexcept
Starts the timer.

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.

Constructor & Destructor Documentation

◆ Timer() [1/2]

iox::posix::Timer::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()
Parameters
[in]timeToWait- How long should be waited?
Note
Does not set up an operating system timer, but uses CLOCK_REALTIME instead
Todo:
refactor this cTor and its functionality to a class called StopWatch

◆ Timer() [2/2]

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

Creates a timer with an operating system callback.

Initially the timer is stopped.

Parameters
[in]timeToWait- How long should be waited?
[in]callback- Function called after timeToWait (User needs to ensure lifetime of function till stop() call)
Note
Operating systems needs a valid reference to this object, hence DesignPattern::Creation can't be used

Member Function Documentation

◆ getOverruns()

cxx::expected< uint64_t, TimerError > iox::posix::Timer::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

◆ now()

static cxx::expected< units::Duration, TimerError > iox::posix::Timer::now ( )
staticnoexcept

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

Returns
if the clock_gettime call failed TimerError is returned otherwise Duration
Todo:
maybe move this to a clock implementation?

◆ restart()

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

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

Parameters
[in]timeToWaitduration till the callback should be called
[in]runModefor continuous callbacks PERIODIC otherwise ONCE
[in]CatchUpPolicydefine behavior when callbackRuntime > timeToWait
Note
Shall only be called when callback is given

◆ start()

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

Starts the timer.

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

Parameters
[in]runModefor continuous callbacks PERIODIC otherwise ONCE
[in]CatchUpPolicydefine behavior when callbackRuntime > timeToWait
Note
Shall only be called when callback is given

◆ stop()

cxx::expected< TimerError > iox::posix::Timer::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

◆ timeUntilExpiration()

cxx::expected< units::Duration, TimerError > iox::posix::Timer::timeUntilExpiration ( )
noexcept
Note
Shall only be called when callback is given

The documentation for this class was generated from the following file: