diff options
Diffstat (limited to 'ace/POSIX_Proactor.h')
| -rw-r--r-- | ace/POSIX_Proactor.h | 380 |
1 files changed, 209 insertions, 171 deletions
diff --git a/ace/POSIX_Proactor.h b/ace/POSIX_Proactor.h index ef43f442dd9..d8f61a25b0f 100644 --- a/ace/POSIX_Proactor.h +++ b/ace/POSIX_Proactor.h @@ -1,20 +1,17 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// POSIX_Proactor.h -// -// = AUTHOR -// Irfan Pyarali <irfan@cs.wustl.edu>, -// Tim Harrison <harrison@cs.wustl.edu> and -// Alexander Babu Arulanthu <alex@cs.wustl.edu> -// -// ============================================================================ + +//============================================================================= +/** + * @file POSIX_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_POSIX_PROACTOR_H #define ACE_POSIX_PROACTOR_H @@ -29,25 +26,29 @@ #include "ace/Pipe.h" #include "ace/POSIX_Asynch_IO.h" +/** + * @class ACE_POSIX_Proactor + * + * @brief POSIX implementation of the Proactor. + * + * There are two different strategies by which Proactor can get + * to know the completion of <aio> operations. One is based on + * Asynchronous I/O Control Blocks (AIOCB) where a list of + * AIOCBs are stored and completion status of the corresponding + * operations are queried on them. The other one is based on + * POSIX Real Time signals. This class abstracts out the common + * code needed for both the strategies. <ACE_AIOCB_Proactor> and + * <ACE_SIG_Proactor> specialize this class for each strategy. + */ class ACE_Export ACE_POSIX_Proactor : public ACE_Proactor_Impl { - // = TITLE - // POSIX implementation of the Proactor. - // - // = DESCRIPTION - // There are two different strategies by which Proactor can get - // to know the completion of <aio> operations. One is based on - // Asynchronous I/O Control Blocks (AIOCB) where a list of - // AIOCBs are stored and completion status of the corresponding - // operations are queried on them. The other one is based on - // POSIX Real Time signals. This class abstracts out the common - // code needed for both the strategies. <ACE_AIOCB_Proactor> and - // <ACE_SIG_Proactor> specialize this class for each strategy. + /** + * For <POSIX_SIG_Asynch_Accept> operation, this handler class does + * the actual work, has to register the real-time signal with the + * Proactor. + */ friend class ACE_POSIX_SIG_Asynch_Accept_Handler; - // For <POSIX_SIG_Asynch_Accept> operation, this handler class does - // the actual work, has to register the real-time signal with the - // Proactor. public: enum Proactor_Type @@ -57,44 +58,46 @@ public: PROACTOR_SIG = 2, PROACTOR_SUN = 3 }; - + virtual Proactor_Type get_impl_type (void); + /// Virtual destructor. virtual ~ACE_POSIX_Proactor (void); - // Virtual destructor. + /// Close down the Proactor. virtual int close (void); - // Close down the Proactor. + /// This function is a no-op function for Unix systems. Returns 0. virtual int register_handle (ACE_HANDLE handle, const void *completion_key); - // This function is a no-op function for Unix systems. Returns 0. - + + /** + * Post a result to the completion port of the Proactor. If errors + * occur, the result will be deleted by this method. If successful, + * the result will be deleted by the Proactor when the result is + * removed from the completion port. Therefore, the result should + * have been dynamically allocated and should be orphaned by the + * user once this method is called. + */ virtual int post_completion (ACE_POSIX_Asynch_Result *result) = 0; - // Post a result to the completion port of the Proactor. If errors - // occur, the result will be deleted by this method. If successful, - // the result will be deleted by the Proactor when the result is - // removed from the completion port. Therefore, the result should - // have been dynamically allocated and should be orphaned by the - // user once this method is called. + /// @@ This is a no-op on POSIX platforms. Returns 0. int wake_up_dispatch_threads (void); - // @@ This is a no-op on POSIX platforms. Returns 0. + /// @@ This is a no-op on POSIX platforms. Returns 0. int close_dispatch_threads (int wait); - // @@ This is a no-op on POSIX platforms. Returns 0. + /// @@ This is a no-op on POSIX platforms. Returns 0. size_t number_of_threads (void) const; void number_of_threads (size_t threads); - // @@ This is a no-op on POSIX platforms. Returns 0. + /// This is a no-op in POSIX. Returns ACE_INVALID_HANDLE. virtual ACE_HANDLE get_handle (void) const; - // This is a no-op in POSIX. Returns ACE_INVALID_HANDLE. // Methods used to create Asynch_IO_Result objects. We create the right // objects here in these methods. - virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result + virtual ACE_Asynch_Read_Stream_Result_Impl *create_asynch_read_stream_result (ACE_Handler &handler, ACE_HANDLE handle, ACE_Message_Block &message_block, @@ -104,7 +107,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Write_Stream_Result_Impl *create_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, @@ -114,7 +117,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Read_File_Result_Impl *create_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, @@ -125,8 +128,8 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - - virtual ACE_Asynch_Write_File_Result_Impl *create_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, @@ -138,7 +141,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result + virtual ACE_Asynch_Accept_Result_Impl *create_asynch_accept_result (ACE_Handler &handler, ACE_HANDLE listen_handle, ACE_HANDLE accept_handle, @@ -149,7 +152,7 @@ public: int priority = 0, int signal_number = ACE_SIGRTMIN); - virtual ACE_Asynch_Transmit_File_Result_Impl *create_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, @@ -163,89 +166,100 @@ public: ACE_HANDLE event = ACE_INVALID_HANDLE, int priority = 0, int signal_number = ACE_SIGRTMIN); - - virtual ACE_Asynch_Result_Impl *create_asynch_timer + + /// Create a timer result object which can be used with the Timer + /// mechanism 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. - + protected: + /// Constructor. ACE_POSIX_Proactor (void); - // Constructor. + /** + * Protect against structured exceptions caused by user code when + * dispatching handles. The <completion_key> is not very useful + * compared to <AST> that can be associated each asynchronous + * operation. <completion_key> is implemented right now for the + * POSIX Proators. + */ void application_specific_code (ACE_POSIX_Asynch_Result *asynch_result, u_long bytes_transferred, int success, const void *completion_key, u_long error); - // Protect against structured exceptions caused by user code when - // dispatching handles. The <completion_key> is not very useful - // compared to <AST> that can be associated each asynchronous - // operation. <completion_key> is implemented right now for the - // POSIX Proators. + /** + * 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>. + */ virtual 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>. protected: + /// Handler to handle the wakeups. This works in conjunction with the + /// <ACE_Proactor::run_event_loop>. ACE_Handler wakeup_handler_; - // Handler to handle the wakeups. This works in conjunction with the - // <ACE_Proactor::run_event_loop>. }; // Forward declarations. class ACE_AIOCB_Notify_Pipe_Manager; +/** + * @class ACE_POSIX_AIOCB_Proactor + * + * @brief This Proactor makes use of Asynchronous I/O Control Blocks + * (AIOCB) to notify/get the completion status of the <aio_> + * operations issued. + */ class ACE_Export ACE_POSIX_AIOCB_Proactor : public ACE_POSIX_Proactor { - // = TITLE - // This Proactor makes use of Asynchronous I/O Control Blocks - // (AIOCB) to notify/get the completion status of the <aio_> - // operations issued. + /// Handler needs to call application specific code. friend class ACE_AIOCB_Notify_Pipe_Manager; - // Handler needs to call application specific code. - + + /// This class does the registering of Asynch Operations with the + /// Proactor which is necessary in the AIOCB strategy. friend class ACE_POSIX_AIOCB_Asynch_Operation; - // This class does the registering of Asynch Operations with the - // Proactor which is necessary in the AIOCB strategy. // friend class ACE_POSIX_AIOCB_Asynch_Accept_Handler; For // <Asynch_Accept> operation class, this helper class takes care of // doing the <Asynch_Accept>. public: + /// Constructor defines max number asynchronous operations + /// which can be started at the same time ACE_POSIX_AIOCB_Proactor (size_t nmaxop = 256) ; //ACE_RTSIG_MAX - // Constructor defines max number asynchronous operations - // which can be started at the same time virtual Proactor_Type get_impl_type (void); + /// Destructor. virtual ~ACE_POSIX_AIOCB_Proactor (void); - // Destructor. + /** + * 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. + /// Post a result to the completion port of the Proactor. virtual int post_completion (ACE_POSIX_Asynch_Result *result); - // Post a result to the completion port of the Proactor. // = Methods used to create Asynch_IO objects. We create the right // objects here in these methods. @@ -264,104 +278,119 @@ public: protected: + /// Special constructor for ACE_SUN_Proactor ACE_POSIX_AIOCB_Proactor (size_t nmaxop, int flg); - // Special constructor for ACE_SUN_Proactor - + + /// Call these methods from derived class when virtual table is + /// built. void create_notify_manager (void); void delete_notify_manager (void); - // Call these methods from derived class when virtual table is - // built. - + + /** + * Dispatch a single set of events. If <milli_seconds> elapses + * before any events occur, return 0. Return 1 if a completion + * dispatched. Return -1 on errors. + */ virtual int handle_events (u_long milli_seconds); - // Dispatch a single set of events. If <milli_seconds> elapses - // before any events occur, return 0. Return 1 if a completion - // dispatched. Return -1 on errors. + /// We will call the base class's application_specific_code from + /// here. void application_specific_code (ACE_POSIX_Asynch_Result *asynch_result, u_long bytes_transferred, int success, const void *completion_key, u_long error); - // We will call the base class's application_specific_code from - // here. - + virtual int register_and_start_aio (ACE_POSIX_Asynch_Result *result, int op); virtual int start_aio (ACE_POSIX_Asynch_Result *result, - int op); - + int op); + + /// Extract the results of aio. ACE_POSIX_Asynch_Result *find_completed_aio (int &error_status, int &return_status); - // Extract the results of aio. + /// This class takes care of doing <accept> when we use + /// AIO_CONTROL_BLOCKS strategy. ACE_AIOCB_Notify_Pipe_Manager *aiocb_notify_pipe_manager_; - // This class takes care of doing <accept> when we use - // AIO_CONTROL_BLOCKS strategy. - + + /// Use a dynamically allocated array to keep track of all the aio's + /// issued currently. aiocb **aiocb_list_; ACE_POSIX_Asynch_Result **result_list_; - // Use a dynamically allocated array to keep track of all the aio's - // issued currently. - + + /// To maintain the maximum size of the array (list). size_t aiocb_list_max_size_; - // To maintain the maximum size of the array (list). + /// To maintain the current size of the array (list). size_t aiocb_list_cur_size_; - // To maintain the current size of the array (list). #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) + /// Mutex to protect work with lists. ACE_Thread_Mutex mutex_; - // Mutex to protect work with lists. #endif /* ACE_MT_SAFE */ }; +/** + * @class ACE_POSIX_SIG_Proactor + * + * @brief This Proactor implementation does compeltion querying using + * POSIX Real Time signals. <sigtimedwait>/<sigwaitinfo> call is + * used to get the notify/get the completions. + * The real-time signals that are going to be used with this + * Proactor should be given apriori in the constructor, so that + * those signals can be masked from asynchornous delivery. + */ class ACE_Export ACE_POSIX_SIG_Proactor : public ACE_POSIX_Proactor { - // = TITLE - // This Proactor implementation does compeltion querying using - // POSIX Real Time signals. <sigtimedwait>/<sigwaitinfo> call is - // used to get the notify/get the completions. - // The real-time signals that are going to be used with this - // Proactor should be given apriori in the constructor, so that - // those signals can be masked from asynchornous delivery. + /** + * This class does the registering of Asynch Operations with the + * Proactor which is necessary in the SIG strategy, because we need + * to store the signal number. + */ friend class ACE_POSIX_SIG_Asynch_Operation; - // This class does the registering of Asynch Operations with the - // Proactor which is necessary in the SIG strategy, because we need - // to store the signal number. public: + /** + * This constructor masks only the <ACE_SIGRTMIN> + * real-time signal. Only this signal should be used to issue + * asynchronous operations using this Proctor. + */ ACE_POSIX_SIG_Proactor (void); - // This constructor masks only the <ACE_SIGRTMIN> - // real-time signal. Only this signal should be used to issue - // asynchronous operations using this Proctor. virtual Proactor_Type get_impl_type (void); + /** + * This constructor should be used to tell the Proactor to mask and + * wait for the real-time signals specified in this set. Only these + * signals should be used by the asynchronous operations when they + * use this Proactor. + */ ACE_POSIX_SIG_Proactor (const sigset_t mask_set); - // This constructor should be used to tell the Proactor to mask and - // wait for the real-time signals specified in this set. Only these - // signals should be used by the asynchronous operations when they - // use this Proactor. + /// Destructor. virtual ~ACE_POSIX_SIG_Proactor (void); - // Destructor. + /** + * 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. - + + /// Post a result to the completion port of the Proactor. virtual int post_completion (ACE_POSIX_Asynch_Result *result); - // Post a result to the completion port of the Proactor. // = Methods used to create Asynch_IO objects. We create the right // objects here in these methods. @@ -378,73 +407,82 @@ public: virtual ACE_Asynch_Transmit_File_Impl *create_asynch_transmit_file (void); + /** + * If <signal_number> is -1, check with the Proactor and use one of + * the signals that is present in the mask set (i.e. the signals for + * which the Proactor will be waiting) of the Proactor. If there are + * more than one signal, the higher numbered signal will be chosen. + */ 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); - // If <signal_number> is -1, check with the Proactor and use one of - // the signals that is present in the mask set (i.e. the signals for - // which the Proactor will be waiting) of the Proactor. If there are - // more than one signal, the higher numbered signal will be chosen. protected: + /// To setup the handler for a real-time signbal. int setup_signal_handler (int signal_number) const; - // To setup the handler for a real-time signbal. + /// Dummy signal handler. This wont get called at all, since we are + /// going to be masking the signal in all the threads. static void null_handler (int signal_number, siginfo_t *info, void *context); - // Dummy signal handler. This wont get called at all, since we are - // going to be masking the signal in all the threads. - + + /// To mask all the signals in a thread. int mask_all (void) const; - // To mask all the signals in a thread. + /** + * Dispatch a single set of events. If <milli_seconds> elapses + * before any events occur, return 0. Return 1 if a completion is + * dispatched. Return -1 on errors. + */ virtual int handle_events (u_long milli_seconds); - // Dispatch a single set of events. If <milli_seconds> elapses - // before any events occur, return 0. Return 1 if a completion is - // dispatched. Return -1 on errors. + /** + * These signals are used for completion notification by the + * Proactor. The signals specified while issueing <Asynch + * Operation>s are stored here in this set. These signals are masked + * for a thread when it calls the Proactor::handle_events. + */ sigset_t RT_completion_signals_; - // These signals are used for completion notification by the - // Proactor. The signals specified while issueing <Asynch - // Operation>s are stored here in this set. These signals are masked - // for a thread when it calls the Proactor::handle_events. }; +/** + * @class ACE_POSIX_Asynch_Timer + * + * @brief This class is posted to the completion port when a timer + * expires. When the <complete method> of this object is + * called, the <handler>'s <handle_timeout> method will be + * called. + */ class ACE_Export ACE_POSIX_Asynch_Timer : public ACE_POSIX_Asynch_Result { - // = TITLE - // This class is posted to the completion port when a timer - // expires. When the <complete method> of this object is - // called, the <handler>'s <handle_timeout> method will be - // called. - + + /// The factory method for this class is with the POSIX_Proactor + /// class. friend class ACE_POSIX_Proactor; friend class ACE_POSIX_SIG_Proactor; - // The factory method for this class is with the POSIX_Proactor - // class. protected: + /// Constructor. ACE_POSIX_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); - // Constructor. - + + /// Destructor. virtual ~ACE_POSIX_Asynch_Timer (void) {} - // Destructor. + /// This method calls the <handler>'s handle_timeout method. virtual void complete (u_long bytes_transferred, int success, const void *completion_key, u_long error = 0); - // This method calls the <handler>'s handle_timeout method. + /// Time value requested by caller ACE_Time_Value time_; - // Time value requested by caller }; #if defined (__ACE_INLINE__) |