Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Related Pages

# ACE_Mutex_Token Class Reference

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

`#include <Local_Tokens.h>`

Inheritance diagram for ACE_Mutex_Token:

[legend]
Collaboration diagram for ACE_Mutex_Token:

[legend]
List of all members.

## Public Methods
ACE_EXPLICIT | ACE_Mutex_Token (const ACE_TCHAR *name)
| Constructor. More...
virtual | ~ACE_Mutex_Token (void)
| Destructor. More...
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. More...
virtual int | tryacquire (ACE_TPQ_Entry *caller)
| Same as acquire, but fails if would block. More...
virtual int | renew (ACE_TPQ_Entry *caller, int requeue_position)
| An optimized method that efficiently reacquires the token if no other threads are waiting. More...
virtual int | release (ACE_TPQ_Entry *caller)
| Relinquish the token. More...
void | dump (void) const
| Dump the state of the class. More...
virtual int | type (void) const
| Returns ACE_Tokens::MUTEX. More...
virtual int | owners (OWNER_STACK &o, const ACE_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. More...
virtual int | is_waiting_for (const ACE_TCHAR *id)
| Returns 1 if <id> is waiting for this token. 0 otherwise. More...
virtual int | is_owner (const ACE_TCHAR *id)
| Returns 1 if <id> is an owner of this token. 0 otherwise. More...
## Private Attributes
ACE_TOKEN_CONST::MUTEX | lock_
| ACE_Mutex_Token used to lock internal data structures. More...

## Detailed Description

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

Not a public interface. This class is a more general-purpose synchronization mechanism than SunOS 5.x mutexes. For example, it implements "recursive mutex" semantics, where a thread that owns the token can reacquire it without deadlocking. In addition, threads that are blocked awaiting the token are serviced in strict FIFO order as other threads release the token (SunOS 5.x mutexes don't strictly enforce an acquisition order).

## Constructor & Destructor Documentation

ACE_Mutex_Token::ACE_Mutex_Token | ( | const ACE_TCHAR * | name | ) |

| Constructor.

ACE_Mutex_Token::~ACE_Mutex_Token | ( | void |  | ) | `[virtual]`

| Destructor.

## Member Function Documentation

int ACE_Mutex_Token::acquire | ( | ACE_TPQ_Entry * | caller,
|  | int | ignore_deadlock,
|  | int | notify
| ) | `[virtual]`

| 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. Reimplemented from ACE_Tokens.

void ACE_Mutex_Token::dump | ( | void |  | ) | const

| Dump the state of the class. Reimplemented from ACE_Tokens.

int ACE_Mutex_Token::is_owner | ( | const ACE_TCHAR * | id | ) | `[virtual]`

| Returns 1 if <id> is an owner of this token. 0 otherwise. Reimplemented from ACE_Tokens.

int ACE_Mutex_Token::is_waiting_for | ( | const ACE_TCHAR * | id | ) | `[virtual]`

| Returns 1 if <id> is waiting for this token. 0 otherwise. Reimplemented from ACE_Tokens.

int ACE_Mutex_Token::owners | ( | OWNER_STACK & | stack,
|  | const ACE_TCHAR * | id
| ) | `[virtual]`

| 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. Reimplemented from ACE_Tokens.

int ACE_Mutex_Token::release | ( | ACE_TPQ_Entry * | caller | ) | `[virtual]`

| 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. Reimplemented from ACE_Tokens.

int ACE_Mutex_Token::renew | ( | ACE_TPQ_Entry * | caller,
|  | int | requeue_position
| ) | `[virtual]`

| 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. Reimplemented from ACE_Tokens.

int ACE_Mutex_Token::tryacquire | ( | ACE_TPQ_Entry * | caller | ) | `[virtual]`

| Same as acquire, but fails if would block. Reimplemented from ACE_Tokens.

virtual int ACE_Mutex_Token::type | ( | void |  | ) | const`[virtual]`

| Returns ACE_Tokens::MUTEX. Reimplemented from ACE_Tokens.

## Member Data Documentation

ACE_TOKEN_CONST::MUTEX ACE_Mutex_Token::lock_`[private]`

| ACE_Mutex_Token used to lock internal data structures.

The documentation for this class was generated from the following files:

- Local_Tokens.h
- Local_Tokens.cpp