ACE/ace/Sig_Handler.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Sig_Handler.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_SIGNAL_HANDLER_H
  12 #define ACE_SIGNAL_HANDLER_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/ACE_export.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/Event_Handler.h"
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 class ACE_Sig_Action;
  26
  27 /**
  28  * @class ACE_Sig_Handler
  29  *
  30  * @brief This is the main dispatcher of signals for ACE.  It improves
  31  * the existing UNIX signal handling mechanism by allowing C++
  32  * objects to handle signals in a way that avoids the use of
  33  * global/static variables and functions.
  34  *
  35  * Using this class a program can register an ACE_Event_Handler
  36  * with the ACE_Sig_Handler in order to handle a designated
  37  * @a signum.  When a signal occurs that corresponds to this
  38  * @a signum, the @c handle_signal method of the registered
  39  * ACE_Event_Handler is invoked automatically.
  40  */
  41 class ACE_Export ACE_Sig_Handler
  42 {
  43 public:
  44   /// Default constructor.
  45   ACE_Sig_Handler ();
  46
  47   /// Destructor
  48   virtual ~ACE_Sig_Handler ();
  49
  50   // = Registration and removal methods.
  51   /**
  52    * Add a new ACE_Event_Handler and a new sigaction associated with
  53    * @a signum.  Passes back the existing ACE_Event_Handler and its
  54    * sigaction if pointers are non-zero.  Returns -1 on failure and >=
  55    * 0 on success.
  56    */
  57   virtual int register_handler (int signum,
  58                                 ACE_Event_Handler *new_sh,
  59                                 ACE_Sig_Action *new_disp = 0,
  60                                 ACE_Event_Handler **old_sh = 0,
  61                                 ACE_Sig_Action *old_disp = 0);
  62
  63   /**
  64    * Remove the ACE_Event_Handler currently associated with
  65    * @a signum.  @a sigkey is ignored in this implementation since there
  66    * is only one instance of a signal handler.  Install the new
  67    * disposition (if given) and return the previous disposition (if
  68    * desired by the caller).  Returns 0 on success and -1 if @a signum
  69    * is invalid.
  70    */
  71   virtual int remove_handler (int signum,
  72                               ACE_Sig_Action *new_disp = 0,
  73                               ACE_Sig_Action *old_disp = 0,
  74                               int sigkey = -1);
  75
  76   // Set/get signal status.
  77   /// True if there is a pending signal.
  78   static int sig_pending ();
  79
  80   /// Reset the value of sig_pending_ so that no signal is pending.
  81   static void sig_pending (int);
  82
  83   // = Set/get the handler associated with a particular signal.
  84
  85   /// Return the ACE_Sig_Handler associated with @a signum.
  86   virtual ACE_Event_Handler *handler (int signum);
  87
  88   /// Set a new ACE_Event_Handler that is associated with @a signum.
  89   /// Return the existing handler.
  90   virtual ACE_Event_Handler *handler (int signum, ACE_Event_Handler *);
  91
  92   /**
  93    * Callback routine registered with sigaction(2) that dispatches the
  94    * handle_signal() method of the appropriate pre-registered
  95    * ACE_Event_Handler.
  96    */
  97   static void dispatch (int, siginfo_t *, ucontext_t *);
  98
  99   /// Dump the state of an object.
 100   void dump () const;
 101
 102   /// Declare the dynamic allocation hooks.
 103   ACE_ALLOC_HOOK_DECLARE;
 104
 105 protected:
 106   // = These methods and data members are shared by derived classes.
 107
 108   /**
 109    * Set a new ACE_Event_Handler that is associated with @a signum.
 110    * Return the existing handler.  Does not acquire any locks so that
 111    * it can be called from a signal handler, such as dispatch().
 112    */
 113   static ACE_Event_Handler *handler_i (int signum, ACE_Event_Handler *);
 114
 115   /**
 116    * This implementation method is called by register_handler() and
 117    * @c dispatch.  It doesn't do any locking so that it can be called
 118    * within a signal handler, such as @c dispatch.  It adds a new
 119    * ACE_Event_Handler and a new sigaction associated with @a signum.
 120    * Passes back the existing ACE_Event_Handler and its sigaction if
 121    * pointers are non-zero.  Returns -1 on failure and >= 0 on
 122    * success.
 123    */
 124   static int register_handler_i (int signum,
 125                                  ACE_Event_Handler *new_sh,
 126                                  ACE_Sig_Action *new_disp = nullptr,
 127                                  ACE_Event_Handler **old_sh = nullptr,
 128                                  ACE_Sig_Action *old_disp = nullptr);
 129
 130   static int remove_handler_i (int signum,
 131                                ACE_Sig_Action *new_disp = nullptr,
 132                                ACE_Sig_Action *old_disp = nullptr,
 133                                int sigkey = -1);
 134
 135   /// Check whether the SIGNUM is within the legal range of signals.
 136   static int in_range (int signum);
 137
 138   /// Keeps track of whether a signal is pending.
 139   static sig_atomic_t sig_pending_;
 140
 141 private:
 142   /// Array used to store one user-defined Event_Handler for every
 143   /// signal.
 144   static ACE_Event_Handler *signal_handlers_[ACE_NSIG];
 145 };
 146
 147 /**
 148  * @class ACE_Sig_Handlers
 149  *
 150  * @brief This is an alternative signal handling dispatcher for ACE. It
 151  * allows a list of signal handlers to be registered for each
 152  * signal.  It also makes SA_RESTART the default mode.
 153  *
 154  * Using this class a program can register one or more
 155  * ACE_Event_Handler with the ACE_Sig_Handler in order to
 156  * handle a designated @a signum.  When a signal occurs that
 157  * corresponds to this @a signum, the handle_signal() methods of
 158  * all the registered ACE_Event_Handlers are invoked
 159  * automatically.
 160  */
 161 class ACE_Export ACE_Sig_Handlers : public ACE_Sig_Handler
 162 {
 163 public:
 164   /// Default constructor
 165   ACE_Sig_Handlers ();
 166
 167   // = Registration and removal methods.
 168   /**
 169    * Add a new ACE_Event_Handler and a new sigaction associated with
 170    * @a signum.  Passes back the existing ACE_Event_Handler and its
 171    * sigaction if pointers are non-zero.  Returns -1 on failure and
 172    * a sigkey that is >= 0 on success.
 173    */
 174   int register_handler (int signum,
 175                         ACE_Event_Handler *new_sh,
 176                         ACE_Sig_Action *new_disp = 0,
 177                         ACE_Event_Handler **old_sh = 0,
 178                         ACE_Sig_Action *old_disp = 0) override;
 179
 180   /**
 181    * Remove an ACE_Event_Handler currently associated with @a signum.
 182    * We remove the handler if (1) its sigkey> matches the @a sigkey
 183    * passed as a parameter or (2) if we've been told to remove all the
 184    * handlers, i.e., @a sigkey == -1.  If a new disposition is given it
 185    * is installed and the previous disposition is returned (if desired
 186    * by the caller).  Returns 0 on success and -1 if @a signum is
 187    * invalid.
 188    */
 189   int remove_handler (int signum,
 190                       ACE_Sig_Action *new_disp = 0,
 191                       ACE_Sig_Action *old_disp = 0,
 192                       int sigkey = -1) override;
 193
 194   // = Set/get the handler associated with a particular signal.
 195
 196   /// Return the head of the list of ACE_Sig_Handlers associated with
 197   /// @a signum.
 198   ACE_Event_Handler *handler (int signum) override;
 199
 200   /**
 201    * Set a new ACE_Event_Handler that is associated with @a signum at
 202    * the head of the list of signals. Return the existing handler
 203    * that was at the head.
 204    */
 205   ACE_Event_Handler *handler (int signum, ACE_Event_Handler *) override;
 206
 207   /**
 208    * Callback routine registered with sigaction(2) that dispatches the
 209    * handle_signal() method of all the pre-registered
 210    * ACE_Event_Handlers for @a signum
 211    */
 212   static void dispatch (int signum, siginfo_t *, ucontext_t *);
 213
 214   /// Dump the state of an object.
 215   void dump () const;
 216
 217   /// Declare the dynamic allocation hooks.
 218   ACE_ALLOC_HOOK_DECLARE;
 219
 220 private:
 221   /**
 222    * Keeps track of the id that uniquely identifies each registered
 223    * signal handler.  This id can be used to cancel a timer via the
 224    * remove_handler() method.
 225    */
 226   static int sigkey_;
 227
 228   /// If this is true then a 3rd party library has registered a
 229   /// handler...
 230   static bool third_party_sig_handler_;
 231 };
 232
 233 ACE_END_VERSIONED_NAMESPACE_DECL
 234
 235 #if defined (__ACE_INLINE__)
 236 #include "ace/Sig_Handler.inl"
 237 #endif /* __ACE_INLINE__ */
 238
 239 #include /**/ "ace/post.h"
 240 #endif /* ACE_SIG_HANDLER_H */