Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Reactor.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Reactor.h
00006  *
00007  *  $Id: Reactor.h,v 1.1.1.4 2003/02/21 18:36:32 chad 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 #include "ace/pre.h"
00017 
00018 class ACE_Reactor_Impl;
00019 
00020 // Need the class def for ACE_Handle_Set to compile references to it in
00021 // programs.
00022 #include "ace/Handle_Set.h"
00023 
00024 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00025 # pragma once
00026 #endif /* ACE_LACKS_PRAGMA_ONCE */
00027 
00028 // Timer Queue is a complicated template class. A simple forward
00029 // declaration will not work
00030 #include "ace/Timer_Queue.h"
00031 
00032 // Event_Handler.h contains the definition of ACE_Reactor_Mask
00033 #include "ace/Event_Handler.h"
00034 
00035 // We are using 4 or 5 signal classes, we could forward declare
00036 // them.... But Timer_Queue_T.h includes Signal.h, so I don't think
00037 // forward declaration will be useful here
00038 #include "ace/Signal.h"
00039 
00040 /**
00041  * @class ACE_Reactor
00042  *
00043  * @brief The responsibility of this class is to forward all methods to
00044  * its delegation/implementation class, e.g.,
00045  * <ACE_Select_Reactor> or <ACE_WFMO_Reactor>.
00046  */
00047 class ACE_Export ACE_Reactor
00048 {
00049 public:
00050   /// Operations on the "ready" mask and the "dispatch" mask.
00051   enum
00052   {
00053     /// Retrieve current value of the the "ready" mask or the
00054     /// "dispatch" mask.
00055     GET_MASK = 1,
00056     /// Set value of bits to new mask (changes the entire mask).
00057     SET_MASK = 2,
00058     /// Bitwise "or" the value into the mask (only changes enabled
00059     /// bits).
00060     ADD_MASK = 3,
00061     /// Bitwise "and" the negation of the value out of the mask (only
00062     /// changes enabled bits).
00063     CLR_MASK = 4
00064   };
00065 
00066   /**
00067    * You can add a hook to various run_event methods and the hook will
00068    * be called after handling every reactor event.  If this function
00069    * returns 0, <run_reactor_event_loop> will check for the return
00070    * value of <handle_event>.  If it is -1, the
00071    * <run_reactor_event_loop> will return (pre-maturely.)
00072    */
00073   typedef int (*REACTOR_EVENT_HOOK)(ACE_Reactor *);
00074 
00075   /// Get pointer to a process-wide <ACE_Reactor>.
00076   static ACE_Reactor *instance (void);
00077 
00078   /**
00079    * Set pointer to a process-wide <ACE_Reactor> and return existing
00080    * pointer.  If <delete_reactor> != 0 then we'll delete the Reactor
00081    * at destruction time.
00082    */
00083   static ACE_Reactor *instance (ACE_Reactor *,
00084                                 int delete_reactor = 0);
00085 
00086   /// Delete the dynamically allocated Singleton
00087   static void close_singleton (void);
00088 
00089   /// Name of the dll in which the dll lives.
00090   static const ACE_TCHAR *dll_name (void);
00091 
00092   /// Name of the component--ACE_Reactor in this case.
00093   static const ACE_TCHAR *name (void);
00094 
00095   // = Singleton reactor event loop management methods.
00096 
00097   // Note that these method ONLY work on the "Singleton Reactor,"
00098   // i.e., the one returned from <ACE_Reactor::instance>.
00099   /**
00100    * Run the event loop until the
00101    * <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events>
00102    * method returns -1 or the <end_event_loop> method is invoked.
00103    * Note that this method can only be used by the singleton
00104    * <ACE_Reactor::instance>.  Thus, to run another reactor use
00105    * <ACE_Reactor::run_reactor_event_loop>.
00106    *
00107    * @deprecated Use ACE_Reactor::instance()->run_reactor_event_loop() instead
00108    */
00109   static int run_event_loop (void);
00110   static int run_alertable_event_loop (void);
00111 
00112   /**
00113    * Run the event loop until the <ACE_Reactor::handle_events> or
00114    * <ACE_Reactor::alertable_handle_events> methods returns -1, the
00115    * <end_event_loop> method is invoked, or the <ACE_Time_Value>
00116    * expires.  Note that this method can only be used by the singleton
00117    * <ACE_Reactor::instance>.  Thus, to run another reactor use
00118    * <ACE_Reactor::run_reactor_event_loop>.
00119    *
00120    * @deprecated Use ACE_Reactor::instance()->run_reactor_event_loop() instead
00121    */
00122   static int run_event_loop (ACE_Time_Value &tv);
00123   static int run_alertable_event_loop (ACE_Time_Value &tv);
00124 
00125   /**
00126    * Instruct the <ACE_Reactor::instance> to terminate its event loop
00127    * and notifies the <ACE_Reactor::instance> so that it can wake up
00128    * and close down gracefully.  Note that this method can only be
00129    * used by the singleton <ACE_Reactor::instance>.  Thus, to
00130    * terminate another reactor, use
00131    * <ACE_Reactor::end_reactor_event_loop>.
00132    *
00133    * @deprecated Use ACE_Reactor::instance()->end_reactor_event_loop() instead
00134    */
00135   static int end_event_loop (void);
00136 
00137   /**
00138    * Report if the <ACE_Reactor::instance>'s event loop is finished.
00139    * Note that this method can only be used by the singleton
00140    * <ACE_Reactor::instance>.  Thus, to check another reactor use
00141    * <ACE_Reactor::reactor_event_loop_done>.
00142    *
00143    * @deprecated Use ACE_Reactor::instance()->reactor_event_loop_done() instead
00144    */
00145   static int event_loop_done (void);
00146 
00147   /**
00148    * Resets the <ACE_Reactor::end_event_loop_> static so that the
00149    * <run_event_loop> method can be restarted.  Note that this method
00150    * can only be used by the singleton <ACE_Reactor::instance>.  Thus,
00151    * to reset another reactor use <ACE_Reactor::reset_reactor_event_loop>.
00152    *
00153    * @deprecated Use ACE_Reactor::instance()->reset_reactor_event_loop()
00154    * instead
00155    */
00156   static void reset_event_loop (void);
00157 
00158   /**
00159    * The singleton reactor is used by the <ACE_Service_Config>.
00160    * Therefore, we must check for the reconfiguration request and
00161    * handle it after handling an event.
00162    */
00163   static int check_reconfiguration (ACE_Reactor *);
00164 
00165   // = Reactor event loop management methods.
00166 
00167   // These methods work with an instance of a reactor.
00168   /**
00169    * Run the event loop until the
00170    * <ACE_Reactor::handle_events/ACE_Reactor::alertable_handle_events>
00171    * method returns -1 or the <end_reactor_event_loop> method is invoked.
00172    */
00173   virtual int run_reactor_event_loop (REACTOR_EVENT_HOOK = 0);
00174   virtual int run_alertable_reactor_event_loop (REACTOR_EVENT_HOOK = 0);
00175 
00176   /**
00177    * Run the event loop until the <ACE_Reactor::handle_events> or
00178    * <ACE_Reactor::alertable_handle_events> methods returns -1, the
00179    * <end_reactor_event_loop> method is invoked, or the <ACE_Time_Value>
00180    * expires.
00181    */
00182   virtual int run_reactor_event_loop (ACE_Time_Value &tv,
00183                                       REACTOR_EVENT_HOOK = 0);
00184   virtual int run_alertable_reactor_event_loop (ACE_Time_Value &tv,
00185                                                 REACTOR_EVENT_HOOK = 0);
00186 
00187   /**
00188    * Instruct the Reactor to terminate its event loop and notifies the
00189    * Reactor so that it can wake up and deactivate
00190    * itself. Deactivating the Reactor would allow the Reactor to be
00191    * shutdown gracefully. Internally the Reactor calls deactivate ()
00192    * on the underlying implementation.
00193    * Any queued notifications remain queued on return from this method.
00194    * If the event loop is restarted in the future, the notifications
00195    * will be dispatched then. If the reactor is closed or deleted without
00196    * further dispatching, the notifications will be lost.
00197    */
00198   virtual int end_reactor_event_loop (void);
00199 
00200   /// Indicate if the Reactor's event loop has been ended.
00201   virtual int reactor_event_loop_done (void);
00202 
00203   /// Resets the <ACE_Reactor::end_event_loop_> static so that the
00204   /// <run_event_loop> method can be restarted.
00205   virtual void reset_reactor_event_loop (void);
00206 
00207   /**
00208    * Create the Reactor using <implementation>.  The flag
00209    * <delete_implementation> tells the Reactor whether or not to
00210    * delete the <implementation> on destruction.
00211    */
00212   ACE_Reactor (ACE_Reactor_Impl *implementation = 0,
00213                int delete_implementation = 0);
00214 
00215   /// Close down and release all resources.
00216   /**
00217    * Any notifications that remain queued on this reactor instance are
00218    * lost.
00219    */
00220   virtual ~ACE_Reactor (void);
00221 
00222   /**
00223    * Initialize the <ACE_Reactor> to manage <max_number_of_handles>.
00224    * If <restart> is non-0 then the <ACE_Reactor>'s <handle_events>
00225    * method will be restarted automatically when <EINTR> occurs.  If
00226    * <signal_handler> or <timer_queue> are non-0 they are used as the
00227    * signal handler and timer queue, respectively.
00228    */
00229   virtual int open (size_t max_number_of_handles,
00230                     int restart = 0,
00231                     ACE_Sig_Handler *signal_handler = 0,
00232                     ACE_Timer_Queue *timer_queue = 0);
00233 
00234   /// Use a user specified signal handler instead.
00235   virtual int set_sig_handler (ACE_Sig_Handler *signal_handler);
00236 
00237   // = The following method is deprecated.
00238   /// @deprecated Use <timer_queue> instead.
00239   /// Set a user specified timer queue.
00240   virtual int set_timer_queue (ACE_Timer_Queue *tq);
00241 
00242   /// Set a user-specified timer queue.
00243   virtual int timer_queue (ACE_Timer_Queue *tq);
00244 
00245   /// Return the current <ACE_Timer_Queue>.
00246   virtual ACE_Timer_Queue *timer_queue (void) const;
00247 
00248   /// Close down and release all resources.
00249   virtual int close (void);
00250 
00251   // = Event loop drivers.
00252 
00253   /**
00254    * Returns non-zero if there are I/O events "ready" for dispatching,
00255    * but does not actually dispatch the event handlers.  By default,
00256    * don't block while checking this, i.e., "poll".
00257    */
00258   virtual int work_pending (const ACE_Time_Value &max_wait_time =  ACE_Time_Value::zero);
00259 
00260   /**
00261    * This event loop driver blocks for up to <max_wait_time> before
00262    * returning.  It will return earlier if events occur.  Note that
00263    * <max_wait_time> can be 0, in which case this method blocks
00264    * indefinitely until events occur.
00265    *
00266    * <max_wait_time> is decremented to reflect how much time this call
00267    * took.  For instance, if a time value of 3 seconds is passed to
00268    * handle_events and an event occurs after 2 seconds,
00269    * <max_wait_time> will equal 1 second.  This can be used if an
00270    * application wishes to handle events for some fixed amount of
00271    * time.
00272    *
00273    * Returns the total number of timers and I/O <ACE_Event_Handler>s
00274    * that were dispatched, 0 if the <max_wait_time> elapsed without
00275    * dispatching any handlers, or -1 if an error occurs.
00276    *
00277    * The only difference between <alertable_handle_events> and
00278    * <handle_events> is that in the alertable case, the eventloop will
00279    * return when the system queues an I/O completion routine or an
00280    * Asynchronous Procedure Call.
00281    */
00282   virtual int handle_events (ACE_Time_Value *max_wait_time = 0);
00283   virtual int alertable_handle_events (ACE_Time_Value *max_wait_time = 0);
00284 
00285   /**
00286    * This method is just like the one above, except the
00287    * <max_wait_time> value is a reference and can therefore never be
00288    * NULL.
00289    *
00290    * The only difference between <alertable_handle_events> and
00291    * <handle_events> is that in the alertable case, the eventloop will
00292    * return when the system queues an I/O completion routine or an
00293    * Asynchronous Procedure Call.
00294    */
00295   virtual int handle_events (ACE_Time_Value &max_wait_time);
00296   virtual int alertable_handle_events (ACE_Time_Value &max_wait_time);
00297 
00298   // = Register and remove Handlers.
00299 
00300   /// Register <event_handler> with <mask>.  The I/O handle will always
00301   /// come from <get_handle> on the <event_handler>.
00302   virtual int register_handler (ACE_Event_Handler *event_handler,
00303                                 ACE_Reactor_Mask mask);
00304 
00305   /// Register <event_handler> with <mask>.  The I/O handle is provided
00306   /// through the <io_handle> parameter.
00307   virtual int register_handler (ACE_HANDLE io_handle,
00308                                 ACE_Event_Handler *event_handler,
00309                                 ACE_Reactor_Mask mask);
00310 
00311 #if defined (ACE_WIN32)
00312   /**
00313    * Register an <event_handler> that will be notified when
00314    * <event_handle> is signaled.  Since no event mask is passed
00315    * through this interface, it is assumed that the <event_handle>
00316    * being passed in is an event handle and not an I/O handle.
00317    *
00318    * Originally this interface was available for all platforms, but
00319    * because ACE_HANDLE is an int on non-Win32 platforms, compilers
00320    * are not able to tell the difference between
00321    * register_handler(ACE_Event_Handler*,ACE_Reactor_Mask) and
00322    * register_handler(ACE_Event_Handler*,ACE_HANDLE). Therefore, we
00323    * have restricted this method to Win32 only.
00324    */
00325   virtual int register_handler (ACE_Event_Handler *event_handler,
00326                                 ACE_HANDLE event_handle = ACE_INVALID_HANDLE);
00327 #endif /* ACE_WIN32 */
00328 
00329   /**
00330    * Register an <event_handler> that will be notified when
00331    * <event_handle> is signaled.  <mask> specifies the network events
00332    * that the <event_handler> is interested in.
00333    */
00334   virtual int register_handler (ACE_HANDLE event_handle,
00335                                 ACE_HANDLE io_handle,
00336                                 ACE_Event_Handler *event_handler,
00337                                 ACE_Reactor_Mask mask);
00338 
00339   /// Register <event_handler> with all the <handles> in the <Handle_Set>.
00340   virtual int register_handler (const ACE_Handle_Set &handles,
00341                                 ACE_Event_Handler *event_handler,
00342                                 ACE_Reactor_Mask mask);
00343 
00344   /**
00345    * Register <new_sh> to handle the signal <signum> using the
00346    * <new_disp>.  Returns the <old_sh> that was previously registered
00347    * (if any), along with the <old_disp> of the signal handler.
00348    */
00349   virtual int register_handler (int signum,
00350                                 ACE_Event_Handler *new_sh,
00351                                 ACE_Sig_Action *new_disp = 0,
00352                                 ACE_Event_Handler **old_sh = 0,
00353                                 ACE_Sig_Action *old_disp = 0);
00354 
00355   /// Registers <new_sh> to handle a set of signals <sigset> using the
00356   /// <new_disp>.
00357   virtual int register_handler (const ACE_Sig_Set &sigset,
00358                                 ACE_Event_Handler *new_sh,
00359                                 ACE_Sig_Action *new_disp = 0);
00360 
00361   /**
00362    * Removes <event_handler>.  Note that the I/O handle will be
00363    * obtained using <get_handle> method of <event_handler> .  If
00364    * <mask> includes <ACE_Event_Handler::DONT_CALL> then the
00365    * <handle_close> method of the <event_handler> is not invoked.
00366    */
00367   virtual int remove_handler (ACE_Event_Handler *event_handler,
00368                               ACE_Reactor_Mask mask);
00369 
00370   /**
00371    * Removes the <ACE_Event_Handler> associated with <handle>.  If
00372    * <mask> includes <ACE_Event_Handler::DONT_CALL> then the
00373    * <handle_close> method of the associated <event_handler> is not
00374    * invoked.
00375    */
00376   virtual int remove_handler (ACE_HANDLE handle,
00377                               ACE_Reactor_Mask mask);
00378 
00379   /**
00380    * Removes all handles in <handle_set>.  If <mask> ==
00381    * <ACE_Event_Handler::DONT_CALL> then the <handle_close> method of
00382    * the associated <event_handler>s is not invoked.
00383    */
00384   virtual int remove_handler (const ACE_Handle_Set &handle_set,
00385                               ACE_Reactor_Mask mask);
00386 
00387   /**
00388    * Remove the ACE_Event_Handler currently associated with <signum>.
00389    * Install the new disposition (if given) and return the previous
00390    * disposition (if desired by the caller).  Returns 0 on success and
00391    * -1 if <signum> is invalid.
00392    */
00393   virtual int remove_handler (int signum,
00394                               ACE_Sig_Action *new_disp,
00395                               ACE_Sig_Action *old_disp = 0,
00396                               int sigkey = -1);
00397 
00398   /// Calls <remove_handler> for every signal in <sigset>.
00399   virtual int remove_handler (const ACE_Sig_Set &sigset);
00400 
00401   // = Suspend and resume Handlers.
00402 
00403   /// Suspend <event_handler> temporarily.  Use
00404   /// <ACE_Event_Handler::get_handle> to get the handle.
00405   virtual int suspend_handler (ACE_Event_Handler *event_handler);
00406 
00407   /// Suspend <handle> temporarily.
00408   virtual int suspend_handler (ACE_HANDLE handle);
00409 
00410   /// Suspend all <handles> in handle set temporarily.
00411   virtual int suspend_handler (const ACE_Handle_Set &handles);
00412 
00413   /// Suspend all <handles> temporarily.
00414   virtual int suspend_handlers (void);
00415 
00416   /// Resume <event_handler>. Use <ACE_Event_Handler::get_handle> to
00417   /// get the handle.
00418   virtual int resume_handler (ACE_Event_Handler *event_handler);
00419 
00420   /// Resume <handle>.
00421   virtual int resume_handler (ACE_HANDLE handle);
00422 
00423   /// Resume all <handles> in handle set.
00424   virtual int resume_handler (const ACE_Handle_Set &handles);
00425 
00426   /// Resume all <handles>.
00427   virtual int resume_handlers (void);
00428 
00429   /// Does the reactor allow the application to resume the handle on
00430   /// its own ie. can it pass on the control of handle resumption to
00431   /// the application. A positive value indicates that the handlers
00432   /// are application resumable. A value of 0 indicates otherwise.
00433   virtual int resumable_handler (void);
00434 
00435   // = Timer management.
00436 
00437   /**
00438    * Schedule an ACE_Event_Handler that will expire after an amount
00439    * of time.  The return value of this method, a timer_id value,
00440    * uniquely identifies the event_handler in the ACE_Reactor's
00441    * internal list of timers.
00442    * This timer_id value can be used to cancel the timer
00443    * with the cancel_timer() call.
00444    *
00445    * @see cancel_timer()
00446    * @see reset_timer_interval()
00447    *
00448    * @param event_handler  event handler to schedule on reactor
00449    * @param arg  argument passed to the handle_timeout() method of  event_handler
00450    * @param delay  time interval after which the timer will expire
00451    * @param interval  time interval after which the timer will be automatically rescheduled
00452    * @return -1 on failure, a timer_id value on success
00453    */
00454   virtual long schedule_timer (ACE_Event_Handler *event_handler,
00455                                const void *arg,
00456                                const ACE_Time_Value &delay,
00457                                const ACE_Time_Value &interval = ACE_Time_Value::zero);
00458 
00459   /**
00460    * Resets the interval of the timer represented by <timer_id> to
00461    * <interval>, which is specified in relative time to the current
00462    * <gettimeofday>.  If <interval> is equal to
00463    * <ACE_Time_Value::zero>, the timer will become a non-rescheduling
00464    * timer.  Returns 0 if successful, -1 if not.
00465    */
00466   virtual int reset_timer_interval (long timer_id,
00467                                     const ACE_Time_Value &interval);
00468 
00469   /// Cancel all <Event_Handler>s that match the address of
00470   /// <event_handler>.  Returns number of handlers cancelled.
00471   virtual int cancel_timer (ACE_Event_Handler *event_handler,
00472                             int dont_call_handle_close = 1);
00473 
00474   /**
00475    * Cancel the single <Event_Handler> that matches the <timer_id>
00476    * value, which was returned from the schedule method.  If arg is
00477    * non-NULL then it will be set to point to the ``magic cookie''
00478    * argument passed in when the Event_Handler was registered.  This
00479    * makes it possible to free up the memory and avoid memory leaks.
00480    * Returns 1 if cancellation succeeded and 0 if the <timer_id>
00481    * wasn't found.
00482    */
00483   virtual int cancel_timer (long timer_id,
00484                             const void **arg = 0,
00485                             int dont_call_handle_close = 1);
00486 
00487   // = High-level Event_Handler scheduling operations
00488 
00489   /// Add <masks_to_be_added> to the <event_handler>'s entry.
00490   /// <event_handler> must already have been registered.
00491   /// Note that this call does not cause the Reactor to re-examine
00492   /// its set of handlers - the new masks will be noticed the next
00493   /// time the Reactor waits for activity. If there is no other
00494   /// activity expected, or you need immediate re-examination of
00495   /// the wait masks, either call ACE_Reactor::notify after this
00496   /// call, or use ACE_Reactor::register_handler instead.
00497   virtual int schedule_wakeup (ACE_Event_Handler *event_handler,
00498                                ACE_Reactor_Mask masks_to_be_added);
00499 
00500   /// Add <masks_to_be_added> to the <handle>'s entry.  <event_handler>
00501   /// associated with <handle> must already have been registered.
00502   /// Note that this call does not cause the Reactor to re-examine
00503   /// its set of handlers - the new masks will be noticed the next
00504   /// time the Reactor waits for activity. If there is no other
00505   /// activity expected, or you need immediate re-examination of
00506   /// the wait masks, either call ACE_Reactor::notify after this
00507   /// call, or use ACE_Reactor::register_handler instead.
00508   virtual int schedule_wakeup (ACE_HANDLE handle,
00509                                ACE_Reactor_Mask masks_to_be_added);
00510 
00511   /// Clear <masks_to_be_cleared> from the <event_handler>'s entry.
00512   /// Note that this call does not cause the Reactor to re-examine
00513   /// its set of handlers - the new masks will be noticed the next
00514   /// time the Reactor waits for activity. If there is no other
00515   /// activity expected, or you need immediate re-examination of
00516   /// the wait masks, either call ACE_Reactor::notify after this
00517   /// call, or use ACE_Reactor::register_handler instead.
00518   virtual int cancel_wakeup (ACE_Event_Handler *event_handler,
00519                              ACE_Reactor_Mask masks_to_be_cleared);
00520 
00521   /// Clear <masks_to_be_cleared> from the <handle>'s entry.
00522   /// Note that this call does not cause the Reactor to re-examine
00523   /// its set of handlers - the new masks will be noticed the next
00524   /// time the Reactor waits for activity. If there is no other
00525   /// activity expected, or you need immediate re-examination of
00526   /// the wait masks, either call ACE_Reactor::notify after this
00527   /// call, or use ACE_Reactor::register_handler instead.
00528   virtual int cancel_wakeup (ACE_HANDLE handle,
00529                              ACE_Reactor_Mask masks_to_be_cleared);
00530 
00531   // = Notification methods.
00532 
00533   /**
00534    * Notify <event_handler> of <mask> event.  The <ACE_Time_Value>
00535    * indicates how long to blocking trying to notify.  If <timeout> ==
00536    * 0, the caller will block until action is possible, else will wait
00537    * until the relative time specified in <timeout> elapses).  Note that
00538    * <mask> can only be one of the pre-defined <ACE_Event_Handler>
00539    * masks, e.g., <READ_MASK>, <WRITE_MASK>, or <EXCEPT_MASK>.
00540    */
00541   virtual int notify (ACE_Event_Handler *event_handler = 0,
00542                       ACE_Reactor_Mask mask = ACE_Event_Handler::EXCEPT_MASK,
00543                       ACE_Time_Value *tv = 0);
00544 
00545   /**
00546    * Set the maximum number of times that ACE_Reactor will
00547    * iterate and dispatch the <ACE_Event_Handlers> that are passed in
00548    * via the notify queue before breaking out of its
00549    * <ACE_Message_Queue::dequeue> loop.  By default, this is set to
00550    * -1, which means "iterate until the queue is empty."  Setting this
00551    * to a value like "1 or 2" will increase "fairness" (and thus
00552    * prevent starvation) at the expense of slightly higher dispatching
00553    * overhead.
00554    */
00555   virtual void max_notify_iterations (int iterations);
00556 
00557   /**
00558    * Get the maximum number of times that the ACE_Reactor will
00559    * iterate and dispatch the <ACE_Event_Handlers> that are passed in
00560    * via the notify queue before breaking out of its
00561    * <ACE_Message_Queue::dequeue> loop.
00562    */
00563   virtual int max_notify_iterations (void);
00564 
00565   /**
00566    * Purge any notifications pending in this reactor for the specified
00567    * <ACE_Event_Handler> object. If <eh> == 0, all notifications for all
00568    * handlers are removed (but not any notifications posted just to wake up
00569    * the reactor itself). Returns the number of notifications purged.
00570    * Returns -1 on error.
00571    */
00572   virtual int purge_pending_notifications (ACE_Event_Handler *,
00573                                            ACE_Reactor_Mask = ACE_Event_Handler::ALL_EVENTS_MASK);
00574 
00575   // = Assorted helper methods.
00576 
00577   /**
00578    * Check to see if <handle> is associated with a valid Event_Handler
00579    * bound to <mask>.  Return the <event_handler> associated with this
00580    * <handler> if <event_handler> != 0.
00581    */
00582   virtual int handler (ACE_HANDLE handle,
00583                        ACE_Reactor_Mask mask,
00584                        ACE_Event_Handler **event_handler = 0);
00585 
00586   /**
00587    * Check to see if <signum> is associated with a valid Event_Handler
00588    * bound to a signal.  Return the <event_handler> associated with
00589    * this <handler> if <event_handler> != 0.
00590    */
00591   virtual int handler (int signum,
00592                        ACE_Event_Handler **event_handler = 0);
00593 
00594   /// Returns true if Reactor has been successfully initialized, else
00595   /// false.
00596   virtual int initialized (void);
00597 
00598   /// Returns the current size of the Reactor's internal descriptor
00599   /// table.
00600   virtual size_t size (void) const;
00601 
00602   /// Returns a reference to the Reactor's internal lock.
00603   virtual ACE_Lock &lock (void);
00604 
00605   /// Wake up all threads in waiting in the event loop
00606   virtual void wakeup_all_threads (void);
00607 
00608   /// Transfers ownership of Reactor to the <new_owner>.
00609   virtual int owner (ACE_thread_t new_owner,
00610                      ACE_thread_t *old_owner = 0);
00611 
00612   /// Return the ID of the "owner" thread.
00613   virtual int owner (ACE_thread_t *owner);
00614 
00615   /// Set position of the owner thread.
00616   virtual void requeue_position (int position);
00617 
00618   /// Get position of the owner thread.
00619   virtual int requeue_position (void);
00620 
00621   /// Get the existing restart value.
00622   virtual int restart (void);
00623 
00624   /// Set a new value for restart and return the original value.
00625   virtual int restart (int r);
00626 
00627   // = Low-level wait_set mask manipulation methods.
00628 
00629   /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the
00630   /// <event_handler> and <mask>.
00631   virtual int mask_ops (ACE_Event_Handler *event_handler,
00632                         ACE_Reactor_Mask mask,
00633                         int ops);
00634 
00635   /// GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle>
00636   /// and <mask>.
00637   virtual int mask_ops (ACE_HANDLE handle,
00638                         ACE_Reactor_Mask mask,
00639                         int ops);
00640 
00641   // = Low-level ready_set mask manipulation methods.
00642   /// GET/SET/ADD/CLR the ready "bit" bound with the <event_handler>
00643   /// and <mask>.
00644   virtual int ready_ops (ACE_Event_Handler *event_handler,
00645                          ACE_Reactor_Mask mask,
00646                          int ops);
00647 
00648   /// GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>.
00649   virtual int ready_ops (ACE_HANDLE handle,
00650                          ACE_Reactor_Mask mask,
00651                          int ops);
00652 
00653   /// Get the implementation class
00654   virtual ACE_Reactor_Impl *implementation (void) const;
00655 
00656   /**
00657    * Returns 0, if the size of the current message has been put in
00658    * <size> returns -1, if not.  ACE_HANDLE allows the reactor to
00659    * check if the caller is valid.  Used for CLASSIX Reactor
00660    * implementation.
00661    */
00662   virtual int current_info (ACE_HANDLE handle,
00663                             size_t &msg_size);
00664 
00665   /// Return 1 if we any event associations were made by the reactor
00666   /// for the handles that it waits on, 0 otherwise.
00667   virtual int uses_event_associations (void);
00668 
00669   /// Declare the dynamic allocation hooks.
00670   ACE_ALLOC_HOOK_DECLARE;
00671 
00672   /// Dump the state of the object.
00673   void dump (void) const;
00674 
00675 protected:
00676   /// Set the implementation class.
00677   virtual void implementation (ACE_Reactor_Impl *implementation);
00678 
00679   /// Delegation/implementation class that all methods will be
00680   /// forwarded to.
00681   ACE_Reactor_Impl *implementation_;
00682 
00683   /// Flag used to indicate whether we are responsible for cleaning up
00684   /// the implementation instance
00685   int delete_implementation_;
00686 
00687   /// Pointer to a process-wide <ACE_Reactor> singleton.
00688   static ACE_Reactor *reactor_;
00689 
00690   /// Must delete the <reactor_> singleton if non-0.
00691   static int delete_reactor_;
00692 
00693   /// Deny access since member-wise won't work...
00694   ACE_Reactor (const ACE_Reactor &);
00695   ACE_Reactor &operator = (const ACE_Reactor &);
00696 };
00697 
00698 #if defined (__ACE_INLINE__)
00699 #include "ace/Reactor.i"
00700 #endif /* __ACE_INLINE__ */
00701 
00702 #include "ace/post.h"
00703 #endif /* ACE_REACTOR_H */

Generated on Mon Jun 16 11:21:01 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002