ACE/ace/Reactor_Token_T.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Reactor_Token_T.h
   6  *
   7  *  @author Steve Huston <shuston@riverace.com>
   8  */
   9 //=============================================================================
  10
  11
  12 #ifndef ACE_REACTOR_TOKEN_T_H
  13 #define ACE_REACTOR_TOKEN_T_H
  14 #include /**/ "ace/pre.h"
  15
  16 #include "ace/Reactor_Impl.h"
  17 #include "ace/Token.h"
  18
  19 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  20
  21 /**
  22  * @class ACE_Reactor_Token_T
  23  *
  24  * @internal For ACE internal use only.
  25  *
  26  * @brief Used as a synchronization mechanism to coordinate concurrent
  27  * access to an ACE_Reactor_Impl object.
  28  *
  29  * This class is used to make access to a reactor's internals and
  30  * demultiplexing mechanism thread-safe.  By default, the thread that
  31  * runs the handle_events() loop holds the token, even when it is blocked
  32  * in the demultiplexer.  Whenever another thread wants to access the
  33  * reactor, such as via the register_handler(), remove_handler(), etc.
  34  * methods, it must ask the token owner for temporary release of the token.
  35  * To accomplish this, this class reimplements the ACE_Token::sleep_hook()
  36  * method through which the owning thread can be notified to temporarily
  37  * release the token if the current situation permits.
  38  *
  39  * The owner of the token is responsible for deciding which
  40  * request for the token can be granted.  By using the
  41  * ACE_Token::renew() method, the thread that releases the token
  42  * temporarily can specify to get the token back right after the
  43  * other thread has completed using the token.  Thus, there is a
  44  * dedicated thread that owns the token by default.  This
  45  * thread grants other threads access to the token by ensuring
  46  * that whenever somebody else has finished using the token the
  47  * original owner reclaims the token again, i.e., the owner has the
  48  * chance to schedule other threads. The thread that most likely needs
  49  * the token most of the time is the thread running the dispatch loop.
  50  */
  51 template <class ACE_TOKEN_TYPE>
  52 class ACE_Reactor_Token_T : public ACE_TOKEN_TYPE
  53 {
  54 public:
  55   ACE_Reactor_Token_T (ACE_Reactor_Impl &r,
  56                        int s_queue = ACE_TOKEN_TYPE::FIFO);
  57   ACE_Reactor_Token_T (int s_queue = ACE_TOKEN_TYPE::FIFO);
  58   virtual ~ACE_Reactor_Token_T ();
  59
  60   /// Called just before a token waiter goes to sleep.
  61   /// @see ACE_Token::sleep_hook
  62   virtual void sleep_hook ();
  63
  64   /// Get the reactor implementation
  65   ACE_Reactor_Impl &reactor ();
  66
  67   /// Set the reactor implementation
  68   void reactor (ACE_Reactor_Impl &);
  69
  70   /// Dump the state of an object.
  71   virtual void dump () const;
  72
  73   /// Declare the dynamic allocation hooks.
  74   ACE_ALLOC_HOOK_DECLARE;
  75
  76 private:
  77   ACE_Reactor_Impl *reactor_;
  78 };
  79
  80 ACE_END_VERSIONED_NAMESPACE_DECL
  81
  82 #include "ace/Reactor_Token_T.cpp"
  83
  84 #include /**/ "ace/post.h"
  85 #endif /* ACE_REACTOR_TOKEN_T_H */