diff options
Diffstat (limited to 'ace/Proactor.h')
| -rw-r--r-- | ace/Proactor.h | 341 |
1 files changed, 181 insertions, 160 deletions
diff --git a/ace/Proactor.h b/ace/Proactor.h index 05f1cb72a03..e82af128929 100644 --- a/ace/Proactor.h +++ b/ace/Proactor.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Proactor.h -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu>, -// Tim Harrison <harrison@cs.wustl.edu> and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file Proactor.h + * + * $Id$ + * + * @author Irfan Pyarali <irfan@cs.wustl.edu> + * @author Tim Harrison <harrison@cs.wustl.edu> + * @author Alexander Babu Arulanthu <alex@cs.wustl.edu> + */ +//============================================================================= + #ifndef ACE_PROACTOR_H #define ACE_PROACTOR_H @@ -42,62 +39,66 @@ class ACE_Proactor_Impl; class ACE_Proactor_Timer_Handler; +/** + * @class ACE_Proactor_Handle_Timeout_Upcall + * + * @brief Functor for <ACE_Timer_Queue>. + * + * This class implements the functor required by the Timer + * Queue to call <handle_timeout> on ACE_Handlers. + */ class ACE_Export ACE_Proactor_Handle_Timeout_Upcall { - // = TITLE - // Functor for <ACE_Timer_Queue>. - // - // = DESCRIPTION - // This class implements the functor required by the Timer - // Queue to call <handle_timeout> on ACE_Handlers. - + + /// Type def for the timer queue. typedef ACE_Timer_Queue_T<ACE_Handler *, ACE_Proactor_Handle_Timeout_Upcall, ACE_SYNCH_RECURSIVE_MUTEX> TIMER_QUEUE; - // Type def for the timer queue. - + + /// The main Proactor class has special permissions. friend class ACE_Proactor; - // The main Proactor class has special permissions. public: + /// Constructor. ACE_Proactor_Handle_Timeout_Upcall (void); - // Constructor. - + + /// This method is called when the timer expires. int timeout (TIMER_QUEUE &timer_queue, ACE_Handler *handler, const void *arg, const ACE_Time_Value &cur_time); - // This method is called when the timer expires. + /// This method is called when the timer is canceled. int cancellation (TIMER_QUEUE &timer_queue, ACE_Handler *handler); - // This method is called when the timer is canceled. + /// This method is called when the timer queue is destroyed and the + /// timer is still contained in it. int deletion (TIMER_QUEUE &timer_queue, ACE_Handler *handler, const void *arg); - // This method is called when the timer queue is destroyed and the - // timer is still contained in it. protected: + /// Set the proactor. This will fail, if one is already set! int proactor (ACE_Proactor &proactor); - // Set the proactor. This will fail, if one is already set! + /// Handle to the proactor. This is needed for posting a timer result + /// to the Proactor's completion queue. ACE_Proactor *proactor_; - // Handle to the proactor. This is needed for posting a timer result - // to the Proactor's completion queue. }; +/** + * @class ACE_Proactor + * + * @brief A manager for asynchronous event demultiplexing. + * + * See the Proactor pattern description at + * http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more + * details. + */ class ACE_Export ACE_Proactor { - // = TITLE - // A manager for asynchronous event demultiplexing. - // - // = DESCRIPTION - // See the Proactor pattern description at - // http://www.cs.wustl.edu/~schmidt/proactor.ps.gz for more - // details. // = Here are the private typedefs that the <ACE_Proactor> uses. @@ -129,87 +130,95 @@ class ACE_Export ACE_Proactor ACE_Proactor_Handle_Timeout_Upcall, ACE_SYNCH_RECURSIVE_MUTEX> TIMER_WHEEL_ITERATOR; - + // = Friendship. - + + /// Timer handler runs a thread and manages the timers, on behalf of + /// the Proactor. friend class ACE_Proactor_Timer_Handler; - // Timer handler runs a thread and manages the timers, on behalf of - // the Proactor. public: + /// Public type. typedef ACE_Timer_Queue_T<ACE_Handler *, ACE_Proactor_Handle_Timeout_Upcall, ACE_SYNCH_RECURSIVE_MUTEX> TIMER_QUEUE; - // Public type. + /** + * Constructor. If <implementation> is 0, the correct implementation + * object will be created. <delete_implementation> flag determines + * whether the implementation object should be deleted by the + * Proactor or not. If <tq> is 0, a new TIMER_QUEUE is created. + */ ACE_Proactor (ACE_Proactor_Impl *implementation = 0, int delete_implementation = 0, TIMER_QUEUE *tq = 0); - // Constructor. If <implementation> is 0, the correct implementation - // object will be created. <delete_implementation> flag determines - // whether the implementation object should be deleted by the - // Proactor or not. If <tq> is 0, a new TIMER_QUEUE is created. + /// Virtual destruction. virtual ~ACE_Proactor (void); - // Virtual destruction. + /// Get pointer to a process-wide <ACE_Proactor>. <threads> should + /// be part of another method. static ACE_Proactor *instance (size_t threads = 0); - // Get pointer to a process-wide <ACE_Proactor>. <threads> should - // be part of another method. + /// Set pointer to a process-wide <ACE_Proactor> and return existing + /// pointer. static ACE_Proactor *instance (ACE_Proactor *); - // Set pointer to a process-wide <ACE_Proactor> and return existing - // pointer. + /// Delete the dynamically allocated Singleton. static void close_singleton (void); - // Delete the dynamically allocated Singleton. + /// Cleanup method, used by the <ACE_Object_Manager> to destroy the + /// singleton. static void cleanup (void *instance, void *arg); - // Cleanup method, used by the <ACE_Object_Manager> to destroy the - // singleton. - + // = Proactor event loop management methods. + /// Run the event loop until the <ACE_Proactor::handle_events> method + /// returns -1 or the <end_event_loop> method is invoked. static int run_event_loop (void); - // Run the event loop until the <ACE_Proactor::handle_events> method - // returns -1 or the <end_event_loop> method is invoked. + /** + * Run the event loop until the <ACE_Proactor::handle_events> method + * returns -1, the <end_event_loop> method is invoked, or the + * <ACE_Time_Value> expires. + */ static int run_event_loop (ACE_Time_Value &tv); - // Run the event loop until the <ACE_Proactor::handle_events> method - // returns -1, the <end_event_loop> method is invoked, or the - // <ACE_Time_Value> expires. + /** + * Instruct the <ACE_Proactor::instance> to terminate its event + * loop. + * This method wakes up all the threads blocked on waiting for + * completions and end the event loop. + */ static int end_event_loop (void); - // Instruct the <ACE_Proactor::instance> to terminate its event - // loop. - // This method wakes up all the threads blocked on waiting for - // completions and end the event loop. + /// Report if the <ACE_Proactor::instance> event loop is finished. static int event_loop_done (void); - // Report if the <ACE_Proactor::instance> event loop is finished. + /// Close the IO completion port. virtual int close (void); - // Close the IO completion port. + /// This method adds the <handle> to the I/O completion port. This + /// function is a no-op function for Unix systems and returns 0; virtual int register_handle (ACE_HANDLE handle, const void *completion_key); - // This method adds the <handle> to the I/O completion port. This - // function is a no-op function for Unix systems and returns 0; // = Timer management. + /** + * Schedule a <handler> that will expire after <time>. If it + * expires then <act> is passed in as the value to the <handler>'s + * <handle_timeout> callback method. This method returns a + * <timer_id>. This <timer_id> can be used to cancel a timer before + * it expires. The cancellation ensures that <timer_ids> are unique + * up to values of greater than 2 billion timers. As long as timers + * don't stay around longer than this there should be no problems + * with accidentally deleting the wrong timer. Returns -1 on + * failure (which is guaranteed never to be a valid <timer_id>). + */ virtual long schedule_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &time); - // Schedule a <handler> that will expire after <time>. If it - // expires then <act> is passed in as the value to the <handler>'s - // <handle_timeout> callback method. This method returns a - // <timer_id>. This <timer_id> can be used to cancel a timer before - // it expires. The cancellation ensures that <timer_ids> are unique - // up to values of greater than 2 billion timers. As long as timers - // don't stay around longer than this there should be no problems - // with accidentally deleting the wrong timer. Returns -1 on - // failure (which is guaranteed never to be a valid <timer_id>). virtual long schedule_repeating_timer (ACE_Handler &handler, const void *act, @@ -218,97 +227,106 @@ public: // Same as above except <interval> it is used to reschedule the // <handler> automatically. + /// This combines the above two methods into one. Mostly for backward + /// compatibility. virtual long schedule_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &time, const ACE_Time_Value &interval); - // This combines the above two methods into one. Mostly for backward - // compatibility. + /// Cancel all timers associated with this <handler>. Returns number + /// of timers cancelled. virtual int cancel_timer (ACE_Handler &handler, int dont_call_handle_close = 1); - // Cancel all timers associated with this <handler>. Returns number - // of timers cancelled. + /** + * Cancel the single <ACE_Handler> that matches the <timer_id> value + * (which was returned from the <schedule> method). If <act> is + * non-NULL then it will be set to point to the ``magic cookie'' + * argument passed in when the <Handler> was registered. This makes + * it possible to free up the memory and avoid memory leaks. + * Returns 1 if cancellation succeeded and 0 if the <timer_id> + * wasn't found. + */ virtual int cancel_timer (long timer_id, const void **act = 0, int dont_call_handle_close = 1); - // Cancel the single <ACE_Handler> that matches the <timer_id> value - // (which was returned from the <schedule> method). If <act> is - // non-NULL then it will be set to point to the ``magic cookie'' - // argument passed in when the <Handler> was registered. This makes - // it possible to free up the memory and avoid memory leaks. - // Returns 1 if cancellation succeeded and 0 if the <timer_id> - // wasn't found. + /** + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (ACE_Time_Value &wait_time); - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /** + * Block indefinitely until at least one event is dispatched. + * Dispatch a single set of events. If <wait_time> elapses before + * any events occur, return 0. Return 1 on success i.e., when a + * completion is dispatched, non-zero (-1) on errors and errno is + * set accordingly. + */ virtual int handle_events (void); - // Block indefinitely until at least one event is dispatched. - // Dispatch a single set of events. If <wait_time> elapses before - // any events occur, return 0. Return 1 on success i.e., when a - // completion is dispatched, non-zero (-1) on errors and errno is - // set accordingly. + /// Add wakeup dispatch threads (reinit). int wake_up_dispatch_threads (void); - // Add wakeup dispatch threads (reinit). + /// Close all dispatch threads. int close_dispatch_threads (int wait); - // Close all dispatch threads. + /// Number of thread used as a parameter to CreatIoCompletionPort. size_t number_of_threads (void) const; void number_of_threads (size_t threads); - // Number of thread used as a parameter to CreatIoCompletionPort. + /// Get/Set timer queue. TIMER_QUEUE *timer_queue (void) const; void timer_queue (TIMER_QUEUE *timer_queue); - // Get/Set timer queue. - + + /** + * Get the event handle. + * It is a no-op in POSIX platforms and it returns + * ACE_INVALID_HANDLE. + */ virtual ACE_HANDLE get_handle (void) const; - // Get the event handle. - // It is a no-op in POSIX platforms and it returns - // ACE_INVALID_HANDLE. + /// Get the implementation class. virtual ACE_Proactor_Impl *implementation (void) const; - // Get the implementation class. // = Factory methods for the operations // Note that the user does not have to use or know about these // methods. + /// Create the correct implementation class for doing + /// Asynch_Read_Stream. virtual ACE_Asynch_Read_Stream_Impl *create_asynch_read_stream (void); - // Create the correct implementation class for doing - // Asynch_Read_Stream. + /// Create the correct implementation class for doing + /// Asynch_Write_Stream. virtual ACE_Asynch_Write_Stream_Impl *create_asynch_write_stream (void); - // Create the correct implementation class for doing - // Asynch_Write_Stream. + /// Create the correct implementation class for doing + /// Asynch_Read_File. virtual ACE_Asynch_Read_File_Impl *create_asynch_read_file (void); - // Create the correct implementation class for doing - // Asynch_Read_File. + /// Create the correct implementation class for doing + /// Asynch_Write_File. virtual ACE_Asynch_Write_File_Impl *create_asynch_write_file (void); - // Create the correct implementation class for doing - // Asynch_Write_File. + /// Create the correct implementation class for doing Asynch_Accept. virtual ACE_Asynch_Accept_Impl *create_asynch_accept (void); - // Create the correct implementation class for doing Asynch_Accept. + /// Create the correct implementation class for doing + /// Asynch_Transmit_File. virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file (void); - // Create the correct implementation class for doing - // Asynch_Transmit_File. // = Factory methods for the results // Note that the user does not have to use or know about these // methods unless they want to "fake" results. + /// Create the correct implementation class for ACE_Asynch_Read_Stream::Result class. virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -317,8 +335,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Read_Stream::Result class. + /// Create the correct implementation class for ACE_Asynch_Write_Stream::Result. virtual ACE_Asynch_Write_Stream_Result_Impl *create_asynch_write_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -327,8 +345,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Write_Stream::Result. + /// Create the correct implementation class for ACE_Asynch_Read_File::Result. virtual ACE_Asynch_Read_File_Result_Impl *create_asynch_read_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -339,8 +357,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Read_File::Result. + /// Create the correct implementation class for ACE_Asynch_Write_File::Result. virtual ACE_Asynch_Write_File_Result_Impl *create_asynch_write_file_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -351,8 +369,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Write_File::Result. + /// Create the correct implementation class for ACE_Asynch_Accept::Result. virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (ACE_Handler &handler, ACE_HANDLE listen_handle, ACE_HANDLE accept_handle, @@ -362,8 +380,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Accept::Result. + /// Create the correct implementation class for ACE_Asynch_Transmit_File::Result. virtual ACE_Asynch_Transmit_File_Result_Impl *create_asynch_transmit_file_result (ACE_Handler &handler, ACE_HANDLE socket, ACE_HANDLE file, @@ -377,66 +395,69 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create the correct implementation class for ACE_Asynch_Transmit_File::Result. - + + /** + * Create a timer result object which can be used with the Timer + * mechanism of the Proactor. + * If <signal_number> is -1, <POSIX_SIG_Proactor> will create a + * Timer object with a meaningful signal number, choosing the + * largest signal number from the signal mask of the Proactor. + */ virtual ACE_Asynch_Result_Impl *create_asynch_timer (ACE_Handler &handler, const void *act, const ACE_Time_Value &tv, ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - // Create a timer result object which can be used with the Timer - // mechanism of the Proactor. - // If <signal_number> is -1, <POSIX_SIG_Proactor> will create a - // Timer object with a meaningful signal number, choosing the - // largest signal number from the signal mask of the Proactor. protected: + /** + * Post <how_many> completions to the completion port so that all + * threads can wake up. This is used in conjunction with the + * <run_event_loop>. + */ static int post_wakeup_completions (int how_many); - // Post <how_many> completions to the completion port so that all - // threads can wake up. This is used in conjunction with the - // <run_event_loop>. + /// Set the implementation class. virtual void implementation (ACE_Proactor_Impl *implementation); - // Set the implementation class. + /// Delegation/implementation class that all methods will be + /// forwarded to. ACE_Proactor_Impl *implementation_; - // Delegation/implementation class that all methods will be - // forwarded to. + /// Flag used to indicate whether we are responsible for cleaning up + /// the implementation instance. int delete_implementation_; - // Flag used to indicate whether we are responsible for cleaning up - // the implementation instance. + /// Pointer to a process-wide <ACE_Proactor>. static ACE_Proactor *proactor_; - // Pointer to a process-wide <ACE_Proactor>. + /// Must delete the <proactor_> if non-0. static int delete_proactor_; - // Must delete the <proactor_> if non-0. - + + /// Handles timeout events. ACE_Proactor_Timer_Handler *timer_handler_; - // Handles timeout events. - + + /// This will manage the thread in the Timer_Handler. ACE_Thread_Manager thr_mgr_; - // This will manage the thread in the Timer_Handler. + /// Timer Queue. TIMER_QUEUE *timer_queue_; - // Timer Queue. + /// Flag on whether to delete the timer queue. int delete_timer_queue_; - // Flag on whether to delete the timer queue. + /// Terminate the proactor event loop. static sig_atomic_t end_event_loop_; - // Terminate the proactor event loop. + /// Number of threads in the event loop. static sig_atomic_t event_loop_thread_count_; - // Number of threads in the event loop. private: + /// Deny access since member-wise won't work... ACE_Proactor (const ACE_Proactor &); ACE_Proactor &operator= (const ACE_Proactor &); - // Deny access since member-wise won't work... }; #else /* NOT WIN32 or POSIX with AIO features. */ @@ -449,26 +470,26 @@ public: virtual int handle_events (void) { return -1; } virtual int handle_events (ACE_Time_Value &) { return -1; } + /// Placeholder to enable compilation on non-Win32 platforms static ACE_Proactor *instance (size_t threads = 0); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static ACE_Proactor *instance (ACE_Proactor *); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static void close_singleton (void); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static int run_event_loop (void); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static int run_event_loop (ACE_Time_Value &tv); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static int end_event_loop (void); - // Placeholder to enable compilation on non-Win32 platforms + /// Placeholder to enable compilation on non-Win32 platforms static sig_atomic_t event_loop_done (void); - // Placeholder to enable compilation on non-Win32 platforms }; #endif /* ACE_WIN32 && !ACE_HAS_WINCE || ACE_HAS_AIO_CALLS*/ #include "ace/post.h" |