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 (void);
  46
  47   /// Destructor
  48   virtual ~ACE_Sig_Handler (void);
  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 (void);
  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 *,
  98                         ucontext_t *);
  99
 100   /// Dump the state of an object.
 101   void dump (void) const;
 102
 103   /// Declare the dynamic allocation hooks.
 104   ACE_ALLOC_HOOK_DECLARE;
 105
 106 protected:
 107   // = These methods and data members are shared by derived classes.
 108
 109   /**
 110    * Set a new ACE_Event_Handler that is associated with @a signum.
 111    * Return the existing handler.  Does not acquire any locks so that
 112    * it can be called from a signal handler, such as <dispatch>.
 113    */
 114   static ACE_Event_Handler *handler_i (int signum,
 115                                        ACE_Event_Handler *);
 116
 117   /**
 118    * This implementation method is called by <register_handler> and
 119    * @c dispatch.  It doesn't do any locking so that it can be called
 120    * within a signal handler, such as @c dispatch.  It adds a new
 121    * ACE_Event_Handler and a new sigaction associated with @a signum.
 122    * Passes back the existing ACE_Event_Handler and its sigaction if
 123    * pointers are non-zero.  Returns -1 on failure and >= 0 on
 124    * success.
 125    */
 126   static int register_handler_i (int signum,
 127                                  ACE_Event_Handler *new_sh,
 128                                  ACE_Sig_Action *new_disp = 0,
 129                                  ACE_Event_Handler **old_sh = 0,
 130                                  ACE_Sig_Action *old_disp = 0);
 131
 132   static int remove_handler_i (int signum,
 133                                ACE_Sig_Action *new_disp = 0,
 134                                ACE_Sig_Action *old_disp = 0,
 135                                int sigkey = -1);
 136
 137   /// Check whether the SIGNUM is within the legal range of signals.
 138   static int in_range (int signum);
 139
 140   /// Keeps track of whether a signal is pending.
 141   static sig_atomic_t sig_pending_;
 142
 143 private:
 144   /// Array used to store one user-defined Event_Handler for every
 145   /// signal.
 146   static ACE_Event_Handler *signal_handlers_[ACE_NSIG];
 147 };
 148
 149 /**
 150  * @class ACE_Sig_Handlers
 151  *
 152  * @brief This is an alternative signal handling dispatcher for ACE.  It
 153  * allows a list of signal handlers to be registered for each
 154  * signal.  It also makes SA_RESTART the default mode.
 155  *
 156  * Using this class a program can register one or more
 157  * ACE_Event_Handler with the ACE_Sig_Handler in order to
 158  * handle a designated @a signum.  When a signal occurs that
 159  * corresponds to this @a signum, the <handle_signal> methods of
 160  * all the registered ACE_Event_Handlers are invoked
 161  * automatically.
 162  */
 163 class ACE_Export ACE_Sig_Handlers : public ACE_Sig_Handler
 164 {
 165 public:
 166   /// Default constructor
 167   ACE_Sig_Handlers (void);
 168
 169   // = Registration and removal methods.
 170   /**
 171    * Add a new ACE_Event_Handler and a new sigaction associated with
 172    * @a signum.  Passes back the existing ACE_Event_Handler and its
 173    * sigaction if pointers are non-zero.  Returns -1 on failure and
 174    * a <sigkey> that is >= 0 on success.
 175    */
 176   virtual int register_handler (int signum,
 177                                 ACE_Event_Handler *new_sh,
 178                                 ACE_Sig_Action *new_disp = 0,
 179                                 ACE_Event_Handler **old_sh = 0,
 180                                 ACE_Sig_Action *old_disp = 0);
 181
 182   /**
 183    * Remove an ACE_Event_Handler currently associated with @a signum.
 184    * We remove the handler if (1) its sigkey> matches the @a sigkey
 185    * passed as a parameter or (2) if we've been told to remove all the
 186    * handlers, i.e., @a sigkey == -1.  If a new disposition is given it
 187    * is installed and the previous disposition is returned (if desired
 188    * by the caller).  Returns 0 on success and -1 if @a signum is
 189    * invalid.
 190    */
 191   virtual int remove_handler (int signum,
 192                               ACE_Sig_Action *new_disp = 0,
 193                               ACE_Sig_Action *old_disp = 0,
 194                               int sigkey = -1);
 195
 196   // = Set/get the handler associated with a particular signal.
 197
 198   /// Return the head of the list of ACE_Sig_Handlers associated with
 199   /// SIGNUM.
 200   virtual ACE_Event_Handler *handler (int signum);
 201
 202   /**
 203    * Set a new ACE_Event_Handler that is associated with SIGNUM at
 204    * the head of the list of signals.  Return the existing handler
 205    * that was at the head.
 206    */
 207   virtual ACE_Event_Handler *handler (int signum,
 208                                       ACE_Event_Handler *);
 209
 210   /**
 211    * Callback routine registered with sigaction(2) that dispatches the
 212    * handle_signal() method of all the pre-registered
 213    * ACE_Event_Handlers for @a signum
 214    */
 215   static void dispatch (int signum, siginfo_t *, ucontext_t *);
 216
 217   /// Dump the state of an object.
 218   void dump (void) const;
 219
 220   /// Declare the dynamic allocation hooks.
 221   ACE_ALLOC_HOOK_DECLARE;
 222
 223 private:
 224   /**
 225    * Keeps track of the id that uniquely identifies each registered
 226    * signal handler.  This id can be used to cancel a timer via the
 227    * <remove_handler> method.
 228    */
 229   static int sigkey_;
 230
 231   /// If this is true then a 3rd party library has registered a
 232   /// handler...
 233   static bool third_party_sig_handler_;
 234 };
 235
 236 ACE_END_VERSIONED_NAMESPACE_DECL
 237
 238 #if defined (__ACE_INLINE__)
 239 #include "ace/Sig_Handler.inl"
 240 #endif /* __ACE_INLINE__ */
 241
 242 #include /**/ "ace/post.h"
 243 #endif /* ACE_SIG_HANDLER_H */