ACE/ace/Event_Handler.h

   1 /* -*- C++ -*- */
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Event_Handler.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_EVENT_HANDLER_H
  12 #define ACE_EVENT_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/os_include/os_signal.h"
  22 #include "ace/Atomic_Op.h"
  23 #include "ace/OS_NS_Thread.h"
  24 #include "ace/Synch_Traits.h"
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 // Forward declaration.
  29 class ACE_Message_Block;
  30 class ACE_Reactor;
  31 class ACE_Reactor_Timer_Interface;
  32 class ACE_Thread_Manager;
  33 class ACE_Process;
  34
  35 typedef unsigned long ACE_Reactor_Mask;
  36
  37 /**
  38  * @class ACE_Event_Handler
  39  *
  40  * @brief
  41  * 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   /// Get the priority of the Event_Handler.
  98   /// @note Priorities run from MIN_PRIORITY (which is the "lowest priority")
  99   /// to MAX_PRIORITY (which is the "highest priority").
 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   /**
 150    * Called to figure out whether the handler needs to resumed by the
 151    * reactor or the application can take care of it. The default
 152    * value of 0 would be returned which would allow the reactor to
 153    * take care of resumption of the handler. The application can
 154    * return a value more than zero and decide to resume the handler
 155    * themselves.
 156    *
 157    * @note This method has an affect only when used with the
 158    * ACE_Dev_Poll_Reactor (and then, only on Linux) or the ACE_TP_Reactor.
 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
 243    * This policy dictates the reference counting requirements
 244    * for the handler.
 245    *
 246    * This policy allows applications to configure whether it wants the
 247    * Reactor to call add_reference() and remove_reference() during
 248    * registrations, removals, and upcalls.
 249    *
 250    * <B>Default:</B> DISABLED.
 251    */
 252   class ACE_Export Reference_Counting_Policy : public Policy
 253   {
 254     /// This policy can only be created by the handler.
 255     friend class ACE_Event_Handler;
 256
 257   public:
 258
 259     enum Value
 260       {
 261         /// Perform reference counting.
 262         ENABLED,
 263         /// Don't perform reference counting.
 264         DISABLED
 265       };
 266
 267     /// Current Reference_Counting_Policy.
 268     Value value (void) const;
 269
 270     /// Update Reference_Counting_Policy.
 271     void value (Value value);
 272
 273   private:
 274
 275     /// Private constructor.
 276     Reference_Counting_Policy (Value value);
 277
 278     /// The value of the policy.
 279     Value value_;
 280    };
 281
 282   /// Current Reference_Counting_Policy.
 283   Reference_Counting_Policy &reference_counting_policy (void);
 284
 285 protected:
 286   /// Force ACE_Event_Handler to be an abstract base class.
 287   ACE_Event_Handler (ACE_Reactor * = 0,
 288                      int priority = ACE_Event_Handler::LO_PRIORITY);
 289
 290   /// Typedef for implementation of reference counting.
 291   typedef ACE_Atomic_Op<ACE_SYNCH_MUTEX, Reference_Count> Atomic_Reference_Count;
 292
 293   /// Reference count.
 294   Atomic_Reference_Count reference_count_;
 295
 296 private:
 297
 298   /// Priority of this Event_Handler.
 299   int priority_;
 300
 301   /// Pointer to the various event demultiplexors.
 302   ACE_Reactor *reactor_;
 303
 304   /// Reference counting requirements.
 305   Reference_Counting_Policy reference_counting_policy_;
 306 };
 307
 308 /**
 309  * @class ACE_Event_Handler_var
 310  *
 311  * @brief Auto pointer like class for Event Handlers.
 312  *
 313  * Used to manage lifecycle of handlers. This class calls
 314  * ACE_Event_Handler::remove_reference() in its destructor.
 315  */
 316 class ACE_Export ACE_Event_Handler_var
 317 {
 318 public:
 319   /// Default constructor.
 320   ACE_Event_Handler_var (void);
 321
 322   /// Construct with a handler.
 323   ACE_Event_Handler_var (ACE_Event_Handler *p);
 324
 325   /// Copy constructor.
 326   ACE_Event_Handler_var (const ACE_Event_Handler_var &b);
 327
 328   /// Destructor.
 329   ~ACE_Event_Handler_var (void);
 330
 331   /// Assignment to a handler.
 332   ACE_Event_Handler_var &operator= (ACE_Event_Handler *p);
 333
 334   /// Assignment to a ACE_Event_Handler_var.
 335   ACE_Event_Handler_var &operator= (const ACE_Event_Handler_var &b);
 336
 337   /// Overloaded "->".
 338   ACE_Event_Handler *operator-> () const;
 339
 340   /// Access the handler.
 341   ACE_Event_Handler *handler (void) const;
 342
 343   /// Release the handler.
 344   ACE_Event_Handler *release (void);
 345
 346   /// Reset the handler.
 347   void reset (ACE_Event_Handler *p = 0);
 348
 349 #if defined (ACE_HAS_CPP11)
 350   /// Bool operator to check if the ACE_Event_Handler_var has a value
 351   explicit operator bool() const;
 352   /// Equality operator to compare with nullptr_t
 353   bool operator ==(std::nullptr_t) const;
 354   /// Not equal operator to compare with nullptr_t
 355   bool operator !=(std::nullptr_t) const;
 356 #endif
 357
 358 private:
 359
 360   /// Handler.
 361   ACE_Event_Handler *ptr_;
 362 };
 363
 364 #if defined ACE_HAS_CPP11
 365
 366 /// Define that we can use in user code to check if this
 367 /// helper factory method is there
 368 #define ACE_HAS_ACE_MAKE_EVENT_HANDLER
 369
 370 namespace ACE
 371 {
 372   /// With C++11 it is common to not use C++ new and delete, but
 373   /// use std::make_shared and std::make_unique. This will not
 374   /// work for ACE event handlers so we introduce a new
 375   /// ACE::make_event_handler which can be used in user code to
 376   /// allocate a new ACE event handler instance and directly assign
 377   /// it to a ACE_Event_Handler_var
 378   /// As user this now makes it for example possible to implement
 379   /// the following when Simple_Handler is derived from ACE_Event_Handler
 380   /// ACE_Event_Handler_var v =
 381   ///   ACE::make_event_handler<Simple_Handler> (reactor.get());
 382   template<class T,
 383            typename = typename
 384              std::enable_if<std::is_base_of<ACE_Event_Handler, T>::value>::type,
 385            typename ...Args> inline
 386   ACE_Event_Handler_var make_event_handler (Args&& ...args)
 387   {
 388     return ACE_Event_Handler_var (new T (std::forward<Args> (args)...));
 389   }
 390 }
 391
 392 #endif
 393
 394 /**
 395  * @class ACE_Notification_Buffer
 396  *
 397  * @brief Simple wrapper for passing ACE_Event_Handler *s and
 398  * ACE_Reactor_Masks between threads.
 399  */
 400 class ACE_Export ACE_Notification_Buffer
 401 {
 402 public:
 403   ACE_Notification_Buffer (void);
 404
 405   ACE_Notification_Buffer (ACE_Event_Handler *eh,
 406                            ACE_Reactor_Mask mask);
 407
 408   /// Default destructor.
 409   ~ACE_Notification_Buffer (void);
 410
 411   /// Pointer to the Event_Handler that will be dispatched
 412   /// by the main event loop.
 413   ACE_Event_Handler *eh_;
 414
 415   /// Mask that indicates which method to call.
 416   ACE_Reactor_Mask mask_;
 417 };
 418
 419 ACE_END_VERSIONED_NAMESPACE_DECL
 420
 421 #if defined (__ACE_INLINE__)
 422 #include "ace/Event_Handler.inl"
 423 #endif /* __ACE_INLINE__ */
 424
 425 #include /**/ "ace/post.h"
 426 #endif /* ACE_EVENT_HANDLER_H */