dep/ACE_wrappers/ace/Event_Handler.h

   1 /* -*- C++ -*- */
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Event_Handler.h
   6  *
   7  *  $Id: Event_Handler.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  10  */
  11 //==========================================================================
  12
  13 #ifndef ACE_EVENT_HANDLER_H
  14 #define ACE_EVENT_HANDLER_H
  15 #include /**/ "ace/pre.h"
  16
  17 #include /**/ "ace/ACE_export.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/os_include/os_signal.h"
  24 #include "ace/Atomic_Op.h"
  25 #include "ace/Synch_Traits.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 // Forward declaration.
  30 class ACE_Message_Block;
  31 class ACE_Reactor;
  32 class ACE_Reactor_Timer_Interface;
  33 class ACE_Thread_Manager;
  34 class ACE_Process;
  35
  36 typedef unsigned long ACE_Reactor_Mask;
  37
  38 /**
  39  * @class ACE_Event_Handler
  40  *
  41  * @brief Provides an abstract interface for handling various types of
  42  * I/O, timer, and signal events.
  43  *
  44  * Subclasses read/write input/output on an I/O descriptor,
  45  * handle an exception raised on an I/O descriptor, handle a
  46  * timer's expiration, or handle a signal.
  47  */
  48 class ACE_Export ACE_Event_Handler
  49 {
  50 public:
  51   enum
  52   {
  53     LO_PRIORITY = 0,
  54     HI_PRIORITY = 10,
  55     NULL_MASK = 0,
  56 #if defined (ACE_USE_POLL)
  57     READ_MASK = POLLIN,
  58     WRITE_MASK = POLLOUT,
  59     EXCEPT_MASK = POLLPRI,
  60 #else /* USE SELECT */
  61     READ_MASK = (1 << 0),
  62     WRITE_MASK = (1 << 1),
  63     EXCEPT_MASK = (1 << 2),
  64 #endif /* ACE_USE_POLL */
  65     ACCEPT_MASK = (1 << 3),
  66     CONNECT_MASK = (1 << 4),
  67     TIMER_MASK = (1 << 5),
  68     QOS_MASK = (1 << 6),
  69     GROUP_QOS_MASK = (1 << 7),
  70     SIGNAL_MASK = (1 << 8),
  71     ALL_EVENTS_MASK = READ_MASK |
  72                       WRITE_MASK |
  73                       EXCEPT_MASK |
  74                       ACCEPT_MASK |
  75                       CONNECT_MASK |
  76                       TIMER_MASK |
  77                       QOS_MASK |
  78                       GROUP_QOS_MASK |
  79                       SIGNAL_MASK,
  80     RWE_MASK = READ_MASK |
  81                WRITE_MASK |
  82                EXCEPT_MASK,
  83     DONT_CALL = (1 << 9)
  84   };
  85
  86   /// Destructor is virtual to enable proper cleanup.
  87   virtual ~ACE_Event_Handler (void);
  88
  89   /// Get the I/O handle.
  90   virtual ACE_HANDLE get_handle (void) const;
  91
  92   /// Set the I/O handle.
  93   virtual void set_handle (ACE_HANDLE);
  94
  95   // = Get/set priority
  96
  97   // Priorities run from MIN_PRIORITY (which is the "lowest priority")
  98   // to MAX_PRIORITY (which is the "highest priority").
  99   /// Get the priority of the Event_Handler.
 100   virtual int priority (void) const;
 101
 102   /// Set the priority of the Event_Handler.
 103   virtual void priority (int priority);
 104
 105   /// Called when input events occur (e.g., connection or data).
 106   virtual int handle_input (ACE_HANDLE fd = ACE_INVALID_HANDLE);
 107
 108   /// Called when output events are possible (e.g., when flow control
 109   /// abates or non-blocking connection completes).
 110   virtual int handle_output (ACE_HANDLE fd = ACE_INVALID_HANDLE);
 111
 112   /// Called when an exceptional events occur (e.g., SIGURG).
 113   virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE);
 114
 115   /**
 116    * Called when timer expires.  @a current_time represents the current
 117    * time that the <Event_Handler> was selected for timeout
 118    * dispatching and @a act is the asynchronous completion token that
 119    * was passed in when <schedule_timer> was invoked.
 120    */
 121   virtual int handle_timeout (const ACE_Time_Value &current_time,
 122                               const void *act = 0);
 123
 124   /// Called when a process exits.
 125   virtual int handle_exit (ACE_Process *);
 126
 127   /// Called when a <handle_*()> method returns -1 or when the
 128   /// <remove_handler> method is called on an ACE_Reactor.  The
 129   /// @a close_mask indicates which event has triggered the
 130   /// <handle_close> method callback on a particular @a handle.
 131   virtual int handle_close (ACE_HANDLE handle,
 132                             ACE_Reactor_Mask close_mask);
 133
 134   /// Called when object is signaled by OS (either via UNIX signals or
 135   /// when a Win32 object becomes signaled).
 136   virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0);
 137
 138   enum
 139     {
 140       /// The handler is not resumed at all. Could lead to deadlock..
 141       ACE_EVENT_HANDLER_NOT_RESUMED = -1,
 142       /// The reactor takes responsibility of resuming the handler and
 143       /// is the default
 144       ACE_REACTOR_RESUMES_HANDLER = 0,
 145       /// The application takes responsibility of resuming the handler
 146       ACE_APPLICATION_RESUMES_HANDLER
 147     };
 148   /**
 149    * Called to figure out whether the handler needs to resumed by the
 150    * reactor or the application can take care of it. The default
 151    * value of 0 would be returned which would allow the reactor to
 152    * take care of resumption of the handler. The application can
 153    * return a value more than zero and decide to resume the handler
 154    * themseleves.
 155    *
 156    * @note This method is only useful for the ACE_TP_Reactor. Sad
 157    * that we have to have this method in a class that is supposed to
 158    * be used across different components in ACE.
 159    */
 160   virtual int resume_handler (void);
 161
 162   virtual int handle_qos (ACE_HANDLE = ACE_INVALID_HANDLE);
 163   virtual int handle_group_qos (ACE_HANDLE = ACE_INVALID_HANDLE);
 164
 165   // = Accessors to set/get the various event demultiplexors.
 166   /// Set the event demultiplexors.
 167   virtual void reactor (ACE_Reactor *reactor);
 168
 169   /// Get the event demultiplexors.
 170   virtual ACE_Reactor *reactor (void) const;
 171
 172   /// Get only the reactor's timer related interface.
 173   virtual ACE_Reactor_Timer_Interface *reactor_timer_interface (void) const;
 174
 175   /**
 176    * Used to read from non-socket ACE_HANDLEs in our own thread to
 177    * work around Win32 limitations that don't allow us to <select> on
 178    * non-sockets (such as ACE_STDIN).  This is commonly used in
 179    * situations where the Reactor is used to demultiplex read events
 180    * on ACE_STDIN on UNIX.  Note that @a event_handler must be a
 181    * subclass of ACE_Event_Handler.  If the <get_handle> method of
 182    * this event handler returns <ACE_INVALID_HANDLE> we default to
 183    * reading from ACE_STDIN.
 184    */
 185   static ACE_THR_FUNC_RETURN read_adapter (void *event_handler);
 186
 187   /**
 188    * Abstracts away from the differences between Win32 and ACE with
 189    * respect to reading from ACE_STDIN, which is non-<select>'able on
 190    * Win32.
 191    */
 192   static int register_stdin_handler (ACE_Event_Handler *eh,
 193                                      ACE_Reactor *reactor,
 194                                      ACE_Thread_Manager *thr_mgr,
 195                                      int flags = THR_DETACHED);
 196
 197   /// Performs the inverse of the <register_stdin_handler> method.
 198   static int remove_stdin_handler (ACE_Reactor *reactor,
 199                                    ACE_Thread_Manager *thr_mgr);
 200
 201   /// Reference count type.
 202   typedef long Reference_Count;
 203
 204   /// Increment reference count on the handler.
 205   /**
 206    * This method is called when the handler is registered with the
 207    * Reactor and when the Reactor makes an upcall on the handler.
 208    * Reference count is 1 when the handler is created.
 209    *
 210    * @return Current reference count.
 211    */
 212   virtual Reference_Count add_reference (void);
 213
 214   /// Decrement reference count on the handler.
 215   /**
 216    * This method is called when the handler is removed from the
 217    * Reactor and when an upcall made on the handler by the Reactor
 218    * completes.  Handler is deleted when the reference count reaches
 219    * 0.
 220    *
 221    * @return Current reference count.
 222    */
 223   virtual Reference_Count remove_reference (void);
 224
 225   /**
 226    * @class Policy
 227    *
 228    * @brief Base class for all handler policies.
 229    */
 230   class ACE_Export Policy
 231   {
 232
 233   public:
 234
 235     /// Virtual destructor.
 236     virtual ~Policy (void);
 237   };
 238
 239   /**
 240    * @class Reference_Counting_Policy
 241    *
 242    * @brief This policy dictates the reference counting requirements
 243    * for the handler.
 244    *
 245    * This policy allows applications to configure whether it wants the
 246    * Reactor to call add_reference() and remove_reference() during
 247    * registrations, removals, and upcalls.
 248    *
 249    * <B>Default:</B> DISABLED.
 250    */
 251   class ACE_Export Reference_Counting_Policy : public Policy
 252   {
 253     /// This policy can only be created by the handler.
 254     friend class ACE_Event_Handler;
 255
 256   public:
 257
 258     enum Value
 259       {
 260         /// Perform reference counting.
 261         ENABLED,
 262         /// Don't perform reference counting.
 263         DISABLED
 264       };
 265
 266     /// Current Reference_Counting_Policy.
 267     Value value (void) const;
 268
 269     /// Update Reference_Counting_Policy.
 270     void value (Value value);
 271
 272   private:
 273
 274     /// Private constructor.
 275     Reference_Counting_Policy (Value value);
 276
 277     /// The value of the policy.
 278     Value value_;
 279    };
 280
 281   /// Current Reference_Counting_Policy.
 282   Reference_Counting_Policy &reference_counting_policy (void);
 283
 284 protected:
 285   /// Force ACE_Event_Handler to be an abstract base class.
 286   ACE_Event_Handler (ACE_Reactor * = 0,
 287                      int priority = ACE_Event_Handler::LO_PRIORITY);
 288
 289   /// Typedef for implementation of reference counting.
 290   typedef ACE_Atomic_Op<ACE_SYNCH_MUTEX, Reference_Count> Atomic_Reference_Count;
 291
 292   /// Reference count.
 293   Atomic_Reference_Count reference_count_;
 294
 295 private:
 296
 297   /// Priority of this Event_Handler.
 298   int priority_;
 299
 300   /// Pointer to the various event demultiplexors.
 301   ACE_Reactor *reactor_;
 302
 303   /// Reference counting requirements.
 304   Reference_Counting_Policy reference_counting_policy_;
 305 };
 306
 307 /**
 308  * @class ACE_Event_Handler_var
 309  *
 310  * @brief Auto pointer like class for Event Handlers.
 311  *
 312  * Used to manage lifecycle of handlers. This class calls
 313  * ACE_Event_Handler::remove_reference() in its destructor.
 314  */
 315 class ACE_Export ACE_Event_Handler_var
 316 {
 317
 318 public:
 319
 320   /// Default constructor.
 321   ACE_Event_Handler_var (void);
 322
 323   /// Construct with a handler.
 324   ACE_Event_Handler_var (ACE_Event_Handler *p);
 325
 326   /// Copy constructor.
 327   ACE_Event_Handler_var (const ACE_Event_Handler_var &b);
 328
 329   /// Destructor.
 330   ~ACE_Event_Handler_var (void);
 331
 332   /// Assignment to a handler.
 333   ACE_Event_Handler_var &operator= (ACE_Event_Handler *p);
 334
 335   /// Assignment to a ACE_Event_Handler_var.
 336   ACE_Event_Handler_var &operator= (const ACE_Event_Handler_var &b);
 337
 338   /// Overloaded "->".
 339   ACE_Event_Handler *operator-> () const;
 340
 341   /// Access the handler.
 342   ACE_Event_Handler *handler (void) const;
 343
 344   /// Release the handler.
 345   ACE_Event_Handler *release (void);
 346
 347   /// Reset the handler.
 348   void reset (ACE_Event_Handler *p = 0);
 349
 350 private:
 351
 352   /// Handler.
 353   ACE_Event_Handler *ptr_;
 354 };
 355
 356 /**
 357  * @class ACE_Notification_Buffer
 358  *
 359  * @brief Simple wrapper for passing <ACE_Event_Handler *>s and
 360  * ACE_Reactor_Masks between threads.
 361  */
 362 class ACE_Export ACE_Notification_Buffer
 363 {
 364 public:
 365   ACE_Notification_Buffer (void);
 366
 367   ACE_Notification_Buffer (ACE_Event_Handler *eh,
 368                            ACE_Reactor_Mask mask);
 369
 370   /// Default dtor.
 371   ~ACE_Notification_Buffer (void);
 372
 373   /// Pointer to the Event_Handler that will be dispatched
 374   /// by the main event loop.
 375   ACE_Event_Handler *eh_;
 376
 377   /// Mask that indicates which method to call.
 378   ACE_Reactor_Mask mask_;
 379 };
 380
 381 ACE_END_VERSIONED_NAMESPACE_DECL
 382
 383 #if defined (__ACE_INLINE__)
 384 #include "ace/Event_Handler.inl"
 385 #endif /* __ACE_INLINE__ */
 386
 387 #include /**/ "ace/post.h"
 388 #endif /* ACE_EVENT_HANDLER_H */