iox::posix::Timer🔗
Interface for timers on POSIX operating systems. More...
#include <iceoryx_hoofs/posix_wrapper/timer.hpp>
Public Types🔗
| Name | |
|---|---|
| enum | RunMode { ONCE, PERIODIC} |
| enum | 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 Functions🔗
| Name | |
|---|---|
| Timer(const units::Duration timeToWait) Creates a timer without an operating system callback. |
|
| Timer(const units::Duration timeToWait, const std::function< void()> & callback) Creates a timer with an operating system callback. |
|
| Timer(const Timer & other) Move or semantics are forbidden as address of object is not allowed to change. |
|
| Timer(Timer && other) Move or semantics are forbidden as address of object is not allowed to change. |
|
| Timer & | operator=(const Timer & other) Move or semantics are forbidden as address of object is not allowed to change. |
| Timer & | operator=(Timer && other) Move or semantics are forbidden as address of object is not allowed to change. |
| virtual | ~Timer() =default D'tor. |
| cxx::expected< TimerError > | start(const RunMode runMode, const CatchUpPolicy catchUpPolicy) Starts the timer. |
| cxx::expected< TimerError > | stop() Disarms the timer. |
| cxx::expected< TimerError > | restart(const units::Duration timeToWait, const RunMode runMode, const CatchUpPolicy catchUpPolicy) Disarms the timer, assigns a new timeToWait value and arms the timer. |
| cxx::expected< units::Duration, TimerError > | timeUntilExpiration() |
| cxx::expected< uint64_t, TimerError > | getOverruns() In case the callback is not immediately called by the operating system, getOverruns() returns the additional overruns that happended in the delay interval. |
| bool | hasError() const Returns true if the construction of the object was successful. |
| TimerError | getError() const Returns the error that occured on constructing the object. |
| cxx::expected< units::Duration, TimerError > | now() creates Duration from the result of clock_gettime(CLOCK_REALTIME, ...) |
Detailed Description🔗
class iox::posix::Timer;
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
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.
Public Types Documentation🔗
enum RunMode🔗
| Enumerator | Value | Description |
|---|---|---|
| ONCE | ||
| PERIODIC |
enum CatchUpPolicy🔗
| Enumerator | Value | Description |
|---|---|---|
| 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 Functions Documentation🔗
function Timer🔗
Timer(
const units::Duration timeToWait
)
Creates a timer without an operating system callback.
Parameters:
- 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
Creates a light-weight timer object that can be used with
- hasExpiredComparedToCreationTime()
- resetCreationTime()
function Timer🔗
Timer(
const units::Duration timeToWait,
const std::function< void()> & callback
)
Creates a timer with an operating system callback.
Parameters:
- timeToWait - How long should be waited?
- 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
Initially the timer is stopped.
function Timer🔗
Timer(
const Timer & other
)
Move or semantics are forbidden as address of object is not allowed to change.
function Timer🔗
Timer(
Timer && other
)
Move or semantics are forbidden as address of object is not allowed to change.
function operator=🔗
Timer & operator=(
const Timer & other
)
Move or semantics are forbidden as address of object is not allowed to change.
function operator=🔗
Timer & operator=(
Timer && other
)
Move or semantics are forbidden as address of object is not allowed to change.
function ~Timer🔗
virtual ~Timer() =default
D'tor.
function start🔗
cxx::expected< TimerError > start(
const RunMode runMode,
const CatchUpPolicy catchUpPolicy
)
Starts the timer.
Parameters:
- runMode for continuous callbacks PERIODIC otherwise ONCE
- CatchUpPolicy define behavior when callbackRuntime > timeToWait
Note: Shall only be called when callback is given
The callback is called by the operating system after the time has expired.
function stop🔗
cxx::expected< TimerError > stop()
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
function restart🔗
cxx::expected< TimerError > restart(
const units::Duration timeToWait,
const RunMode runMode,
const CatchUpPolicy catchUpPolicy
)
Disarms the timer, assigns a new timeToWait value and arms the timer.
Parameters:
- timeToWait duration till the callback should be called
- runMode for continuous callbacks PERIODIC otherwise ONCE
- CatchUpPolicy define behavior when callbackRuntime > timeToWait
Note: Shall only be called when callback is given
function timeUntilExpiration🔗
cxx::expected< units::Duration, TimerError > timeUntilExpiration()
Note: Shall only be called when callback is given
function getOverruns🔗
cxx::expected< uint64_t, TimerError > getOverruns()
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
function hasError🔗
bool hasError() const
Returns true if the construction of the object was successful.
function getError🔗
TimerError getError() const
Returns the error that occured on constructing the object.
function now🔗
static cxx::expected< units::Duration, TimerError > now()
creates Duration from the result of clock_gettime(CLOCK_REALTIME, ...)
Return: if the clock_gettime call failed TimerError is returned otherwise Duration
Todo: maybe move this to a clock implementation?
Updated on 18 December 2023 at 13:02:34 CET