00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Token_Manager.h 00006 * 00007 * Token_Manager.h,v 4.24 2005/10/28 23:55:10 ossama Exp 00008 * 00009 * @author Tim Harrison (harrison@cs.wustl.edu) 00010 */ 00011 //============================================================================= 00012 00013 #ifndef ACE_TOKEN_MANAGER_H 00014 #define ACE_TOKEN_MANAGER_H 00015 #include /**/ "ace/pre.h" 00016 00017 #include "ace/config-all.h" 00018 00019 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00020 # pragma once 00021 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00022 00023 #include "ace/Local_Tokens.h" 00024 00025 #if defined (ACE_HAS_TOKENS_LIBRARY) 00026 00027 #include "ace/Null_Mutex.h" 00028 #include "ace/Map_Manager.h" 00029 00030 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00031 00032 class ACE_Local_Mutex; 00033 class ACE_Mutex_Token; 00034 00035 /** 00036 * @class ACE_Token_Manager 00037 * 00038 * @brief Manages all tokens in a process space. 00039 * 00040 * Factory: Proxies use the token manager to obtain token 00041 * references. This allows multiple proxies to reference the same 00042 * logical token. 00043 * Deadlock detection: Tokens use the manager to check for 00044 * deadlock situations during acquires. 00045 */ 00046 class ACE_Export ACE_Token_Manager : public ACE_Cleanup 00047 { 00048 00049 // To add a new type of token (e.g. semaphore), do the following 00050 // steps: 1. Create a new derivation of ACE_Token. This class 00051 // defines the semantics of the new Token. 2. Create a 00052 // derivation of ACE_Token_Manager. You will only need to 00053 // redefine make_mutex. 00054 public: 00055 ACE_Token_Manager (void); 00056 virtual ~ACE_Token_Manager (void); 00057 00058 /// Get the pointer to token manager singleton. 00059 static ACE_Token_Manager *instance (void); 00060 00061 /// Set the pointer to token manager singleton. 00062 void instance (ACE_Token_Manager *); 00063 00064 /** 00065 * The Token manager uses ACE_Token_Proxy::token_id_ to look for 00066 * an existing token. If none is found, the Token Manager calls 00067 * ACE_Token_Proxy::create_token to create a new one. When 00068 * finished, sets ACE_Token_Proxy::token_. @a token_name uniquely 00069 * id's the token name. 00070 */ 00071 void get_token (ACE_Token_Proxy *, const ACE_TCHAR *token_name); 00072 00073 /** 00074 * Check whether acquire will cause deadlock or not. 00075 * returns 1 if the acquire will _not_ cause deadlock. 00076 * returns 0 if the acquire _will_ cause deadlock. 00077 * This method ignores recursive acquisition. That is, it will not 00078 * report deadlock if the client holding the token requests the 00079 * token again. Thus, it assumes recursive mutexes. 00080 */ 00081 int check_deadlock (ACE_Token_Proxy *proxy); 00082 int check_deadlock (ACE_Tokens *token, ACE_Token_Proxy *proxy); 00083 00084 /// Notify the token manager that a token has been released. If as a 00085 /// result, there is no owner of the token, the token is deleted. 00086 void release_token (ACE_Tokens *&token); 00087 00088 /** 00089 * This is to allow Tokens to perform atomic transactions. The 00090 * typical usage is to acquire this mutex, check for a safe_acquire, 00091 * perform some queueing (if need be) and then release the lock. 00092 * This is necessary since safe_acquire is implemented in terms of 00093 * the Token queues. 00094 */ 00095 ACE_TOKEN_CONST::MUTEX &mutex (void); 00096 00097 /// Dump the state of the class. 00098 void dump (void) const; 00099 00100 /// Turn debug mode on/off. 00101 void debug (int d); 00102 00103 private: 00104 /// Whether to print debug messages or not. 00105 int debug_; 00106 00107 /// pointer to singleton token manager. 00108 static ACE_Token_Manager *token_manager_; 00109 00110 /// Return the token that the given client_id is waiting for, if any 00111 ACE_Tokens *token_waiting_for (const ACE_TCHAR *client_id); 00112 00113 /// ACE_Mutex_Token used to lock internal data structures. 00114 ACE_TOKEN_CONST::MUTEX lock_; 00115 00116 /// This may be changed to a template type. 00117 typedef ACE_Token_Name TOKEN_NAME; 00118 00119 /// COLLECTION maintains a mapping from token names to ACE_Tokens* 00120 typedef ACE_Map_Manager<TOKEN_NAME, ACE_Tokens *, ACE_Null_Mutex> 00121 COLLECTION; 00122 00123 /// Allows iterations through collection_ 00124 /** 00125 * @deprecated Deprecated typedef. Use COLLECTION::ITERATOR trait 00126 * instead. 00127 */ 00128 typedef COLLECTION::ITERATOR COLLECTION_ITERATOR; 00129 00130 /// Allows iterations through collection_ 00131 /** 00132 * @deprecated Deprecated typedef. Use COLLECTION::ENTRY trait 00133 * instead. 00134 */ 00135 typedef COLLECTION::ENTRY COLLECTION_ENTRY; 00136 00137 /// COLLECTION maintains a mapping from token names to ACE_Tokens*. 00138 COLLECTION collection_; 00139 }; 00140 00141 ACE_END_VERSIONED_NAMESPACE_DECL 00142 00143 #if defined (__ACE_INLINE__) 00144 #include "ace/Token_Manager.inl" 00145 #endif /* __ACE_INLINE__ */ 00146 00147 #endif /* ACE_HAS_TOKENS_LIBRARY */ 00148 00149 #include /**/ "ace/post.h" 00150 #endif /* ACE_TOKEN_MANAGER_H */