diff options
Diffstat (limited to 'ace/Event_Handler.h')
| -rw-r--r-- | ace/Event_Handler.h | 128 |
1 files changed, 68 insertions, 60 deletions
diff --git a/ace/Event_Handler.h b/ace/Event_Handler.h index 0f2f719960c..3d62528e38f 100644 --- a/ace/Event_Handler.h +++ b/ace/Event_Handler.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Event_Handler.h -// -// = AUTHOR -// Douglas C. Schmidt <schmidt@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Event_Handler.h + * + * $Id$ + * + * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_EVENT_HANDLER_H #define ACE_EVENT_HANDLER_H @@ -32,16 +29,18 @@ class ACE_Process; typedef u_long ACE_Reactor_Mask; +/** + * @class ACE_Event_Handler + * + * @brief Provides an abstract interface for handling various types of + * I/O, timer, and signal events. + * + * Subclasses read/write input/output on an I/O descriptor, + * handle an exception raised on an I/O descriptor, handle a + * timer's expiration, or handle a signal. + */ class ACE_Export ACE_Event_Handler { - // = TITLE - // Provides an abstract interface for handling various types of - // I/O, timer, and signal events. - // - // = DESCRIPTION - // Subclasses read/write input/output on an I/O descriptor, - // handle an exception raised on an I/O descriptor, handle a - // timer's expiration, or handle a signal. public: enum { @@ -78,50 +77,52 @@ public: DONT_CALL = (1 << 9) }; + /// Destructor is virtual to enable proper cleanup. virtual ~ACE_Event_Handler (void); - // Destructor is virtual to enable proper cleanup. + /// Get the I/O handle. + /// Set the I/O handle. virtual ACE_HANDLE get_handle (void) const; - // Get the I/O handle. virtual void set_handle (ACE_HANDLE); - // Set the I/O handle. // = Get/set priority // Priorities run from MIN_PRIORITY (which is the "lowest priority") // to MAX_PRIORITY (which is the "highest priority"). + /// Get the priority of the Event_Handler. + /// Set the priority of the Event_Handler. virtual int priority (void) const; - // Get the priority of the Event_Handler. virtual void priority (int priority); - // Set the priority of the Event_Handler. + /// Called when input events occur (e.g., connection or data). virtual int handle_input (ACE_HANDLE fd = ACE_INVALID_HANDLE); - // Called when input events occur (e.g., connection or data). + /// Called when output events are possible (e.g., flow control + /// abates). virtual int handle_output (ACE_HANDLE fd = ACE_INVALID_HANDLE); - // Called when output events are possible (e.g., flow control - // abates). + /// Called when execption events occur (e.g., SIGURG). virtual int handle_exception (ACE_HANDLE fd = ACE_INVALID_HANDLE); - // Called when execption events occur (e.g., SIGURG). + /** + * Called when timer expires. <current_time> represents the current + * time that the <Event_Handler> was selected for timeout + * dispatching and <act> is the asynchronous completion token that + * was passed in when <schedule_timer> was invoked. + */ virtual int handle_timeout (const ACE_Time_Value ¤t_time, const void *act = 0); - // Called when timer expires. <current_time> represents the current - // time that the <Event_Handler> was selected for timeout - // dispatching and <act> is the asynchronous completion token that - // was passed in when <schedule_timer> was invoked. + /// Called when a process exits. virtual int handle_exit (ACE_Process *); - // Called when a process exits. + /// Called when object is removed from the <ACE_Reactor>. virtual int handle_close (ACE_HANDLE handle, ACE_Reactor_Mask close_mask); - // Called when object is removed from the <ACE_Reactor>. + /// Called when object is signaled by OS (either via UNIX signals or + /// when a Win32 object becomes signaled). virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // Called when object is signaled by OS (either via UNIX signals or - // when a Win32 object becomes signaled). virtual int handle_qos (ACE_HANDLE = ACE_INVALID_HANDLE); virtual int handle_group_qos (ACE_HANDLE = ACE_INVALID_HANDLE); @@ -131,63 +132,70 @@ public: virtual ACE_Reactor *reactor (void) const; #if !defined (ACE_HAS_WINCE) + /** + * Used to read from non-socket ACE_HANDLEs in our own thread to + * work around Win32 limitations that don't allow us to <select> on + * non-sockets (such as ACE_STDIN). This is commonly used in + * situations where the Reactor is used to demultiplex read events + * on ACE_STDIN on UNIX. Note that <event_handler> must be a + * subclass of <ACE_Event_Handler>. If the <get_handle> method of + * this event handler returns <ACE_INVALID_HANDLE> we default to + * reading from ACE_STDIN. + */ static void *read_adapter (void *event_handler); - // Used to read from non-socket ACE_HANDLEs in our own thread to - // work around Win32 limitations that don't allow us to <select> on - // non-sockets (such as ACE_STDIN). This is commonly used in - // situations where the Reactor is used to demultiplex read events - // on ACE_STDIN on UNIX. Note that <event_handler> must be a - // subclass of <ACE_Event_Handler>. If the <get_handle> method of - // this event handler returns <ACE_INVALID_HANDLE> we default to - // reading from ACE_STDIN. + /** + * Abstracts away from the differences between Win32 and ACE with + * respect to reading from ACE_STDIN (which is non-<select>'able on + * Win32. + */ static int register_stdin_handler (ACE_Event_Handler *eh, ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr, int flags = THR_DETACHED); - // Abstracts away from the differences between Win32 and ACE with - // respect to reading from ACE_STDIN (which is non-<select>'able on - // Win32. + /// Performs the inverse of the <register_stdin_handler> method. static int remove_stdin_handler (ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr); - // Performs the inverse of the <register_stdin_handler> method. #endif /* ACE_HAS_WINCE */ protected: + /// Force ACE_Event_Handler to be an abstract base class. ACE_Event_Handler (ACE_Reactor * = 0, int priority = ACE_Event_Handler::LO_PRIORITY); - // Force ACE_Event_Handler to be an abstract base class. private: + /// Priority of this Event_Handler. int priority_; - // Priority of this Event_Handler. // = Pointers to the various event demultiplexors. ACE_Reactor *reactor_; }; +/** + * @class ACE_Notification_Buffer + * + * @brief Simple wrapper for passing <ACE_Event_Handler *>s and + * <ACE_Reactor_Mask>s between threads. + */ class ACE_Export ACE_Notification_Buffer { - // = TITLE - // Simple wrapper for passing <ACE_Event_Handler *>s and - // <ACE_Reactor_Mask>s between threads. public: ACE_Notification_Buffer (void); ACE_Notification_Buffer (ACE_Event_Handler *eh, ACE_Reactor_Mask mask); + /// Default dtor. ~ACE_Notification_Buffer (void); - // Default dtor. + /// Pointer to the Event_Handler that will be dispatched + /// by the main event loop. ACE_Event_Handler *eh_; - // Pointer to the Event_Handler that will be dispatched - // by the main event loop. + /// Mask that indicates which method to call. ACE_Reactor_Mask mask_; - // Mask that indicates which method to call. }; #if defined (__ACE_INLINE__) |