ACE/ace/Token_Manager.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Token_Manager.h
   6  *
   7  *  @author Tim Harrison (harrison@cs.wustl.edu)
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_TOKEN_MANAGER_H
  12 #define ACE_TOKEN_MANAGER_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/config-all.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/Local_Tokens.h"
  22
  23 #if defined (ACE_HAS_TOKENS_LIBRARY)
  24
  25 #include "ace/Null_Mutex.h"
  26 #include "ace/Map_Manager.h"
  27
  28 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  29
  30 class ACE_Local_Mutex;
  31 class ACE_Mutex_Token;
  32
  33 /**
  34  * @class ACE_Token_Manager
  35  *
  36  * @brief Manages all tokens in a process space.
  37  *
  38  * Factory:  Proxies use the token manager to obtain token
  39  * references.  This allows multiple proxies to reference the same
  40  * logical token.
  41  * Deadlock detection:  Tokens use the manager to check for
  42  * deadlock situations during acquires.
  43  */
  44 class ACE_Export ACE_Token_Manager : public ACE_Cleanup
  45 {
  46   //   To add a new type of token (e.g. semaphore), do the following
  47   //   steps: 1. Create a new derivation of ACE_Token.  This class
  48   //   defines the semantics of the new Token.  2.  Create a
  49   //   derivation of ACE_Token_Manager.  You will only need to
  50   //   redefine make_mutex.
  51 public:
  52   ACE_Token_Manager ();
  53   virtual ~ACE_Token_Manager ();
  54
  55   /// Get the pointer to token manager singleton.
  56   static ACE_Token_Manager *instance ();
  57
  58   /// Set the pointer to token manager singleton.
  59   void instance (ACE_Token_Manager *);
  60
  61   /**
  62    * The Token manager uses ACE_Token_Proxy::token_id_ to look for
  63    * an existing token.  If none is found, the Token Manager calls
  64    * ACE_Token_Proxy::create_token to create a new one.  When
  65    * finished, sets ACE_Token_Proxy::token_.  @a token_name uniquely
  66    * id's the token name.
  67    */
  68   void get_token (ACE_Token_Proxy *, const ACE_TCHAR *token_name);
  69
  70   /**
  71    * Check whether acquire will cause deadlock or not.
  72    * returns 1 if the acquire will _not_ cause deadlock.
  73    * returns 0 if the acquire _will_ cause deadlock.
  74    * This method ignores recursive acquisition.  That is, it will not
  75    * report deadlock if the client holding the token requests the
  76    * token again.  Thus, it assumes recursive mutexes.
  77    */
  78   int check_deadlock (ACE_Token_Proxy *proxy);
  79   int check_deadlock (ACE_Tokens *token, ACE_Token_Proxy *proxy);
  80
  81   /// Notify the token manager that a token has been released.  If as a
  82   /// result, there is no owner of the token, the token is deleted.
  83   void release_token (ACE_Tokens *&token);
  84
  85   /**
  86    * This is to allow Tokens to perform atomic transactions.  The
  87    * typical usage is to acquire this mutex, check for a safe_acquire,
  88    * perform some queueing (if need be) and then release the lock.
  89    * This is necessary since safe_acquire is implemented in terms of
  90    * the Token queues.
  91    */
  92   ACE_TOKEN_CONST::MUTEX &mutex ();
  93
  94   /// Dump the state of the class.
  95   void dump () const;
  96
  97   /// Turn debug mode on/off.
  98   void debug (bool d);
  99
 100 private:
 101   /// Whether to print debug messages or not.
 102   bool debug_;
 103
 104   /// pointer to singleton token manager.
 105   static ACE_Token_Manager *token_manager_;
 106
 107   /// Return the token that the given client_id is waiting for, if any
 108   ACE_Tokens *token_waiting_for (const ACE_TCHAR *client_id);
 109
 110   /// ACE_Mutex_Token used to lock internal data structures.
 111   ACE_TOKEN_CONST::MUTEX lock_;
 112
 113   /// This may be changed to a template type.
 114   typedef ACE_Token_Name TOKEN_NAME;
 115
 116   /// COLLECTION maintains a mapping from token names to ACE_Tokens*
 117   typedef ACE_Map_Manager<TOKEN_NAME, ACE_Tokens *, ACE_Null_Mutex>
 118   COLLECTION;
 119
 120   /// COLLECTION maintains a mapping from token names to ACE_Tokens*.
 121   COLLECTION collection_;
 122 };
 123
 124 ACE_END_VERSIONED_NAMESPACE_DECL
 125
 126 #if defined (__ACE_INLINE__)
 127 #include "ace/Token_Manager.inl"
 128 #endif /* __ACE_INLINE__ */
 129
 130 #endif /* ACE_HAS_TOKENS_LIBRARY */
 131
 132 #include /**/ "ace/post.h"
 133 #endif /* ACE_TOKEN_MANAGER_H */