NAME
ACE_Token_Proxy - Abstract representation of ACE tokens.
SYNOPSIS
#include <ace/Local_Tokens.h>
class ACE_Token_Proxy
{
public:
friend class ACE_Token_Manager;
friend class ACE_Token_Invariant_Manager; // For testing.;
ACE_Token_Proxy (void);
virtual ~ACE_Token_Proxy (void);
virtual int open (
const ASYS_TCHAR *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 int acquire_read (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
virtual int acquire_write (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
virtual int tryacquire_read (void (*sleep_hook)(void *) = 0);
virtual int tryacquire_write (void (*sleep_hook)(void *) = 0);
virtual const ASYS_TCHAR *client_id (void) const;
virtual void client_id (const ASYS_TCHAR *client_id);
virtual const ASYS_TCHAR *name (void) const;
virtual void sleep_hook (void);
virtual void token_acquired (ACE_TPQ_Entry *);
virtual const ASYS_TCHAR *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 ASYS_TCHAR *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
Note that the locking classes defined in this file are *not*
intended to be used as general-purpose synchronization
mechanisms, such as mutexes or semaphores. Instead, you should
use the ACE_Recursive_Thread_Mutex, ACE_Thread_Mutex,
ACE_Thread_Semaphore, etc., that are defined in
$ACE_ROOT/ace/Synch.h and $ACE_ROOT/ace/Synch_T.h or the
ACE_Token that's defined in $ACE_ROOT/ace/Token.h.
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.
virtual int acquire_read (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
Since the locking mechanism doesn't support read locks then this just calls acquire.
virtual int acquire_write (int notify = 0, void (*sleep_hook)(
void *) = 0,
ACE_Synch_Options &options = ACE_Synch_Options::defaults
);
Since the locking mechanism doesn't support write locks then this just calls acquire.
virtual int tryacquire_read (void (*sleep_hook)(void *) = 0);
Since the locking mechanism doesn't support read locks then this just calls tryacquire.
virtual int tryacquire_write (void (*sleep_hook)(void *) = 0);
Since the locking mechanism doesn't support write locks then this just calls tryacquire.
Utility methods.
virtual const ASYS_TCHAR *client_id (void) const;
Get the client id of the proxy. This is implemented as thread-specific data.
virtual void client_id (const ASYS_TCHAR *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 ASYS_TCHAR *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 ASYS_TCHAR *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 [email protected], Douglas C. Schmidt [email protected], and Tim Harrison [email protected]
LIBRARY
ace