Reactor.h

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

Generated on Sun Jan 27 12:05:36 2008 for ACE by doxygen 1.3.6