Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

ACE_Token Class Reference

Class that acquires, renews, and releases a synchronization token that is serviced in strict FIFO/LIFO ordering and that also supports (1) recursion and (2) readers/writer semantics. More...

#include <Token.h>

Collaboration diagram for ACE_Token:

Collaboration graph
[legend]
List of all members.

Public Types

enum  QUEUEING_STRATEGY { FIFO = -1, LIFO = 0 }

Public Member Functions

 ACE_Token (const ACE_TCHAR *name=0, void *=0)
 Constructor.
virtual ~ACE_Token (void)
 Destructor.
int queueing_strategy (void)
 Retrieve the current queueing strategy.
void queueing_strategy (int queueing_strategy)
 Set the queueing strategy.
int acquire (void(*sleep_hook)(void *), void *arg=0, ACE_Time_Value *timeout=0)
int acquire (ACE_Time_Value *timeout=0)
virtual void sleep_hook (void)
int renew (int requeue_position=0, ACE_Time_Value *timeout=0)
int tryacquire (void)
int remove (void)
 Shuts down the ACE_Token instance.
int release (void)
int acquire_read (void)
int acquire_read (void(*sleep_hook)(void *), void *arg=0, ACE_Time_Value *timeout=0)
int acquire_write (void)
 Calls acquire().
int acquire_write (void(*sleep_hook)(void *), void *arg=0, ACE_Time_Value *timeout=0)
 Calls acquire().
int tryacquire_read (void)
 Lower priority try_acquire().
int tryacquire_write (void)
 Just calls <tryacquire>.
int tryacquire_write_upgrade (void)
 Assumes the caller has acquired the token and returns 0.
int waiters (void)
ACE_thread_t current_owner (void)
 Return the id of the current thread that owns the token.
void dump (void) const
 Dump the state of an object.

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks.

Private Types

enum  ACE_Token_Op_Type { READ_TOKEN = 1, WRITE_TOKEN }

Private Member Functions

int shared_acquire (void(*sleep_hook_func)(void *), void *arg, ACE_Time_Value *timeout, ACE_Token_Op_Type op_type)
 Implements the <acquire> and <tryacquire> methods above.
void wakeup_next_waiter (void)
 Wake next in line for ownership.

Private Attributes

ACE_Token_Queue writers_
 A queue of writer threads.
ACE_Token_Queue readers_
 A queue of reader threads.
ACE_Thread_Mutex lock_
 ACE_Thread_Mutex used to lock internal data structures.
ACE_thread_t owner_
 Current owner of the token.
int in_use_
int waiters_
 Number of waiters.
int nesting_level_
 Current nesting level.
ACE_Condition_Attributes attributes_
 The attributes for the condition variables, optimizes lock time.
int queueing_strategy_
 Queueing strategy, LIFO/FIFO.

Detailed Description

Class that acquires, renews, and releases a synchronization token that is serviced in strict FIFO/LIFO ordering and that also supports (1) recursion and (2) readers/writer semantics.

This class is a more general-purpose synchronization mechanism than many native OS mutexes. For example, it implements "recursive mutex" semantics, where a thread that owns the token can reacquire it without deadlocking. If the same thread calls <acquire> multiple times, however, it must call <release> an equal number of times before the token is actually released. Threads that are blocked awaiting the token are serviced in strict FIFO/LIFO order as other threads release the token (Solaris and Pthread mutexes don't strictly enforce an acquisition order). There are two lists within the class. Write acquires always have higher priority over read acquires. Which means, if you use both write/read operations, care must be taken to avoid starvation on the readers. Notice that the read/write acquire operations do not have the usual semantic of reader/writer locks. Only one reader can acquire the token at a time (which is different from the usual reader/writer locks where several readers can acquire a lock at the same time as long as there is no writer waiting for the lock). We choose the names to (1) borrow the semantic to give writers higher priority and (2) support a common interface for all locking classes in ACE.


Member Enumeration Documentation

enum ACE_Token::ACE_Token_Op_Type [private]
 

Enumeration values:
READ_TOKEN 
WRITE_TOKEN 

enum ACE_Token::QUEUEING_STRATEGY
 

Available queueing strategies.

Enumeration values:
FIFO  FIFO, First In, First Out.
LIFO  LIFO, Last In, First Out.


Constructor & Destructor Documentation

ACE_Token::ACE_Token const ACE_TCHAR name = 0,
void *  = 0
 

Constructor.

ACE_Token::~ACE_Token void   )  [virtual]
 

Destructor.


Member Function Documentation

int ACE_Token::acquire ACE_Time_Value timeout = 0  ) 
 

This behaves just like the previous <acquire> method, except that it invokes the virtual function called <sleep_hook> that can be overridden by a subclass of ACE_Token.

int ACE_Token::acquire void(*)(void *)  sleep_hook,
void *  arg = 0,
ACE_Time_Value timeout = 0
 

Acquire the token, sleeping until it is obtained or until the expiration of <timeout>, which is treated as "absolute" time. If some other thread currently holds the token then <sleep_hook> is called before our thread goes to sleep. This <sleep_hook> can be used by the requesting thread to unblock a token-holder that is sleeping, e.g., by means of writing to a pipe (the ACE ACE_Reactor uses this functionality). Return values: 0 if acquires without calling <sleep_hook> 1 if <sleep_hook> is called. 2 if the token is signaled. -1 if failure or timeout occurs (if timeout occurs errno == ETIME) If <timeout> == <&ACE_Time_Value::zero> then acquire has polling semantics (and does *not* call <sleep_hook>).

ACE_INLINE int ACE_Token::acquire_read void(*)(void *)  sleep_hook,
void *  arg = 0,
ACE_Time_Value timeout = 0
 

Behaves like acquire() but at a lower priority. It should probably be called acquire_yield() since the semantics aren't really what's commonly expected for readers/writer locks. See the class documentation above for more details.

ACE_INLINE int ACE_Token::acquire_read void   ) 
 

Behaves like acquire() but at a lower priority. It should probably be called acquire_yield() since the semantics aren't really what's commonly expected for readers/writer locks. See the class documentation above for more details.

ACE_INLINE int ACE_Token::acquire_write void(*)(void *)  sleep_hook,
void *  arg = 0,
ACE_Time_Value timeout = 0
 

Calls acquire().

ACE_INLINE int ACE_Token::acquire_write void   ) 
 

Calls acquire().

ACE_INLINE ACE_thread_t ACE_Token::current_owner void   ) 
 

Return the id of the current thread that owns the token.

void ACE_Token::dump void   )  const
 

Dump the state of an object.

ACE_INLINE void ACE_Token::queueing_strategy int  queueing_strategy  ) 
 

Set the queueing strategy.

ACE_INLINE int ACE_Token::queueing_strategy void   ) 
 

Retrieve the current queueing strategy.

int ACE_Token::release void   ) 
 

Relinquish the token. If there are any waiters then the next one in line gets it.

ACE_INLINE int ACE_Token::remove void   ) 
 

Shuts down the ACE_Token instance.

int ACE_Token::renew int  requeue_position = 0,
ACE_Time_Value timeout = 0
 

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 according to the queueing strategy. 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... This method maintians the original token priority. As in <acquire>, the <timeout> value is an absolute time.

int ACE_Token::shared_acquire void(*)(void *)  sleep_hook_func,
void *  arg,
ACE_Time_Value timeout,
ACE_Token_Op_Type  op_type
[private]
 

Implements the <acquire> and <tryacquire> methods above.

void ACE_Token::sleep_hook void   )  [virtual]
 

This should be overridden by a subclass to define the appropriate behavior before <acquire> goes to sleep. By default, this is a no-op...

ACE_INLINE int ACE_Token::tryacquire void   ) 
 

Become interface-compliant with other lock mechanisms (implements a non-blocking <acquire>).

ACE_INLINE int ACE_Token::tryacquire_read void   ) 
 

Lower priority try_acquire().

ACE_INLINE int ACE_Token::tryacquire_write void   ) 
 

Just calls <tryacquire>.

ACE_INLINE int ACE_Token::tryacquire_write_upgrade void   ) 
 

Assumes the caller has acquired the token and returns 0.

ACE_INLINE int ACE_Token::waiters void   ) 
 

Return the number of threads that are currently waiting to get the token.

void ACE_Token::wakeup_next_waiter void   )  [private]
 

Wake next in line for ownership.


Member Data Documentation

ACE_Token::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

ACE_Condition_Attributes ACE_Token::attributes_ [private]
 

The attributes for the condition variables, optimizes lock time.

int ACE_Token::in_use_ [private]
 

Some thread (i.e., <owner_>) is using the token. We need this extra variable to deal with POSIX pthreads madness...

ACE_Thread_Mutex ACE_Token::lock_ [private]
 

ACE_Thread_Mutex used to lock internal data structures.

int ACE_Token::nesting_level_ [private]
 

Current nesting level.

ACE_thread_t ACE_Token::owner_ [private]
 

Current owner of the token.

int ACE_Token::queueing_strategy_ [private]
 

Queueing strategy, LIFO/FIFO.

ACE_Token_Queue ACE_Token::readers_ [private]
 

A queue of reader threads.

int ACE_Token::waiters_ [private]
 

Number of waiters.

ACE_Token_Queue ACE_Token::writers_ [private]
 

A queue of writer threads.


The documentation for this class was generated from the following files:
Generated on Wed Jun 8 23:56:45 2005 for ACE by  doxygen 1.3.9.1