---
name: "ACE_Remote_Token_Proxy"
section: "3"
platform: "linux"
package: "libace-doc"
version: "5.0.7-4"
release: "Debian 2.2 (Potato)"
platforms: ["linux"]
url: "https://new.carta.tech/ACE_Remote_Token_Proxy"
---

# ACE\_Remote\_Token\_Proxy(3)

Proxy for acquiring, renewing, and releasing a distributed synchronization token.

## NAME

ACE\_Remote\_Token\_Proxy -  Proxy for acquiring, renewing, and releasing a distributed synchronization token.

## SYNOPSIS

```
#include <ACE/Remote_Tokens.h>
class ACE_Remote_Token_Proxy : public ACE_Token_Proxy
{
  public:
    ACE_Remote_Token_Proxy (void);
    virtual ~ACE_Remote_Token_Proxy (void);
    int open (
        const ASYS_TCHAR *name,
        int ignore_deadlock = 0,
        int debug = 0
        );
    int initiate_connection (void);
    virtual int acquire (int notify = 0, void (*sleep_hook)(
        void *) = 0,
        ACE_Synch_Options &options = ACE_Synch_Options::synch
        );
    virtual int tryacquire (void (*sleep_hook)(void *) = 0);
    virtual int renew (
        int requeue_position = 0,
        ACE_Synch_Options &options = ACE_Synch_Options::synch
        );
    ACE_Synch_Options::synch);
    ACE_Synch_Options::synch);
    virtual void token_acquired (ACE_TPQ_Entry *);
    virtual const ASYS_TCHAR* owner_id (void);
    static void set_server_address (
        const ACE_INET_Addr &server_address
        );
    void dump (void) const;
  protected:
    int ignore_shadow_deadlock_;
    int request_reply (
        ACE_Token_Request &request,
        ACE_Synch_Options &options
        );
};
```

## DESCRIPTION

The Remote\_Token\_Proxy class implements the mechanisms for distributed token operations.  It is similar to the ACE\_Token\_Proxy.

## PUBLIC MEMBERS

```
ACE_Remote_Token_Proxy (void);
```

Null construction.

```
virtual ~ACE_Remote_Token_Proxy (void);
```

Death.

```
int open (
    const ASYS_TCHAR *name,
    int ignore_deadlock = 0,
    int debug = 0
    );
```

Same as Token\_Proxy. name is the string uniquely identifying the token.  ignore\_deadlock can be 1 to disable deadlock notifications.  debug prints debug messages.

```
int initiate_connection (void);
```

Open a connection with the token server.  This only need be used when the user wishes to explicitly open a connection to check if the server exists.  Connections are stored in the ACE\_Token\_Connections singleton as thread-specific data.  That is, every thread has only one connection that is used for all remote tokens.

```
virtual int acquire (int notify = 0, void (*sleep_hook)(
    void *) = 0,
    ACE_Synch_Options &options = ACE_Synch_Options::synch
    );
```

Acquire the distributed token.  If notify is specified and the token is already held, the owner is notified.  options contains the timeout value for the acquire call.  The timer is kept at the token server.  Asynchronous operations are not supported. Returns 0 on success, -1 on failure with errno == problem.

```
virtual int tryacquire (void (*sleep_hook)(void *) = 0);
```

Try to acquire the distributed token.  If the token is already held, the call returns without queueing the caller as a waiter. Returns 0 on success (the token was acquired), and -1 with EWOULDBLOCK if the token was already held.

```
virtual int renew (
    int requeue_position = 0,
    ACE_Synch_Options &options = ACE_Synch_Options::synch
    );
```

Renew the token by offering to release it if there are any other waiters, otherwise get the token back immediately.  This renew has the same semantics as ACE\_Local\_Mutex release.  It is semantically equivalent to release followed by acquire, but it is faster.  options contains the timeout value used if renew blocks.  As with acquire, the timer is maintained at the token server.  If there are waiters and requeue\_position == -1, the caller is queued at the rear of the waiter list.  Otherwise, requeue\_position specifies the number of waiters to "let by" before reacquiring the token (effectively, the position in the waiter list.)

```
ACE_Synch_Options::synch);
```

Release the distributed token. Similar to ACE\_Local\_Mutex, if the caller is not the owner, it is removed from the waiter list (if applicable.) Returns 0 on success, -1 on failure with errno == problem.

```
ACE_Synch_Options::synch);
```

Become interface compliant for ACE\_Guard.  This has no functionality.

```
virtual void token_acquired (ACE_TPQ_Entry *);
```

Override the default to do nothing.

```
virtual const ASYS_TCHAR* owner_id (void);
```

the client id of the current token holder

```
static void set_server_address (const ACE_INET_Addr &server_address);
```

sets the server address for all instances of ACE\_Remote\_Token\_Proxy If this isn't called, the environment variable TOKEN\_SERVER is checked for the server address.  If that is not specified, all ACE\_Remote\_\*\* operations will fail.

```
void dump (void) const;
```

Dump the state of the class.

## PROTECTED MEMBERS

```
int ignore_shadow_deadlock_;
```

if shadows report deadlock, go remote anyway

```
int request_reply (
    ACE_Token_Request &request,
    ACE_Synch_Options &options
    );
```

Perform the request and wait for the reply.

## AUTHOR

Douglas C. Schmidt (schmidt@cs.wustl.edu) and Tim Harrison (harrison@cs.wustl.edu)

## BUGS

Distributed sleep\_hooks have not been implemented.  owner\_id is not implemented.

## LIBRARY

ACE