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