Scarab  v3.9.1
Project 8 C++ Utility Library
Public Member Functions | Protected Attributes | Private Member Functions | List of all members
cancelable Class Reference

Base class for a cancelable object (i.e. an object that can be canceled by scarab::signal_handler or other client code) More...

#include <cancelable.hh>

Inheritance diagram for cancelable:
Inheritance graph

Public Member Functions

 cancelable ()
 
 cancelable (const cancelable &a_orig)
 
 cancelable (cancelable &&a_orig)
 
virtual ~cancelable ()
 
cancelableoperator= (const cancelable &a_orig)
 
cancelableoperator= (cancelable &&a_orig)
 
void cancel (int a_code=0)
 asynchronous cancel function More...
 
void reset_cancel ()
 reset to non-canceled state More...
 
bool is_canceled () const
 check canceled state More...
 

Protected Attributes

std::atomic< bool > f_canceled
 

Private Member Functions

virtual void do_cancellation (int a_code)
 
virtual void do_reset_cancellation ()
 

Detailed Description

Base class for a cancelable object (i.e. an object that can be canceled by scarab::signal_handler or other client code)

Author
N. S. Oblath

A cancelable object is one which has some execution operation that should be asynchronously cancelable. Cancellation is performed using cancelable::cancel().

For example, if the object of a derived class is executing in thread 1, client code in thread 2 or a signal (e.g. SIGINT) from the user or a system should be able to cancel execution.

If a derived class has a function execute() that performs the main execution loop, that loop should include a periodic check of cancelable::is_canceled() to know whether to exit the loop.

Any actions that should take place when cancelable::cancel() is used should be implemented by the derived class in do_cancellation().

Cancelable objects can exist within a parent/child hierarchy to ensure that execution can be cleanly shut down. Parent classes should implement do_cancellation(int) to cancel their children.

For example, if a parent object in thread 1 starts the execution of two children, each in their own thread (i.e. threads 2 and 3), then the parent object should be added to the signal_handler (using signal_handler::add_cancelable()). The parent's implementation of do_cancellation() should take care of calling cancelable::cancel() on each of the children. The children should not be separately added to the signal_handler.

Genreally it's assumed that a top-level-parent cancelable object will be created on the heap using std::shared_ptr (hence why signal_handler adds cancelables using std::shared_ptr<cancelable>).

Definition at line 51 of file cancelable.hh.

Constructor & Destructor Documentation

◆ cancelable() [1/3]

Definition at line 19 of file cancelable.cc.

◆ cancelable() [2/3]

cancelable ( const cancelable a_orig)

Definition at line 23 of file cancelable.cc.

◆ cancelable() [3/3]

cancelable ( cancelable &&  a_orig)

Definition at line 27 of file cancelable.cc.

◆ ~cancelable()

~cancelable ( )
virtual

Definition at line 33 of file cancelable.cc.

Member Function Documentation

◆ cancel()

void cancel ( int  a_code = 0)
inline

asynchronous cancel function

Definition at line 115 of file cancelable.hh.

◆ do_cancellation()

void do_cancellation ( int  a_code)
privatevirtual

Reimplemented in cancelable_wrapper.

Definition at line 54 of file cancelable.cc.

◆ do_reset_cancellation()

void do_reset_cancellation ( )
privatevirtual

Definition at line 62 of file cancelable.cc.

◆ is_canceled()

bool is_canceled ( ) const
inline

check canceled state

Definition at line 129 of file cancelable.hh.

◆ operator=() [1/2]

cancelable & operator= ( const cancelable a_orig)

Definition at line 38 of file cancelable.cc.

◆ operator=() [2/2]

cancelable & operator= ( cancelable &&  a_orig)

Definition at line 44 of file cancelable.cc.

◆ reset_cancel()

void reset_cancel ( )
inline

reset to non-canceled state

Definition at line 122 of file cancelable.hh.

Member Data Documentation

◆ f_canceled

std::atomic< bool > f_canceled
protected

Definition at line 76 of file cancelable.hh.


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