Scarab  v3.9.3
Project 8 C++ Utility Library
Public Member Functions | Static Public Member Functions | Private Types | Static Private Attributes | List of all members
signal_handler Class Reference

Deals with cleanly exiting an application, and includes signal and std::terminate handler functions. More...

#include <signal_handler.hh>

Public Member Functions

 signal_handler ()
 
virtual ~signal_handler ()
 
 snake_case_mv_accessible_static_noset (int, ref_count)
 
 snake_case_mv_accessible_static_noset (bool, exited)
 
 snake_case_mv_accessible_static (int, return_code)
 
 snake_case_mv_accessible_static_noset (bool, handling_sig_abrt)
 
 snake_case_mv_accessible_static_noset (bool, handling_sig_term)
 
 snake_case_mv_accessible_static_noset (bool, handling_sig_int)
 
 snake_case_mv_accessible_static_noset (bool, handling_sig_quit)
 
 snake_case_mv_referrable_static (struct sigaction, old_sig_abrt_action)
 
 snake_case_mv_referrable_static (struct sigaction, old_sig_term_action)
 
 snake_case_mv_referrable_static (struct sigaction, old_sig_int_action)
 
 snake_case_mv_referrable_static (struct sigaction, old_sig_quit_action)
 

Static Public Member Functions

static void add_cancelable (std::shared_ptr< cancelable > a_cancelable)
 Static version: add a cancelable object. More...
 
static void remove_cancelable (std::shared_ptr< cancelable > a_cancelable)
 Static version: remove a cancelable object. More...
 
static void remove_cancelable (cancelable *a_cancelable)
 Static version: remove a cancelable object with a plain pointer. More...
 
static void reset ()
 Remove all cancelables and signal handling. More...
 
static void handle_signals ()
 Start handling signals. More...
 
static void unhandle_signals ()
 Stop handling signals. More...
 
static bool is_handling (int a_signal)
 Check if a signal is handled. More...
 
static void handle_terminate () noexcept
 Handler for std::terminate – does not cleanup memory or threads. More...
 
static void handle_exit_error (int a_sig)
 Handler for error signals – cleanly exits. More...
 
static void handle_exit_success (int a_sig)
 Handler for success signals – cleanly exits. More...
 
static void terminate (int a_code) noexcept
 Main terminate function – does not cleanup memory or threads. More...
 
static void exit (int a_code)
 Main exit function – cleanly exits. More...
 
static void print_current_exception (bool a_use_logging)
 Prints the current exception, if there is one. More...
 
static void print_stack_trace (bool a_use_logging)
 Prints the stack trace. More...
 
static void cancel_all (int a_code)
 Asynchronous call to cancel all cancelables with the given exit code. More...
 

Private Types

typedef std::weak_ptr< cancelablecancelable_wptr_t
 
typedef std::map< cancelable *, cancelable_wptr_tcancelers
 
typedef cancelers::const_iterator cancelers_cit_t
 
typedef cancelers::iterator cancelers_it_t
 

Static Private Attributes

static cancelers s_cancelers
 
static std::recursive_mutex s_mutex
 

Detailed Description

Deals with cleanly exiting an application, and includes signal and std::terminate handler functions.

Author
N. S. Oblath

Exiting and Terminating

This class differentiates between two different ways of finishing a program:

Termination occurs in situations where the program must finish immediately. These are the situations in which std::terminate is used, for example, or there are unhandled exceptions. This can occur during execution, or even during static initialization and cleanup. Therefore only minimal global resources are assumed to be available (e.g. std::cerr). See https://akrzemi1.wordpress.com/2011/10/05/using-stdterminate/ for more information about the way in which termination can be handled. Termination can be commenced by:

Exiting occurs in situations where cleanly shutting down is possible. This includes both successful exiting and exiting with an error condition. signal_handler will be responsible for cancelling all threads that it knows about (via add_cancelable()). After the exit process is complete, it's the responsiblity of the program to stop execution. The program can use get_exited() to check whether the exit process has been used. Exiting can be commenced by:

To cleanly exit, signal_handler takes responsibility for canceling the cancelable objects that it knows about. Responsibility for canceling a cancelable is given to the signal_handler using add_cancelable(), and it's taken away using remove_cancelable().

Signal Handling

To perform the tasks of exiting and terminating applications, signal_handler allows the user to control when signals are handled, and when they aren't. In most cases, a user will control signal handling through the existence of a signal_handler instance. The user should create the instance of signal_handler when they want signal_handler to start handling those signals, and it should be destructed when handling the signals should cease. Here are several examples of how this could be done:

  1. The instance is created as a global static object at static initialization time. Signals will be handled for the entire time the application is running.
  2. The instance is created in the main() function of the application and exists until the application exits.
  3. The instance is created in some function for a specific limited time to cover a particular action. This could be for the entire scope of the function, or it could be destructed when signal handling is no longer wanted.

Note that signals are handled as long as one or more instances of signal_handler exist. If two instance exist, and one goes out of scope, signals are still handled until the second instance is destructed.

In addition to this typical behavior, signal_handler includes an interface for more fine-grained control over when signals are handled while the signal_handler exists (i.e. handle_signals(), unhandle_signals(), and is_handling()), but the recommended use case is as described above, where signal handling is controled by the existence of a signal_handler instance.

Note that the interface for signal_handler uses all static functions, so there is no need to create an extra instance of the class to use any part of that interface. So the creation and destruction of instances can be used to control whether or not signals are handled, and the rest of the interface can be used without an instance.

Cancelables

This class communicates the need to exit to other objects via the cancelable interface. Simply put, a cancelable object can be canceled, or told to exit, asynchronously by the signal_handler. Only the cancelable objects that the user wants to be directly canceled by signal_handler should be added with add_cancelable(). In some cases that might be all of the cancelable objects. In other cases, where there's some hierarchy of cancelables, it would only be the top-level cancelables.

While add_cancelable() takes a std::shared_ptr<cancelable> as an argument, it stores only std::weak_ptr<cancelable>, and claims no ownership or responsibility for the lifetime of the cancelable object.

Manual Cancelation/Exiting/Terminating

In addition to acting automatically via handled signals, a user can manually terminate, exit, or cancel using terminate(), exit(), or cancel_all(), respectively. cancel_all() will only affect the canceled objects. exit() perform a clean exit using cancel_all(), in addition to setting a return code, though it assumes the application will take care of actually exiting. And terminate() will immediately exit the application using std::_Exit().

Definition at line 114 of file signal_handler.hh.

Member Typedef Documentation

◆ cancelable_wptr_t

typedef std::weak_ptr< cancelable > cancelable_wptr_t
private

Definition at line 163 of file signal_handler.hh.

◆ cancelers

typedef std::map< cancelable*, cancelable_wptr_t > cancelers
private

Definition at line 167 of file signal_handler.hh.

◆ cancelers_cit_t

typedef cancelers::const_iterator cancelers_cit_t
private

Definition at line 168 of file signal_handler.hh.

◆ cancelers_it_t

typedef cancelers::iterator cancelers_it_t
private

Definition at line 169 of file signal_handler.hh.

Constructor & Destructor Documentation

◆ signal_handler()

Definition at line 62 of file signal_handler.cc.

◆ ~signal_handler()

~signal_handler ( )
virtual

Definition at line 70 of file signal_handler.cc.

Member Function Documentation

◆ add_cancelable()

void add_cancelable ( std::shared_ptr< cancelable a_cancelable)
static

Static version: add a cancelable object.

Definition at line 80 of file signal_handler.cc.

◆ cancel_all()

void cancel_all ( int  a_code)
static

Asynchronous call to cancel all cancelables with the given exit code.

Definition at line 441 of file signal_handler.cc.

◆ exit()

void exit ( int  a_code)
static

Main exit function – cleanly exits.

Definition at line 376 of file signal_handler.cc.

◆ handle_exit_error()

void handle_exit_error ( int  a_sig)
static

Handler for error signals – cleanly exits.

Definition at line 348 of file signal_handler.cc.

◆ handle_exit_success()

void handle_exit_success ( int  a_sig)
static

Handler for success signals – cleanly exits.

Definition at line 356 of file signal_handler.cc.

◆ handle_signals()

void handle_signals ( )
static

Start handling signals.

Definition at line 101 of file signal_handler.cc.

◆ handle_terminate()

void handle_terminate ( )
staticnoexcept

Handler for std::terminate – does not cleanup memory or threads.

Definition at line 343 of file signal_handler.cc.

◆ is_handling()

bool is_handling ( int  a_signal)
static

Check if a signal is handled.

Definition at line 303 of file signal_handler.cc.

◆ print_current_exception()

void print_current_exception ( bool  a_use_logging)
static

Prints the current exception, if there is one.

Definition at line 390 of file signal_handler.cc.

◆ print_stack_trace()

void print_stack_trace ( bool  a_use_logging)
static

Prints the stack trace.

Definition at line 416 of file signal_handler.cc.

◆ remove_cancelable() [1/2]

static void remove_cancelable ( std::shared_ptr< cancelable a_cancelable)
static

Static version: remove a cancelable object.

◆ remove_cancelable() [2/2]

void remove_cancelable ( scarab::cancelable a_cancelable)
static

Static version: remove a cancelable object with a plain pointer.

Definition at line 94 of file signal_handler.cc.

◆ reset()

void reset ( )
static

Remove all cancelables and signal handling.

Definition at line 330 of file signal_handler.cc.

◆ snake_case_mv_accessible_static()

snake_case_mv_accessible_static ( int  ,
return_code   
)

◆ snake_case_mv_accessible_static_noset() [1/6]

snake_case_mv_accessible_static_noset ( int  ,
ref_count   
)

◆ snake_case_mv_accessible_static_noset() [2/6]

snake_case_mv_accessible_static_noset ( bool  ,
exited   
)

◆ snake_case_mv_accessible_static_noset() [3/6]

snake_case_mv_accessible_static_noset ( bool  ,
handling_sig_abrt   
)

◆ snake_case_mv_accessible_static_noset() [4/6]

snake_case_mv_accessible_static_noset ( bool  ,
handling_sig_term   
)

◆ snake_case_mv_accessible_static_noset() [5/6]

snake_case_mv_accessible_static_noset ( bool  ,
handling_sig_int   
)

◆ snake_case_mv_accessible_static_noset() [6/6]

snake_case_mv_accessible_static_noset ( bool  ,
handling_sig_quit   
)

◆ snake_case_mv_referrable_static() [1/4]

snake_case_mv_referrable_static ( struct sigaction  ,
old_sig_abrt_action   
)

◆ snake_case_mv_referrable_static() [2/4]

snake_case_mv_referrable_static ( struct sigaction  ,
old_sig_term_action   
)

◆ snake_case_mv_referrable_static() [3/4]

snake_case_mv_referrable_static ( struct sigaction  ,
old_sig_int_action   
)

◆ snake_case_mv_referrable_static() [4/4]

snake_case_mv_referrable_static ( struct sigaction  ,
old_sig_quit_action   
)

◆ terminate()

void terminate ( int  a_code)
staticnoexcept

Main terminate function – does not cleanup memory or threads.

Definition at line 364 of file signal_handler.cc.

◆ unhandle_signals()

void unhandle_signals ( )
static

Stop handling signals.

Definition at line 226 of file signal_handler.cc.

Member Data Documentation

◆ s_cancelers

signal_handler::cancelers s_cancelers
staticprivate

Definition at line 171 of file signal_handler.hh.

◆ s_mutex

std::recursive_mutex s_mutex
staticprivate

Definition at line 172 of file signal_handler.hh.


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