ACE_Token_Collection(3)

NAME

ACE_Token_Collection - Allows atomic token group operations AND provides a ACE_Token manager interface.

SYNOPSIS

#include <ACE/Token_Collection.h>
class ACE_Token_Collection : public ACE_Token_Proxy
{
  public:
    ACE_Token_Collection (int debug = 0, const ASYS_TCHAR *name = 0);
    int insert (ACE_Token_Proxy &token);
    int extract (
        const ASYS_TCHAR *token_name,
        ACE_Token_Proxy *&proxy
        );
    ACE_Token_Proxy *is_member (const ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *token_name,
        int requeue_position = 0,
        ACE_Synch_Options &options = ACE_Synch_Options::defaults
        );
    ACE_Synch_Options::defaults);
    virtual int release (
        const ASYS_TCHAR *token_name,
        ACE_Synch_Options &options = ACE_Synch_Options::defaults
        );
    ~ACE_Token_Collection (void);
    void dump (void) const;
    virtual const ASYS_TCHAR *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_;
    ASYS_TCHAR name_[ACE_MAXTOKENNAMELEN];
    virtual ACE_Token_Proxy *clone (void) const;
    virtual ACE_Tokens *create_token (const ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *name);

AUTHOR

Douglas C. Schmidt ([email protected]) and Tim Harrison ([email protected])

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