NAME

ACE_Token - Class that acquires, renews, and releases a synchronization token that is serviced in strict FIFO ordering and that also supports readers/writer semantics.

SYNOPSIS

#include <ace/Token.h>

class ACE_Token { public: ACE_Token (LPCTSTR name = 0, void * = 0); virtual ~ACE_Token (void); 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); 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); int acquire_write (void (*sleep_hook)( void *), void *arg = 0, ACE_Time_Value *timeout = 0 ); int tryacquire_read (void); int tryacquire_write (void); int waiters (void); ACE_thread_t current_owner (void); int signal_all_threads (void); void dump (void) const; ACE_ALLOC_HOOK_DECLARE;

struct ACE_Token_Queue_Entry { public: ACE_Token_Queue_Entry ( ACE_Thread_Mutex &m, ACE_thread_t t_id ); ACE_Token_Queue_Entry ( ACE_Thread_Mutex &m, ACE_thread_t t_id, ACE_Condition_Attributes &attributes ); int wait (ACE_Time_Value *timeout, ACE_Thread_Mutex &lock); int signal (void); ACE_Token_Queue_Entry *next_; ACE_thread_t thread_id_; ACE_Semaphore cv_; ACE_Condition_Thread_Mutex cv_; int runable_; };

inline int acquire (ACE_Time_Value * = 0); inline int tryacquire (void); inline int remove (void); inline int release (void); private: enum ACE_Token_Op_Type{ READ_TOKEN = 1, WRITE_TOKEN };

struct ACE_Token_Queue { public: ACE_Token_Queue (void); void remove_entry (ACE_Token_Queue_Entry *); ACE_Token_Queue_Entry *head_; ACE_Token_Queue_Entry *tail_; }; int shared_acquire (void (*sleep_hook_func)( void *), void *arg, ACE_Time_Value *timeout, ACE_Token_Op_Type op_type ); ACE_Token_Queue writers_; ACE_Token_Queue readers_; ACE_Thread_Mutex lock_; ACE_thread_t owner_; int in_use_; int waiters_; int nesting_level_; int signal_all_threads_; ACE_Condition_Attributes attributes_; };

DESCRIPTION

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 (Solaris and Pthread mutexes don't strictly enforce an acquisition order). There are two FIFO 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 1.) to borrow the semantic to give writers higher priority, and, 2.) to support a common interface over all locking classes in ACE.

Initialization and termination.

ACE_Token (LPCTSTR name = 0, void * = 0);

virtual ~ACE_Token (void);

Synchronization operations.

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

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

int acquire_write (void (*sleep_hook)(
    void *),
    void *arg = 0,
    ACE_Time_Value *timeout = 0
    );

int tryacquire_read (void);

int tryacquire_write (void);

Accessor methods.

int waiters (void);

ACE_thread_t current_owner (void);

int signal_all_threads (void);

void dump (void) const;

ACE_ALLOC_HOOK_DECLARE;

The following structure implements a ACE_FIFO of waiter threads

that are asleep waiting to obtain the token.

AUTHOR

Original author -- Karl-Heinz Dorn (kdorn@erlh.siemens.de) Ported to ACE by Douglas C. Schmidt (schmidt@cs.wustl.edu)

LIBRARY

ace