Event_Handler.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //==========================================================================
00004 /**
00005  *  @file    Event_Handler.h
00006  *
00007  *  Event_Handler.h,v 4.59 2006/03/15 08:39:55 jwillemsen Exp
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00010  */
00011 //==========================================================================
00012 
00013 #ifndef ACE_EVENT_HANDLER_H
00014 #define ACE_EVENT_HANDLER_H
00015 #include /**/ "ace/pre.h"
00016 
00017 #include "ace/ACE_export.h"
00018 
00019 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00020 # pragma once
00021 #endif /* ACE_LACKS_PRAGMA_ONCE */
00022 
00023 #include "ace/os_include/os_signal.h"
00024 #include "ace/Atomic_Op.h"
00025 #include "ace/Synch_Traits.h"
00026 
00027 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00028 
00029 // Forward declaration.
00030 class ACE_Message_Block;
00031 class ACE_Reactor;
00032 class ACE_Reactor_Timer_Interface;
00033 class ACE_Thread_Manager;
00034 class ACE_Process;
00035 
00036 typedef unsigned long ACE_Reactor_Mask;
00037 
00038 /**
00039  * @class ACE_Event_Handler
00040  *
00041  * @brief Provides an abstract interface for handling various types of
00042  * I/O, timer, and signal events.
00043  *
00044  * Subclasses read/write input/output on an I/O descriptor,
00045  * handle an exception raised on an I/O descriptor, handle a
00046  * timer's expiration, or handle a signal.
00047  */
00048 class ACE_Export ACE_Event_Handler
00049 {
00050 public:
00051   enum
00052   {
00053     LO_PRIORITY = 0,
00054     HI_PRIORITY = 10,
00055     NULL_MASK = 0,
00056 #if defined (ACE_USE_POLL)
00057     READ_MASK = POLLIN,
00058     WRITE_MASK = POLLOUT,
00059     EXCEPT_MASK = POLLPRI,
00060 #else /* USE SELECT */
00061     READ_MASK = (1 << 0),
00062     WRITE_MASK = (1 << 1),
00063     EXCEPT_MASK = (1 << 2),
00064 #endif /* ACE_USE_POLL */
00065     ACCEPT_MASK = (1 << 3),
00066     CONNECT_MASK = (1 << 4),
00067     TIMER_MASK = (1 << 5),
00068     QOS_MASK = (1 << 6),
00069     GROUP_QOS_MASK = (1 << 7),
00070     SIGNAL_MASK = (1 << 8),
00071     ALL_EVENTS_MASK = READ_MASK |
00072                       WRITE_MASK |
00073                       EXCEPT_MASK |
00074                       ACCEPT_MASK |
00075                       CONNECT_MASK |
00076                       TIMER_MASK |
00077                       QOS_MASK |
00078                       GROUP_QOS_MASK |
00079                       SIGNAL_MASK,
00080     RWE_MASK = READ_MASK |
00081                WRITE_MASK |
00082                EXCEPT_MASK,
00083     DONT_CALL = (1 << 9)
00084   };
00085 
00086   /// Destructor is virtual to enable proper cleanup.
00087   virtual ~ACE_Event_Handler (void);
00088 
00089   /// Get the I/O handle.
00090   virtual ACE_HANDLE get_handle (void) const;
00091 
00092   /// Set the I/O handle.
00093   virtual void set_handle (ACE_HANDLE);
00094 
00095   // = Get/set priority
00096 
00097   // Priorities run from MIN_PRIORITY (which is the "lowest priority")
00098   // to MAX_PRIORITY (which is the "highest priority").
00099   /// Get the priority of the Event_Handler.
00100   virtual int priority (void) const;
00101 
00102   /// Set the priority of the Event_Handler.
00103   virtual void priority (int priority);
00104 
00105   /// Called when input events occur (e.g., connection or data).
00106   virtual int handle_input (ACE_HANDLE fd = ACE_INVALID_HANDLE);
00107 
00108   /// Called when output events are possible (e.g., when flow control
00109   /// abates or non-blocking connection completes).
00110   virtual int handle_output (ACE_HANDLE fd = ACE_INVALID_HANDLE);
00111 
00112   /// Called when an exceptional events occur (e.g., SIGURG).
00113   virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE);
00114 
00115   /**
00116    * Called when timer expires.  <current_time> represents the current
00117    * time that the <Event_Handler> was selected for timeout
00118    * dispatching and <act> is the asynchronous completion token that
00119    * was passed in when <schedule_timer> was invoked.
00120    */
00121   virtual int handle_timeout (const ACE_Time_Value &current_time,
00122                               const void *act = 0);
00123 
00124   /// Called when a process exits.
00125   virtual int handle_exit (ACE_Process *);
00126 
00127   /// Called when a <handle_*()> method returns -1 or when the
00128   /// <remove_handler> method is called on an ACE_Reactor.  The
00129   /// <close_mask> indicates which event has triggered the
00130   /// <handle_close> method callback on a particular <handle>.
00131   virtual int handle_close (ACE_HANDLE handle,
00132                             ACE_Reactor_Mask close_mask);
00133 
00134   /// Called when object is signaled by OS (either via UNIX signals or
00135   /// when a Win32 object becomes signaled).
00136   virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0);
00137 
00138   enum
00139     {
00140       /// The handler is not resumed at all. Could lead to deadlock..
00141       ACE_EVENT_HANDLER_NOT_RESUMED = -1,
00142       /// The reactor takes responsibility of resuming the handler and
00143       /// is the default
00144       ACE_REACTOR_RESUMES_HANDLER = 0,
00145       /// The application takes responsibility of resuming the handler
00146       ACE_APPLICATION_RESUMES_HANDLER
00147     };
00148   /**
00149    * Called to figure out whether the handler needs to resumed by the
00150    * reactor or the application can take care of it. The default
00151    * value of 0 would be returned which would allow the reactor to
00152    * take care of resumption of the handler. The application can
00153    * return a value more than zero and decide to resume the handler
00154    * themseleves.
00155    *
00156    * @note This method is only useful for the ACE_TP_Reactor. Sad
00157    * that we have to have this method in a class that is supposed to
00158    * be used across different components in ACE.
00159    */
00160   virtual int resume_handler (void);
00161 
00162   virtual int handle_qos (ACE_HANDLE = ACE_INVALID_HANDLE);
00163   virtual int handle_group_qos (ACE_HANDLE = ACE_INVALID_HANDLE);
00164 
00165   // = Accessors to set/get the various event demultiplexors.
00166   /// Set the event demultiplexors.
00167   virtual void reactor (ACE_Reactor *reactor);
00168 
00169   /// Get the event demultiplexors.
00170   virtual ACE_Reactor *reactor (void) const;
00171 
00172   /// Get only the reactor's timer related interface.
00173   virtual ACE_Reactor_Timer_Interface *reactor_timer_interface (void) const;
00174 
00175   //#if !defined (ACE_HAS_WINCE)
00176   /**
00177    * Used to read from non-socket ACE_HANDLEs in our own thread to
00178    * work around Win32 limitations that don't allow us to <select> on
00179    * non-sockets (such as ACE_STDIN).  This is commonly used in
00180    * situations where the Reactor is used to demultiplex read events
00181    * on ACE_STDIN on UNIX.  Note that <event_handler> must be a
00182    * subclass of ACE_Event_Handler.  If the <get_handle> method of
00183    * this event handler returns <ACE_INVALID_HANDLE> we default to
00184    * reading from ACE_STDIN.
00185    */
00186   static ACE_THR_FUNC_RETURN read_adapter (void *event_handler);
00187 
00188   /**
00189    * Abstracts away from the differences between Win32 and ACE with
00190    * respect to reading from ACE_STDIN, which is non-<select>'able on
00191    * Win32.
00192    */
00193   static int register_stdin_handler (ACE_Event_Handler *eh,
00194                                      ACE_Reactor *reactor,
00195                                      ACE_Thread_Manager *thr_mgr,
00196                                      int flags = THR_DETACHED);
00197 
00198   /// Performs the inverse of the <register_stdin_handler> method.
00199   static int remove_stdin_handler (ACE_Reactor *reactor,
00200                                    ACE_Thread_Manager *thr_mgr);
00201   //#endif /* ACE_HAS_WINCE */
00202 
00203   /// Reference count type.
00204   typedef long Reference_Count;
00205 
00206   /// Increment reference count on the handler.
00207   /**
00208    * This method is called when the handler is registered with the
00209    * Reactor and when the Reactor makes an upcall on the handler.
00210    * Reference count is 1 when the handler is created.
00211    *
00212    * @return Current reference count.
00213    */
00214   virtual Reference_Count add_reference (void);
00215 
00216   /// Decrement reference count on the handler.
00217   /**
00218    * This method is called when the handler is removed from the
00219    * Reactor and when an upcall made on the handler by the Reactor
00220    * completes.  Handler is deleted when the reference count reaches
00221    * 0.
00222    *
00223    * @return Current reference count.
00224    */
00225   virtual Reference_Count remove_reference (void);
00226 
00227   /**
00228    * @class Policy
00229    *
00230    * @brief Base class for all handler policies.
00231    */
00232   class ACE_Export Policy
00233   {
00234 
00235   public:
00236 
00237     /// Virtual destructor.
00238     virtual ~Policy (void);
00239   };
00240 
00241   /**
00242    * @class Reference_Counting_Policy
00243    *
00244    * @brief This policy dictates the reference counting requirements
00245    * for the handler.
00246    *
00247    * This policy allows applications to configure whether it wants the
00248    * Reactor to call add_reference() and remove_reference() during
00249    * registrations, removals, and upcalls.
00250    *
00251    * <B>Default:</B> DISABLED.
00252    */
00253   class ACE_Export Reference_Counting_Policy : public Policy
00254   {
00255     /// This policy can only be created by the handler.
00256     friend class ACE_Event_Handler;
00257 
00258   public:
00259 
00260     enum Value
00261       {
00262         /// Perform reference counting.
00263         ENABLED,
00264         /// Don't perform reference counting.
00265         DISABLED
00266       };
00267 
00268     /// Current Reference_Counting_Policy.
00269     Value value (void) const;
00270 
00271     /// Update Reference_Counting_Policy.
00272     void value (Value value);
00273 
00274   private:
00275 
00276     /// Private constructor.
00277     Reference_Counting_Policy (Value value);
00278 
00279     /// The value of the policy.
00280     Value value_;
00281    };
00282 
00283   /// Current Reference_Counting_Policy.
00284   Reference_Counting_Policy &reference_counting_policy (void);
00285 
00286 protected:
00287   /// Force ACE_Event_Handler to be an abstract base class.
00288   ACE_Event_Handler (ACE_Reactor * = 0,
00289                      int priority = ACE_Event_Handler::LO_PRIORITY);
00290 
00291   /// Typedef for implementation of reference counting.
00292   typedef ACE_Atomic_Op<ACE_SYNCH_MUTEX, Reference_Count> Atomic_Reference_Count;
00293 
00294   /// Reference count.
00295   Atomic_Reference_Count reference_count_;
00296 
00297 private:
00298 
00299   /// Priority of this Event_Handler.
00300   int priority_;
00301 
00302   /// Pointer to the various event demultiplexors.
00303   ACE_Reactor *reactor_;
00304 
00305   /// Reference counting requirements.
00306   Reference_Counting_Policy reference_counting_policy_;
00307 };
00308 
00309 /**
00310  * @class ACE_Event_Handler_var
00311  *
00312  * @brief Auto pointer like class for Event Handlers.
00313  *
00314  * Used to manage lifecycle of handlers. This class calls
00315  * ACE_Event_Handler::remove_reference() in its destructor.
00316  */
00317 class ACE_Export ACE_Event_Handler_var
00318 {
00319 
00320 public:
00321 
00322   /// Default constructor.
00323   ACE_Event_Handler_var (void);
00324 
00325   /// Construct with a handler.
00326   ACE_Event_Handler_var (ACE_Event_Handler *p);
00327 
00328   /// Copy constructor.
00329   ACE_Event_Handler_var (const ACE_Event_Handler_var &b);
00330 
00331   /// Destructor.
00332   ~ACE_Event_Handler_var (void);
00333 
00334   /// Assignment to a handler.
00335   ACE_Event_Handler_var &operator= (ACE_Event_Handler *p);
00336 
00337   /// Assignment to a ACE_Event_Handler_var.
00338   ACE_Event_Handler_var &operator= (const ACE_Event_Handler_var &b);
00339 
00340   /// Overloaded "->".
00341   ACE_Event_Handler *operator-> () const;
00342 
00343   /// Access the handler.
00344   ACE_Event_Handler *handler (void) const;
00345 
00346   /// Release the handler.
00347   ACE_Event_Handler *release (void);
00348 
00349   /// Reset the handler.
00350   void reset (ACE_Event_Handler *p = 0);
00351 
00352 private:
00353 
00354   /// Handler.
00355   ACE_Event_Handler *ptr_;
00356 };
00357 
00358 /**
00359  * @class ACE_Notification_Buffer
00360  *
00361  * @brief Simple wrapper for passing <ACE_Event_Handler *>s and
00362  * <ACE_Reactor_Mask>s between threads.
00363  */
00364 class ACE_Export ACE_Notification_Buffer
00365 {
00366 public:
00367   ACE_Notification_Buffer (void);
00368 
00369   ACE_Notification_Buffer (ACE_Event_Handler *eh,
00370                            ACE_Reactor_Mask mask);
00371 
00372   /// Default dtor.
00373   ~ACE_Notification_Buffer (void);
00374 
00375   /// Pointer to the Event_Handler that will be dispatched
00376   /// by the main event loop.
00377   ACE_Event_Handler *eh_;
00378 
00379   /// Mask that indicates which method to call.
00380   ACE_Reactor_Mask mask_;
00381 };
00382 
00383 ACE_END_VERSIONED_NAMESPACE_DECL
00384 
00385 #if defined (__ACE_INLINE__)
00386 #include "ace/Event_Handler.inl"
00387 #endif /* __ACE_INLINE__ */
00388 
00389 #include /**/ "ace/post.h"
00390 #endif /* ACE_EVENT_HANDLER_H */

Generated on Thu Nov 9 09:41:50 2006 for ACE by doxygen 1.3.6