00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Reactor.h 00006 * 00007 * $Id: Reactor.h 88832 2010-02-04 09:57:42Z johnnyw $ 00008 * 00009 * @author Irfan Pyarali <irfan@cs.wustl.edu> 00010 * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> 00011 */ 00012 //============================================================================= 00013 00014 #ifndef ACE_REACTOR_H 00015 #define ACE_REACTOR_H 00016 00017 #include /**/ "ace/pre.h" 00018 00019 // Timer Queue is a complicated template class. A simple forward 00020 // declaration will not work. 00021 #include "ace/Timer_Queuefwd.h" 00022 00023 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00024 # pragma once 00025 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00026 00027 // Contains the timer related interface for the Reactor. 00028 #include "ace/Reactor_Timer_Interface.h" 00029 00030 // Event_Handler.h contains the definition of ACE_Reactor_Mask 00031 #include "ace/Event_Handler.h" 00032 00033 // Get ACE_Time_Value in 00034 #include "ace/Time_Value.h" 00035 00036 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00037 00038 class ACE_Reactor_Impl; 00039 class ACE_Handle_Set; 00040 class ACE_Sig_Action; 00041 class ACE_Sig_Handler; 00042 class ACE_Sig_Set; 00043 00044 /* 00045 * Hook to specialize the Reactor implementation with the concrete 00046 * Reactor type, for exmaple, select, thread pool reactor known 00047 * at compile time. 00048 */ 00049 //@@ REACTOR_SPL_INCLUDE_FORWARD_DECL_ADD_HOOK 00050 00051 /** 00052 * @class ACE_Reactor 00053 * 00054 * @brief This class forwards all methods to its delegation/implementation class, e.g., 00055 * ACE_Select_Reactor or ACE_WFMO_Reactor. 00056 */ 00057 class ACE_Export ACE_Reactor : public ACE_Reactor_Timer_Interface 00058 { 00059 public: 00060 /// Operations on the "ready" mask and the "dispatch" mask. 00061 enum 00062 { 00063 /// Retrieve current value of the the "ready" mask or the 00064 /// "dispatch" mask. 00065 GET_MASK = 1, 00066 /// Set value of bits to new mask (changes the entire mask). 00067 SET_MASK = 2, 00068 /// Bitwise "or" the value into the mask (only changes enabled 00069 /// bits). 00070 ADD_MASK = 3, 00071 /// Bitwise "and" the negation of the value out of the mask (only 00072 /// changes enabled bits). 00073 CLR_MASK = 4 00074 }; 00075 00076 /** 00077 * You can specify a hook function to event-handling methods that will 00078 * be called after each iteration of event handling. If the hook function 00079 * returns a non-zero value, the event loop will immediately resume 00080 * waiting for the next event(s) to process without checking the error 00081 * status of the just-completed iteration of event handling or the 00082 * end-of-loop indication. If the hook function returns 0, the event 00083 * handling error status and the end-of-loop indication will be checked 00084 * as normal, just as if there is no hook function specified. 00085 */ 00086 typedef int (*REACTOR_EVENT_HOOK)(ACE_Reactor *); 00087 00088 /// Get pointer to a process-wide ACE_Reactor. 00089 static ACE_Reactor *instance (void); 00090 00091 /** 00092 * Set pointer to a process-wide ACE_Reactor and return existing 00093 * pointer. If @a delete_reactor == true then we'll delete the Reactor 00094 * at destruction time. 00095 */ 00096 static ACE_Reactor *instance (ACE_Reactor *, bool delete_reactor = false); 00097 00098 /// Delete the dynamically allocated Singleton 00099 static void close_singleton (void); 00100 00101 /// Name of the dll in which the dll lives. 00102 static const ACE_TCHAR *dll_name (void); 00103 00104 /// Name of the component--ACE_Reactor in this case. 00105 static const ACE_TCHAR *name (void); 00106 00107 // = Singleton reactor event loop management methods. 00108 00109 // Note that these method ONLY work on the "Singleton Reactor," 00110 // i.e., the one returned from <ACE_Reactor::instance>. 00111 /** 00112 * Run the event loop until the 00113 * <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events> 00114 * method returns -1 or the <end_event_loop> method is invoked. 00115 * Note that this method can only be used by the singleton 00116 * <ACE_Reactor::instance>. Thus, to run another reactor use 00117 * <ACE_Reactor::run_reactor_event_loop>. 00118 * 00119 * @deprecated Use ACE_Reactor::instance()->run_reactor_event_loop() instead 00120 */ 00121 static int run_event_loop (void); 00122 static int run_alertable_event_loop (void); 00123 00124 /** 00125 * Run the event loop until the <ACE_Reactor::handle_events> or 00126 * <ACE_Reactor::alertable_handle_events> methods returns -1, the 00127 * <end_event_loop> method is invoked, or the ACE_Time_Value 00128 * expires. Note that this method can only be used by the singleton 00129 * <ACE_Reactor::instance>. Thus, to run another reactor use 00130 * <ACE_Reactor::run_reactor_event_loop>. 00131 * 00132 * @deprecated Use ACE_Reactor::instance()->run_reactor_event_loop() instead 00133 */ 00134 static int run_event_loop (ACE_Time_Value &tv); 00135 static int run_alertable_event_loop (ACE_Time_Value &tv); 00136 00137 /** 00138 * Instruct the <ACE_Reactor::instance> to terminate its event loop 00139 * and notifies the <ACE_Reactor::instance> so that it can wake up 00140 * and close down gracefully. Note that this method can only be 00141 * used by the singleton <ACE_Reactor::instance>. Thus, to 00142 * terminate another reactor, use 00143 * <ACE_Reactor::end_reactor_event_loop>. 00144 * 00145 * @deprecated Use ACE_Reactor::instance()->end_reactor_event_loop() instead 00146 */ 00147 static int end_event_loop (void); 00148 00149 /** 00150 * Report if the <ACE_Reactor::instance>'s event loop is finished. 00151 * Note that this method can only be used by the singleton 00152 * <ACE_Reactor::instance>. Thus, to check another reactor use 00153 * <ACE_Reactor::reactor_event_loop_done>. 00154 * 00155 * @deprecated Use ACE_Reactor::instance()->reactor_event_loop_done() instead 00156 */ 00157 static int event_loop_done (void); 00158 00159 /** 00160 * Resets the <ACE_Reactor::end_event_loop_> static so that the 00161 * <run_event_loop> method can be restarted. Note that this method 00162 * can only be used by the singleton <ACE_Reactor::instance>. Thus, 00163 * to reset another reactor use <ACE_Reactor::reset_reactor_event_loop>. 00164 * 00165 * @deprecated Use ACE_Reactor::instance()->reset_reactor_event_loop() 00166 * instead 00167 */ 00168 static void reset_event_loop (void); 00169 00170 /** 00171 * The singleton reactor is used by the ACE_Service_Config. 00172 * Therefore, we must check for the reconfiguration request and 00173 * handle it after handling an event. 00174 */ 00175 static int check_reconfiguration (ACE_Reactor *); 00176 00177 // = Reactor event loop management methods. 00178 00179 // These methods work with an instance of a reactor. 00180 /** 00181 * Run the event loop until the 00182 * <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events> 00183 * method returns -1 or the <end_reactor_event_loop> method is invoked. 00184 */ 00185 int run_reactor_event_loop (REACTOR_EVENT_HOOK = 0); 00186 int run_alertable_reactor_event_loop (REACTOR_EVENT_HOOK = 0); 00187 00188 /** 00189 * Run the event loop until the <ACE_Reactor::handle_events> or 00190 * <ACE_Reactor::alertable_handle_events> methods returns -1, the 00191 * <end_reactor_event_loop> method is invoked, or the ACE_Time_Value 00192 * expires. 00193 */ 00194 int run_reactor_event_loop (ACE_Time_Value &tv, 00195 REACTOR_EVENT_HOOK = 0); 00196 int run_alertable_reactor_event_loop (ACE_Time_Value &tv, 00197 REACTOR_EVENT_HOOK = 0); 00198 00199 /** 00200 * Instruct the Reactor to terminate its event loop and notifies the 00201 * Reactor so that it can wake up and deactivate 00202 * itself. Deactivating the Reactor would allow the Reactor to be 00203 * shutdown gracefully. Internally the Reactor calls deactivate () 00204 * on the underlying implementation. 00205 * Any queued notifications remain queued on return from this method. 00206 * If the event loop is restarted in the future, the notifications 00207 * will be dispatched then. If the reactor is closed or deleted without 00208 * further dispatching, the notifications will be lost. 00209 */ 00210 int end_reactor_event_loop (void); 00211 00212 /// Indicate if the Reactor's event loop has been ended. 00213 int reactor_event_loop_done (void); 00214 00215 /// Resets the <ACE_Reactor::end_event_loop_> static so that the 00216 /// <run_event_loop> method can be restarted. 00217 void reset_reactor_event_loop (void); 00218 00219 /** 00220 * Create the Reactor using @a implementation. The flag 00221 * @a delete_implementation tells the Reactor whether or not to 00222 * delete the @a implementation on destruction. 00223 */ 00224 ACE_Reactor (ACE_Reactor_Impl *implementation = 0, 00225 bool delete_implementation = false); 00226 00227 /// Close down and release all resources. 00228 /** 00229 * Any notifications that remain queued on this reactor instance are 00230 * lost. 00231 */ 00232 virtual ~ACE_Reactor (void); 00233 00234 /** 00235 * Initialize the ACE_Reactor to manage <max_number_of_handles>. 00236 * If @a restart is false then the ACE_Reactor's <handle_events> 00237 * method will be restarted automatically when <EINTR> occurs. If 00238 * @a signal_handler or @a timer_queue are non-0 they are used as the 00239 * signal handler and timer queue, respectively. 00240 */ 00241 int open (size_t max_number_of_handles, 00242 bool restart = false, 00243 ACE_Sig_Handler *signal_handler = 0, 00244 ACE_Timer_Queue *timer_queue = 0); 00245 00246 /// Use a user specified signal handler instead. 00247 int set_sig_handler (ACE_Sig_Handler *signal_handler); 00248 00249 /// Set a user-specified timer queue. 00250 int timer_queue (ACE_Timer_Queue *tq); 00251 00252 /// Return the current ACE_Timer_Queue. 00253 ACE_Timer_Queue *timer_queue (void) const; 00254 00255 /// Close down and release all resources. 00256 int close (void); 00257 00258 // = Event loop drivers. 00259 00260 /** 00261 * Returns non-zero if there are I/O events "ready" for dispatching, 00262 * but does not actually dispatch the event handlers. By default, 00263 * don't block while checking this, i.e., "poll". 00264 */ 00265 int work_pending (const ACE_Time_Value &max_wait_time = ACE_Time_Value::zero); 00266 00267 /** 00268 * This event loop driver blocks for up to @a max_wait_time before 00269 * returning. It will return earlier if events occur. Note that 00270 * @a max_wait_time can be 0, in which case this method blocks 00271 * indefinitely until events occur. 00272 * 00273 * @a max_wait_time is decremented to reflect how much time this call 00274 * took. For instance, if a time value of 3 seconds is passed to 00275 * handle_events and an event occurs after 2 seconds, 00276 * @a max_wait_time will equal 1 second. This can be used if an 00277 * application wishes to handle events for some fixed amount of 00278 * time. 00279 * 00280 * Returns the total number of timers and I/O ACE_Event_Handlers 00281 * that were dispatched, 0 if the @a max_wait_time elapsed without 00282 * dispatching any handlers, or -1 if an error occurs. 00283 * 00284 * The only difference between alertable_handle_events() and 00285 * handle_events() is that in the alertable case, the eventloop will 00286 * return when the system queues an I/O completion routine or an 00287 * Asynchronous Procedure Call. 00288 */ 00289 int handle_events (ACE_Time_Value *max_wait_time = 0); 00290 int alertable_handle_events (ACE_Time_Value *max_wait_time = 0); 00291 00292 /** 00293 * This method is just like the one above, except the 00294 * @a max_wait_time value is a reference and can therefore never be 00295 * NULL. 00296 * 00297 * The only difference between alertable_handle_events() and 00298 * handle_events() is that in the alertable case, the eventloop will 00299 * return when the system queues an I/O completion routine or an 00300 * Asynchronous Procedure Call. 00301 */ 00302 int handle_events (ACE_Time_Value &max_wait_time); 00303 int alertable_handle_events (ACE_Time_Value &max_wait_time); 00304 00305 // = Register and remove handlers. 00306 00307 /** 00308 * Register handler for I/O events. 00309 * 00310 * A handler can be associated with multiple handles. A handle 00311 * cannot be associated with multiple handlers. 00312 * 00313 * The handle will come from ACE_Event_Handler::get_handle(). 00314 * 00315 * Reactor will call ACE_Event_Handler::add_reference() for a new 00316 * handler/handle pair. 00317 * 00318 * If this handler/handle pair has already been registered, any new 00319 * masks specified will be added. In this case, 00320 * ACE_Event_Handler::add_reference() will not be called. 00321 * 00322 * If the registered handler is currently suspended, it will remain 00323 * suspended. When the handler is resumed, it will have the 00324 * existing masks plus any masks added through this call. Handlers 00325 * do not have partial suspensions. 00326 */ 00327 int register_handler (ACE_Event_Handler *event_handler, 00328 ACE_Reactor_Mask mask); 00329 00330 /** 00331 * Register handler for I/O events. 00332 * 00333 * Same as register_handler(ACE_Event_Handler*,ACE_Reactor_Mask), 00334 * except handle is explicitly specified. 00335 */ 00336 int register_handler (ACE_HANDLE io_handle, 00337 ACE_Event_Handler *event_handler, 00338 ACE_Reactor_Mask mask); 00339 00340 #if defined (ACE_WIN32) 00341 00342 /** 00343 * Register handler for OS events. 00344 * 00345 * Register an @a event_handler that will be notified when 00346 * <event_handle> is signaled. This will call back its 00347 * <handle_signal> hook method. 00348 * 00349 * Reactor will call ACE_Event_Handler::add_reference() for a new 00350 * handler/handle pair. 00351 * 00352 * This interface is only available Win32 platforms because 00353 * ACE_HANDLE is an int on non-Win32 platforms and compilers are not 00354 * able to tell the difference between 00355 * register_handler(ACE_Event_Handler*,ACE_Reactor_Mask) and 00356 * register_handler(ACE_Event_Handler*,ACE_HANDLE). 00357 */ 00358 int register_handler (ACE_Event_Handler *event_handler, 00359 ACE_HANDLE event_handle = ACE_INVALID_HANDLE); 00360 00361 #endif /* ACE_WIN32 */ 00362 00363 /** 00364 * Register handler for I/O events. 00365 * 00366 * Similar to 00367 * register_handler(ACE_HANDLE,ACE_Event_Handler*,ACE_Reactor_Mask), 00368 * except that the user gets to specify the event handle that will 00369 * be used for this registration. This only applies to Reactors 00370 * that use event handles for I/O registrations. 00371 */ 00372 int register_handler (ACE_HANDLE event_handle, 00373 ACE_HANDLE io_handle, 00374 ACE_Event_Handler *event_handler, 00375 ACE_Reactor_Mask mask); 00376 00377 /** 00378 * Register handler for multiple I/O events. 00379 * 00380 * Shorthand for calling 00381 * register_handler(ACE_HANDLE,ACE_Event_Handler*,ACE_Reactor_Mask), 00382 * multiple times for the same @a event_handler and @a masks but 00383 * different @a handles. 00384 */ 00385 int register_handler (const ACE_Handle_Set &handles, 00386 ACE_Event_Handler *event_handler, 00387 ACE_Reactor_Mask masks); 00388 00389 /** 00390 * Register handler for signals. 00391 * 00392 * Register @a new_sh to handle the signal @a signum using the 00393 * @a new_disp. Returns the @a old_sh that was previously registered 00394 * (if any), along with the @a old_disp of the signal handler. 00395 * 00396 * Reactor will call ACE_Event_Handler::add_reference() on @a new_sh 00397 * and ACE_Event_Handler::remove_reference() on @a old_sh. 00398 */ 00399 int register_handler (int signum, 00400 ACE_Event_Handler *new_sh, 00401 ACE_Sig_Action *new_disp = 0, 00402 ACE_Event_Handler **old_sh = 0, 00403 ACE_Sig_Action *old_disp = 0); 00404 00405 /** 00406 * Register handler for multiple signals. 00407 * 00408 * Shorthand for calling 00409 * register_handler(int,ACE_Event_Handler*,ACE_Sig_Action*,ACE_Event_Handler**,ACE_Sig_Action*) 00410 * multiple times for the same @a event_handler and @a sig_action but 00411 * different <signals>. 00412 */ 00413 int register_handler (const ACE_Sig_Set &sigset, 00414 ACE_Event_Handler *event_handler, 00415 ACE_Sig_Action *sig_action = 0); 00416 00417 /** 00418 * Remove @a masks from @a handle registration. 00419 * 00420 * For I/O handles, @a masks are removed from the Reactor. Unless 00421 * @a masks includes ACE_Event_Handler::DONT_CALL, 00422 * ACE_Event_Handler::handle_close() will be called with the @a masks 00423 * that have been removed. If all masks have been removed, 00424 * ACE_Event_Handler::remove_reference() will be called. 00425 * 00426 * For OS handles, the @a handle is removed from the Reactor. Unless 00427 * @a masks includes ACE_Event_Handler::DONT_CALL, 00428 * ACE_Event_Handler::handle_close() will be called with 00429 * ACE_Event_Handler::NULL_MASK. 00430 * ACE_Event_Handler::remove_reference() will also be called. 00431 */ 00432 int remove_handler (ACE_HANDLE handle, 00433 ACE_Reactor_Mask masks); 00434 00435 /** 00436 * Remove @a masks from @a event_handler registration. 00437 * 00438 * Same as remove_handler(ACE_HANDLE,ACE_Reactor_Mask), except 00439 * @a handle comes from ACE_Event_Handler::get_handle(). 00440 */ 00441 int remove_handler (ACE_Event_Handler *event_handler, 00442 ACE_Reactor_Mask masks); 00443 00444 /** 00445 * Remove @a masks from multiple <handle> registrations. 00446 * 00447 * Shorthand for calling remove_handler(ACE_HANDLE,ACE_Reactor_Mask) 00448 * multiple times for the same @a masks but different @a handles. 00449 */ 00450 int remove_handler (const ACE_Handle_Set &handles, 00451 ACE_Reactor_Mask masks); 00452 00453 /** 00454 * Remove signal handler registration. 00455 * 00456 * Remove the ACE_Event_Handler currently associated with @a signum. 00457 * Install the new disposition (if given) and return the previous 00458 * disposition (if desired by the caller). 00459 * 00460 * Note that, unlike removing handler for I/O events, 00461 * ACE_Event_Handler::handle_close() will not be called when the 00462 * handler is removed. Neither will any reference-counting activity be 00463 * involved. 00464 * 00465 * @note There's an existing enhancement request in Bugzilla, 00466 * #2368, to change this behavior so that ACE_Event_Handler::handle_close() 00467 * is called when the signal handler is removed. Thus, there's some chance 00468 * this behavior will change in a future version of ACE. 00469 */ 00470 int remove_handler (int signum, 00471 ACE_Sig_Action *new_disp, 00472 ACE_Sig_Action *old_disp = 0, 00473 int sigkey = -1); 00474 00475 /** 00476 * Remove multiple signal handler registrations. 00477 * 00478 * Shorthand for calling 00479 * remove_handler(int,ACE_Sig_Action*,ACE_Sig_Action*,int) multiple 00480 * times for every signal in @a sigset. 00481 */ 00482 int remove_handler (const ACE_Sig_Set &sigset); 00483 00484 // = Suspend and resume Handlers. 00485 00486 /** 00487 * Suspend @a handle temporarily. 00488 */ 00489 int suspend_handler (ACE_HANDLE handle); 00490 00491 /** 00492 * Suspend @a event_handler temporarily. 00493 * 00494 * Handle is obtained from ACE_Event_Handler::get_handle(). 00495 */ 00496 int suspend_handler (ACE_Event_Handler *event_handler); 00497 00498 /** 00499 * Suspend @a handles temporarily. 00500 * 00501 * Shorthand for calling suspend_handler(ACE_HANDLE) with multiple 00502 * @a handles. 00503 */ 00504 int suspend_handler (const ACE_Handle_Set &handles); 00505 00506 /** 00507 * Suspend all registered handles temporarily. 00508 */ 00509 int suspend_handlers (void); 00510 00511 /** 00512 * Resume @a handle. 00513 */ 00514 int resume_handler (ACE_HANDLE handle); 00515 00516 /** 00517 * Resume @a event_handler. 00518 * 00519 * Handle is obtained from ACE_Event_Handler::get_handle(). 00520 */ 00521 int resume_handler (ACE_Event_Handler *event_handler); 00522 00523 /** 00524 * Resume @a handles. 00525 * 00526 * Shorthand for calling resume_handler(ACE_HANDLE) with multiple 00527 * @a handles. 00528 */ 00529 int resume_handler (const ACE_Handle_Set &handles); 00530 00531 /** 00532 * Resume all registered handles. 00533 */ 00534 int resume_handlers (void); 00535 00536 /// Does the reactor allow the application to resume the handle on 00537 /// its own ie. can it pass on the control of handle resumption to 00538 /// the application. A positive value indicates that the handlers 00539 /// are application resumable. A value of 0 indicates otherwise. 00540 int resumable_handler (void); 00541 00542 // = Timer management. 00543 00544 /** 00545 * Schedule a timer event. 00546 * 00547 * Schedule a timer event that will expire after an <delay> amount 00548 * of time. The return value of this method, a timer_id value, 00549 * uniquely identifies the @a event_handler in the ACE_Reactor's 00550 * internal list of timers. This timer_id value can be used to 00551 * cancel the timer with the cancel_timer() call. 00552 * 00553 * Reactor will call ACE_Event_Handler::add_reference() on the 00554 * handler. After the timeout occurs and 00555 * ACE_Event_Handler::handle_timeout() has completed, the handler 00556 * will be implicitly removed from the Reactor and 00557 * ACE_Event_Handler::remove_reference() will be called. 00558 * 00559 * @see cancel_timer() 00560 * @see reset_timer_interval() 00561 * 00562 * @param event_handler Event handler to schedule on reactor 00563 * @param arg Argument passed to the handle_timeout() method of 00564 * event_handler 00565 * @param delay Time interval after which the timer will expire 00566 * @param interval Time interval after which the timer will be automatically 00567 * rescheduled 00568 * @return -1 on failure, a timer_id value on success 00569 */ 00570 virtual long schedule_timer (ACE_Event_Handler *event_handler, 00571 const void *arg, 00572 const ACE_Time_Value &delay, 00573 const ACE_Time_Value &interval = 00574 ACE_Time_Value::zero); 00575 00576 /** 00577 * Reset recurring timer interval. 00578 * 00579 * Resets the interval of the timer represented by @a timer_id to 00580 * @a interval, which is specified in relative time to the current 00581 * <gettimeofday>. If @a interval is equal to 00582 * ACE_Time_Value::zero, the timer will become a non-rescheduling 00583 * timer. Returns 0 if successful, -1 if not. 00584 * 00585 * This change will not take effect until the next timeout. 00586 */ 00587 virtual int reset_timer_interval (long timer_id, 00588 const ACE_Time_Value &interval); 00589 00590 /** 00591 * Cancel timer. 00592 * 00593 * Cancel timer associated with @a timer_id that was returned from 00594 * the schedule_timer() method. If arg is non-NULL then it will be 00595 * set to point to the ``magic cookie'' argument passed in when the 00596 * handler was registered. This makes it possible to free up the 00597 * memory and avoid memory leaks. Returns 1 if cancellation 00598 * succeeded and 0 if the @a timer_id wasn't found. 00599 * 00600 * On successful cancellation, ACE_Event_Handler::handle_close() 00601 * will be called with ACE_Event_Handler::TIMER_MASK. 00602 * ACE_Event_Handler::remove_reference() will also be called. 00603 */ 00604 virtual int cancel_timer (long timer_id, 00605 const void **arg = 0, 00606 int dont_call_handle_close = 1); 00607 00608 /** 00609 * Cancel all timers associated with event handler. 00610 * 00611 * Shorthand for calling cancel_timer(long,const void **,int) 00612 * multiple times for all timer associated with @a event_handler. 00613 * 00614 * ACE_Event_Handler::handle_close() will be called with 00615 * ACE_Event_Handler::TIMER_MASK only once irrespective of the 00616 * number of timers associated with the event handler. 00617 * ACE_Event_Handler::remove_reference() will also be called once 00618 * for every timer associated with the event handler. 00619 * 00620 * Returns number of handlers cancelled. 00621 */ 00622 virtual int cancel_timer (ACE_Event_Handler *event_handler, 00623 int dont_call_handle_close = 1); 00624 00625 // = High-level Event_Handler scheduling operations 00626 00627 /// Add @a masks_to_be_added to the @a event_handler's entry. 00628 /// @a event_handler must already have been registered. 00629 /// Note that this call does not cause the Reactor to re-examine 00630 /// its set of handlers - the new masks will be noticed the next 00631 /// time the Reactor waits for activity. If there is no other 00632 /// activity expected, or you need immediate re-examination of the 00633 /// wait masks, either call ACE_Reactor::notify after this call, or 00634 /// use ACE_Reactor::register_handler instead. 00635 int schedule_wakeup (ACE_Event_Handler *event_handler, 00636 ACE_Reactor_Mask masks_to_be_added); 00637 00638 /// Add @a masks_to_be_added to the @a handle's entry. <event_handler> 00639 /// associated with @a handle must already have been registered. 00640 /// Note that this call does not cause the Reactor to re-examine 00641 /// its set of handlers - the new masks will be noticed the next 00642 /// time the Reactor waits for activity. If there is no other 00643 /// activity expected, or you need immediate re-examination of 00644 /// the wait masks, either call ACE_Reactor::notify after this call, 00645 /// or use ACE_Reactor::register_handler instead. 00646 int schedule_wakeup (ACE_HANDLE handle, 00647 ACE_Reactor_Mask masks_to_be_added); 00648 00649 /// Clear @a masks_to_be_cleared from the @a event_handler's entry. 00650 /// Note that this call does not cause the Reactor to re-examine 00651 /// its set of handlers - the new masks will be noticed the next 00652 /// time the Reactor waits for activity. If there is no other 00653 /// activity expected, or you need immediate re-examination of 00654 /// the wait masks, either call ACE_Reactor::notify after this 00655 /// call, or use ACE_Reactor::register_handler instead. 00656 int cancel_wakeup (ACE_Event_Handler *event_handler, 00657 ACE_Reactor_Mask masks_to_be_cleared); 00658 00659 /// Clear @a masks_to_be_cleared from the @a handle's entry. 00660 /// Note that this call does not cause the Reactor to re-examine 00661 /// its set of handlers - the new masks will be noticed the next 00662 /// time the Reactor waits for activity. If there is no other 00663 /// activity expected, or you need immediate re-examination of 00664 /// the wait masks, either call ACE_Reactor::notify after this 00665 /// call, or use ACE_Reactor::register_handler instead. 00666 int cancel_wakeup (ACE_HANDLE handle, 00667 ACE_Reactor_Mask masks_to_be_cleared); 00668 00669 // = Notification methods. 00670 00671 /** 00672 * Dispatch user specified events. 00673 * 00674 * Handler will be dispatched irrespective of whether it is 00675 * registered, not registered, or suspended in the Reactor. 00676 * 00677 * If user specified event is successfully queued, 00678 * ACE_Event_Handler::add_reference() will be called. After the 00679 * notify occurs and the upcall to the handler completes, the 00680 * handler will be implicitly removed from the Reactor and 00681 * ACE_Event_Handler::remove_reference() will be called. No other 00682 * upcall reference counting is done. 00683 * 00684 * For I/O or OS events, the upcall is invoked with an 00685 * ACE_INVALID_HANDLE. 00686 * 00687 * For timer events, the upcall is invoked with a null ACT. 00688 * 00689 * @param event_handler: IN - Handler on which the event will be 00690 * dispatched. 00691 * @param masks: IN - Events to be dispatched - multiple events can 00692 * be OR'd together. 00693 * @param timeout: INOUT - Relative time up to which to wait for 00694 * user specified event to be queued. If tv is 0, wait 00695 * indefinitely. When the call returns, tv has the time remaining 00696 * after the call completes. 00697 */ 00698 int notify (ACE_Event_Handler *event_handler = 0, 00699 ACE_Reactor_Mask masks = ACE_Event_Handler::EXCEPT_MASK, 00700 ACE_Time_Value *timeout = 0); 00701 00702 /** 00703 * Set the maximum number of times that ACE_Reactor will 00704 * iterate and dispatch the ACE_Event_Handlers that are passed in 00705 * via the notify queue before breaking out of its 00706 * ACE_Message_Queue::dequeue() loop. By default, this is set to 00707 * -1, which means "iterate until the queue is empty." Setting this 00708 * to a value like "1 or 2" will increase "fairness" (and thus 00709 * prevent starvation) at the expense of slightly higher dispatching 00710 * overhead. 00711 */ 00712 void max_notify_iterations (int iterations); 00713 00714 /** 00715 * Get the maximum number of times that the ACE_Reactor will 00716 * iterate and dispatch the ACE_Event_Handler's that are passed in 00717 * via the notify queue before breaking out of its 00718 * ACE_Message_Queue::dequeue() loop. 00719 */ 00720 int max_notify_iterations (void); 00721 00722 /** 00723 * Purge any notifications pending in this reactor for the specified 00724 * ACE_Event_Handler object. If @a eh == 0, all notifications for 00725 * all handlers are removed (but not any notifications posted just 00726 * to wake up the reactor itself). Returns the number of 00727 * notifications purged. Returns -1 on error. 00728 * 00729 * After the purging occurs, the handler will be implicitly removed 00730 * from the Reactor and ACE_Event_Handler::remove_reference() will 00731 * be called. 00732 */ 00733 int purge_pending_notifications (ACE_Event_Handler *eh, 00734 ACE_Reactor_Mask = 00735 ACE_Event_Handler::ALL_EVENTS_MASK); 00736 00737 // = Assorted helper methods. 00738 00739 /** 00740 * Return the Event_Handler associated with @a handle. Return 0 if 00741 * @a handle is not registered. 00742 * 00743 * Reactor will call ACE_Event_Handler::add_reference() on the 00744 * handler before returning it. 00745 */ 00746 ACE_Event_Handler *find_handler (ACE_HANDLE handle); 00747 00748 /** 00749 * Check to see if @a handle is associated with a valid Event_Handler 00750 * bound to @a mask. Return the @c event_handler associated with this 00751 * @a handler if @a event_handler != 0. 00752 * 00753 * Reactor will call ACE_Event_Handler::add_reference() on the 00754 * handler before returning it if @a event_handler != 0. 00755 */ 00756 int handler (ACE_HANDLE handle, 00757 ACE_Reactor_Mask mask, 00758 ACE_Event_Handler **event_handler = 0); 00759 00760 /** 00761 * Check to see if @a signum is associated with a valid Event_Handler 00762 * bound to a signal. Return the @a event_handler associated with 00763 * this @c handler if @a event_handler != 0. 00764 */ 00765 int handler (int signum, 00766 ACE_Event_Handler **event_handler = 0); 00767 00768 /// Returns true if Reactor has been successfully initialized, else 00769 /// false. 00770 int initialized (void); 00771 00772 /// Returns the current size of the Reactor's internal descriptor 00773 /// table. 00774 size_t size (void) const; 00775 00776 /// Returns a reference to the Reactor's internal lock. 00777 ACE_Lock &lock (void); 00778 00779 /// Wake up all threads in waiting in the event loop 00780 void wakeup_all_threads (void); 00781 00782 /// Transfers ownership of Reactor to the @a new_owner. 00783 int owner (ACE_thread_t new_owner, 00784 ACE_thread_t *old_owner = 0); 00785 00786 /// Return the ID of the "owner" thread. 00787 int owner (ACE_thread_t *owner); 00788 00789 /// Set position of the owner thread. 00790 void requeue_position (int position); 00791 00792 /// Get position of the owner thread. 00793 int requeue_position (void); 00794 00795 /// Get the existing restart value. 00796 bool restart (void); 00797 00798 /// Set a new value for restart and return the original value. 00799 bool restart (bool r); 00800 00801 // = Low-level wait_set mask manipulation methods. 00802 00803 /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the 00804 /// @a event_handler and @a mask. 00805 int mask_ops (ACE_Event_Handler *event_handler, 00806 ACE_Reactor_Mask mask, 00807 int ops); 00808 00809 /// GET/SET/ADD/CLR the dispatch MASK "bit" bound with the @a handle 00810 /// and @a mask. 00811 int mask_ops (ACE_HANDLE handle, 00812 ACE_Reactor_Mask mask, 00813 int ops); 00814 00815 // = Low-level ready_set mask manipulation methods. 00816 /// GET/SET/ADD/CLR the ready "bit" bound with the @a event_handler 00817 /// and @a mask. 00818 int ready_ops (ACE_Event_Handler *event_handler, 00819 ACE_Reactor_Mask mask, 00820 int ops); 00821 00822 /// GET/SET/ADD/CLR the ready "bit" bound with the @a handle and @a mask. 00823 int ready_ops (ACE_HANDLE handle, 00824 ACE_Reactor_Mask mask, 00825 int ops); 00826 00827 /// Get the implementation class 00828 ACE_Reactor_Impl *implementation (void) const; 00829 00830 /** 00831 * Returns 0, if the size of the current message has been put in 00832 * @a size returns -1, if not. ACE_HANDLE allows the reactor to 00833 * check if the caller is valid. Used for CLASSIX Reactor 00834 * implementation. 00835 */ 00836 int current_info (ACE_HANDLE handle, size_t &msg_size); 00837 00838 /// Return true if we any event associations were made by the reactor 00839 /// for the handles that it waits on, false otherwise. 00840 bool uses_event_associations (void); 00841 00842 /// Declare the dynamic allocation hooks. 00843 ACE_ALLOC_HOOK_DECLARE; 00844 00845 /// Dump the state of the object. 00846 void dump (void) const; 00847 00848 protected: 00849 /// Set the implementation class. 00850 void implementation (ACE_Reactor_Impl *implementation); 00851 00852 /// Delegation/implementation class that all methods will be 00853 /// forwarded to. 00854 ACE_Reactor_Impl *implementation_; 00855 00856 /// Flag used to indicate whether we are responsible for cleaning up 00857 /// the implementation instance 00858 bool delete_implementation_; 00859 00860 /// Pointer to a process-wide ACE_Reactor singleton. 00861 static ACE_Reactor *reactor_; 00862 00863 /// Must delete the reactor_ singleton if true. 00864 static bool delete_reactor_; 00865 00866 /// Deny access since member-wise won't work... 00867 ACE_Reactor (const ACE_Reactor &); 00868 ACE_Reactor &operator = (const ACE_Reactor &); 00869 }; 00870 00871 ACE_END_VERSIONED_NAMESPACE_DECL 00872 00873 00874 #if defined (__ACE_INLINE__) 00875 #include "ace/Reactor.inl" 00876 #endif /* __ACE_INLINE__ */ 00877 00878 #include /**/ "ace/post.h" 00879 00880 #endif /* ACE_REACTOR_H */