diff options
Diffstat (limited to 'ace/Token_Manager.h')
| -rw-r--r-- | ace/Token_Manager.h | 107 |
1 files changed, 56 insertions, 51 deletions
diff --git a/ace/Token_Manager.h b/ace/Token_Manager.h index 79e37935d95..56fb63db6a0 100644 --- a/ace/Token_Manager.h +++ b/ace/Token_Manager.h @@ -1,18 +1,15 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Token_Manager.h -// -// = AUTHOR -// Tim Harrison (harrison@cs.wustl.edu) -// -// ============================================================================ + +//============================================================================= +/** + * @file Token_Manager.h + * + * $Id$ + * + * @author Tim Harrison (harrison@cs.wustl.edu) + */ +//============================================================================= + #ifndef ACE_TOKEN_MANAGER_H #define ACE_TOKEN_MANAGER_H @@ -30,17 +27,19 @@ class ACE_Local_Mutex; class ACE_Mutex_Token; +/** + * @class ACE_Token_Manager + * + * @brief Manages all tokens in a process space. + * + * Factory: Proxies use the token manager to obtain token + * references. This allows multiple proxies to reference the same + * logical token. + * Deadlock detection: Tokens use the manager to check for + * deadlock situations during acquires. + */ class ACE_Export ACE_Token_Manager : public ACE_Cleanup { - // = TITLE - // Manages all tokens in a process space. - // - // = DESCRIPTION - // Factory: Proxies use the token manager to obtain token - // references. This allows multiple proxies to reference the same - // logical token. - // Deadlock detection: Tokens use the manager to check for - // deadlock situations during acquires. // To add a new type of token (e.g. semaphore), do the following // steps: 1. Create a new derivation of ACE_Token. This class @@ -55,68 +54,74 @@ public: static ACE_Token_Manager *instance (void); void instance (ACE_Token_Manager *); + /** + * The Token manager uses ACE_Token_Proxy::token_id_ to look for + * an existing token. If none is found, the Token Manager calls + * ACE_Token_Proxy::create_token to create a new one. When + * finished, sets ACE_Token_Proxy::token_. <token_name> uniquely + * id's the token name. + */ void get_token (ACE_Token_Proxy *, const ACE_TCHAR *token_name); - // The Token manager uses ACE_Token_Proxy::token_id_ to look for - // an existing token. If none is found, the Token Manager calls - // ACE_Token_Proxy::create_token to create a new one. When - // finished, sets ACE_Token_Proxy::token_. <token_name> uniquely - // id's the token name. + /** + * returns 1 if the acquire will _not_ cause deadlock. + * returns 0 if the acquire _will_ cause deadlock. + * this method ignores recursive acquisition. That is, it will not + * report deadlock if the client holding the token requests the + * token again. Thus, it assumes recursive mutexes. + */ int check_deadlock (ACE_Token_Proxy *proxy); int check_deadlock (ACE_Tokens *token, ACE_Token_Proxy *proxy); - // returns 1 if the acquire will _not_ cause deadlock. - // returns 0 if the acquire _will_ cause deadlock. - // this method ignores recursive acquisition. That is, it will not - // report deadlock if the client holding the token requests the - // token again. Thus, it assumes recursive mutexes. + /// notify the token manager that a token has been released. If as a + /// result, there is no owner of the token, the token is deleted. void release_token (ACE_Tokens *&token); - // notify the token manager that a token has been released. If as a - // result, there is no owner of the token, the token is deleted. + /** + * This is to allow Tokens to perform atomic transactions. The + * typical usage is to acquire this mutex, check for a safe_acquire, + * perform some queueing (if need be) and then release the lock. + * This is necessary since safe_acquire is implemented in terms of + * the Token queues. + */ ACE_TOKEN_CONST::MUTEX &mutex (void); - // This is to allow Tokens to perform atomic transactions. The - // typical usage is to acquire this mutex, check for a safe_acquire, - // perform some queueing (if need be) and then release the lock. - // This is necessary since safe_acquire is implemented in terms of - // the Token queues. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. + /// Turn debug mode on/off. void debug (int d); - // Turn debug mode on/off. private: + /// Whether to print debug messages or not. int debug_; - // Whether to print debug messages or not. + /// pointer to singleton token manager. static ACE_Token_Manager *token_manager_; - // pointer to singleton token manager. + /// return the token that the given client_id is waiting for, if any ACE_Tokens *token_waiting_for (const ACE_TCHAR *client_id); - // return the token that the given client_id is waiting for, if any + /// ACE_Mutex_Token used to lock internal data structures. ACE_TOKEN_CONST::MUTEX lock_; - // ACE_Mutex_Token used to lock internal data structures. + /// This may be changed to a template type. typedef ACE_Token_Name TOKEN_NAME; - // This may be changed to a template type. + /// COLLECTION maintains a mapping from token names to ACE_Tokens* typedef ACE_Map_Manager<TOKEN_NAME, ACE_Tokens *, ACE_Null_Mutex> COLLECTION; - // COLLECTION maintains a mapping from token names to ACE_Tokens* + /// Allows iterations through collection_ typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Tokens *, ACE_Null_Mutex> COLLECTION_ITERATOR; - // Allows iterations through collection_ + /// Allows iterations through collection_ typedef ACE_Map_Entry<TOKEN_NAME, ACE_Tokens *> COLLECTION_ENTRY; - // Allows iterations through collection_ + /// COLLECTION maintains a mapping from token names to ACE_Tokens*. COLLECTION collection_; - // COLLECTION maintains a mapping from token names to ACE_Tokens*. }; #if defined (__ACE_INLINE__) |