dep/ACE_wrappers/ace/Token_Manager.h

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