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

Select_Reactor_T.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Select_Reactor_T.h
00006  *
00007  *  $Id: Select_Reactor_T.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_SELECT_REACTOR_T_H
00014 #define ACE_SELECT_REACTOR_T_H
00015 #include "ace/pre.h"
00016 
00017 #include "ace/Select_Reactor_Base.h"
00018 
00019 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00020 # pragma once
00021 #endif /* ACE_LACKS_PRAGMA_ONCE */
00022 
00023 /**
00024  * @class ACE_Select_Reactor_Token_T
00025  *
00026  * @brief Used as a synchronization mechanism to coordinate concurrent
00027  * access to a Select_Reactor object.
00028  *
00029  * This class is used to make the <ACE_Select_Reactor>
00030  * thread-safe.  By default, the thread that runs the
00031  * <handle_events> loop holds the token, even when it is blocked
00032  * in the <select> call.  Whenever another thread wants to
00033  * access the <ACE_Reactor> via its <register_handler>,
00034  * <remove_handler>, etc. methods) it must ask the token owner
00035  * for temporary release of the token.  To accomplish this, the
00036  * owner of a token must define a <sleep_hook> through which it
00037  * can be notified to temporarily release the token if the
00038  * current situation permits this.
00039  * The owner of the token is responsible for deciding which
00040  * request for the token can be granted.  By using the
00041  * <ACE_Token::renew> API, the thread that releases the token
00042  * temporarily can specify to get the token back right after the
00043  * other thread has completed using the token.  Thus, there is a
00044  * dedicated thread that owns the token ``by default.''  This
00045  * thread grants other threads access to the token by ensuring
00046  * that whenever somebody else has finished using the token the
00047  * ``default owner'' first holds the token again, i.e., the
00048  * owner has the chance to schedule other threads.
00049  * The thread that most likely needs the token most of the time
00050  * is the thread running the dispatch loop.  Typically the token
00051  * gets released prior to entering the <select> call and gets
00052  * ``re-acquired'' as soon as the <select> call returns, which
00053  * results probably in many calls to <release>/<acquire> that
00054  * are not really needed since no other thread would need the
00055  * token in the meantime.  That's why the dispatcher thread is
00056  * chosen to be the owner of the token.
00057  * In case the token would have been released while in <select>
00058  * there would be a good chance that the <fd_set> could have
00059  * been modified while the <select> returns from blocking and
00060  * trying to re-acquire the lock.  Through the token mechanism
00061  * it is ensured that while another thread is holding the token,
00062  * the dispatcher thread is blocked in the <renew> call and not
00063  * in <select>.  Thus, it is not critical to change the
00064  * <fd_set>.  The implementation of the <sleep_hook> mechanism
00065  * provided by the <ACE_Select_Reactor_Token> enables the
00066  * default owner to be the thread that executes the dispatch
00067  * loop.
00068  */
00069 template <class ACE_SELECT_REACTOR_MUTEX>
00070 class ACE_Select_Reactor_Token_T : public ACE_SELECT_REACTOR_MUTEX
00071 {
00072 public:
00073 
00074   ACE_Select_Reactor_Token_T (ACE_Select_Reactor_Impl &r,
00075                               int s_queue = ACE_SELECT_TOKEN::FIFO);
00076   ACE_Select_Reactor_Token_T (int s_queue = ACE_SELECT_TOKEN::FIFO);
00077   virtual ~ACE_Select_Reactor_Token_T (void);
00078 
00079   /// Called just before the ACE_Event_Handler goes to sleep.
00080   virtual void sleep_hook (void);
00081 
00082   /// Get the select_reactor implementation
00083   ACE_Select_Reactor_Impl &select_reactor (void);
00084 
00085   /// Set the select_reactor implementation
00086   void select_reactor (ACE_Select_Reactor_Impl &);
00087 
00088   /// Dump the state of an object.
00089   virtual void dump (void) const;
00090 
00091   /// Declare the dynamic allocation hooks.
00092   ACE_ALLOC_HOOK_DECLARE;
00093 
00094 private:
00095   ACE_Select_Reactor_Impl *select_reactor_;
00096 };
00097 
00098 /**
00099  * @class ACE_Select_Reactor_T
00100  *
00101  * @brief An object oriented event demultiplexor and event handler
00102  * dispatcher.
00103  *
00104  * The <ACE_Select_Reactor> is an object-oriented event
00105  * demultiplexor and event handler dispatcher.  The sources of
00106  * events that the <ACE_Select_Reactor> waits for and dispatches
00107  * includes I/O events, signals, and timer events.  All public
00108  * methods acquire the main <ACE_Select_Reactor_Token> lock and
00109  * call down to private or protected methods, which assume that
00110  * the lock is held and so therefore don't (re)acquire the lock.
00111  */
00112 template <class ACE_SELECT_REACTOR_TOKEN>
00113 class ACE_Select_Reactor_T : public ACE_Select_Reactor_Impl
00114 {
00115 public:
00116 
00117   // = Initialization and termination methods.
00118 
00119   /// If <disable_notify_pipe> is non-0 then the reactor will
00120   /// not create a notification pipe, which will save two I/O handles
00121   /// but will elide the <notify()> feature.  If <mask_signals> is
00122   /// 1 the reactor is "signal-safe" when dispatching handlers to
00123   /// signal events, whereas if <mask_signals> is 0 the reactor will
00124   /// be more efficient, but not signal-safe (which may be perfectly
00125   /// fine if your application doesn't use the reactor to handle signals).
00126   ACE_Select_Reactor_T (ACE_Sig_Handler * = 0,
00127                         ACE_Timer_Queue * = 0,
00128                         int disable_notify_pipe = 0,
00129                         ACE_Reactor_Notify *notify = 0,
00130                         int mask_signals = 1,
00131                         int s_queue = ACE_SELECT_TOKEN::FIFO);
00132 
00133   /// Initialize @c ACE_Select_Reactor with size @arg size.
00134   /// If @arg disable_notify_pipe is non-0 then the reactor will
00135   /// not create a notification pipe, which will save two I/O handles
00136   /// but will elide the notification feature.  If @arg mask_signals is
00137   /// 1 the reactor is "signal-safe" when dispatching handlers to
00138   /// signal events, whereas if @arg mask_signals is 0 the reactor will
00139   /// be more efficient, but not signal-safe (which may be perfectly
00140   /// fine if your application doesn't use the reactor to handle signals).
00141   /**
00142    * @note On Unix platforms, the size parameter should be as large as
00143    *       the maximum number of file descriptors allowed for a given
00144    *       process.  This is necessary since a file descriptor is used
00145    *       to directly index the array of event handlers maintained by
00146    *       the Reactor's handler repository.  Direct indexing is used
00147    *       for efficiency reasons.
00148    */
00149   ACE_Select_Reactor_T (size_t size,
00150                         int restart = 0,
00151                         ACE_Sig_Handler * = 0,
00152                         ACE_Timer_Queue * = 0,
00153                         int disable_notify_pipe = 0,
00154                         ACE_Reactor_Notify *notify = 0,
00155                         int mask_signals = 1,
00156                         int s_queue = ACE_SELECT_TOKEN::FIFO);
00157 
00158   /**
00159    * Initialize the @c ACE_Select_Reactor to manage
00160    * @arg max_number_of_handles.  If @arg restart is non-0 then the
00161    * @c ACE_Reactor's @c handle_events method will be restarted
00162    * automatically when @c EINTR occurs.  If @arg signal_handler or
00163    * @arg timer_queue are non-0 they are used as the signal handler and
00164    * timer queue, respectively.  If @arg disable_notify_pipe is non-0 the
00165    * notification pipe is not created, thereby saving two I/O handles.
00166    *
00167    * @note On Unix platforms, the maximum_number_of_handles parameter
00168    *       should be as large as the maximum number of file
00169    *       descriptors allowed for a given process.  This is necessary
00170    *       since a file descriptor is used to directly index the array
00171    *       of event handlers maintained by the Reactor's handler
00172    *       repository.  Direct indexing is used for efficiency
00173    *       reasons.
00174    */
00175   virtual int open (size_t max_number_of_handles = DEFAULT_SIZE,
00176                     int restart = 0,
00177                     ACE_Sig_Handler * = 0,
00178                     ACE_Timer_Queue * = 0,
00179                     int disable_notify_pipe = 0,
00180                     ACE_Reactor_Notify * = 0);
00181 
00182   /// Returns -1 (not used in this implementation);
00183   virtual int current_info (ACE_HANDLE, size_t & /* size */);
00184 
00185   /// Use a user specified signal handler instead.
00186   virtual int set_sig_handler (ACE_Sig_Handler *signal_handler);
00187 
00188   /// @deprecated The following method is deprecated.  Use <timer_queue> instead.
00189   /// Set a user specified timer queue.
00190   virtual int set_timer_queue (ACE_Timer_Queue *tq);
00191 
00192   /// Set a user-specified timer queue.
00193   virtual int timer_queue (ACE_Timer_Queue *tq);
00194 
00195   /// Return the current <ACE_Timer_Queue>.
00196   virtual ACE_Timer_Queue *timer_queue (void) const;
00197 
00198   /// Close down the select_reactor and release all of its resources.
00199   virtual int close (void);
00200 
00201   /// Close down the select_reactor and release all of its resources.
00202   virtual ~ACE_Select_Reactor_T (void);
00203 
00204   // = Event loop drivers.
00205 
00206   /**
00207    * Returns non-zero if there are I/O events "ready" for dispatching,
00208    * but does not actually dispatch the event handlers.  By default,
00209    * don't block while checking this, i.e., "poll".
00210    */
00211   virtual int work_pending (const ACE_Time_Value &max_wait_time =  ACE_Time_Value::zero);
00212 
00213   /**
00214    * This event loop driver that blocks for <max_wait_time> before
00215    * returning.  It will return earlier if timer events, I/O events,
00216    * or signal events occur.  Note that <max_wait_time> can be 0, in
00217    * which case this method blocks indefinitely until events occur.
00218    *
00219    * <max_wait_time> is decremented to reflect how much time this call
00220    * took.  For instance, if a time value of 3 seconds is passed to
00221    * handle_events and an event occurs after 2 seconds,
00222    * <max_wait_time> will equal 1 second.  This can be used if an
00223    * application wishes to handle events for some fixed amount of
00224    * time.
00225    *
00226    * Returns the total number of I/O and Timer <ACE_Event_Handler>s
00227    * that were dispatched, 0 if the <max_wait_time> elapsed without
00228    * dispatching any handlers, or -1 if something goes wrong.
00229    *
00230    * Current <alertable_handle_events> is identical to
00231    * <handle_events>.
00232    */
00233   virtual int handle_events (ACE_Time_Value *max_wait_time = 0);
00234   virtual int alertable_handle_events (ACE_Time_Value *max_wait_time = 0);
00235 
00236   /**
00237    * This method is just like the one above, except the
00238    * <max_wait_time> value is a reference and can therefore never be
00239    * NULL.
00240    *
00241    * Current <alertable_handle_events> is identical to
00242    * <handle_events>.
00243    */
00244   virtual int handle_events (ACE_Time_Value &max_wait_time);
00245   virtual int alertable_handle_events (ACE_Time_Value &max_wait_time);
00246 
00247   // = Event handling control.
00248 
00249   /**
00250    * Return the status of Reactor.  If this function returns 0, the reactor is
00251    * actively handling events.  If it returns non-zero, <handling_events> and
00252    * <handle_alertable_events> return -1 immediately.
00253    */
00254   virtual int deactivated (void);
00255 
00256   /**
00257    * Control whether the Reactor will handle any more incoming events or not.
00258    * If <do_stop> == 1, the Reactor will be disabled.  By default, a reactor
00259    * is in active state and can be deactivated/reactived as wish.
00260    */
00261   virtual void deactivate (int do_stop);
00262 
00263   // = Register and remove <ACE_Event_Handler>s.
00264   /**
00265    * Register a <eh> with a particular <mask>.  Note that the
00266    * <Select_Reactor> will call <ACE_Event_Handler::get_handle> to
00267    * extract the underlying I/O handle.
00268    */
00269   virtual int register_handler (ACE_Event_Handler *eh,
00270                                 ACE_Reactor_Mask mask);
00271 
00272   /**
00273    * Register a <eh> with a particular <mask>.  Note that since the
00274    * <handle> is given the Select_Reactor will *not* call
00275    * <ACE_Event_Handler::get_handle> to extract the underlying I/O
00276    * handle.
00277    */
00278   virtual int register_handler (ACE_HANDLE handle,
00279                                 ACE_Event_Handler *eh,
00280                                 ACE_Reactor_Mask mask);
00281 
00282 #if defined (ACE_WIN32)
00283 
00284   // Originally this interface was available for all platforms, but
00285   // because ACE_HANDLE is an int on non-Win32 platforms, compilers
00286   // are not able to tell the difference between
00287   // register_handler(ACE_Event_Handler*,ACE_Reactor_Mask) and
00288   // register_handler(ACE_Event_Handler*,ACE_HANDLE). Therefore, we
00289   // have restricted this method to Win32 only.
00290 
00291   /// Not implemented.
00292   virtual int register_handler (ACE_Event_Handler *event_handler,
00293                                 ACE_HANDLE event_handle = ACE_INVALID_HANDLE);
00294 
00295 #endif /* ACE_WIN32 */
00296 
00297   /// Not implemented.
00298   virtual int register_handler (ACE_HANDLE event_handle,
00299                                 ACE_HANDLE io_handle,
00300                                 ACE_Event_Handler *event_handler,
00301                                 ACE_Reactor_Mask mask);
00302 
00303   /// Register <eh> with all the <handles> in the <Handle_Set>.
00304   virtual int register_handler (const ACE_Handle_Set &handles,
00305                                 ACE_Event_Handler *eh,
00306                                 ACE_Reactor_Mask mask);
00307 
00308   /**
00309    * Register <new_sh> to handle the signal <signum> using the
00310    * <new_disp>.  Returns the <old_sh> that was previously registered
00311    * (if any), along with the <old_disp> of the signal handler.
00312    */
00313   virtual int register_handler (int signum,
00314                                 ACE_Event_Handler *new_sh,
00315                                 ACE_Sig_Action *new_disp = 0,
00316                                 ACE_Event_Handler **old_sh = 0,
00317                                 ACE_Sig_Action *old_disp = 0);
00318 
00319   /// Registers <new_sh> to handle a set of signals <sigset> using the
00320   /// <new_disp>.
00321   virtual int register_handler (const ACE_Sig_Set &sigset,
00322                                 ACE_Event_Handler *new_sh,
00323                                 ACE_Sig_Action *new_disp = 0);
00324 
00325   /**
00326    * Removes the <mask> binding of <eh> from the Select_Reactor.  If
00327    * there are no more bindings for this <eh> then it is removed from
00328    * the Select_Reactor.  Note that the Select_Reactor will call
00329    * <ACE_Event_Handler::get_handle> to extract the underlying I/O
00330    * handle.
00331    */
00332   virtual int remove_handler (ACE_Event_Handler *eh,
00333                               ACE_Reactor_Mask mask);
00334 
00335   /**
00336    * Removes the <mask> bind of <Event_Handler> whose handle is
00337    * <handle> from the Select_Reactor.  If there are no more bindings
00338    * for this <eh> then it is removed from the Select_Reactor.
00339    */
00340   virtual int remove_handler (ACE_HANDLE handle,
00341                               ACE_Reactor_Mask);
00342 
00343   /**
00344    * Removes all the <mask> bindings for handles in the <handle_set>
00345    * bind of <Event_Handler>.  If there are no more bindings for any
00346    * of these handlers then they are removed from the Select_Reactor.
00347    */
00348   virtual int remove_handler (const ACE_Handle_Set &handle_set,
00349                               ACE_Reactor_Mask);
00350 
00351   /**
00352    * Remove the ACE_Event_Handler currently associated with <signum>.
00353    * <sigkey> is ignored in this implementation since there is only
00354    * one instance of a signal handler.  Install the new disposition
00355    * (if given) and return the previous disposition (if desired by the
00356    * caller).  Returns 0 on success and -1 if <signum> is invalid.
00357    */
00358   virtual int remove_handler (int signum,
00359                               ACE_Sig_Action *new_disp,
00360                               ACE_Sig_Action *old_disp = 0,
00361                               int sigkey = -1);
00362 
00363   /// Calls <remove_handler> for every signal in <sigset>.
00364   virtual int remove_handler (const ACE_Sig_Set &sigset);
00365 
00366   // = Suspend and resume Handlers.
00367 
00368   /// Temporarily suspend the <Event_Handler> associated with <eh>.
00369   virtual int suspend_handler (ACE_Event_Handler *eh);
00370 
00371   /// Temporarily suspend the <Event_Handler> associated with <handle>.
00372   virtual int suspend_handler (ACE_HANDLE handle);
00373 
00374   /// Suspend all <handles> in handle set temporarily.
00375   virtual int suspend_handler (const ACE_Handle_Set &handles);
00376 
00377   /// Suspend all the <Event_Handlers> in the Select_Reactor.
00378   virtual int suspend_handlers (void);
00379 
00380   /// Resume a temporarily suspend <Event_Handler> associated with
00381   /// <eh>.
00382   virtual int resume_handler (ACE_Event_Handler *eh);
00383 
00384   /// Resume a temporarily suspended <Event_Handler> associated with
00385   /// <handle>.
00386   virtual int resume_handler (ACE_HANDLE handle);
00387 
00388   /// Resume all <handles> in handle set.
00389   virtual int resume_handler (const ACE_Handle_Set &handles);
00390 
00391   /// Resume all the <Event_Handlers> in the Select_Reactor.
00392   virtual int resume_handlers (void);
00393 
00394   /**
00395    * Return 1 if we any event associations were made by the reactor
00396    * for the handles that it waits on, 0 otherwise. Since the
00397    * Select_Reactor does not do any event associations, this function
00398    * always return 0.
00399    */
00400   virtual int uses_event_associations (void);
00401 
00402   // = Timer management.
00403   /**
00404    * Schedule an ACE_Event_Handler that will expire after an amount
00405    * of time.  The return value of this method, a timer_id value,
00406    * uniquely identifies the event_handler in the ACE_Reactor's
00407    * internal list of timers.
00408    * This timer_id value can be used to cancel the timer
00409    * with the cancel_timer() call.
00410    *
00411    * @see cancel_timer()
00412    * @see reset_timer_interval()
00413    *
00414    * @param event_handler  Event handler to schedule on reactor
00415    * @param arg   Argument passed to the handle_timeout() method of  event_handler
00416    * @param delay  Time interval after which the timer will expire
00417    * @param interval  Time interval after which the timer will be automatically rescheduled
00418    * @return -1 on failure, a timer_id value on success
00419    */
00420   virtual long schedule_timer (ACE_Event_Handler * event_handler,
00421                                const void *arg,
00422                                const ACE_Time_Value &delay,
00423                                const ACE_Time_Value &interval = ACE_Time_Value::zero);
00424 
00425   /**
00426    * Resets the interval of the timer represented by <timer_id> to
00427    * <interval>, which is specified in relative time to the current
00428    * <gettimeofday>.  If <interval> is equal to
00429    * <ACE_Time_Value::zero>, the timer will become a non-rescheduling
00430    * timer.  Returns 0 if successful, -1 if not.
00431    */
00432   virtual int reset_timer_interval (long timer_id,
00433                                     const ACE_Time_Value &interval);
00434 
00435   /**
00436    * Cancel all <event_handlers> that match the address of
00437    * <event_handler>.  If <dont_call_handle_close> is 0 then the
00438    * <handle_close> method of <event_handler> will be invoked.
00439    * Returns number of handler's cancelled.
00440    */
00441   virtual int cancel_timer (ACE_Event_Handler *event_handler,
00442                             int dont_call_handle_close = 1);
00443 
00444   /**
00445    * Cancel the single <ACE_Event_Handler> that matches the <timer_id>
00446    * value (which was returned from the <schedule> method).  If arg is
00447    * non-NULL then it will be set to point to the ``magic cookie''
00448    * argument passed in when the <Event_Handler> was registered.  This
00449    * makes it possible to free up the memory and avoid memory leaks.
00450    * If <dont_call_handle_close> is 0 then the <handle_close> method
00451    * of <event_handler> will be invoked.  Returns 1 if cancellation
00452    * succeeded and 0 if the <timer_id> wasn't found.
00453    */
00454   virtual int cancel_timer (long timer_id,
00455                             const void **arg = 0,
00456                             int dont_call_handle_close = 1);
00457 
00458   // = High-level Event_Handler scheduling operations
00459 
00460   /// ADD the dispatch MASK "bit" bound with the <eh> and the <mask>.
00461   virtual int schedule_wakeup (ACE_Event_Handler *eh,
00462                                ACE_Reactor_Mask mask);
00463 
00464   /// ADD the dispatch MASK "bit" bound with the <handle> and the <mask>.
00465   virtual int schedule_wakeup (ACE_HANDLE handle,
00466                                ACE_Reactor_Mask mask);
00467 
00468   /// CLR the dispatch MASK "bit" bound with the <eh> and the <mask>.
00469   virtual int cancel_wakeup (ACE_Event_Handler *eh,
00470                              ACE_Reactor_Mask mask);
00471 
00472   /// CLR the dispatch MASK "bit" bound with the <handle> and the <mask>.
00473   virtual int cancel_wakeup (ACE_HANDLE handle,
00474                              ACE_Reactor_Mask mask);
00475 
00476   // = Notification methods.
00477   /**
00478    * Called by a thread when it wants to unblock the Select_Reactor.
00479    * This wakeups the <ACE_Select_Reactor> if currently blocked in
00480    * <select>/<poll>.  Pass over both the <Event_Handler> *and* the
00481    * <mask> to allow the caller to dictate which <Event_Handler>
00482    * method the <Select_Reactor> will invoke.  The <ACE_Time_Value>
00483    * indicates how long to blocking trying to notify the
00484    * <Select_Reactor>.  If <timeout> == 0, the caller will block until
00485    * action is possible, else will wait until the relative time
00486    * specified in *<timeout> elapses).
00487    */
00488   virtual int notify (ACE_Event_Handler * = 0,
00489                       ACE_Reactor_Mask = ACE_Event_Handler::EXCEPT_MASK,
00490                       ACE_Time_Value * = 0);
00491 
00492   /**
00493    * Set the maximum number of times that the
00494    * <ACE_Select_Reactor_Notify::handle_input> method will iterate and
00495    * dispatch the <ACE_Event_Handlers> that are passed in via the
00496    * notify pipe before breaking out of its <recv> loop.  By default,
00497    * this is set to -1, which means "iterate until the pipe is empty."
00498    * Setting this to a value like "1 or 2" will increase "fairness"
00499    * (and thus prevent starvation) at the expense of slightly higher
00500    * dispatching overhead.
00501    */
00502   virtual void max_notify_iterations (int);
00503 
00504   /**
00505    * Get the maximum number of times that the
00506    * <ACE_Select_Reactor_Notify::handle_input> method will iterate and
00507    * dispatch the <ACE_Event_Handlers> that are passed in via the
00508    * notify pipe before breaking out of its <recv> loop.
00509    */
00510   virtual int max_notify_iterations (void);
00511 
00512   /// Get the existing restart value.
00513   virtual int restart (void);
00514 
00515   /// Set a new value for restart and return the original value.
00516   virtual int restart (int r);
00517 
00518   /// Set position that the main ACE_Select_Reactor thread is requeued in the
00519   /// list of waiters during a <notify> callback.
00520   virtual void requeue_position (int);
00521 
00522   /// Get position that the main ACE_Select_Reactor thread is requeued in the
00523   /// list of waiters during a <notify> callback.
00524   virtual int requeue_position (void);
00525 
00526   // = Low-level wait_set mask manipulation methods.
00527   /// GET/SET/ADD/CLR the dispatch mask "bit" bound with the <eh> and
00528   /// <mask>.
00529   virtual int mask_ops (ACE_Event_Handler *eh,
00530                         ACE_Reactor_Mask mask,
00531                         int ops);
00532 
00533   /// GET/SET/ADD/CLR the dispatch MASK "bit" bound with the <handle>
00534   /// and <mask>.
00535   virtual int mask_ops (ACE_HANDLE handle,
00536                         ACE_Reactor_Mask mask,
00537                         int ops);
00538 
00539   // = Low-level ready_set mask manipulation methods.
00540   /// GET/SET/ADD/CLR the ready "bit" bound with the <eh> and <mask>.
00541   virtual int ready_ops (ACE_Event_Handler *eh,
00542                          ACE_Reactor_Mask mask,
00543                          int ops);
00544 
00545   /// GET/SET/ADD/CLR the ready "bit" bound with the <handle> and <mask>.
00546   virtual int ready_ops (ACE_HANDLE handle,
00547                          ACE_Reactor_Mask,
00548                          int ops);
00549 
00550   /// Wake up all threads in waiting in the event loop
00551   virtual void wakeup_all_threads (void);
00552 
00553   // = Only the owner thread can perform a <handle_events>.
00554 
00555   /// Set the new owner of the thread and return the old owner.
00556   virtual int owner (ACE_thread_t n_id, ACE_thread_t *o_id = 0);
00557 
00558   /// Return the current owner of the thread.
00559   virtual int owner (ACE_thread_t *);
00560 
00561   // = Miscellaneous Handler operations.
00562   /**
00563    * Check to see if <handle> is associated with a valid Event_Handler
00564    * bound to <mask>.  Return the <eh> associated with this <handler>
00565    * if <eh> != 0.
00566    */
00567   virtual int handler (ACE_HANDLE handle,
00568                        ACE_Reactor_Mask mask,
00569                        ACE_Event_Handler **eh = 0);
00570 
00571   /**
00572    * Check to see if <signum> is associated with a valid Event_Handler
00573    * bound to a signal.  Return the <eh> associated with this
00574    * <handler> if <eh> != 0.
00575    */
00576   virtual int handler (int signum,
00577                        ACE_Event_Handler ** = 0);
00578 
00579   /// Returns true if we've been successfully initialized, else false.
00580   virtual int initialized (void);
00581 
00582   /// Returns the current size of the Reactor's internal descriptor
00583   /// table.
00584   virtual size_t size (void) const;
00585 
00586   /**
00587    * Returns a reference to the <ACE_Select_Reactor_Token> that is
00588    * used to serialize the internal Select_Reactor's processing logic.
00589    * This can be useful for situations where you need to avoid
00590    * deadlock efficiently when <ACE_Event_Handlers> are used in
00591    * multiple threads.
00592    */
00593   virtual ACE_Lock &lock (void);
00594 
00595   /// Dump the state of an object.
00596   virtual void dump (void) const;
00597 
00598   /// Declare the dynamic allocation hooks.
00599   ACE_ALLOC_HOOK_DECLARE;
00600 
00601 protected:
00602   // = Internal methods that do the actual work.
00603 
00604   // All of these methods assume that the <Select_Reactor>'s token
00605   // lock is held by the public methods that call down to them.
00606 
00607   /// Do the work of actually binding the <handle> and <eh> with the
00608   /// <mask>.
00609   virtual int register_handler_i (ACE_HANDLE handle,
00610                                   ACE_Event_Handler *eh,
00611                                   ACE_Reactor_Mask mask);
00612 
00613   /// Register a set of <handles>.
00614   virtual int register_handler_i (const ACE_Handle_Set &handles,
00615                                   ACE_Event_Handler *handler,
00616                                   ACE_Reactor_Mask mask);
00617 
00618   /// Do the work of actually unbinding the <handle> and <eh> with the
00619   /// <mask>.
00620   virtual int remove_handler_i (ACE_HANDLE handle,
00621                                 ACE_Reactor_Mask);
00622 
00623   /// Remove a set of <handles>.
00624   virtual int remove_handler_i (const ACE_Handle_Set &handles,
00625                                 ACE_Reactor_Mask);
00626 
00627   /// Suspend the <Event_Handler> associated with <handle>
00628   virtual int suspend_i (ACE_HANDLE handle);
00629 
00630   /// Check to see if the <Event_Handler> associated with <handle> is
00631   /// suspended. Returns 0 if not, 1 if so.
00632   virtual int is_suspended_i (ACE_HANDLE handle);
00633 
00634   /// Resume the <Event_Handler> associated with <handle>
00635   virtual int resume_i (ACE_HANDLE handle);
00636 
00637   /// Implement the public <handler> method.
00638   virtual int handler_i (ACE_HANDLE handle,
00639                          ACE_Reactor_Mask,
00640                          ACE_Event_Handler ** = 0);
00641 
00642   /// Implement the public <handler> method.
00643   virtual int handler_i (int signum, ACE_Event_Handler ** = 0);
00644 
00645   /**
00646    * Check if there are any HANDLEs enabled in the <ready_set_>, and
00647    * if so, update the <handle_set> and return the number ready.  If
00648    * there aren't any HANDLEs enabled return 0.
00649    */
00650   virtual int any_ready (ACE_Select_Reactor_Handle_Set &handle_set);
00651 
00652   /// Implement the <any_ready> method, assuming that the Sig_Guard is
00653   /// beign held
00654   virtual int any_ready_i (ACE_Select_Reactor_Handle_Set &handle_set);
00655 
00656   /// Take corrective action when errors occur.
00657   virtual int handle_error (void);
00658 
00659   /// Make sure the handles are all valid.
00660   virtual int check_handles (void);
00661 
00662   /// Wait for events to occur.
00663   virtual int wait_for_multiple_events (ACE_Select_Reactor_Handle_Set &,
00664                                         ACE_Time_Value *);
00665 
00666   // = Dispatching methods.
00667 
00668   /**
00669    * Template Method that dispatches <ACE_Event_Handler>s for time
00670    * events, I/O events, and signal events.  Returns the total number
00671    * of <ACE_Event_Handler>s that were dispatched or -1 if something
00672    * goes wrong.
00673    */
00674   virtual int dispatch (int nfound,
00675                         ACE_Select_Reactor_Handle_Set &);
00676 
00677   /**
00678    * Dispatch all timer handlers that have expired.  Returns -1 if the
00679    * state of the <wait_set_> has changed, else 0.
00680    * <number_dispatched> is set to the number of timer handlers
00681    * dispatched.
00682    */
00683   virtual int dispatch_timer_handlers (int &number_dispatched);
00684 
00685   /**
00686    * Dispatch any notification handlers.  Returns -1 if the state of
00687    * the <wait_set_> has changed, else returns number of handlers
00688    * notified.
00689    */
00690   virtual int dispatch_notification_handlers (ACE_Select_Reactor_Handle_Set &dispatch_set,
00691                                               int &number_of_active_handles,
00692                                               int &number_of_handlers_dispatched);
00693 
00694   /**
00695    * Dispatch all the input/output/except handlers that are enabled in
00696    * the <dispatch_set>.  Updates <number_of_active_handles> and
00697    * <number_of_handlers_dispatched> according to the behavior of the
00698    * number Returns -1 if the state of the <wait_set_> has changed,
00699    * else 0.
00700    */
00701   virtual int dispatch_io_handlers (ACE_Select_Reactor_Handle_Set &dispatch_set,
00702                                     int &number_of_active_handles,
00703                                     int &number_of_handlers_dispatched);
00704 
00705   /**
00706    * Factors the dispatching of an io handle set (each WRITE, EXCEPT
00707    * or READ set of handles).  It updates the
00708    * <number_of_handlers_dispatched> and invokes this->notify_handle
00709    * for all the handles in <dispatch_set> using the <mask>,
00710    * <ready_set> and <callback> parameters.  Must return -1 if
00711    * this->state_changed otherwise it must return 0.
00712    */
00713   virtual int dispatch_io_set (int number_of_active_handles,
00714                                int &number_of_handlers_dispatched,
00715                                int mask,
00716                                ACE_Handle_Set& dispatch_mask,
00717                                ACE_Handle_Set& ready_mask,
00718                                ACE_EH_PTMF callback);
00719 
00720   /// Notify the appropriate <callback> in the context of the <eh>
00721   /// associated with <handle> that a particular event has occurred.
00722   virtual void notify_handle (ACE_HANDLE handle,
00723                               ACE_Reactor_Mask mask,
00724                               ACE_Handle_Set &,
00725                               ACE_Event_Handler *eh,
00726                               ACE_EH_PTMF callback);
00727 
00728   /// Enqueue ourselves into the list of waiting threads at the
00729   /// appropriate point specified by <requeue_position_>.
00730   virtual void renew (void);
00731 
00732   /// Synchronization token for the MT_SAFE ACE_Select_Reactor.
00733   ACE_SELECT_REACTOR_TOKEN token_;
00734 
00735   /// Adapter used to return internal lock to outside world.
00736   ACE_Lock_Adapter<ACE_SELECT_REACTOR_TOKEN> lock_adapter_;
00737 
00738   /// Release the token lock when a Win32 structured exception occurs.
00739   int release_token (void);
00740 
00741   /// Stops the VC++ compiler from bitching about exceptions and destructors
00742   int handle_events_i (ACE_Time_Value *max_wait_time = 0);
00743 
00744   /// This flag is used to keep track of whether we are actively handling
00745   /// events or not.
00746   sig_atomic_t deactivated_;
00747 
00748   /**
00749    * If 0 then the Reactor will not mask the signals during the event
00750    * dispatching.  This is useful for applications that do not
00751    * register any signal handlers and want to reduce the overhead
00752    * introduce by the kernel level locks required to change the mask.
00753    */
00754   int mask_signals_;
00755 
00756 private:
00757   /// Deny access since member-wise won't work...
00758   ACE_UNIMPLEMENTED_FUNC (ACE_Select_Reactor_T (const ACE_Select_Reactor_T<ACE_SELECT_REACTOR_TOKEN> &))
00759   ACE_UNIMPLEMENTED_FUNC (ACE_Select_Reactor_T<ACE_SELECT_REACTOR_TOKEN> &operator=  (const ACE_Select_Reactor_T<ACE_SELECT_REACTOR_TOKEN> &) )
00760 };
00761 
00762 // @@ The latest version of SunCC can't grok the code if we put inline
00763 // function here.  Therefore, we temporarily disable the code here.
00764 // We shall turn this back on once we know the problem gets fixed.
00765 #if 0 // defined (__ACE_INLINE__)
00766 #include "ace/Select_Reactor_T.i"
00767 #endif /* __ACE_INLINE__ */
00768 
00769 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00770 #include "ace/Select_Reactor_T.cpp"
00771 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00772 
00773 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00774 #pragma implementation ("Select_Reactor_T.cpp")
00775 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00776 
00777 #include "ace/post.h"
00778 #endif /* ACE_SELECT_REACTOR_T_H */

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