Callback_Watchdog Class Reference

Wrapper class which allows to start a timer and if it is not stopped in the given time then the internally subscribed callback will be called, which informs the user of the failure to stop the timer in time, meaning a timeout has occured. More...

#include <Callback_Watchdog.h>

Inheritance diagram for Callback_Watchdog:

Collaboration diagram for Callback_Watchdog:

Public Member Functions
	Callback_Watchdog ()=default
	Constructs empty timeout timer callback, will result in never being called. Internals are simply default constructed as nullptr. More...
	Callback_Watchdog (function callback)
	Constructs callback, will be called if the timeout time passes without detach() being called beforehand. More...
void	once (uint64_t const &timeout_microseconds)
	Starts the watchdog timer once for the given timeout. More...
void	detach ()
	Stops the currently ongoing watchdog timer and ensures the callback is not called. Timer can simply be restarted with calling once() again. More...
void	update ()
	Internally checks if the time already passed, has to be done because we are using a simple software timer. More...
Public Member Functions inherited from Callback< void >
	Callback ()=default
	Constructs empty callback, will result in never being called. Internals are simply default constructed as nullptr. More...
	Callback (function callback)
	Constructor. More...
virtual	~Callback ()=default
	Virtual default destructor, created to ensure that if a pointer to this class is used and deleted, we will also call the derived base class destructor. More...
void	Call_Callback (argument_types const &... arguments) const
	Calls the callback that was subscribed, when this class instance was initally created. More...
void	Set_Callback (function callback)
	Sets the callback method that will be called upon data arrival with the given data that was received. If nullptr is passed the callback will never be called and instead return with a defaulted instance of the requested return variable. More...

Additional Inherited Members
Public Types inherited from Callback< void >
using	function = std::function< void(argument_types... arguments)>
	Callback signature. More...

Detailed Description

Wrapper class which allows to start a timer and if it is not stopped in the given time then the internally subscribed callback will be called, which informs the user of the failure to stop the timer in time, meaning a timeout has occured.

Note

The class wraps around either the Arduino timer class from Arduino (https://github.com/contrem/arduino-timer) or the offical ESP Timer implementation from Espressif (https://github.com/espressif/esp-idf/tree/master/examples/system/esp_timer), the latter takes precendence if it exists. This is done because it uses FreeRTOS to start the actual timer in the background, which removes the need for a Hardware Timer with Interrupts as well as the need for active polling, while still achieve the advantage of accurate timings. For all other use cases where the ESP timer does not exists we instead use the Arduino timer as a fallback, because is is a simple software timer with active polling that works on all Arduino based devices. Tt simply uses the millis() method per default but can be configured over template arguments to use other methods that return the current time.

The class instance is meant to be started with once() which will then call the registered callback after the timeout has passed, if the detach() method has not been called yet. This results in behaviour similair to an ESP task watchdog but without as high of an accuracy and without immediately restarting the device when triggered, allowing to let it fail and handle the error case silently by the user in the callback method. Documentation about the specific uses and caviates of the ESP Timer implementation can be found here https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_timer.html

Constructor & Destructor Documentation

Callback_Watchdog() [1/2]

Callback_Watchdog::Callback_Watchdog ( )

default

Constructs empty timeout timer callback, will result in never being called. Internals are simply default constructed as nullptr.

Callback_Watchdog() [2/2]

Callback_Watchdog::Callback_Watchdog ( function  callback )

inlineexplicit

Constructs callback, will be called if the timeout time passes without detach() being called beforehand.

Parameters

callback

Callback method that will be called as soon as the internal software timers have processed that the given timeout time passed without detach() being called beforehand

Member Function Documentation

detach()

void Callback_Watchdog::detach ( )

inline

Stops the currently ongoing watchdog timer and ensures the callback is not called. Timer can simply be restarted with calling once() again.

once()

void Callback_Watchdog::once ( uint64_t const &  timeout_microseconds )

inline

Starts the watchdog timer once for the given timeout.

Parameters

timeout_microseconds

Amount of microseconds until the detach() method is excpected to have been called or the initally given callback method will be called

update()

void Callback_Watchdog::update ( )

inline

Internally checks if the time already passed, has to be done because we are using a simple software timer.

Note

Indirectly called from the interal processing loop of this library, so we expect the user to relatively often call the internal library loop() function. In the worst case the actual call of the callback method might be massively delayed compared to the original given timeout time.

This is the case if the timeout occured but we just updated the internal time before, that timeout will then only be registered on the next update call. Meaning if we call the internal library loop() function every 500 milliseconds it might be delayed by that time in the worst case.

---

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

• src/Callback_Watchdog.h