NAME
ACE_Mutex_Token -
Not a public interface.
SYNOPSIS
#include <ace/Local_Tokens>
class ACE_Mutex_Token : public ACE_Tokens
{
public:
ACE_Mutex_Token (const char* name);
~ACE_Mutex_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;
virtual int type (void) const;
virtual int owners (OWNER_STACK &o, const char *id);
virtual int is_waiting_for (const char *id);
virtual int is_owner (const char *id);
private:
ACE_TOKEN_CONST::MUTEX lock_;
};
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
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, but fails if 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 ACE_Tokens::MUTEX.
virtual int owners (OWNER_STACK &o, const char *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 char *id);
Returns 1 if id
is waiting for this token. 0 otherwise.
virtual int is_owner (const char *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)
Tim Harrison (harrison@cs.wustl.edu)
DESCRIPTION
Class that acquires, renews, and releases a process-local
synchronization token.
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).
LIBRARY
ace