A Watchdog object can be used by applications to limit the amount of processing time taken by a block of code. More...

#include <be_time_watchdog.h>

Public Member Functions
	Watchdog (const uint8_t type)
	Construct a new Watchdog object. More...

uint64_t	getInterval () const noexcept
	Obtain the timer interval. More...

void	setInterval (uint64_t interval)
	Set the interval for the timer, but don't start the timer. More...

void	start ()
	Start a watchdog timer. More...

void	stop ()
	Stop a watchdog timer. More...

bool	expired ()
	Indicate whether the watchdog timer expired. More...

void	setCanSigJump ()
	Indicate that the signal handler can jump into the application code after handling the signal. More...

void	clearCanSigJump ()
	Clears the flag for the Watchdog object to indicate that the signal jump block is no longer valid. More...

void	setExpired ()
	Set a flag to indicate the timer expired. More...

void	clearExpired ()
	Clear the flag indicating the timer expired. More...

void	setEnabled (const bool enabled)
	Enable or disable the timer. More...

bool	isEnabled () const
	Check the enabled status of the timer. More...

Static Public Attributes
static const uint8_t	PROCESSTIME = 0
	A Watchdog based on process time. More...

static const uint8_t	REALTIME = 1
	A Watchdog based on real (wall clock) time. More...

static bool	_canSigJump

static sigjmp_buf	_sigJumpBuf

Detailed Description

A Watchdog object can be used by applications to limit the amount of processing time taken by a block of code.

A Watchdog object is used to set a timer that, upon expiration, will force a jump to a location within the process. An application can detect whether the timer expired at that point in the code. Watchdog builds on the POSIX setitimer(2) call. Timer intervals are in terms of process virtual time or real time, based on how the object is constructed.

Most applications will not directly invoke the methods of the WatchDog class, instead using the BEGIN_WATCHDOG_BLOCK() and END_WATCHDOG_BLOCK() macros. Applications should not install their own signal handlers, but use the SignalManager class instead.

The BEGIN_WATCHDOG_BLOCK() macro sets up the jump block and tells the Watchdog object to start handling the alarm signal. Applications must call setInterval() before invoking the BEGIN_WATCHDOG_BLOCK() macro.

The END_WATCHDOG_BLOCK() macro disables the watchdog timer, but doesn't affect the assigned interval value. Applications can set the interval once and use the block macros repeatedly. Failure to call setInterval() results in an effectively disabled timer, as does setting the interval to 0.

The ABORT_WATCHDOG() macro also disables the watchdog timer but does not create the code point destination for the jump point. This macro should be used to disable a Watchdog object when the application is no longer interested in the timeout condition.

Attention: The BEGIN_WATCHDOG_BLOCK() macro must be paired with either the END_WATCHDOG_BLOCK() macro or ABORT_WATCHDOG_BLOCK() macro. Failure to do so may result in undefined behavior as a running Watchdog timer may expire, forcing a jump into an incompletely initialized function.

Note: Process virtual timing may not be available on all systems. In those cases, an application compilation error will occur because PROCESSTIME will not be defined.

Attention: On many systems, the sleep(3) call is implemented using alarm signals, the same technique used by the Watchdog class. Therefore, applications should not call sleep(3) inside the Watchdog block; behavior is undefined in that case, but usually results in cancellation of the Watchdog timer.; The setCanSigJump(), clearCanSigJump(), setExpired() and clearExpired() methods are not meant to be used directly by applications, which should use the BEGIN_WATCHDOG_BLOCK()/END_WATCHDOG_BLOCK() macro pair.

See also: Error::SignalManager

Definition at line 118 of file be_time_watchdog.h.

Constructor & Destructor Documentation

◆ Watchdog()

BiometricEvaluation::Time::Watchdog::Watchdog ( const uint8_t type )

Construct a new Watchdog object.

Parameters

[in] type The type of timer, ProcessTime or RealTime.

Exceptions

Error::NotImplemented	The type of watchdog requested is not implemented.
Error::ParameterError	The type is invalid.

Warning: Watchdog::PROCESSTIME is not supported under Cygwin.

Member Function Documentation

◆ getInterval()

uint64_t BiometricEvaluation::Time::Watchdog::getInterval ( ) const

noexcept

Obtain the timer interval.

Returns: Current timer interval.

◆ setInterval()

void BiometricEvaluation::Time::Watchdog::setInterval ( uint64_t interval )

Set the interval for the timer, but don't start the timer.

Setting a value of 0 will essentially disable the timer. Timer intervals are in microseconds, however actual intervals are dependent on the resolution of the system clock, and may not be at microsecond resolution.

Parameters

[in] interval The timer interval, in microseconds.

◆ start()

void BiometricEvaluation::Time::Watchdog::start ( )

Start a watchdog timer.

Exceptions

Error::StrategyError Could not register the signal handler, or could not create the timer.

◆ stop()

void BiometricEvaluation::Time::Watchdog::stop ( )

Stop a watchdog timer.

Exceptions

Error::StrategyError Could not clear the timer.

◆ expired()

bool BiometricEvaluation::Time::Watchdog::expired ( )

Indicate whether the watchdog timer expired.

Returns: true if the timer expired, false otherwise.

◆ setCanSigJump()

void BiometricEvaluation::Time::Watchdog::setCanSigJump ( )

Indicate that the signal handler can jump into the application code after handling the signal.

◆ clearCanSigJump()

void BiometricEvaluation::Time::Watchdog::clearCanSigJump ( )

Clears the flag for the Watchdog object to indicate that the signal jump block is no longer valid.

◆ setExpired()

void BiometricEvaluation::Time::Watchdog::setExpired ( )

Set a flag to indicate the timer expired.

◆ clearExpired()

void BiometricEvaluation::Time::Watchdog::clearExpired ( )

Clear the flag indicating the timer expired.

◆ setEnabled()

void BiometricEvaluation::Time::Watchdog::setEnabled ( const bool enabled )

Enable or disable the timer.

Parameters

enabled true if enabled, false otherwise.

Note: This enables easier debugging without changing sourcecode to remove Watchdog blocks.

◆ isEnabled()

bool BiometricEvaluation::Time::Watchdog::isEnabled ( ) const

Check the enabled status of the timer.

Member Data Documentation

◆ PROCESSTIME

const uint8_t BiometricEvaluation::Time::Watchdog::PROCESSTIME = 0

static

A Watchdog based on process time.

Definition at line 122 of file be_time_watchdog.h.

◆ REALTIME

const uint8_t BiometricEvaluation::Time::Watchdog::REALTIME = 1

static

A Watchdog based on real (wall clock) time.

Definition at line 124 of file be_time_watchdog.h.

◆ _canSigJump

bool BiometricEvaluation::Time::Watchdog::_canSigJump

static

Definition at line 233 of file be_time_watchdog.h.

◆ _sigJumpBuf

sigjmp_buf BiometricEvaluation::Time::Watchdog::_sigJumpBuf

static

Definition at line 234 of file be_time_watchdog.h.

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

be_time_watchdog.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Watchdog()

Member Function Documentation

◆ getInterval()

◆ setInterval()

◆ start()

◆ stop()

◆ expired()

◆ setCanSigJump()

◆ clearCanSigJump()

◆ setExpired()

◆ clearExpired()

◆ setEnabled()

◆ isEnabled()

Member Data Documentation

◆ PROCESSTIME

◆ REALTIME

◆ _canSigJump

◆ _sigJumpBuf