ACE_RW_Token Class Reference

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

#include <Local_Tokens.h>

Inheritance diagram for ACE_RW_Token:

[legend]Collaboration diagram for ACE_RW_Token:

[legend]List of all members.

Public Types
enum	PROXY_TYPE { READER, WRITER }
	These are the types that proxies can be. More...
Public Member Functions
	ACE_RW_Token (const ACE_TCHAR *name)
	Constructor.
virtual	~ACE_RW_Token (void)
	Destructor.
virtual int	acquire (ACE_TPQ_Entry *caller, int ignore_deadlock, int notify)
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)
virtual int	release (ACE_TPQ_Entry *caller)
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 ACE_TCHAR *id)
virtual int	is_waiting_for (const ACE_TCHAR *id)
	Returns 1 if is waiting for this token. 0 otherwise.
virtual int	is_owner (const ACE_TCHAR *id)
	Returns 1 if is an owner of this token. 0 otherwise.
Protected Member Functions
void	notify_new_owner (ACE_TPQ_Entry *caller)
	Sets the new owner.
Protected Attributes
int	num_writers_
	The number of waiting writers.
ACE_TOKEN_CONST::MUTEX	lock_
	ACE_Mutex_Token used to lock internal data structures.

---

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

Definition at line 593 of file Local_Tokens.h.

---

Member Enumeration Documentation

enum ACE_RW_Token::PROXY_TYPE

These are the types that proxies can be. Enumeration values: READER  WRITER  Definition at line 655 of file Local_Tokens.h. { READER, WRITER };

---

Constructor & Destructor Documentation

ACE_RW_Token::ACE_RW_Token (  const ACE_TCHAR *  name  )  [explicit]

Constructor. Definition at line 722 of file Local_Tokens.cpp. References ACE_MAXTOKENNAMELEN, ACE_TCHAR, ACE_TRACE, and ACE_OS::strsncpy(). : num_writers_ (0) { ACE_TRACE ("ACE_RW_Token::ACE_RW_Token"); ACE_OS::strsncpy (this->token_name_, name, ACE_MAXTOKENNAMELEN); }

ACE_RW_Token::~ACE_RW_Token (  void   )  [virtual]

Destructor. Definition at line 732 of file Local_Tokens.cpp. References ACE_TRACE. { ACE_TRACE ("ACE_RW_Token::~ACE_RW_Token"); }

---

Member Function Documentation

int ACE_RW_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. Implements ACE_Tokens. Definition at line 738 of file Local_Tokens.cpp. References ACE_GUARD_RETURN, ACE_RETURN, ACE_TRACE, ACE_TPQ_Entry::call_sleep_hook(), ACE_Token_Manager::check_deadlock(), ACE_TPQ_Entry::client_id(), EDEADLK, ACE_Token_Proxy_Queue::enqueue(), EWOULDBLOCK, ACE_Token_Manager::instance(), is_owner(), ACE_TOKEN_CONST::MUTEX, ACE_TPQ_Entry::nesting_level(), ACE_TPQ_Entry::next_, num_writers_, ACE_Tokens::owner(), ACE_TPQ_Entry::proxy(), READER, ACE_Token_Proxy::type(), and WRITER. { ACE_TRACE ("ACE_RW_Token::acquire"); // We need to acquire two locks. This one to ensure that only one // thread uses this token at a time. ACE_GUARD_RETURN (ACE_TOKEN_CONST::MUTEX, ace_mon1, this->lock_, -1); // This one to ensure an atomic transaction across all tokens. Note // that this order is crucial too. It's resource coloring for other // threads which may be calling this same token. ACE_GUARD_RETURN (ACE_TOKEN_CONST::MUTEX, ace_mon2, ACE_Token_Manager::instance ()->mutex (), -1); if (caller->proxy ()->type () == ACE_RW_Token::WRITER) this->num_writers_++; // Does _anyone_ own the token? if (this->owner () == 0) { // There are no waiters, so queue as the first waiter (the owner). this->waiters_.enqueue (caller, -1); return 0; } // Check for recursive acquisition. if (this->is_owner (caller->client_id ())) { caller->nesting_level (1); return 0; // Success. } // Reader. if (caller->proxy ()->type () == ACE_RW_Token::READER) { // Are there any writers? if (this->num_writers_ == 0) { // Queue the caller at the end of the queue. this->waiters_.enqueue (caller, -1); return 0; } // Else failure. } // Failure code. // Check for deadlock. if (!ignore_deadlock && ACE_Token_Manager::instance ()->check_deadlock (caller->proxy ()) == 1) { if (caller->proxy ()->type () == ACE_RW_Token::WRITER) this->num_writers_--; errno = EDEADLK; ACE_RETURN (-1); } // Queue the caller at the end of the queue. this->waiters_.enqueue (caller, -1); if (notify) { // If it's a writer, just notify it. if (this->owner ()->proxy ()->type () == ACE_RW_Token::WRITER) this->owner ()->call_sleep_hook (); else { // Call back all reader owners. ACE_TPQ_Entry *temp = this->owner (); do { temp->call_sleep_hook (); temp = temp->next_; } while (temp != 0 && temp->proxy ()->type () == ACE_RW_Token::READER); } } errno = EWOULDBLOCK; ACE_RETURN (-1); ACE_NOTREACHED (return -1); }

void ACE_RW_Token::dump (  void   )  const

Dump the state of the class. Reimplemented from ACE_Tokens. Definition at line 706 of file Local_Tokens.cpp. References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, ACE_TRACE, ACE_Tokens::dump(), ACE_Null_Mutex::dump(), LM_DEBUG, and num_writers_. { #if defined (ACE_HAS_DUMP) ACE_TRACE ("ACE_RW_Token::dump"); ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this)); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("ACE_RW_Token::dump:\n") ACE_LIB_TEXT ("num_writers_ = %d\n"), num_writers_)); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("lock_\n"))); this->lock_.dump (); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("base:\n"))); ACE_Tokens::dump (); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("ACE_RW_Token::dump end.\n"))); ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP)); #endif /* ACE_HAS_DUMP */ }

int ACE_RW_Token::is_owner (  const ACE_TCHAR *  id  )  [virtual]

Returns 1 if is an owner of this token. 0 otherwise. Implements ACE_Tokens. Definition at line 1059 of file Local_Tokens.cpp. References ACE_TCHAR, ACE_TRACE, ACE_TPQ_Iterator::advance(), ACE_TPQ_Entry::equal_client_id(), ACE_TPQ_Iterator::next(), ACE_Tokens::owner(), ACE_TPQ_Entry::proxy(), READER, ACE_Token_Proxy::type(), and WRITER. Referenced by acquire(), is_waiting_for(), release(), renew(), and tryacquire(). { ACE_TRACE ("ACE_RW_Token::is_owner"); // If there is no owner, return false. if (this->owner () == 0) return 0; // A writer owns us. if (this->owner ()->proxy ()->type () == ACE_RW_Token::WRITER) return this->owner ()->equal_client_id (id); // Readers own us. // Step through each owning reader looking for <id>. ACE_TPQ_Iterator iterator (waiters_); for (ACE_TPQ_Entry *temp = 0; iterator.next (temp) != 0; iterator.advance ()) { if (temp->proxy ()->type () != ACE_RW_Token::READER) break; if (temp->equal_client_id (id)) return 1; } return 0; }

int ACE_RW_Token::is_waiting_for (  const ACE_TCHAR *  id  )  [virtual]

Returns 1 if is waiting for this token. 0 otherwise. Implements ACE_Tokens. Definition at line 1036 of file Local_Tokens.cpp. References ACE_TCHAR, ACE_TRACE, ACE_TPQ_Iterator::advance(), ACE_TPQ_Entry::equal_client_id(), is_owner(), ACE_TPQ_Iterator::next(), and ACE_Tokens::owner(). { ACE_TRACE ("ACE_RW_Token::is_waiting_for"); // If there is no owner, or <id> is the owner, return false. if ((this->owner () == 0) || this->is_owner (id)) return 0; // Step through each waiter looking for <id>. ACE_TPQ_Iterator iterator (waiters_); iterator.advance (); for (ACE_TPQ_Entry *temp = 0; iterator.next (temp) != 0; iterator.advance ()) { if (temp->equal_client_id (id)) return 1; } return 0; }

void ACE_RW_Token::notify_new_owner (  ACE_TPQ_Entry *  caller  )  [protected]

Sets the new owner. Definition at line 957 of file Local_Tokens.cpp. References ACE_TRACE, ACE_TPQ_Iterator::advance(), ACE_TPQ_Iterator::next(), ACE_Tokens::owner(), ACE_TPQ_Entry::proxy(), READER, ACE_Token_Proxy::token_acquired(), ACE_Token_Proxy::type(), and WRITER. Referenced by release(), and renew(). { ACE_TRACE ("ACE_RW_Token::notify_new_owner"); if (this->owner () == 0) return; if (this->owner ()->proxy ()->type () == ACE_RW_Token::READER) { if (old_owner->proxy ()->type () == ACE_RW_Token::READER) // the owners already know that they're owners return; // The current owner is a reader and the previous owner was a // writer, so notify all waiting readers up to the first writer. // call back all reader owners. ACE_TPQ_Iterator iterator (waiters_); for (ACE_TPQ_Entry *temp = 0; iterator.next (temp) != 0; iterator.advance ()) { if (temp->proxy ()->type () == WRITER) // We've gone through all the readers. break; temp->proxy ()->token_acquired (temp); } } else // writer this->owner ()->proxy ()->token_acquired (this->owner ()); }

int ACE_RW_Token::owners (  OWNER_STACK &  o, const ACE_TCHAR *  id )  [virtual]

Returns a stack of the current owners. Returns -1 on error, 0 on success. If is non-zero, returns 1 if id is an owner. Implements ACE_Tokens. Definition at line 991 of file Local_Tokens.cpp. References ACE_TCHAR, ACE_TRACE, ACE_TPQ_Iterator::advance(), ACE_TPQ_Entry::client_id(), ACE_TPQ_Iterator::next(), ACE_Tokens::owner(), ACE_TPQ_Entry::proxy(), ACE_OS::strcmp(), ACE_Token_Proxy::type(), and WRITER. { ACE_TRACE ("ACE_RW_Token::owners"); if (this->owner () == 0) return 0; int id_is_owner = 0; // The first waiter is a writer, so there is only one owner. if (this->owner ()->proxy ()->type () == WRITER) { stack.push (this->owner ()); // If an <id> is specified, return whether it is the owner being // returned. if ((id != 0) && (ACE_OS::strcmp (id, this->owner ()->client_id ()) == 0)) id_is_owner = 1; } // The first waiter is a reader, so there can be multiple owning // readers. else { ACE_TPQ_Iterator iterator (waiters_); for (ACE_TPQ_Entry *temp = 0; iterator.next (temp) != 0; iterator.advance ()) { if (temp->proxy ()->type () == WRITER) // We've gone through all the readers. break; stack.push (temp); if (!id_is_owner && (id != 0) && (ACE_OS::strcmp (id, temp->client_id ()) == 0)) id_is_owner = 1; } } return id_is_owner; }

int ACE_RW_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. Implements ACE_Tokens. Definition at line 926 of file Local_Tokens.cpp. References ACE_GUARD_RETURN, ACE_RETURN, ACE_TRACE, ACE_TPQ_Entry::client_id(), is_owner(), ACE_TOKEN_CONST::MUTEX, ACE_TPQ_Entry::nesting_level(), notify_new_owner(), num_writers_, ACE_Tokens::owner(), ACE_TPQ_Entry::proxy(), ACE_Tokens::remove(), ACE_Token_Proxy::type(), and WRITER. { ACE_TRACE ("ACE_RW_Token::release"); ACE_GUARD_RETURN (ACE_TOKEN_CONST::MUTEX, ace_mon, this->lock_, -1); // Check for errors. if ((this->owner () == 0) || (this->is_owner (caller->client_id ()) == 0)) { errno = EACCES; ACE_RETURN (-1); } if (caller->proxy ()->type () == ACE_RW_Token::WRITER) num_writers_--; // Recursive release. if (caller->nesting_level () > 0) { caller->nesting_level (-1); return 0; } // Remove the caller and notify the new owner(s). this->remove (caller); this->notify_new_owner (caller); return 0; }

int ACE_RW_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 == -1 and there are other threads waiting to obtain the token we are queued at the end of the list of waiters. If > -1 then it indicates how many entries to skip over before inserting our thread into the list of waiters (e.g., == 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. Implements ACE_Tokens. Definition at line 880 of file Local_Tokens.cpp. References ACE_GUARD_RETURN, ACE_RETURN, ACE_TRACE, ACE_TPQ_Entry::client_id(), ACE_Token_Proxy_Queue::enqueue(), EWOULDBLOCK, is_owner(), ACE_TOKEN_CONST::MUTEX, notify_new_owner(), ACE_TPQ_Entry::proxy(), READER, ACE_Tokens::remove(), ACE_Token_Proxy_Queue::size(), and ACE_Token_Proxy::type(). { ACE_TRACE ("ACE_RW_Token::renew"); ACE_GUARD_RETURN (ACE_TOKEN_CONST::MUTEX, ace_mon, this->lock_, -1); // Werify that the caller is the owner if (this->is_owner (caller->client_id ()) == 0) { errno = EACCES; ACE_RETURN (-1); } // The caller is the owner, so check to see if there are any // waiters. If not, we just keep the token. if (this->waiters_.size () == 1 || requeue_position == 0) return 0; // There are waiters, so remove the caller. this->remove (caller); // Requeue the caller. this->waiters_.enqueue (caller, requeue_position); if (caller->proxy ()->type () == ACE_RW_Token::READER) { // If the caller got queued before any writers, the caller is // still the owner. if (this->is_owner (caller->client_id ())) return 0; // success // else fallthrough and return would block. } // Writers will always have to block since waiters_.size () == 1 or // requeue_position == 0. // Get a new owner. this->notify_new_owner (caller); // Tell the caller that the operation would block. errno = EWOULDBLOCK; ACE_RETURN (-1); ACE_NOTREACHED (return -1); }

int ACE_RW_Token::tryacquire (  ACE_TPQ_Entry *  caller  )  [virtual]

Same as acquire except fails on would block. Implements ACE_Tokens. Definition at line 823 of file Local_Tokens.cpp. References ACE_GUARD_RETURN, ACE_RETURN, ACE_TRACE, ACE_TPQ_Entry::client_id(), ACE_Token_Proxy_Queue::enqueue(), EWOULDBLOCK, is_owner(), ACE_TOKEN_CONST::MUTEX, ACE_TPQ_Entry::nesting_level(), num_writers_, ACE_Tokens::owner(), ACE_TPQ_Entry::proxy(), READER, ACE_Token_Proxy::type(), and WRITER. { ACE_TRACE ("ACE_RW_Token::tryacquire"); // We need to acquire two locks. This one to ensure that only one // thread uses this token at a time. ACE_GUARD_RETURN (ACE_TOKEN_CONST::MUTEX, ace_mon1, this->lock_, -1); // This one to ensure an atomic transaction across all tokens. Note // that this order is crucial too. It's resource coloring for other // threads which may be calling this same token. ACE_GUARD_RETURN (ACE_TOKEN_CONST::MUTEX, ace_mon2, ACE_Token_Manager::instance ()->mutex (), -1); if (caller->proxy ()->type () == ACE_RW_Token::WRITER) { this->num_writers_++; } // Does _anyone_ own the token? if (this->owner () == 0) { // There are no waiters, so queue as the first waiter (the owner). this->waiters_.enqueue (caller, -1); return 0; } // Check for recursive acquisition. if (this->is_owner (caller->client_id ())) { caller->nesting_level (1); return 0; // Success. } // Reader. if (caller->proxy ()->type () == ACE_RW_Token::READER) { // Are there any writers? if (this->num_writers_ == 0) { // queue the caller at the end of the queue. this->waiters_.enqueue (caller, -1); return 0; } // Else, fail. } else // Writer. // We're going to fail, so decrement the num_writers. { this->num_writers_--; } errno = EWOULDBLOCK; ACE_RETURN (-1); ACE_NOTREACHED (return -1); }

int ACE_RW_Token::type (  void   )  const [virtual]

Returns READER or WRITER. Implements ACE_Tokens. Definition at line 699 of file Local_Tokens.cpp. References ACE_TRACE. { ACE_TRACE ("ACE_RW_Token::type"); return (int) ACE_Tokens::RWLOCK; }

---

Member Data Documentation

ACE_TOKEN_CONST::MUTEX ACE_RW_Token::lock_ [protected]

ACE_Mutex_Token used to lock internal data structures. Definition at line 675 of file Local_Tokens.h.

int ACE_RW_Token::num_writers_ [protected]

The number of waiting writers. Definition at line 672 of file Local_Tokens.h. Referenced by acquire(), dump(), release(), and tryacquire().

---

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

• Local_Tokens.h
• Local_Tokens.cpp

---