Aria  2.8.0
ArSignalHandler Class Reference

Signal handling class. More...

#include <ArSignalHandler.h>

Inherits ArASyncTask.

Public Types

enum  Signal {
  SigHUP =1, SigINT, SigQUIT, SigILL,
  SigTRAP, SigABRT, SigBUS, SigFPE,
  SigKILL, SigUSR1, SigSEGV, SigUSR2,
  SigPIPE, SigALRM, SigTERM, SigSTKFLT,
  SigCHLD, SigCONT, SigSTOP, SigTSTP,
  SigTTIN, SigTTOU, SigURG, SigXCPU,
  SigXFSZ, SigVTALRM, SigPROF, SigWINCH,
  SigIO, SigPWR
}
 
- Public Types inherited from ArThread
typedef std::map< ThreadType, ArThread * > MapType
 
enum  Status {
  STATUS_FAILED =1, STATUS_NORESOURCE, STATUS_NO_SUCH_THREAD, STATUS_INVALID,
  STATUS_JOIN_SELF, STATUS_ALREADY_DETATCHED
}
 
typedef pthread_t ThreadType
 

Public Member Functions

virtual void * runThread (void *arg)
 
virtual ~ArSignalHandler ()
 Destructor.
 
- Public Member Functions inherited from ArASyncTask
 ArASyncTask ()
 Constructor.
 
virtual int create (bool joinable=true, bool lowerPriority=true)
 Create the task and start it going.
 
virtual const char * getThreadActivity (void)
 Gets a string that describes what the thread is doing, or NULL if it doesn't know. More...
 
virtual void run (void)
 Run without creating a new thread. More...
 
virtual void runAsync (void)
 Run in its own thread.
 
virtual void * runInThisThread (void *arg=0)
 Internal function used with system threading system to run the new thread. More...
 
virtual void stopRunning (void)
 Stop the thread.
 
virtual ~ArASyncTask ()
 Destructor.
 
- Public Member Functions inherited from ArThread
 ArThread (bool blockAllSignals=true)
 Constructor.
 
 ArThread (ThreadType thread, bool joinable, bool blockAllSignals=true)
 Constructor - starts the thread.
 
 ArThread (ArFunctor *func, bool joinable=true, bool blockAllSignals=true)
 Constructor - starts the thread.
 
virtual void cancel (void)
 Cancel the thread.
 
virtual int detach (void)
 Detatch the thread so it cant be joined.
 
bool getBlockAllSignals (void)
 Do we block all process signals at startup?
 
virtual ArFunctorgetFunc (void) const
 Get the functor that the thread runs.
 
virtual bool getJoinable (void) const
 Get the joinable status of the thread.
 
virtual ThreadType getOSThread (void) const
 Get the underlying os thread type.
 
pid_t getPID (void)
 
virtual bool getRunning (void) const
 Get the running status of the thread.
 
virtual bool getRunningWithLock (void)
 Get the running status of the thread, locking around the variable.
 
virtual const ThreadType * getThread (void) const
 Get the underlying thread type.
 
virtual const char * getThreadName (void)
 Gets the name of the thread.
 
pid_t getTID (void)
 
virtual bool isThreadFinished () const
 Returns whether the thread has been completed and can be deleted. More...
 
virtual bool isThreadStarted () const
 Returns whether the thread has been started. More...
 
virtual int join (void **ret=NULL)
 Join on the thread.
 
int lock (void)
 Lock the thread instance. More...
 
virtual void logThreadInfo (void)
 Logs the information about this thread.
 
virtual void setRunning (bool running)
 Set the running value on the thread.
 
virtual void setThreadName (const char *name)
 Sets the name of the thread.
 
virtual void threadFinished (void)
 Marks the thread as finished and logs useful debugging information. More...
 
virtual void threadStarted (void)
 Marks the thread as started and logs useful debugging information. More...
 
int tryLock (void)
 Try to lock the thread instance without blocking. More...
 
int unlock (void)
 Unlock the thread instance. More...
 
virtual ~ArThread ()
 Destructor.
 

Static Public Member Functions

static void addHandlerCB (ArFunctor1< int > *func, ArListPos::Pos position)
 Add a handler callback. More...
 
static void block (Signal sig)
 Block the given signal. More...
 
static void blockAllThisThread ()
 Block all the signals for the calling thread only.
 
static void blockCommon ()
 Block all the common signals the kill a program. More...
 
static void blockCommonThisThread ()
 Block all the common signals for the calling thread only. More...
 
static void createHandlerNonThreaded ()
 Setup the signal handling for a non-threaded program. More...
 
static void createHandlerThreaded ()
 Setup the signal handling for a multi-threaded program. More...
 
static void delAllHandlerCBs (void)
 Removes all the handlers. More...
 
static void delHandlerCB (ArFunctor1< int > *func)
 Remove a handler callback. More...
 
static ArSignalHandlergetHandler ()
 Get a pointer to the single ArSignalHandler instance. More...
 
static void handle (Signal sig)
 Handle the given signal. More...
 
static void logThread (void)
 
static const char * nameSignal (int sig)
 Get the name of the given signal.
 
static void signalCB (int sig)
 
static void unblock (Signal sig)
 Unblock the given signal. More...
 
static void unblockAll ()
 Unblock all the signals. More...
 
static void unhandle (Signal sig)
 Dont handle the given signal. More...
 
- Static Public Member Functions inherited from ArThread
static void cancelAll (void)
 Cancel all threads.
 
static ArLog::LogLevel getLogLevel (void)
 Gets the logging level for thread information.
 
static ThreadType getThisOSThread (void)
 Get the underlying os thread type of this thread.
 
static const ThreadType * getThisThread (void)
 Get the underlying thread type of this thread.
 
static const char * getThisThreadName (void)
 Gets the name of the this thread.
 
static void init (void)
 Initialize the internal book keeping structures. More...
 
static void joinAll (void)
 Join on all threads.
 
static ThreadType osSelf (void)
 Returns the os self of the current thread. More...
 
static ArThreadself (void)
 Returns the instance of your own thread (the current one) More...
 
static void setLogLevel (ArLog::LogLevel level)
 Sets the logging level for thread information.
 
static void shutdown ()
 Shuts down and deletes the last remaining thread; call after joinAll.
 
static void stopAll ()
 Stop all threads.
 
static void yieldProcessor (void)
 Yield the processor to another thread.
 

Static Protected Member Functions

static void initSigMap ()
 
- Static Protected Member Functions inherited from ArThread
static void addThreadToMap (ThreadType pt, ArThread *at)
 
static ArThreadfindThreadInMap (ThreadType t)
 
static void removeThreadFromMap (ThreadType t)
 

Protected Attributes

bool ourIgnoreQUIT
 
- Protected Attributes inherited from ArThread
bool myBlockAllSignals
 
bool myFinished
 
ArFunctormyFunc
 
bool myJoinable
 
ArMutex myMutex
 
std::string myName
 
pid_t myPID
 
bool myRunning
 State variable to denote when the thread should continue or exit.
 
bool myStarted
 
ArStrMap myStrMap
 
ThreadType myThread
 
pid_t myTID
 

Static Protected Attributes

static sigset_t ourBlockSigSet
 
static std::list< ArFunctor1< int > * > ourHandlerList
 
static sigset_t ourHandleSigSet
 
static ArStrMap ourSigMap
 
static ArSignalHandlerourSignalHandler =0
 
- Static Protected Attributes inherited from ArThread
static ArLog::LogLevel ourLogLevel = ArLog::Verbose
 
static MapType ourThreads
 
static ArMutex ourThreadsMutex
 
static std::string ourUnknownThreadName = "unknown"
 

Additional Inherited Members

- Protected Member Functions inherited from ArThread
virtual int doJoin (void **ret=NULL)
 

Detailed Description

Signal handling class.

This is a signal handling class. It has both a threaded and non-threaded mode of operation. The non-threaded mode will work in a threaded application but it is best to use the threaded mode. The benefit of the threaded mode is that if the signal incures some processing, but does not shutdown the program (ie. SIGUSR1 or SIGUSR2), the threaded mode will handle the signal in its own thread and hopefully that will not hurt the performance of the tight loop robot control. Exaclty how much performance you get out of this depends on your machines physical hardware and exactly what the processing the signal handler does. For instance, a multi-processor machine has a much greater chance of the signal handler not interfering with the robot control loop.

See the Aria main class for how to initialize a default setup of the signal handling.

There are functions to block, unblock, handle and unhandle signals. These functions all must be called before creating the signalhandler. In either single or multi-threaded mode. The functions to block and handle signals creates a set of blocking and handling which is then used by the create functions to tell the Linux kernel what to do.

In the threaded mode, there is a signal handler thread that is created. That thread is created in a detached state, which means it can not be joined on. When the program exits, the signal handler thread will be ignored and that thread will never exit its run loop. This is perfectly fine behavior. There is no state that can be messed up in this fashion. It is just easier to exit the program than to try to wake up that thread and get it to exit itself.

This class is for Linux only. Windows has virtualy no support for signals and the little support that it does have is not realy usefull. There is an empty implementation of this class for Windows so that code can compile in both Linux and Windows. Just do not expect the code that uses this signal handling to do anything in Windows. This should not be a problem since signals are not used in Windows.

Member Function Documentation

◆ addHandlerCB()

void ArSignalHandler::addHandlerCB ( ArFunctor1< int > *  func,
ArListPos::Pos  position 
)
static

Add a handler callback.

Add a handler callback to the list of callbacks.

When there is a signal sent to the process, the list of callbacks are invoked and passed the signal number.

Parameters
funcfunctor created from ArFunctorC1<int> which refers to the function to call.
positionwhether to place the functor first or last

◆ block()

void ArSignalHandler::block ( Signal  sig)
static

Block the given signal.

Call this before calling createHandlerNonThreaded or createHandlerThreaded.

Parameters
sigthe number of the signal

◆ blockCommon()

void ArSignalHandler::blockCommon ( )
static

Block all the common signals the kill a program.

Sets the signal handler to block all the common signals.

The 'common' signals are SIGHUP, SIGINT, SIGQUIT, SIGTERM, SIGSEGV, and SIGPIPE. Call this before calling createHandlerNonThreaded or createHandlerThreaded.

◆ blockCommonThisThread()

void ArSignalHandler::blockCommonThisThread ( )
static

Block all the common signals for the calling thread only.

Block all the common signals for the calling thread.

The calling thread will never receive the common signals which are SIGHUP, SIGINT, SIGQUIT, and SIGTERM. This function can be called at any time.

◆ createHandlerNonThreaded()

void ArSignalHandler::createHandlerNonThreaded ( )
static

Setup the signal handling for a non-threaded program.

Sets up the signal handling for a non-threaded program.

When the program This uses the system call signal(2). This should not be used if you have a threaded program.

See also
createHandlerThreaded

◆ createHandlerThreaded()

void ArSignalHandler::createHandlerThreaded ( )
static

Setup the signal handling for a multi-threaded program.

Sets up the signal handling for a threaded program.

This call is only useful for Linux. This will create a dedicated thread in which to handle signals. The thread calls sigwait(3) and waits for a signal to be sent. By default all ArThread instances block all signals. Thus the signal is sent to the signal handler thread. This will allow the other threads to continue uninterrupted and not skew their timing loops.

See also
createHandlerNonThreaded

◆ delAllHandlerCBs()

void ArSignalHandler::delAllHandlerCBs ( void  )
static

Removes all the handlers.

Removes all of the signal handler callback from the list of callbacks.

◆ delHandlerCB()

void ArSignalHandler::delHandlerCB ( ArFunctor1< int > *  func)
static

Remove a handler callback.

Remove a handler callback from the list of callbacks.

Parameters
funcfunctor created from ArFunctorC1<int> which refers to the function to call.

◆ getHandler()

ArSignalHandler * ArSignalHandler::getHandler ( )
static

Get a pointer to the single ArSignalHandler instance.

Get a pointer to the single instance of the ArSignalHandler.

The signal handler uses the singleton model, which means there can only be one instance of ArSignalHandler. If the single instance of ArSignalHandler has not been created, getHandler will create it. This is how the handler should be created.

Returns
returns a pointer to the instance of the signal handler

◆ handle()

void ArSignalHandler::handle ( Signal  sig)
static

Handle the given signal.

All the handler callbacks will be called with this signal when it is received. Call this before calling createHandlerNonThreaded or createHandlerThreaded.

Parameters
sigthe number of the signal

◆ unblock()

void ArSignalHandler::unblock ( Signal  sig)
static

Unblock the given signal.

Call this before calling createHandlerNonThreaded or createHandlerThreaded.

Parameters
sigthe number of the signal

◆ unblockAll()

void ArSignalHandler::unblockAll ( )
static

Unblock all the signals.

Call this before calling createHandlerNonThreaded or createHandlerThreaded.

◆ unhandle()

void ArSignalHandler::unhandle ( Signal  sig)
static

Dont handle the given signal.

Do not handle the given signal.

Call this before calling createHandlerNonThreaded or createHandlerThreaded.

Parameters
sigthe number of the signal

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