signal_guard.hpp File Reference

#include "config.hpp"
#include "cpp_feature.h"
#include <setjmp.h>
#include <signal.h>
#include <stdbool.h>
#include "bitfield.hpp"
#include <atomic>
#include <cassert>
#include <exception>
#include <new>

Classes
union	raised_signal_info_value
	User defined value. More...
struct	raised_signal_info
	A platform independent subset of siginfo_t. More...
class	quickcpplib::_xxx::signal_guard::signal_guard_install
	On platforms where it is necessary (POSIX), installs, and potentially enables, the global signal handlers for the signals specified by guarded. Each signal installed is threadsafe reference counted, so this is safe to call from multiple threads or instantiate multiple times. It is also guaranteed safe to call from within static data init or deinit, so a very common use case is simply to place an instance into global static data. This ensures that dynamically loaded and unloaded shared objects compose signal guards appropriately. More...
class	quickcpplib::_xxx::signal_guard::signal_guard_global_decider< T >
	Install a global signal continuation decider. More...
class	quickcpplib::_xxx::signal_guard::signal_guard_watchdog< T >
	Call an optional specified routine after a period of time, possibly on another thread. Async signal safe. More...
class	quickcpplib::_xxx::signal_guard::signal_raised
	Thrown by the default signal handler to abort the current operation. More...

Namespaces
namespace	quickcpplib
	The QuickCppLib namespace.
namespace	quickcpplib::_xxx
	Per commit unique namespace to prevent different git submodule versions clashing.
namespace	quickcpplib::_xxx::signal_guard
	The namespace for signal_guard.
namespace	quickcpplib::_xxx::signal_guard::detail

Macros
#define	SIGNALGUARD_CLASS_DECL
#define	SIGNALGUARD_FUNC_DECL   extern
#define	SIGNALGUARD_MEMFUNC_DECL

Typedefs
typedef int	raised_signal_error_code_t
	Typedef to a system specific error code type.
typedef union raised_signal_info_value(*	thrd_signal_guard_guarded_t) (union raised_signal_info_value)
	The type of the guarded function.
typedef union raised_signal_info_value(*	thrd_signal_guard_recover_t) (const struct raised_signal_info *)
	The type of the function called to recover from a signal being raised in a guarded section.
typedef bool(*	thrd_signal_guard_decide_t) (struct raised_signal_info *)
	The type of the function called when a signal is raised. Returns true to continue guarded code, false to recover.
using	quickcpplib::_xxx::signal_guard::raised_signal_info = ::raised_signal_info

Enumerations
enum class	quickcpplib::_xxx::signal_guard::signalc {   quickcpplib::_xxx::signal_guard::none = 0 , quickcpplib::_xxx::signal_guard::abort_process = SIGABRT , quickcpplib::_xxx::signal_guard::undefined_memory_access = SIGBUS , quickcpplib::_xxx::signal_guard::illegal_instruction = SIGILL ,   quickcpplib::_xxx::signal_guard::interrupt , quickcpplib::_xxx::signal_guard::broken_pipe = SIGPIPE , quickcpplib::_xxx::signal_guard::segmentation_fault = SIGSEGV , quickcpplib::_xxx::signal_guard::floating_point_error = SIGFPE ,   quickcpplib::_xxx::signal_guard::process_terminate , quickcpplib::_xxx::signal_guard::timer_expire = SIGALRM , quickcpplib::_xxx::signal_guard::child_exit = SIGCHLD , quickcpplib::_xxx::signal_guard::process_continue = SIGCONT ,   quickcpplib::_xxx::signal_guard::tty_hangup = SIGHUP , quickcpplib::_xxx::signal_guard::process_kill = SIGKILL , quickcpplib::_xxx::signal_guard::profile_event = SIGPROF , quickcpplib::_xxx::signal_guard::process_quit = SIGQUIT ,   quickcpplib::_xxx::signal_guard::process_stop = SIGSTOP , quickcpplib::_xxx::signal_guard::tty_stop = SIGTSTP , quickcpplib::_xxx::signal_guard::bad_system_call = SIGSYS , quickcpplib::_xxx::signal_guard::process_trap = SIGTRAP ,   quickcpplib::_xxx::signal_guard::tty_input = SIGTTIN , quickcpplib::_xxx::signal_guard::tty_output = SIGTTOU , quickcpplib::_xxx::signal_guard::urgent_condition = SIGURG , quickcpplib::_xxx::signal_guard::user_defined1 = SIGUSR1 ,   quickcpplib::_xxx::signal_guard::user_defined2 = SIGUSR2 , quickcpplib::_xxx::signal_guard::virtual_alarm_clock = SIGVTALRM , quickcpplib::_xxx::signal_guard::cpu_time_limit_exceeded = SIGXCPU , quickcpplib::_xxx::signal_guard::file_size_limit_exceeded = SIGXFSZ ,   quickcpplib::_xxx::signal_guard::cxx_out_of_memory = 32 , quickcpplib::_xxx::signal_guard::cxx_termination = 33 , quickcpplib::_xxx::signal_guard::_max_value }
	The signals which are supported. More...

Functions
SIGNALGUARD_FUNC_DECL union raised_signal_info_value	thrd_signal_guard_call (const sigset_t *signals, thrd_signal_guard_guarded_t guarded, thrd_signal_guard_recover_t recovery, thrd_signal_guard_decide_t decider, union raised_signal_info_value value)
	Installs a thread-local signal guard for the calling thread, and calls the guarded function guarded.
SIGNALGUARD_FUNC_DECL bool	thrd_raise_signal (int signo, void *raw_info, void *raw_context)
	Call the currently installed signal handler for a signal (POSIX), or raise a Win32 structured exception (Windows), returning false if no handler was called due to the currently installed handler being SIG_IGN (POSIX).
SIGNALGUARD_FUNC_DECL void *	signal_guard_create (const sigset_t *guarded)
	On platforms where it is necessary (POSIX), installs, and potentially enables, the global signal handlers for the signals specified by guarded. Each signal installed is threadsafe reference counted, so this is safe to call from multiple threads or instantiate multiple times.
SIGNALGUARD_FUNC_DECL bool	signal_guard_destroy (void *i)
	Uninstall a previously installed signal guard.
SIGNALGUARD_FUNC_DECL void *	signal_guard_decider_create (const sigset_t *guarded, bool callfirst, thrd_signal_guard_decide_t decider, union raised_signal_info_value value)
	Create a global signal continuation decider. Threadsafe with respect to other calls of this function, but not reentrant i.e. modifying the global signal continuation decider registry whilst inside a global signal continuation decider is racy. Called after all thread local handling is exhausted. Note that what you can safely do in the decider function is extremely limited, only async signal safe functions may be called.
SIGNALGUARD_FUNC_DECL bool	signal_guard_decider_destroy (void *decider)
	Destroy a global signal continuation decider. Threadsafe with respect to other calls of this function, but not reentrant i.e. do not call whilst inside a global signal continuation decider.
	quickcpplib::_xxx::signal_guard::QUICKCPPLIB_BITFIELD_BEGIN_T (signalc_set, uint64_t)
	Bitfield for the signals which are supported.
SIGNALGUARD_FUNC_DECL const char *	quickcpplib::_xxx::signal_guard::detail::signalc_to_string (signalc code) noexcept
std::atomic< signalc_set > &	quickcpplib::_xxx::signal_guard::detail::signal_guards_installed ()
template<class U , typename = decltype( std::declval<U>()((raised_signal_info *) 0) )>
signal_guard_global_decider< std::decay_t< U > >	quickcpplib::_xxx::signal_guard::make_signal_guard_global_decider (signalc_set guarded, U &&f, bool callfirst=false)
	Convenience instantiator of signal_guard_global_decider.
SIGNALGUARD_FUNC_DECL bool	quickcpplib::_xxx::signal_guard::thrd_raise_signal (signalc signo, void *raw_info=nullptr, void *raw_context=nullptr)
	Call the currently installed signal handler for a signal (POSIX), or raise a Win32 structured exception (Windows), returning false if no handler was called due to the currently installed handler being SIG_IGN (POSIX).
QUICKCPPLIB_NORETURN SIGNALGUARD_FUNC_DECL void	quickcpplib::_xxx::signal_guard::terminate_process_immediately (const char *msg=nullptr) noexcept
	This initiates a fast fail process termination which immediately exits the process without calling any handlers: on POSIX, this is SIGKILL, on Windows this is TerminateProcess().
template<class U , typename = decltype( std::declval<U>()() )>
signal_guard_watchdog< std::decay_t< U > >	quickcpplib::_xxx::signal_guard::make_signal_guard_watchdog (U &&f, unsigned ms=3000)
	Convenience instantiator of signal_guard_watchdog.
signal_guard_watchdog< detail::invoke_terminate_process_immediately >	quickcpplib::_xxx::signal_guard::make_signal_guard_watchdog (unsigned ms=3000)
	Convenience instantiator of signal_guard_watchdog.
SIGNALGUARD_FUNC_DECL void	quickcpplib::_xxx::signal_guard::detail::push_thread_local_signal_handler (thread_local_signal_guard *) noexcept
SIGNALGUARD_FUNC_DECL void	quickcpplib::_xxx::signal_guard::detail::pop_thread_local_signal_handler (thread_local_signal_guard *) noexcept
SIGNALGUARD_FUNC_DECL thread_local_signal_guard *	quickcpplib::_xxx::signal_guard::detail::current_thread_local_signal_handler () noexcept
template<class R >
R	quickcpplib::_xxx::signal_guard::detail::throw_signal_raised (const raised_signal_info *i)
bool	quickcpplib::_xxx::signal_guard::detail::continue_or_handle (const raised_signal_info *) noexcept
template<class F , class H , class C , class... Args, class R = decltype(std::declval<F>()(std::declval<Args>()...)), typename std::enable_if<(detail::is_constructible_or_void< R, decltype(std::declval< H >()(std::declval< const raised_signal_info * >()))>::value), bool >::type = true, typename std::enable_if<(detail::is_constructible_or_void< bool, decltype(std::declval< C >()(std::declval< raised_signal_info * >()))>::value), bool >::type = true>
R	quickcpplib::_xxx::signal_guard::signal_guard (signalc_set guarded, F &&f, H &&h, C &&c, Args &&...args)
template<class F , class R = decltype(std::declval<F>()())>
R	quickcpplib::_xxx::signal_guard::signal_guard (signalc_set guarded, F &&f)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<class F , class H , class R = decltype(std::declval<F>()()), typename std::enable_if<(detail::is_constructible_or_void< R, decltype(std::declval< H >()(std::declval< const raised_signal_info * >()))>::value), bool >::type = true>
auto	quickcpplib::_xxx::signal_guard::signal_guard (signalc_set guarded, F &&f, H &&h)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Macro Definition Documentation

SIGNALGUARD_CLASS_DECL

#define SIGNALGUARD_CLASS_DECL

SIGNALGUARD_FUNC_DECL

#define SIGNALGUARD_FUNC_DECL   extern

SIGNALGUARD_MEMFUNC_DECL

#define SIGNALGUARD_MEMFUNC_DECL

Typedef Documentation

raised_signal_error_code_t

typedef int raised_signal_error_code_t

Typedef to a system specific error code type.

thrd_signal_guard_guarded_t

typedef union raised_signal_info_value(* thrd_signal_guard_guarded_t) (union raised_signal_info_value)

The type of the guarded function.

thrd_signal_guard_recover_t

typedef union raised_signal_info_value(* thrd_signal_guard_recover_t) (const struct raised_signal_info *)

The type of the function called to recover from a signal being raised in a guarded section.

thrd_signal_guard_decide_t

typedef bool(* thrd_signal_guard_decide_t) (struct raised_signal_info *)

The type of the function called when a signal is raised. Returns true to continue guarded code, false to recover.

Function Documentation

thrd_signal_guard_call()

SIGNALGUARD_FUNC_DECL union raised_signal_info_value thrd_signal_guard_call	(	const sigset_t *	signals,
		thrd_signal_guard_guarded_t	guarded,
		thrd_signal_guard_recover_t	recovery,
		thrd_signal_guard_decide_t	decider,
		union raised_signal_info_value	value
	)

Installs a thread-local signal guard for the calling thread, and calls the guarded function guarded.

Returns

The value returned by guarded, or recovery.

Parameters

signals	The set of signals to guard against.
guarded	A function whose execution is to be guarded against signal raises.
recovery	A function to be called if a signal is raised.
decider	A function to be called to decide whether to recover from the signal and continue the execution of the guarded routine, or to abort and call the recovery routine.
value	A value to supply to the guarded routine.

thrd_raise_signal()

SIGNALGUARD_FUNC_DECL bool thrd_raise_signal	(	int	signo,
		void *	raw_info,
		void *	raw_context
	)

Call the currently installed signal handler for a signal (POSIX), or raise a Win32 structured exception (Windows), returning false if no handler was called due to the currently installed handler being SIG_IGN (POSIX).

Note that on POSIX, we fetch the currently installed signal handler and try to call it directly. This allows us to supply custom raw_info and raw_context, and we do all the things which the signal handler flags tell us to do beforehand [1]. If the current handler has been defaulted, we enable the signal and execute pthread_kill(pthread_self(), signo) in order to invoke the default handling.

Note that on Windows, raw_context is ignored as there is no way to override the context thrown with a Win32 structured exception.

[1]: We currently do not implement alternative stack switching. If a handler requests that, we simply abort the process. Code donations implementing support are welcome.

signal_guard_create()

SIGNALGUARD_FUNC_DECL void * signal_guard_create

(

const sigset_t *

guarded

)

On platforms where it is necessary (POSIX), installs, and potentially enables, the global signal handlers for the signals specified by guarded. Each signal installed is threadsafe reference counted, so this is safe to call from multiple threads or instantiate multiple times.

On platforms with better than POSIX global signal support, this function does nothing.

POSIX only

Any existing global signal handlers are replaced with a filtering signal handler, which checks if the current kernel thread has installed a signal guard, and if so executes the guard. If no signal guard has been installed for the current kernel thread, global signal continuation handlers are executed. If none claims the signal, the previously installed signal handler is called.

After the new signal handlers have been installed, the guarded signals are globally enabled for all threads of execution. Be aware that the handlers are installed with SA_NODEFER to avoid the need to perform an expensive syscall when a signal is handled. However this may also produce surprise e.g. infinite loops.

Warning

This class is threadsafe with respect to other concurrent executions of itself, but is NOT threadsafe with respect to other code modifying the global signal handlers.

signal_guard_destroy()

SIGNALGUARD_FUNC_DECL bool signal_guard_destroy

(

void *

i

)

Uninstall a previously installed signal guard.

signal_guard_decider_create()

SIGNALGUARD_FUNC_DECL void * signal_guard_decider_create	(	const sigset_t *	guarded,
		bool	callfirst,
		thrd_signal_guard_decide_t	decider,
		union raised_signal_info_value	value
	)

Create a global signal continuation decider. Threadsafe with respect to other calls of this function, but not reentrant i.e. modifying the global signal continuation decider registry whilst inside a global signal continuation decider is racy. Called after all thread local handling is exhausted. Note that what you can safely do in the decider function is extremely limited, only async signal safe functions may be called.

Returns

An opaque pointer to the registered decider. NULL if malloc failed.

Parameters

guarded	The set of signals to be guarded against.
callfirst	True if this decider should be called before any other. Otherwise call order is in the order of addition.
decider	A decider function, which must return true if execution is to resume, false if the next decider function should be called.
value	A user supplied value to set in the raised_signal_info passed to the decider callback.

signal_guard_decider_destroy()

SIGNALGUARD_FUNC_DECL bool signal_guard_decider_destroy

(

void *

decider

)

Destroy a global signal continuation decider. Threadsafe with respect to other calls of this function, but not reentrant i.e. do not call whilst inside a global signal continuation decider.

Returns

True if recognised and thus removed.