Kea: isc::process::IOSignal Class Reference

| Kea 1.5.0

Classes | Public Member Functions | Static Public Member Functions | List of all members
isc::process::IOSignal Class Reference

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:

- io_service_signal.h
- io_service_signal.cc

isc::process::IOSignalPtr
boost::shared_ptr< IOSignal > IOSignalPtr
Defines a pointer to an IOSignal.
Definition: io_service_signal.h:178
isc::process::IOSignalId
uint64_t IOSignalId
Defines a unique identifier type for IOSignal.
Definition: io_service_signal.h:28