Reactor.h

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

Generated on Thu Nov 9 09:42:01 2006 for ACE by doxygen 1.3.6