ACE_RW_Token(3)

NAME

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

SYNOPSIS

#include <ace/Local_Tokens.h>
class ACE_RW_Token : public ACE_Tokens
{
  public:
    ACE_RW_Token (const ASYS_TCHAR* name);
    virtual ~ACE_RW_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;
    enum PROXY_TYPE { READER, WRITER };
    virtual int type (void) const;
    virtual int owners (OWNER_STACK &o, const ASYS_TCHAR *id);
    virtual int is_waiting_for (const ASYS_TCHAR *id);
    virtual int is_owner (const ASYS_TCHAR *id);
  protected:
    int num_writers_;
    ACE_TOKEN_CONST::MUTEX lock_;
    void notify_new_owner (ACE_TPQ_Entry *caller);
};

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

Note that the locking classes defined in this file are *not*
intended to be used as general-purpose synchronization
mechanisms, such as mutexes or semaphores. Instead, you should
use the ACE_Recursive_Thread_Mutex, ACE_Thread_Mutex,
ACE_Thread_Semaphore, etc., that are defined in
$ACE_ROOT/ace/Synch.h and $ACE_ROOT/ace/Synch_T.h or the
ACE_Token that's defined in $ACE_ROOT/ace/Token.h.

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 except fails on 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 READER or WRITER.

virtual int owners (OWNER_STACK &o, const ASYS_TCHAR *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 ASYS_TCHAR *id);

Returns 1 if id is waiting for this token. 0 otherwise.

virtual int is_owner (const ASYS_TCHAR *id);

Returns 1 if id is an owner of this token. 0 otherwise.

AUTHOR

Karl-Heinz Dorn [email protected], Douglas C. Schmidt [email protected], and Tim Harrison [email protected]

LIBRARY

ace