xentara::utils::application::TerminateHandler Class Reference

A class that registers handlers that catch termination signals and events. More...

#include <xentara/utils/application/TerminateHandler.hpp>

Inheritance diagram for xentara::utils::application::TerminateHandler:

Classes
struct	ConstructorOptions
	Options for creating terminate handlers. More...

Public Types
enum class	State { Run , Suspend , Terminate }
	States. More...

Public Member Functions
	TerminateHandler (ConstructorOptions options={})
	Constructor that registers the handlers.
	~TerminateHandler ()
	Destructor that unregisters the handlers.

Static Public Member Functions
Wait functions
static auto	wait () -> void
	Waits until the Terminate state has been reached.
static auto	wait (State oldState) -> State
	Waits until the state differs from a given state.
static auto	waitFor (const std::chrono::system_clock::duration &timeout) -> bool
	Waits until the Terminate state has been reached using a relative timeout.
static auto	waitFor (State oldState, const std::chrono::system_clock::duration &timeout) -> State
	Waits until the state differs from a given state using a relative timeout.
static auto	waitUntil (const std::chrono::system_clock::time_point &timeoutTime) -> bool
	Waits until the terminate state has been reached using an absolute timeout.
static auto	waitUntil (State oldState, const std::chrono::system_clock::time_point &timeoutTime) -> State
	Waits until the state differs from a given state using an absolute timeout.
Wait functions that do not throw exceptions
static auto	wait (const std::nothrow_t &tag) noexcept -> void
	Waits until the Terminate state has been reached.
static auto	wait (State oldState, const std::nothrow_t &tag) noexcept -> State
	Waits until the state differs from a given state.
static auto	waitFor (const std::chrono::system_clock::duration &timeout, const std::nothrow_t &tag) noexcept -> bool
	Waits until the Terminate state has been reached using a relative timeout.
static auto	waitFor (State oldState, const std::chrono::system_clock::duration &timeout, const std::nothrow_t &tag) noexcept -> State
	Waits until the state differs from a given state using a relative timeout.
static auto	waitUntil (const std::chrono::system_clock::time_point &timeoutTime, const std::nothrow_t &tag) noexcept -> bool
	Waits until the terminate state has been reached using an absolute timeout.
static auto	waitUntil (State oldState, const std::chrono::system_clock::time_point &timeoutTime, const std::nothrow_t &tag) noexcept -> State
	Waits until the state differs from a given state using an absolute timeout.
static auto	rethrowException () -> void
	Rethrows any exception passed to terminate().
Control function
static auto	terminate () noexcept -> void
	Requests the Terminate state.
static auto	terminate (std::exception_ptr exception) noexcept -> void
	Requests the Terminate state, causing a single waiter to throw.
static auto	suspend () noexcept -> void
	Requests the Suspend state.
static auto	resume () noexcept -> void
	Requests returning to the Run state from the Suspend state.

Detailed Description

A class that registers handlers that catch termination signals and events.

Under Linux, this class registers and unregisters signal handlers for SIGINT, SIGHUP, and SIGTERM. Under Windows, this class registers a console control handler.

Only one single terminate handler must ever exist at any time. Handlers for Linux signals and Windows console control events will be registered as long as that single instance exists.

Note

This class has a number of static functions that enable you to wait for and manipulate the termination state. These functions can be called at anytime, irrespective of whether a handler instance currently exists. Waiting for and manipulating the state works as expected at any time; the TerminateHandler instance only controls the signal handlers and the console control event handler.

Member Enumeration Documentation

State

enum class xentara::utils::application::TerminateHandler::State

strong

States.

Enumerator
Run	the programm should be running
Suspend	the programm should be suspended (if enabled)
Terminate	the programm should terminate

Constructor & Destructor Documentation

TerminateHandler()

xentara::utils::application::TerminateHandler::TerminateHandler

(

ConstructorOptions

options = {}

)

Constructor that registers the handlers.

Parameters

options

The options for the handler

Exceptions

std::logic_error

Another termination handler already exists

~TerminateHandler()

xentara::utils::application::TerminateHandler::~TerminateHandler

(

)

Destructor that unregisters the handlers.

Member Function Documentation

resume()

static auto xentara::utils::application::TerminateHandler::resume ( ) -> void

staticnoexcept

Requests returning to the Run state from the Suspend state.

This function does nothing if the state is not State::Suspend

rethrowException()

static auto xentara::utils::application::TerminateHandler::rethrowException ( ) -> void

static

Rethrows any exception passed to terminate().

Exceptions

Rethrows

any exception passed to terminate()

suspend()

static auto xentara::utils::application::TerminateHandler::suspend ( ) -> void

staticnoexcept

Requests the Suspend state.

This function does nothing if the state is not State::Run

terminate() [1/2]

static auto xentara::utils::application::TerminateHandler::terminate ( ) -> void

staticnoexcept

Requests the Terminate state.

terminate() [2/2]

static auto xentara::utils::application::TerminateHandler::terminate ( std::exception_ptr  exception ) -> void

staticnoexcept

Requests the Terminate state, causing a single waiter to throw.

This function will wake all waiting threads and cause them to rethrow the given exception. Waiters that passed std::nothrow to the wait function will be woken up, but will not rethrow the exception. Once this function has been called, any subsequent call to a non-std::nothrow wait function will throw.

This function does nothing if the state is already State::Terminate. If any overload of termine() has already been called, the exception is simply discarded.

Parameters

exception

The exception that waiters should rethrow

wait() [1/4]

static auto xentara::utils::application::TerminateHandler::wait ( ) -> void

static

Waits until the Terminate state has been reached.

Exceptions

Rethrows

any exception passed to terminate()

wait() [2/4]

static auto xentara::utils::application::TerminateHandler::wait ( const std::nothrow_t &  tag ) -> void

staticnoexcept

Waits until the Terminate state has been reached.

Parameters

tag	Always pass std::nothrow as this parameter

wait() [3/4]

static auto xentara::utils::application::TerminateHandler::wait ( State  oldState ) -> State

static

Waits until the state differs from a given state.

This function will wait until the state is no longer oldState.

Note

Due to the ABA problem, transient changes from Run state to Suspend state and back might not cause the wait to terminate.

Parameters

oldState

The old state. The wait will finish once the state differs from this state. If the state is already different from oldState when this function is called, then the function will return immediately. oldState must not be State::Terminate, as the state cannot ever leave State::Terminate.

Returns

Returns the new state

Exceptions

Rethrows

any exception passed to terminate()

wait() [4/4]

static auto xentara::utils::application::TerminateHandler::wait ( State  oldState, const std::nothrow_t &  tag  ) -> State

staticnoexcept

Waits until the state differs from a given state.

This function will wait until the state is no longer oldState.

Note

Due to the ABA problem, transient changes from [Run](State::Run) state to Suspend state and back might not cause the wait to terminate.

Parameters

oldState	The old state. The wait will finish once the state differs from this state. If the state is already different from oldState when this function is called, then the function will return immediately. oldState must not be State::Terminate, as the state cannot ever leave State::Terminate.
tag	Always pass std::nothrow as this parameter

Returns

Returns the new state

waitFor() [1/4]

static auto xentara::utils::application::TerminateHandler::waitFor ( const std::chrono::system_clock::duration &  timeout ) -> bool

static

Waits until the Terminate state has been reached using a relative timeout.

Parameters

timeout

The timeout.

Returns

Returns true if the Terminate state has been reached, or false on timeout.

Exceptions

Rethrows

any exception passed to terminate()

waitFor() [2/4]

static auto xentara::utils::application::TerminateHandler::waitFor ( const std::chrono::system_clock::duration &  timeout, const std::nothrow_t &  tag  ) -> bool

staticnoexcept

Waits until the Terminate state has been reached using a relative timeout.

This function will wait until the Terminate state has been reached, or until a certain amount of time has elapsed.

Parameters

timeout	The timeout.
tag	Always pass std::nothrow as this parameter

Returns

Returns true if the Terminate state has been reached, or false on timeout.

waitFor() [3/4]

static auto xentara::utils::application::TerminateHandler::waitFor ( State  oldState, const std::chrono::system_clock::duration &  timeout  ) -> State

static

Waits until the state differs from a given state using a relative timeout.

This function will wait until the state is no longer oldState, or until a certain amount of time has elapsed.

Note

Due to the ABA problem, transient changes from [Run](State::Run) state to Suspend state and back might not cause the wait to terminate.

Parameters

oldState	The old state. The wait will finish once the state differs from this state. If the state is already different from oldState when this function is called, then the function will return immediately. oldState must not be State::Terminate, as the state cannot ever leave State::Terminate.
timeout	The timeout.

Returns

Returns the new state, or oldState on timeout.

Exceptions

Rethrows

any exception passed to terminate()

waitFor() [4/4]

static auto xentara::utils::application::TerminateHandler::waitFor ( State  oldState, const std::chrono::system_clock::duration &  timeout, const std::nothrow_t &  tag  ) -> State

staticnoexcept

Waits until the state differs from a given state using a relative timeout.

This function will wait until the state is no longer oldState, or until a certain amount of time has elapsed.

Note

Due to the ABA problem, transient changes from [Run](State::Run) state to Suspend state and back might not cause the wait to terminate.

Parameters

oldState	The old state. The wait will finish once the state differs from this state. If the state is already different from oldState when this function is called, then the function will return immediately. oldState must not be State::Terminate, as the state cannot ever leave State::Terminate.
timeout	The timeout.
tag	Always pass std::nothrow as this parameter

Returns

Returns the new state, or oldState on timeout.

waitUntil() [1/4]

static auto xentara::utils::application::TerminateHandler::waitUntil ( const std::chrono::system_clock::time_point &  timeoutTime ) -> bool

static

Waits until the terminate state has been reached using an absolute timeout.

Parameters

timeoutTime

The timeout time.

Returns

Returns true if the Terminate state has been reached, or false on timeout.

Exceptions

Rethrows

any exception passed to terminate()

waitUntil() [2/4]

static auto xentara::utils::application::TerminateHandler::waitUntil ( const std::chrono::system_clock::time_point &  timeoutTime, const std::nothrow_t &  tag  ) -> bool

staticnoexcept

Waits until the terminate state has been reached using an absolute timeout.

Parameters

timeoutTime	The timeout time.
tag	Always pass std::nothrow as this parameter

Returns

Returns true if the Terminate state has been reached, or false on timeout.

waitUntil() [3/4]

static auto xentara::utils::application::TerminateHandler::waitUntil ( State  oldState, const std::chrono::system_clock::time_point &  timeoutTime  ) -> State

static

Waits until the state differs from a given state using an absolute timeout.

This function will wait until the state is no longer oldState, or until a certain timeout time has been reached.

Note

Due to the ABA problem, transient changes from [Run](State::Run) state to Suspend state and back might not cause the wait to terminate.

Parameters

oldState	The old state. The wait will finish once the state differs from this state. If the state is already different from oldState when this function is called, then the function will return immediately. oldState must not be State::Terminate, as the state cannot ever leave State::Terminate.
timeoutTime	The timeout time.

Returns

Returns the new state, or oldState on timeout.

Exceptions

Rethrows

any exception passed to terminate()

waitUntil() [4/4]

static auto xentara::utils::application::TerminateHandler::waitUntil ( State  oldState, const std::chrono::system_clock::time_point &  timeoutTime, const std::nothrow_t &  tag  ) -> State

staticnoexcept

Waits until the state differs from a given state using an absolute timeout.

This function will wait until the state is no longer oldState, or until a certain timeout time has been reached.

Note

Due to the ABA problem, transient changes from [Run](State::Run) state to Suspend state and back might not cause the wait to terminate.

Parameters

oldState	The old state. The wait will finish once the state differs from this state. If the state is already different from oldState when this function is called, then the function will return immediately. oldState must not be State::Terminate, as the state cannot ever leave State::Terminate.
timeoutTime	The timeout time.
tag	Always pass std::nothrow as this parameter

Returns

Returns the new state, or oldState on timeout.