Implements an asynchronous "signal" for IOService driven processing. More...

#include <io_service_signal.h>

Classes
class	TimerCallback
	Defines the callback used by IOSignal's internal timer. More...

Public Member Functions
	IOSignal (asiolink::IOService &io_service, int signum, IOSignalHandler handler)
	Constructor. More...

	~IOSignal ()
	Destructor. More...

IOSignalId	getSequenceId () const
	Gets the IOSignal's sequence_id. More...

int	getSignum () const
	Gets the OS signal value this IOSignal represents. More...

Static Public Member Functions
static IOSignalId	nextSequenceId ()
	Static method for generating IOSignal sequence_ids. More...

Detailed Description

Implements an asynchronous "signal" for IOService driven processing.

This class allows a OS signal such as SIGHUP to propagated to an IOService as a ready event with a callback. While boost::asio provides a signal class, it requires linking in additional boost libraries that as of yet we do not need. Therefore, this class was implemented to allow IOService-based processes to handle signals as IOService events.

The mechanics of IOSignal are straight forward. Upon construction it is given the target IOService, the value of the signal to send (i.e. SIGINT, SIGHUP...), and an IOSignalHandler. The IOSignalHandler should contain the logic the caller would normally execute in its OS signal handler. Each IOSignal instance has a unique identifier called its sequence_id.

Internally, IOSignal creates a 1 ms, one-shot timer, on the given IOService. When the timer expires its event handler invokes the caller's IOSignalHandler passing it the sequence_id of the IOSignal.

Sending IOSignals is done through an IOSignalQueue. This class is used to create the signals, house them until they are delivered, and dequeue them so they can be been handled. To generate an IOSignal when an OS signal arrives, the process's OS signal handler simply calls isc::process::IOSignalQueue::pushSignal() with the appropriate values.

Note: that an IOSignalQueue requires a non-null IOServicePtr to construct. This ensures that the IOService cannot be destroyed before any pending signals can be canceled. It also means that a queue can only be used to send signals to that IOService. If you need to send signals to more than one service, each service must have its own queue.

To dequeue the IOSignal inside the caller's IOSignalHandler, one simply invokes isc::process::IOSignalQueue::popSignal() passing it the sequence_id parameter passed to the handler. This method returns a pointer to instigating IOSignal from which the value of OS signal (i.e. SIGINT, SIGUSR1...) can be obtained. Note that calling popSignal() removes the IOSignalPtr from the queue, which should reduce its reference count to zero upon exiting the handler (unless a deliberate copy of it is made).

A typical IOSignalHandler might be structured as follows:

void processSignal(IOSignalId sequence_id) {
    // Pop the signal instance off the queue.
    IOSignalPtr signal = io_signal_queue_->popSignal(sequence_id);
 
    int os_signal_value = signal->getSignum();
    :
    // logic based on the signal value
    :
 }

IOSignal handler invocation code will catch, log ,and then swallow any exceptions thrown by a IOSignalHandler invocation. This is done to protect the integrity IOService context.

Definition at line 93 of file io_service_signal.h.

Constructor & Destructor Documentation

◆ IOSignal()

isc::process::IOSignal::IOSignal	(	asiolink::IOService &	io_service,
		int	signum,
		IOSignalHandler	handler
	)

Constructor.

Parameters

io_service	IOService to which to send the signal
signum	value of the signal to send
handler	the handler to run when IOService "receives" the signal

Exceptions

IOSignalError if handler is null

Definition at line 16 of file io_service_signal.cc.

References isc_throw, and isc::asiolink::IntervalTimer::ONE_SHOT.

◆ ~IOSignal()

isc::process::IOSignal::~IOSignal ( )

Destructor.

Definition at line 33 of file io_service_signal.cc.

Member Function Documentation

◆ getSequenceId()

IOSignalId isc::process::IOSignal::getSequenceId ( ) const

inline

Gets the IOSignal's sequence_id.

Returns: The sequence_id of the signal.

Definition at line 125 of file io_service_signal.h.

◆ getSignum()

int isc::process::IOSignal::getSignum ( ) const

inline

Gets the OS signal value this IOSignal represents.

Returns: The OS signal value (i.e. SIGINT, SIGUSR1...)

Definition at line 132 of file io_service_signal.h.

◆ nextSequenceId()

static IOSignalId isc::process::IOSignal::nextSequenceId ( )

inlinestatic

Static method for generating IOSignal sequence_ids.

Generates and returns the next IOSignalId. This method is intentionally static in the event a process is using generating signals to more than IOService. It assures that each IOSignal is unique with the process space.

Returns: The next sequential value as an IOSignalId.

Definition at line 117 of file io_service_signal.h.

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

Classes

Public Member Functions

Static Public Member Functions