diff options
Diffstat (limited to 'ace/WFMO_Reactor.h')
| -rw-r--r-- | ace/WFMO_Reactor.h | 180 |
1 files changed, 111 insertions, 69 deletions
diff --git a/ace/WFMO_Reactor.h b/ace/WFMO_Reactor.h index 208d57f584b..c0bef5d74c0 100644 --- a/ace/WFMO_Reactor.h +++ b/ace/WFMO_Reactor.h @@ -31,8 +31,10 @@ class ACE_Handle_Set; class ACE_Export ACE_Wakeup_All_Threads_Handler : public ACE_Event_Handler { // = TITLE + // // This is a helper class whose sole purpose is to handle events // on <ACE_WFMO_Reactor->wakeup_all_threads_> + // public: virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); // Called when the <ACE_WFMO_Reactor->wakeup_all_threads_> @@ -41,6 +43,7 @@ public: class ACE_Export ACE_WFMO_Reactor_Handler_Repository { // = TITLE + // // Used to map <ACE_HANDLE>s onto the appropriate // <ACE_Event_Handler> * and other information. // @@ -50,11 +53,13 @@ public: class Common_Info { // = TITLE + // // This struct contains the necessary information for every // <Event_Handler> entry. The reason the event is not in this // structure is because we need to pass an event array into // WaitForMultipleObjects and therefore keeping the events // seperate makes sense. + // public: int io_entry_; // This indicates whether this entry is for I/O or for a regular @@ -64,18 +69,19 @@ public: // The assosiated <Event_Handler> ACE_HANDLE io_handle_; - // The I/O handle related to the <Event_Handler>. - // This entry is only valid if the <io_entry_> flag is true. + // The I/O handle related to the <Event_Handler>. This entry is + // only valid if the <io_entry_> flag is true. long network_events_; - // This is the set of events that the <Event_Handler> is interested in - // This entry is only valid if the <io_entry_> flag is true. + // This is the set of events that the <Event_Handler> is + // interested in This entry is only valid if the <io_entry_> flag + // is true. int delete_event_; // This flag indicates that <WFMO_Reactor> created the event on // behalf of the user. Therefore we need to clean this up when the - // <Event_Handler> removes itself from <WFMO_Reactor>. - // This entry is only valid if the <io_entry_> flag is true. + // <Event_Handler> removes itself from <WFMO_Reactor>. This entry + // is only valid if the <io_entry_> flag is true. Common_Info (void); // Constructor used for initializing the structure @@ -97,14 +103,17 @@ public: class Current_Info : public Common_Info { // = TITLE + // // This structure inherits from the common structure to add // information for current entries. + // public: int delete_entry_; // This is set when the entry needed to be deleted. ACE_Reactor_Mask close_masks_; - // These are the masks related to <handle_close> for the <Event_Handler>. + // These are the masks related to <handle_close> for the + // <Event_Handler>. int suspend_entry_; // This is set when the entry needed to be suspended. @@ -135,8 +144,10 @@ public: class To_Be_Added_Info : public Common_Info { // = TITLE + // // This structure inherits from the common structure to add // information for <to_be_added> entries. + // public: ACE_HANDLE event_handle_; // Handle for the event @@ -163,8 +174,10 @@ public: class Suspended_Info : public Common_Info { // = TITLE + // // This structure inherits from the common structure to add // information for suspended entries. + // public: ACE_HANDLE event_handle_; // Handle for the event @@ -173,7 +186,8 @@ public: // This is set when the entry needed to be deleted. ACE_Reactor_Mask close_masks_; - // These are the masks related to <handle_close> for the <Event_Handler>. + // These are the masks related to <handle_close> for the + // <Event_Handler>. int resume_entry_; // This is set when the entry needed to be resumed. @@ -249,7 +263,8 @@ public: // Maximum ACE_HANDLE value, plus 1. ACE_HANDLE *handles (void) const; - // Pointer to the beginning of the current array of <ACE_HANDLE> *'s. + // Pointer to the beginning of the current array of <ACE_HANDLE> + // *'s. Current_Info *current_info (void) const; // Pointer to the beginning of the current array of @@ -347,18 +362,21 @@ protected: class ACE_Export ACE_WFMO_Reactor_Notify : public ACE_Event_Handler { // = TITLE - // Unblock the <ACE_WFMO_Reactor> from its event loop, passing it an - // optional <ACE_Event_Handler> to dispatch. + // + // Unblock the <ACE_WFMO_Reactor> from its event loop, passing + // it an optional <ACE_Event_Handler> to dispatch. // // = DESCRIPTION + // // This implementation is necessary for cases where the - // <ACE_WFMO_Reactor> is run in a multi-threaded program. In this - // case, we need to be able to unblock WaitForMultipleObjects() - // when updates occur other than in the main <ACE_WFMO_Reactor> - // thread. To do this, we signal an auto-reset event the - // <ACE_WFMO_Reactor> is listening on. If an <ACE_Event_Handler> - // and <ACE_Reactor_Mask> is passed to <notify>, the appropriate - // <handle_*> method is dispatched. + // <ACE_WFMO_Reactor> is run in a multi-threaded program. In + // this case, we need to be able to unblock + // WaitForMultipleObjects() when updates occur other than in the + // main <ACE_WFMO_Reactor> thread. To do this, we signal an + // auto-reset event the <ACE_WFMO_Reactor> is listening on. If + // an <ACE_Event_Handler> and <ACE_Reactor_Mask> is passed to + // <notify>, the appropriate <handle_*> method is dispatched. + // public: ACE_WFMO_Reactor_Notify (void); // Constructor @@ -374,9 +392,9 @@ public: // occur. All we do is enqueue <event_handler> and <mask> onto the // <ACE_Message_Queue> and wakeup the WFMO_Reactor by signaling its // <ACE_Event> handle. The <ACE_Time_Value> indicates how long to - // blocking trying to notify the <WFMO_Reactor>. If <timeout> == 0, the - // caller will block until action is possible, else will wait until - // the relative time specified in <timeout> elapses). + // blocking trying to notify the <WFMO_Reactor>. If <timeout> == 0, + // the caller will block until action is possible, else will wait + // until the relative time specified in <timeout> elapses). virtual ACE_HANDLE get_handle (void) const; // Returns a handle to the <ACE_Auto_Event>. @@ -404,9 +422,9 @@ private: // Pointer to the wfmo_reactor's timer queue. virtual int handle_signal (int signum, siginfo_t * = 0, ucontext_t * = 0); - // Called when the notification event waited on by <ACE_WFMO_Reactor> - // is signaled. This dequeues all pending <ACE_Event_Handlers> and - // dispatches them. + // Called when the notification event waited on by + // <ACE_WFMO_Reactor> is signaled. This dequeues all pending + // <ACE_Event_Handlers> and dispatches them. ACE_Auto_Event wakeup_one_thread_; // An auto event is used so that we can <signal> it to wakeup one @@ -432,15 +450,32 @@ private: class ACE_Export ACE_WFMO_Reactor : public ACE_Reactor_Impl { // = TITLE + // // An object oriented event demultiplexor and event handler // WFMO_Reactor for Win32 WaitForMultipleObjects // // = DESCRIPTION - // The ACE_WFMO_Reactor is an object-oriented event demultiplexor - // and event handler Reactor. The sources of events that the - // ACE_WFMO_Reactor waits for and dispatches includes I/O events, - // general Win32 synchronization events (such as mutexes, - // semaphores, threads, etc.) and timer events. + // + // The ACE_WFMO_Reactor is an object-oriented event + // demultiplexor and event handler Reactor. The sources of + // events that the ACE_WFMO_Reactor waits for and dispatches + // includes I/O events, general Win32 synchronization events + // (such as mutexes, semaphores, threads, etc.) and timer + // events. + // + // Note that changes to the state of WFMO_Reactor are not + // instantaneous. Most changes (registration, removal, + // suspension, and resumption of handles, and changes in + // ownership) are made when the WFMO_Reactor reaches a stable + // state. Users should be careful, specially when removing + // handlers. This is because the WFMO_Reactor will call + // handle_close on the handler when it is finally removed and + // not when remove_handler is called. If the handler is not + // going to be around when the WFMO_Reactor calls + // handler->handle_close(), use the DONT_CALL flag with + // remove_handler(). Or else, dynamically allocate the handler, + // and then call "delete this" inside handler->handle_close(). + // public: friend class ACE_WFMO_Reactor_Handler_Repository; friend class ACE_WFMO_Reactor_Test; @@ -448,8 +483,8 @@ public: enum { DEFAULT_SIZE = MAXIMUM_WAIT_OBJECTS - 2 - // Default size of the WFMO_Reactor's handle table. Two slots will be - // added to the <size> parameter in the constructor and open + // Default size of the WFMO_Reactor's handle table. Two slots will + // be added to the <size> parameter in the constructor and open // methods which will store handles used for internal management // purposes. }; @@ -464,17 +499,17 @@ public: int unused = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_WFMO_Reactor> with size <size>. Two slots will be - // added to the <size> parameter which will store handles used for - // internal management purposes. + // Initialize <ACE_WFMO_Reactor> with size <size>. Two slots will + // be added to the <size> parameter which will store handles used + // for internal management purposes. virtual int open (size_t size = DEFAULT_SIZE, int restart = 0, ACE_Sig_Handler * = 0, ACE_Timer_Queue * = 0); - // Initialize <ACE_WFMO_Reactor> with size <size>. Two slots will be - // added to the <size> parameter which will store handles used for - // internal management purposes. + // Initialize <ACE_WFMO_Reactor> with size <size>. Two slots will + // be added to the <size> parameter which will store handles used + // for internal management purposes. virtual int set_sig_handler (ACE_Sig_Handler *signal_handler); // Use a user specified signal handler instead. @@ -529,13 +564,13 @@ public: virtual int register_handler (ACE_Event_Handler *event_handler, ACE_HANDLE event_handle = ACE_INVALID_HANDLE); - // Register an <ACE_Event_Handler> <event_handler>. Since no Event Mask is - // passed through this interface, it is assumed that the <handle> - // being passed in is an event handle and when the event becomes - // signaled, <WFMO_Reactor> will call handle_signal on <event_handler>. If - // <handle> == <ACE_INVALID_HANDLE> the <ACE_WFMO_Reactor> will call - // the <get_handle> method of <event_handler> to extract the underlying event - // handle. + // Register an <ACE_Event_Handler> <event_handler>. Since no Event + // Mask is passed through this interface, it is assumed that the + // <handle> being passed in is an event handle and when the event + // becomes signaled, <WFMO_Reactor> will call handle_signal on + // <event_handler>. If <handle> == <ACE_INVALID_HANDLE> the + // <ACE_WFMO_Reactor> will call the <get_handle> method of + // <event_handler> to extract the underlying event handle. virtual int register_handler (ACE_HANDLE event_handle, ACE_HANDLE io_handle, @@ -543,12 +578,13 @@ public: ACE_Reactor_Mask mask); // Register an <ACE_Event_Handler> <event_handle>. <mask> specifies // the network events that the <event_handler> is interested in. If - // <io_handle> == <ACE_INVALID_HANDLE> the <ACE_WFMO_Reactor> will call - // the <get_handle> method of <event_handler> to extract the underlying I/O - // handle. If the <event_handle> == <ACE_INVALID_HANDLE>, WFMO_Reactor - // will create an event for associating it with the I/O handle. When - // the <event_handle> is signalled, the appropriate <handle_*> - // callback will be invoked on the <Event_Handler> + // <io_handle> == <ACE_INVALID_HANDLE> the <ACE_WFMO_Reactor> will + // call the <get_handle> method of <event_handler> to extract the + // underlying I/O handle. If the <event_handle> == + // <ACE_INVALID_HANDLE>, WFMO_Reactor will create an event for + // associating it with the I/O handle. When the <event_handle> is + // signalled, the appropriate <handle_*> callback will be invoked on + // the <Event_Handler> virtual int register_handler (ACE_HANDLE io_handle, ACE_Event_Handler *event_handler, @@ -567,7 +603,8 @@ public: virtual int register_handler (const ACE_Handle_Set &handles, ACE_Event_Handler *event_handler, ACE_Reactor_Mask mask); - // Register <event_handler> with all the <handles> in the <Handle_Set>. + // Register <event_handler> with all the <handles> in the + // <Handle_Set>. virtual int register_handler (int signum, ACE_Event_Handler *new_sh, @@ -597,14 +634,15 @@ public: ACE_Reactor_Mask mask); // Removes <handle> from the <ACE_WFMO_Reactor>. If <mask> == // <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of - // the <event_handler> is not invoked. Note that the <handle> can either be the - // <event_handle> or the <io_handle> + // the <event_handler> is not invoked. Note that the <handle> can + // either be the <event_handle> or the <io_handle> // // For the case of I/O entries, this removes the <mask> binding of // <Event_Handler> whose handle is <handle> from <WFMO_Reactor>. If - // there are no more bindings for this <event_handler> then it is removed from - // the WFMO_Reactor. For simple event entries, mask is mostly ignored - // and the <Event_Handler> is always removed from <WFMO_Reactor> + // there are no more bindings for this <event_handler> then it is + // removed from the WFMO_Reactor. For simple event entries, mask is + // mostly ignored and the <Event_Handler> is always removed from + // <WFMO_Reactor> virtual int remove_handler (const ACE_Handle_Set &handle_set, ACE_Reactor_Mask); @@ -628,7 +666,8 @@ public: // = Suspend and resume Handlers. virtual int suspend_handler (ACE_Event_Handler *event_handler); - // Suspend <event_handler> temporarily. Use <event_handler->get_handle()> to get the handle. + // Suspend <event_handler> temporarily. Use + // <event_handler->get_handle()> to get the handle. virtual int suspend_handler (ACE_HANDLE handle); // Suspend <handle> temporarily. @@ -640,7 +679,8 @@ public: // Suspend all <handles> temporarily. virtual int resume_handler (ACE_Event_Handler *event_handler); - // Resume <event_handler>. Use <event_handler->get_handle()> to get the handle. + // Resume <event_handler>. Use <event_handler->get_handle()> to get + // the handle. virtual int resume_handler (ACE_HANDLE handle); // Resume <handle>. @@ -721,11 +761,12 @@ public: virtual int notify (ACE_Event_Handler * = 0, ACE_Reactor_Mask = ACE_Event_Handler::EXCEPT_MASK, ACE_Time_Value * = 0); - // Wakeup one <ACE_WFMO_Reactor> thread if it is currently blocked in - // <WaitForMultipleObjects>. The <ACE_Time_Value> indicates how - // long to blocking trying to notify the <WFMO_Reactor>. If <timeout> == - // 0, the caller will block until action is possible, else will wait - // until the relative time specified in <timeout> elapses). + // Wakeup one <ACE_WFMO_Reactor> thread if it is currently blocked + // in <WaitForMultipleObjects>. The <ACE_Time_Value> indicates how + // long to blocking trying to notify the <WFMO_Reactor>. If + // <timeout> == 0, the caller will block until action is possible, + // else will wait until the relative time specified in <timeout> + // elapses). virtual void max_notify_iterations (int); // Set the maximum number of times that the @@ -903,6 +944,7 @@ protected: ACE_Process_Mutex lock_; // Synchronization for the ACE_WFMO_Reactor. + // // A Process Mutex is used here because of two reasons: // (a) The implementation of ACE_Thread_Mutex uses CriticalSections // CriticalSections are not waitable using ::WaitForMultipleObjects @@ -938,12 +980,12 @@ protected: // Count of currently active threads ACE_thread_t owner_; - // The thread which is "owner" of the WFMO_Reactor. The owner concept - // is used because we don't want multiple threads to try to expire - // timers. Therefore the "owner" thread is the only one allowed to - // expire timers. Also, the owner thread is the only thread which - // waits on the notify handle. Note that the ownership can be - // transferred. + // The thread which is "owner" of the WFMO_Reactor. The owner + // concept is used because we don't want multiple threads to try to + // expire timers. Therefore the "owner" thread is the only one + // allowed to expire timers. Also, the owner thread is the only + // thread which waits on the notify handle. Note that the ownership + // can be transferred. ACE_thread_t new_owner_; // The owner to be of the WFMO_Reactor |