---
name: "ACE_RW_Token"
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_RW_Token"
---

# ACE\_RW\_Token(3)

Class that acquires, renews, and releases a process-local synchronization token.

## NAME

ACE\_RW\_Token -  Class that acquires, renews, and releases a process-local synchronization token.

## SYNOPSIS

```
#include <ace/Local_Tokens.h>
class ACE_RW_Token : public ACE_Tokens
{
  public:
    ACE_RW_Token (const ASYS_TCHAR* name);
    virtual ~ACE_RW_Token (void);
    virtual int acquire (
        ACE_TPQ_Entry *caller,
        int ignore_deadlock,
        int notify
        );
    virtual int tryacquire (ACE_TPQ_Entry *caller);
    virtual int renew (ACE_TPQ_Entry *caller, int requeue_position);
    virtual int release (ACE_TPQ_Entry *caller);
    void dump (void) const;
    enum PROXY_TYPE { READER, WRITER };
    virtual int type (void) const;
    virtual int owners (OWNER_STACK &o, const ASYS_TCHAR *id);
    virtual int is_waiting_for (const ASYS_TCHAR *id);
    virtual int is_owner (const ASYS_TCHAR *id);
  protected:
    int num_writers_;
    ACE_TOKEN_CONST::MUTEX lock_;
    void notify_new_owner (ACE_TPQ_Entry *caller);
};
```

## 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.

## Synchronization operations.

With acquire, renew, and release, the caller must be specified so that multiple proxies (e.g. ACE\_Local\_Mutex) can use the same token.

```
virtual int acquire (
    ACE_TPQ_Entry *caller,
    int ignore_deadlock,
    int notify
    );
```

Returns 0 on success, -1 on failure with ACE\_Log\_Msg::errnum as the reason.  If errnum == EWOULDBLOCK, and notify == 1, ACE\_Token\_Proxy::sleep\_hook has been called on the current owner of the token.  If ignore\_deadlock is passed as 1 and errnum == EDEADLK, then deadlock was detected via ace\_token\_manager.

```
virtual int tryacquire (ACE_TPQ_Entry *caller);
```

same as acquire except fails on would block

```
virtual int renew (ACE_TPQ_Entry *caller, int requeue_position);
```

An optimized method that efficiently reacquires the token if no other threads are waiting.  This is useful for situations where you don't want to degrade the quality of service if there are other threads waiting to get the token.  If requeue\_position == -1 and there are other threads waiting to obtain the token we are queued at the end of the list of waiters.  If requeue\_position \> -1 then it indicates how many entries to skip over before inserting our thread into the list of waiters (e.g., requeue\_position == 0 means "insert at front of the queue"). Renew has the rather odd semantics such that if there are other waiting threads it will give up the token even if the nesting\_level\_  1.  I'm not sure if this is really the right thing to do (since it makes it possible for shared data to be changed unexpectedly) so use with caution...  Returns 0 on success, -1 on failure with ACE\_Log\_Msg::errnum as the reason. If errnum == EWOULDBLOCK, and notify == 1, ACE\_Token\_Proxy::sleep\_hook has been called on the current owner of the token.

```
virtual int release (ACE_TPQ_Entry *caller);
```

Relinquish the token.  If there are any waiters then the next one in line gets it.  If the caller is not the owner, caller is removed from the waiter list.

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

Dump the state of the class.

```
virtual int type (void) const;
```

Returns READER or WRITER.

```
virtual int owners (OWNER_STACK &o, const ASYS_TCHAR *id);
```

Returns a stack of the current owners.  Returns -1 on error, 0 on success.  If id is non-zero, returns 1 if id is an owner.

```
virtual int is_waiting_for (const ASYS_TCHAR *id);
```

Returns 1 if id is waiting for this token.  0 otherwise.

```
virtual int is_owner (const ASYS_TCHAR *id);
```

Returns 1 if id is an owner of this token.  0 otherwise.

## AUTHOR

Karl-Heinz Dorn kdorn@erlh.siemens.de, Douglas C. Schmidt schmidt@cs.wustl.edu, and Tim Harrison harrison@cs.wustl.edu

## LIBRARY

ace