NAME

ACE_Token - Class that acquires, renews, and releases a synchronization token that is local to the process.

SYNOPSIS


#include <ace/Token.h>


class ACE_Token
{
  public:
    ACE_Token (const char *name = 0, void * = 0);
    ~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 waiters (void);
    ACE_thread_t current_owner (void);
    void dump (void) const;
    ACE_ALLOC_HOOK_DECLARE;
  private:
    int shared_acquire (void (*sleep_hook_func)(
        void *),
        void *arg,
        ACE_Time_Value *timeout
        );
    void remove_entry (ACE_Queue_Entry *);
    ACE_Queue_Entry *head_;
    ACE_Queue_Entry *tail_;
    ACE_Thread_Mutex lock_;
    ACE_thread_t owner_;
    int in_use_;
    int waiters_;
    int nesting_level_;
};

Initialization and termination.

ACE_Token (const char *name = 0, void * = 0);
~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);

Accessor methods.

int waiters (void);
ACE_thread_t current_owner (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.
int shared_acquire (void (*sleep_hook_func)(
    void *),
    void *arg,
    ACE_Time_Value *timeout
    );
void remove_entry (ACE_Queue_Entry *);
ACE_Queue_Entry *head_;
ACE_Queue_Entry *tail_;
ACE_Thread_Mutex lock_;
ACE_thread_t owner_;
int in_use_;
int waiters_;
int nesting_level_;

AUTHOR

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

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 (SunOS 5.x mutexes don't strictly enforce an acquisition order).

LIBRARY

ace