Represents a collection of signals handled in a customized way. More...

#include <signal_set.h>

Inheritance diagram for isc::util::SignalSet:

Public Member Functions
	SignalSet (const int sig0)
	Constructor installing one signal. More...

	SignalSet (const int sig0, const int sig1)
	Constructor installing two signals. More...

	SignalSet (const int sig0, const int sig1, const int sig2)
	Constructor installing three signals. More...

	~SignalSet ()
	Destructor. More...

void	add (const int sig)
	Installs the handler for the specified signal. More...

void	clear ()
	Uninstalls all signals. More...

int	getNext () const
	Returns a code of the next received signal. More...

void	handleNext (SignalHandler signal_handler)
	Calls a handler for the next received signal. More...

void	remove (const int sig)
	Uninstalls signal handler for a specified signal. More...

Static Public Member Functions
static void	clearOnReceiptHandler ()
	Unregisters the onreceipt signal handler. More...

static bool	invokeOnReceiptHandler (int sig)
	Invokes the onreceipt handler if it exists. More...

static void	setOnReceiptHandler (BoolSignalHandler handler)
	Registers a handler as the onreceipt signal handler. More...

Detailed Description

Represents a collection of signals handled in a customized way.

Kea processes must handle selected signals in a specialized way. For example: SIGINT and SIGTERM must perform a graceful shut down of the server. The SIGHUP signal is used to trigger server's reconfiguration.

This class allows the caller to register one or more signals to catch and process. Signals may be handled either immediately upon arrival and/or recorded and processed later. To process signals immediately, the caller must register an "on-receipt" handler. This handler is expected to return a true or false indicating whether or not the signal has been processed. Signal occurrences that are not processed by the on-receipt handler are remembered by SignalSet for deferred processing. The caller can then query SignalSet at their discretion to determine if any signal occurrences are pending and process them.

SignalSet uses an internal handler to catch all registered signals. When a signal arrives the internal handler will first attempt to invoke the on-receipt handler. If one has been registered it is passed the signal value as an argument and if it returns true upon completion, the internal handler will exit without further action. If the on-receipt handler returned false or one is not registered, then internal handler will record the signal value for deferred processing. Note that once a particular signal has been recorded, any further occurrences of that signal will be discarded until the original occurrence has been processed. This guards against rapid-fire occurrences of the same signal.

Note: This class is not thread safe. It uses static variables and functions to track a global state of signal registration and received signals' queue. But the thread library is signal safe as new threads are created with all signals blocked.

Definition at line 87 of file signal_set.h.

Constructor & Destructor Documentation

◆ SignalSet() [1/3]

isc::util::SignalSet::SignalSet ( const int sig0 )

Constructor installing one signal.

Parameters

sig0	First signal.

Exceptions

SignalSetError If attempting to add duplicated signal or the signal is invalid.

Definition at line 134 of file signal_set.cc.

◆ SignalSet() [2/3]

isc::util::SignalSet::SignalSet	(	const int	sig0,
		const int	sig1
	)

Constructor installing two signals.

Parameters

sig0	First signal.
sig1	Second signal.

Exceptions

SignalSetError If attempting to add duplicated signal or the signal is invalid.

Definition at line 141 of file signal_set.cc.

◆ SignalSet() [3/3]

isc::util::SignalSet::SignalSet	(	const int	sig0,
		const int	sig1,
		const int	sig2
	)

Constructor installing three signals.

Parameters

sig0	First signal.
sig1	Second signal.
sig2	Third signal.

Exceptions

SignalSetError If attempting to add duplicated signal or the signal is invalid.

Definition at line 148 of file signal_set.cc.

◆ ~SignalSet()

isc::util::SignalSet::~SignalSet ( )

Destructor.

Removes installed handlers.

Definition at line 156 of file signal_set.cc.

Member Function Documentation

◆ add()

void isc::util::SignalSet::add ( const int sig )

Installs the handler for the specified signal.

This function adds a signal to the set. When the signal is received by the process, it will be recorded and a signal can be later handled by the process.

Parameters

sig	Signal code.

Exceptions

SignalSetError if signal being added duplicates an existing signal.

Definition at line 168 of file signal_set.cc.

References isc_throw.

◆ clear()

void isc::util::SignalSet::clear ( )

Uninstalls all signals.

This function calls isc::util::SignalSet::remove for each installed signal.

Definition at line 188 of file signal_set.cc.

◆ clearOnReceiptHandler()

void isc::util::SignalSet::clearOnReceiptHandler ( )

static

Unregisters the onreceipt signal handler.

Definition at line 312 of file signal_set.cc.

◆ getNext()

int isc::util::SignalSet::getNext ( ) const

Returns a code of the next received signal.

Returns: A code of the next received signal or -1 if there are no more signals received.

Definition at line 201 of file signal_set.cc.

◆ handleNext()

void isc::util::SignalSet::handleNext ( SignalHandler signal_handler )

Calls a handler for the next received signal.

This function handles the next received signal and removes it from the queue of received signals. While the function is executed, all custom signal handlers are blocked to prevent race condition.

Parameters

signal_handler A pointer to the signal handler function to be used to handle the signal.

Definition at line 233 of file signal_set.cc.

◆ invokeOnReceiptHandler()

bool isc::util::SignalSet::invokeOnReceiptHandler ( int sig )

static

Invokes the onreceipt handler if it exists.

This static method is used by isc::util::SignalSet class to invoke the registered handler (if one) immediately upon receipt of a registered signal.

Prior to invoking the handler, it sets signal action for the given signal to SIG_IGN which prevents any repeat signal occurrences from queuing while the handler is executing. Upon completion of the handler, the signal action is restored which re-enables receipt and handling of the signal.

Parameters

sig	Signal number.

Returns: Boolean false if no on-receipt handler was registered, otherwise it is the value returned by the on-receipt handler.

Definition at line 88 of file signal_set.cc.

References isc_throw, and isc::Exception::what().

Here is the call graph for this function:

◆ remove()

void isc::util::SignalSet::remove ( const int sig )

Uninstalls signal handler for a specified signal.

Parameters

sig	A code of the signal to be removed.

Definition at line 282 of file signal_set.cc.

References isc_throw.

◆ setOnReceiptHandler()

void isc::util::SignalSet::setOnReceiptHandler ( BoolSignalHandler handler )

static

Registers a handler as the onreceipt signal handler.

Sets the given handler as the handler to invoke immediately upon receipt of a a registered signal.

Note: Currently, the on-receipt handler is stored as a static value and hence there may only be one such handler at a time for a given process.

Parameters

handler the signal handler to register

Definition at line 307 of file signal_set.cc.

Referenced by isc::process::DControllerBase::initSignalHandling().

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SignalSet() [1/3]

◆ SignalSet() [2/3]

◆ SignalSet() [3/3]

◆ ~SignalSet()

Member Function Documentation

◆ add()

◆ clear()

◆ clearOnReceiptHandler()

◆ getNext()

◆ handleNext()

◆ invokeOnReceiptHandler()

◆ remove()

◆ setOnReceiptHandler()