NAME
ACE_Token_Proxy -
Abstract representation of ACE tokens.
SYNOPSIS
#include <ace/Local_Tokens>
class ACE_Token_Proxy
{
public:
friend class ACE_Token_Manager;
friend class ACE_Token_Invariant_Manager; // For testing.;
ACE_Token_Proxy (void);
~ACE_Token_Proxy (void);
virtual int open (
const char *name,
int ignore_deadlock = 0,
int debug = 0
);
virtual int acquire (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
virtual int renew (
int requeue_position = -1,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
virtual int tryacquire (void (*sleep_hook)(void *) = 0);
ACE_Synch_Options::defaults);
ACE_Synch_Options::defaults);
virtual const char *client_id (void) const;
virtual void client_id (const char *client_id);
virtual const char *name (void) const;
virtual void sleep_hook (void);
virtual void token_acquired (ACE_TPQ_Entry *);
virtual const char *owner_id (void);
virtual ACE_Token_Proxy *clone (void) const = 0;
void dump (void) const;
virtual int type (void) const;
protected:
ACE_Token_Proxy (const ACE_Token_Proxy &);
int ignore_deadlock_;
int debug_;
ACE_Tokens *token_;
int handle_options (
ACE_Synch_Options &options,
ACE_TOKEN_CONST::COND_VAR &cv
);
ACE_TSS_TPQ_Entry waiter_;
virtual ACE_Tokens *create_token (const char *name) = 0;
};
DESCRIPTION
This file contains definitions for the following classes:
public:
7. ACE_Token_Proxy
8. ACE_Null_Token : public ACE_Token_Proxy
9. ACE_Local_Mutex : public ACE_Token_Proxy
*. ACE_Local_RLock : public ACE_Local_Mutex
&. ACE_Local_WLock : public ACE_Local_Mutex
private:
1. ACE_TOKEN_CONST
3. ACE_TPQ_Entry
b. ACE_TSS_TPQ_Entry
c. ACE_TPQ_Iterator
4. ACE_Token_Proxy_Queue
5. ACE_Tokens
6. ACE_Mutex_Token : public ACE_Tokens
12. ACE_RW_Token : public ACE_Tokens
a. ACE_Token_Name
The following methods have implementations which are
independent of the token semantics (mutex, rwlock, etc.) They
forward operations to the underlying token and perform the
necessary blocking semantics for operations (condition variables
etc.) This allows reuse of the blocking code as well as having
multiple proxies to the same token.
virtual int acquire (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
Calls acquire on the token. Blocks the calling thread if would
block.
virtual int renew (
int requeue_position = -1,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
Calls renew on the token. Blocks the calling thread if would
block.
virtual int tryacquire (void (*sleep_hook)(void *) = 0);
Calls renew on the token.
ACE_Synch_Options::defaults);
Calls release on the token.
ACE_Synch_Options::defaults);
Calls remove on the token.
Utility methods.
virtual const char *client_id (void) const;
Get the client id of the proxy. This is implemented as
thread-specific data.
virtual void client_id (const char *client_id);
Set the client_id for the calling thread. I strongly recommend
that this not be used unless you really know what you're doing.
I use this in the Token Server, and it caused many headaches.
virtual const char *name (void) const;
Return the name of the token. This is important for use within
the token servers (local and remote) as well as with token
collections. So, all derivations of ACE_Token_Proxy must be able to
stringify some name. The name must uniquely identify a token.
So, for instance, the token within the reactor should probably be
called "Reactor Token."
virtual void sleep_hook (void);
This should really be called someone_waiting ().
This is called by ACE_Token_xx's when another proxy enters the
waiting list and requests that the current token holder be notified.
virtual void token_acquired (ACE_TPQ_Entry *);
This is called when a queued (waiting) proxy is removed from the
waiters list and given the token.
virtual const char *owner_id (void);
the client id of the current token holder
virtual ACE_Token_Proxy *clone (void) const = 0;
Return a dynamically allocated clone of the derived class.
void dump (void) const;
Dump the state of the class.
virtual int type (void) const;
This method can be used be Tokens (e.g. Readers/Writer Tokens) to
distinguish between Proxy types. For instance a Reader proxy
should return a different type value than a Writer proxy. The
default implementation returns 0.
AUTHOR
Karl-Heinz Dorn (kdorn@erlh.siemens.de)
Douglas C. Schmidt (schmidt@cs.wustl.edu)
Tim Harrison (harrison@cs.wustl.edu)
EXTENDING TOKENS
To add a new type of token (e.g. semaphore), this class is not
changed. See ACE_Token_Manager for details.
RESTRICTIONS
Tokens (e.g. ACE_Mutex_Token) assume that it can always call
ACE_Token_Proxy::token_acquired () on a new token owner. This
is not a problem for synchronous use of token proxies (that is,
when acquires block until successful.) However, for
implementations of the Token Server, which may use asynch
operations, the proxy can not go away after an acquire until
the token is acquired. This is not really a problem, but
should be understood.
LIBRARY
ace