diff options
Diffstat (limited to 'ACE/ace/Token_Collection.h')
| -rw-r--r-- | ACE/ace/Token_Collection.h | 243 |
1 files changed, 243 insertions, 0 deletions
diff --git a/ACE/ace/Token_Collection.h b/ACE/ace/Token_Collection.h new file mode 100644 index 00000000000..0d57cc0ca58 --- /dev/null +++ b/ACE/ace/Token_Collection.h @@ -0,0 +1,243 @@ +// -*- C++ -*- + +//============================================================================= +/** + * @file Token_Collection.h + * + * $Id$ + * + * The ACE_Token class offers methods for acquiring, renewing, + * and releasing a synchronization token on a per-token basis. The + * ACE_Token_Collection offers an interface for performing + * operations on groups of tokens as a whole, or on a single token + * within the collection. + * + * The atomic group operations are not yet implemented. + * + * + * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) + * @author Tim Harrison (harrison@cs.wustl.edu) + */ +//============================================================================= + +#ifndef ACE_TOKEN_COLLECTION_H +#define ACE_TOKEN_COLLECTION_H +#include /**/ "ace/pre.h" + +#include "ace/Map_Manager.h" + +#if !defined (ACE_LACKS_PRAGMA_ONCE) +# pragma once +#endif /* ACE_LACKS_PRAGMA_ONCE */ + +#if defined (ACE_HAS_TOKENS_LIBRARY) + +#include "ace/Local_Tokens.h" +#include "ace/Null_Mutex.h" + +ACE_BEGIN_VERSIONED_NAMESPACE_DECL + +/** + * @class ACE_Token_Collection + * + * @brief Allows atomic token group operations AND + * provides a ACE_Token manager interface. + * + * There are two types of operations offered by + * ACE_Token_Collection. The first is atomic operations on + * collections of Token_Proxies. In this respect, the + * ACE_Token_Collection can be thought of as a single token + * consisting of multiple Token_Proxies. The second role of the + * ACE_Token_Collection is as a ACE_Token manager. + * ACE_Token_Collection allows individual operations on single + * members of a collection of Token_Proxies. This provides a + * single access point for operations on multiple tokens. + */ +class ACE_Export ACE_Token_Collection : public ACE_Token_Proxy +{ + + // = BUGS + // Although ACE_Token_Collection inherits from ACE_Token_Proxy, it + // can not be including in a collection. This is because <clone> + // returns zero for now. +public: + /** + * @a debug print out verbose debugging messages. @a name will give a + * name to the collection. Collections don't really need names, but + * are sometimes useful for debugging. + */ + ACE_Token_Collection (int debug = 0, + const ACE_TCHAR *name = 0); + +// Collection Management operations + + /** + * Insert a Token into the collection. All ACE_Token type + * operations performed on the collection will also be performed on + * the new_proxy until it is removed. Note that no operations + * performed prior to the insertion will be performed. Returns: 0 + * on success, -1 on failure with <errno> == problem. If a token + * proxy already exists in the collection with the same name, the + * insertion will fail. Also, <token> is copied. Note that during + * the copy, client_id's are *not* inherited. The client ID of the + * thread using the collection will be used. Client ID's can be + * changed explicity on each proxy using is_member. + */ + int insert (ACE_Token_Proxy &token); + + /** + * removes the ACE_Token matching the given token_name from the + * collection. On success, extract returns 0. On failure + * (token_name was not in the collection,) extract returns -1. On + * success, the state of the token found is copied into proxy. + * The returned ACE_Token_Proxy* must be deleted by the user. + */ + int extract (const ACE_TCHAR *token_name, ACE_Token_Proxy *&proxy); + + /// returns the proxy if true. 0 otherwise. + ACE_Token_Proxy *is_member (const ACE_TCHAR *token_name); + + /** + * Is the specified token in the collection? + * 1, yes. + * 0, no. + */ + int is_member (const ACE_Token_Proxy &token); + +// = Collective operation semantics. + +// For acquire, renew, and release, there are two interfaces. Once +// interface allows an operation on a single token in the +// collection. The collective interfaces perform atomic operations +// on the entire collection. For instance, a collective acquire +// will perform an acquire for each and every token in the +// collection or the operation will fail. Currently, these +// operations are performed with no ordering heuristics. That is, +// the Collection steps through the tokens in the order they were +// inserted. For each one it performs the operation (acquire, +// renew, or release). + + /** + * Acquire "atomically" all resources in the collection. This is + * only successfull if all tokens in the collection could be + * acquired. options contains the blocking semantics, timeout + * value, etc. Returns: 0 on success, -1 on failure with <errno> == + * problem. If and error or deadlock occurs for one of the tokens, + * all the tokens will be released and the method will return -1. + * Note that returning on detection of deadlock prevents livelock + * between competing collections. If a collection returns after + * detecting deadlock, it is the application's responsibility to not + * to blindly loop on the collection::acquire operation. In other + * words, once the collection reports deadlock, it is out of our + * hands. + */ + virtual int acquire (int notify = 0, + void (*sleep_hook)(void *) = 0, + ACE_Synch_Options &options = + ACE_Synch_Options::defaults); + + /// Acquire the token corresponding to @a token_name. The other + /// parameters are passed to <token>::acquire. + virtual int acquire (const ACE_TCHAR *token_name, + int notify = 0, + void (*sleep_hook)(void *) = 0, + ACE_Synch_Options &options = + ACE_Synch_Options::defaults); + + /// Try to acquire all tokens in collection. + virtual int tryacquire (void (*sleep_hook)(void *) = 0); + + /// Try to acquire @a token_name. + virtual int tryacquire (const ACE_TCHAR *token_name, + void (*sleep_hook)(void *) = 0); + + /** + * Renews "atomically" all resources in the collection. This is + * only successfull if all tokens in the collection could be + * renewed. options contains the blocking semantics, timeout + * value, etc. Returns: 0 on success, -1 on failure with <errno> == + * problem. + */ + virtual int renew (int requeue_position = 0, + ACE_Synch_Options &options = + ACE_Synch_Options::defaults); + + + /// Renew the token corresponding to @a token_name. The other + /// parameters are passed to <token>::renew. + virtual int renew (const ACE_TCHAR *token_name, + int requeue_position = 0, + ACE_Synch_Options &options = + ACE_Synch_Options::defaults); + + /** + * Releases "atomically" all resources in the collection. This is + * only successfull if all tokens in the collection could be + * released. options contains the blocking semantics, timeout + * value, etc. Returns: 0 on success, -1 on failure with <errno> == + * problem. + */ + virtual int release (ACE_Synch_Options &options = + ACE_Synch_Options::defaults); + + + /// Release the token corresponding to <token_name>. The other + /// parameters are passed to <token>::release. + virtual int release (const ACE_TCHAR *token_name, + ACE_Synch_Options &options = + ACE_Synch_Options::defaults); + + ~ACE_Token_Collection (void); + + /// Dump the state of the class. + void dump (void) const; + + /// Return the name of the collection. Not very functionally + /// important, but sometimes a useful debugging tool. + virtual const ACE_TCHAR *name (void) const; + +protected: + + typedef ACE_Token_Name TOKEN_NAME; + + /// COLLECTION maintains a mapping from token names to ACE_Tokens* + typedef ACE_Map_Manager<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex> + COLLECTION; + + /// Allows iterations through collection_ + /** + * @deprecated Deprecated typedef. Use COLLECTION::ITERATOR trait instead. + */ + typedef COLLECTION::ITERATOR COLLECTION_ITERATOR; + + /// Allows iterations through collection_ + /** + * @deprecated Deprecated typedef. Use COLLECTION::ENTRY trait instead. + */ + typedef COLLECTION::ENTRY COLLECTION_ENTRY; + + /// COLLECTION maintains a mapping from token names to ACE_Tokens*. + COLLECTION collection_; + + /// Whether to print out debug messages or not. + int debug_; + + /// Name of the collection. + ACE_TCHAR name_[ACE_MAXTOKENNAMELEN]; + + // = I'm not sure what these mean, but they have to be defined since they're + // pure virtual in ACE_Token_Proxy. + virtual ACE_Token_Proxy *clone (void) const; + virtual ACE_Tokens *create_token (const ACE_TCHAR *name); +}; + +ACE_END_VERSIONED_NAMESPACE_DECL + +#if defined (__ACE_INLINE__) +#include "ace/Token_Collection.inl" +#endif /* __ACE_INLINE__ */ + +#endif /* ACE_HAS_TOKENS_LIBRARY */ + +#include /**/ "ace/post.h" +#endif /* ACE_TOKEN_COLLECTION_H */ |