NAME
ACE_Token_Collection -
Allows atomic token group operations AND
provides a ACE_Token manager interface.
SYNOPSIS
#include <ACE/ACE_Token_Collection.h>
class ACE_Token_Collection : public ACE_Token_Proxy
{
public:
ACE_Token_Collection (int debug = 0, const char *name = 0);
int insert (ACE_Token_Proxy &token);
int extract (const char *token_name, ACE_Token_Proxy *&proxy);
ACE_Token_Proxy *is_member (const char *token_name);
int is_member (const ACE_Token_Proxy &token);
virtual int acquire (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
virtual int acquire (const char *token_name, int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
virtual int tryacquire (void (*sleep_hook)(void *) = 0);
virtual int tryacquire (const char *token_name, void (*sleep_hook)(
void *) = 0
);
virtual int renew (
int requeue_position = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
virtual int renew (
const char *token_name,
int requeue_position = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
ACE_Synch_Options::defaults);
virtual int release (
const char *token_name,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
~ACE_Token_Collection (void);
void dump (void) const;
virtual const char *name (void) const;
protected:
typedef ACE_Token_Name TOKEN_NAME;
typedef ACE_Map_Manager<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex> COLLECTION;
typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Token_Proxy *, ACE_Null_Mutex> COLLECTION_ITERATOR;
typedef ACE_Map_Entry<TOKEN_NAME, ACE_Token_Proxy *> COLLECTION_ENTRY;
COLLECTION collection_;
int debug_;
char name_[ACE_MAXTOKENNAMELEN];
virtual ACE_Token_Proxy *clone (void) const;
virtual ACE_Tokens *create_token (const char *name);
};
DESCRIPTION
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.
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).
virtual int acquire (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
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 (const char *token_name, int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
Acquire the token corresponding to token_name. The other
parameters are passed to token::acquire.
virtual int tryacquire (void (*sleep_hook)(void *) = 0);
Try to acquire all tokens in collection.
virtual int tryacquire (const char *token_name, void (*sleep_hook)(
void *) = 0
);
Try to acquire token_name.
virtual int renew (
int requeue_position = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
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 (
const char *token_name,
int requeue_position = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
Renew the token corresponding to token_name. The other
parameters are passed to token::renew.
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 (
const char *token_name,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
Release the token corresponding to token_name. The other
parameters are passed to token::release.
~ACE_Token_Collection (void);
void dump (void) const;
Dump the state of the class.
virtual const char *name (void) const;
Return the name of the collection. Not very functionally
important, but sometimes a useful debugging tool.
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 char *name);
AUTHOR
Douglas C. Schmidt (schmidt@cs.wustl.edu) and
Tim Harrison (harrison@cs.wustl.edu)
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.
LIBRARY
ACE