Signal Class Reference

RAII wrapper for POSIX signal handler registration. More...

#include <ah-signal.H>

Classes
struct	NoAbortTag

Public Types
using	Handler = void(*)(int)
	Type alias for signal handler function.

Public Member Functions
	Signal (int signo, Handler func, bool restart_calls=true)
	Installs a signal handler.
	~Signal ()
	Restores the previous signal handler.
void	release () noexcept
	Releases ownership of the signal handler.
int	signal_number () const noexcept
	Returns the signal number being handled.
bool	restarts_calls () const noexcept
	Returns whether SA_RESTART is enabled for this handler.
bool	is_active () const noexcept
	Returns whether this object will restore the handler on destruction.
Handler	previous_handler () const noexcept
	Returns the previous handler that will be restored.
const struct sigaction &	previous_action () const noexcept
	Returns the previous sigaction structure.
	Signal (const Signal &)=delete
Signal &	operator= (const Signal &)=delete
	Signal (Signal &&other) noexcept
	Move constructor.
Signal &	operator= (Signal &&other) noexcept
	Move assignment operator.

Static Public Member Functions
static Signal	create (int signo, Handler func, bool restart_calls=true)
	Creates a Signal object or throws on failure.
static Signal	try_create (int signo, Handler func, bool restart_calls, int &error_out)
	Attempts to create a Signal object.

Private Member Functions
	Signal (NoAbortTag, int signo, Handler func, bool restart_calls, int &error_out)

Private Attributes
struct sigaction	old_action_
int	signal_number_
bool	restart_calls_
bool	active_ = true

Detailed Description

RAII wrapper for POSIX signal handler registration.

Installs a signal handler on construction and automatically restores the previous handler when the object is destroyed. This ensures proper cleanup even when exceptions are thrown.

Features

• RAII semantics: Previous handler is automatically restored on destruction.
• SA_RESTART support: System calls can be automatically restarted after signal delivery (except for SIGALRM).
• Move semantics: Signal objects can be moved (but not copied).
• Release mechanism: Option to not restore the handler on destruction.

Special Handling for SIGALRM

For SIGALRM, the SA_INTERRUPT flag is used (if available) instead of SA_RESTART to ensure that blocking calls (like sleep(), read()) are interrupted by the alarm.

Example

void alarm_handler(int) {
    // Handle alarm
}
 
void example() {
    Signal alarm_sig(SIGALRM, alarm_handler);
    alarm(5);  // Set alarm for 5 seconds
 
    // ... do work ...
 
    // When alarm_sig goes out of scope, previous SIGALRM handler is restored
}

Error Handling

By default, the constructor calls abort() if sigaction() fails (for backward compatibility). Use the throwing constructor overload or Signal::try_create() for exception-based error handling.

See also

SignalBlocker for temporarily blocking signals

SignalSet for managing sets of signals

Definition at line 353 of file ah-signal.H.

Member Typedef Documentation

Handler

using Signal::Handler = void (*)(int)

Type alias for signal handler function.

Definition at line 357 of file ah-signal.H.

Constructor & Destructor Documentation

Signal() [1/4]

Signal::Signal ( NoAbortTag  , int  signo, Handler  func, bool  restart_calls, int &  error_out  )

inlineprivate

Definition at line 368 of file ah-signal.H.

References active_, old_action_, and restart_calls_.

Signal() [2/4]

Signal::Signal ( int  signo, Handler  func, bool  restart_calls = true  )

inline

Installs a signal handler.

This constructor maintains backward compatibility by calling abort() if sigaction() fails. For exception-based error handling, use Signal::try_create() or the throwing overload.

Parameters

signo	The signal number to handle (e.g., SIGINT, SIGTERM).
func	The handler function to install. Can be a function pointer, SIG_IGN (to ignore), or SIG_DFL (for default action).
restart_calls	If true (default), interrupted system calls are automatically restarted (SA_RESTART flag). Ignored for SIGALRM.

Warning

Calls abort() if sigaction fails. Use try_create() for exception-based error handling.

Definition at line 416 of file ah-signal.H.

References old_action_, and restart_calls_.

~Signal()

Signal::~Signal ( )

inline

Restores the previous signal handler.

Unless release() was called, the destructor restores the signal handler that was in effect before this Signal object was constructed.

Warning

If restoration fails, the destructor prints an error message and calls abort(). This maintains backward compatibility but may not be ideal in all contexts. Consider calling release() if you don't need automatic restoration.

Definition at line 520 of file ah-signal.H.

References active_, old_action_, and signal_number_.

Signal() [3/4]

Signal::Signal ( const Signal &  )

delete

Signal() [4/4]

Signal::Signal ( Signal &&  other )

inlinenoexcept

Move constructor.

Transfers ownership of signal handler management. The moved-from object will not restore the previous handler.

Definition at line 583 of file ah-signal.H.

Member Function Documentation

create()

static Signal Signal::create ( int  signo, Handler  func, bool  restart_calls = true  )

inlinestatic

Creates a Signal object or throws on failure.

Unlike the regular constructor, this factory method throws a SignalError exception instead of calling abort() on failure.

Parameters

signo	The signal number to handle.
func	The handler function to install.
restart_calls	Whether to restart interrupted system calls.

Returns

A Signal object managing the handler.

Exceptions

SignalError

if sigaction fails.

Example

try {
    auto sig = Signal::create(SIGINT, my_handler);
    // ... use sig ...
} catch (const SignalError & e) {
    std::cerr << "Failed to install handler: " << e.what() << std::endl;
}

Definition at line 470 of file ah-signal.H.

Referenced by TEST_F(), and TEST_F().

is_active()

bool Signal::is_active ( ) const

inlinenoexcept

Returns whether this object will restore the handler on destruction.

Definition at line 559 of file ah-signal.H.

References active_.

Referenced by TEST_F(), TEST_F(), TEST_F(), and TEST_F().

operator=() [1/2]

Signal & Signal::operator= ( const Signal &  )

delete

operator=() [2/2]

Signal & Signal::operator= ( Signal &&  other )

inlinenoexcept

Move assignment operator.

If this object is active, restores its handler before taking ownership from the other object.

Definition at line 598 of file ah-signal.H.

References active_, old_action_, restart_calls_, and signal_number_.

previous_action()

const struct sigaction & Signal::previous_action ( ) const

inlinenoexcept

Returns the previous sigaction structure.

Definition at line 568 of file ah-signal.H.

References old_action_.

previous_handler()

Handler Signal::previous_handler ( ) const

inlinenoexcept

Returns the previous handler that will be restored.

Definition at line 562 of file ah-signal.H.

References old_action_.

Referenced by TEST_F().

release()

void Signal::release ( )

inlinenoexcept

Releases ownership of the signal handler.

After calling this method, the destructor will not restore the previous handler. This is useful when you want to permanently change a signal handler.

Example

{
    Signal sig(SIGTERM, my_permanent_handler);
    sig.release();  // Don't restore on destruction
}
// my_permanent_handler is still installed

Definition at line 550 of file ah-signal.H.

References active_.

Referenced by TEST_F().

restarts_calls()

bool Signal::restarts_calls ( ) const

inlinenoexcept

Returns whether SA_RESTART is enabled for this handler.

Definition at line 556 of file ah-signal.H.

References restart_calls_.

Referenced by TEST_F(), TEST_F(), and TEST_F().

signal_number()

int Signal::signal_number ( ) const

inlinenoexcept

Returns the signal number being handled.

Definition at line 553 of file ah-signal.H.

References signal_number_.

Referenced by TEST_F(), TEST_F(), TEST_F(), and TEST_F().

try_create()

static Signal Signal::try_create ( int  signo, Handler  func, bool  restart_calls, int &  error_out  )

inlinestatic

Attempts to create a Signal object.

Non-throwing version that returns success status through an output parameter.

Parameters

	signo	The signal number to handle.
	func	The handler function to install.
	restart_calls	Whether to restart interrupted system calls.
[out]	error_out	Set to errno value on failure, 0 on success.

Returns

A Signal object (check error_out before using).

Example

int err;
Signal sig = Signal::try_create(SIGINT, my_handler, true, err);
if (err != 0) {
    // Handle error
}

Definition at line 503 of file ah-signal.H.

Referenced by TEST_F().

Member Data Documentation

active_

bool Signal::active_ = true

private

Definition at line 363 of file ah-signal.H.

Referenced by Signal(), ~Signal(), is_active(), operator=(), and release().

old_action_

struct sigaction Signal::old_action_

private

Definition at line 360 of file ah-signal.H.

Referenced by Signal(), Signal(), ~Signal(), operator=(), previous_action(), and previous_handler().

restart_calls_

bool Signal::restart_calls_

private

Definition at line 362 of file ah-signal.H.

Referenced by Signal(), Signal(), operator=(), and restarts_calls().

signal_number_

int Signal::signal_number_

private

Definition at line 361 of file ah-signal.H.

Referenced by ~Signal(), operator=(), and signal_number().

---

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

• ah-signal.H