diff options
Diffstat (limited to 'ace/Local_Tokens.h')
| -rw-r--r-- | ace/Local_Tokens.h | 1121 |
1 files changed, 0 insertions, 1121 deletions
diff --git a/ace/Local_Tokens.h b/ace/Local_Tokens.h deleted file mode 100644 index 1351f73f49f..00000000000 --- a/ace/Local_Tokens.h +++ /dev/null @@ -1,1121 +0,0 @@ -// -*- C++ -*- - -//============================================================================= -/** - * @file Local_Tokens.h - * - * $Id$ - * - * @author Karl-Heinz Dorn <kdorn@erlh.siemens.de> - * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> - * @author Tim Harrison <harrison@cs.wustl.edu> - * - * 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. - * - * - */ -//============================================================================= - -#ifndef ACE_LOCAL_MUTEX_H -#define ACE_LOCAL_MUTEX_H -#include /**/ "ace/pre.h" - -#include "ace/config-all.h" - -#if !defined (ACE_LACKS_PRAGMA_ONCE) -# pragma once -#endif /* ACE_LACKS_PRAGMA_ONCE */ - -#if defined (ACE_HAS_TOKENS_LIBRARY) - -#include "ace/Synch_Traits.h" -#include "ace/Condition_Thread_Mutex.h" -#include "ace/TSS_T.h" -#include "ace/Containers.h" -#include "ace/Synch_Options.h" -#include "ace/Map_Manager.h" -#include "ace/Log_Msg.h" -#include "ace/OS_NS_string.h" -#include "ace/os_include/os_netdb.h" - -#if !(defined (ACE_HAS_THREADS) && defined (ACE_HAS_THREAD_SPECIFIC_STORAGE)) -# define ACE_NO_TSS_TOKENS 1 -#endif /* !(defined (ACE_HAS_THREADS) && defined (ACE_HAS_THREAD_SPECIFIC_STORAGE)) */ - -ACE_BEGIN_VERSIONED_NAMESPACE_DECL - -// 1. -/** - * @class ACE_TOKEN_CONST - * - * @brief Not a public interface. - * - * Constant definitions and typedefs for Token library. Mostly, - * this class is necessary to fight the compiler with order of - * declaration errors. - */ -namespace ACE_TOKEN_CONST -{ -#if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0) - // ACE platform supports some form of threading. - typedef ACE_Condition_Thread_Mutex COND_VAR; - typedef ACE_Thread_Mutex MUTEX; - typedef ACE_Guard<ACE_Thread_Mutex> GUARD; -#else - typedef ACE_Null_Condition COND_VAR; - typedef ACE_Null_Mutex MUTEX; - typedef ACE_Guard<ACE_Null_Mutex> GUARD; -#endif /* ACE_HAS_THREADS */ -} - -// Forward decl. -class ACE_Token_Proxy; - -// 3.. -/** - * @class ACE_TPQ_Entry - * - * @brief Token Proxy Queue entry. Used in the ACE_Token_Proxy_Queue - * - * Not a public interface. - */ -class ACE_Export ACE_TPQ_Entry -{ - friend class ACE_Token_Manager; -public: - typedef void (*PTVF) (void *); - - /// Null constructor. - ACE_TPQ_Entry (void); - - /// Constructor. - ACE_TPQ_Entry (const ACE_Token_Proxy *proxy, - const ACE_TCHAR *client_id); - - /// Copy constructor. - ACE_TPQ_Entry (const ACE_TPQ_Entry &rhs); - - /// Destructor. - ~ACE_TPQ_Entry (void); - - /// Copy operator use by the queue. - void operator= (const ACE_TPQ_Entry &rhs); - - /// Get top of the queue. - ACE_Token_Proxy *proxy (void) const; - - /// Set top of the queue. - void proxy (ACE_Token_Proxy *); - - /// Get nesting level of the entry. - int nesting_level (void) const; - - /// Delta nesting level of the entry. - void nesting_level (int delta); - - /// Get client_id of the entry. - const ACE_TCHAR *client_id (void) const; - - /// Set client_id of the entry. - void client_id (const ACE_TCHAR *); - - /// Returns 1 if @a id == client id. Does not check for @a id == 0. - int equal_client_id (const ACE_TCHAR *id); - - /// One method for arg and sleep_hook. - void set (void (*sleep_hook)(void *)); - - /// Set sleep hook of the entry. - void sleep_hook (void (*sh)(void *)); - - /// Get sleep hook of the entry. - PTVF sleep_hook (void) const; - - /// Call the sleep hook function or method passing arg. - void call_sleep_hook (void); - - /// Dump the state of the class. - void dump (void) const; - - // = Used to block the thread if an acquire fails with EWOULDBLOCK. - ACE_TOKEN_CONST::COND_VAR cond_var_; - ACE_TOKEN_CONST::MUTEX lock_; - - /// Pointer to next in list. - ACE_TPQ_Entry *next_; - - /// Get whether this client is blocked waiting for a token. - int waiting (void) const; - - /// Set whether this client is blocked waiting for a token. - void waiting (int w); - -private: - /// This client is waiting for a token. - int waiting_; - - /// Proxy. - ACE_Token_Proxy *proxy_; - - /// Nesting level. - int nesting_level_; - - /// Arg. - void *arg_; - - /// Client id. - ACE_TCHAR client_id_[ACE_MAXCLIENTIDLEN]; - - /// Sleep hook. - void (*sleep_hook_)(void *); -}; - -// b.. -#if defined (ACE_NO_TSS_TOKENS) -typedef ACE_TPQ_Entry ACE_TPQ_ENTRY; -#else -typedef ACE_TSS<ACE_TPQ_Entry> ACE_TPQ_ENTRY; -#endif /* ACE_NO_TSS_TOKENS */ - -/** - * @class ACE_TSS_TPQ_Entry - * - * @brief ACE_TSS_TPQ_Entry - * - * Not a public interface. - */ -class ACE_Export ACE_TSS_TPQ_Entry : public ACE_TPQ_ENTRY -{ -public: - /// These are passed to the constructor of ACE_TPQ_Entry in - /// make_TSS_TYPE - ACE_TSS_TPQ_Entry (const ACE_Token_Proxy *proxy, - const ACE_TCHAR *client_id); - - /// Destructor. - virtual ~ACE_TSS_TPQ_Entry (void); - - /// Allows us to pass args to the construction of the TSS object. - virtual ACE_TPQ_Entry *make_TSS_TYPE (void) const; - - /// Operator overloading and inheritence don't mix. - operator ACE_TPQ_Entry *(void); - - /// Dump the state of the class. - void dump (void) const; - -#if defined (ACE_NO_TSS_TOKENS) - ACE_TPQ_Entry *operator-> (void) - { - return (ACE_TPQ_Entry *) this; - } -#endif /* ACE_NO_TSS_TOKENS */ - -private: - /// Private: should not be used - ACE_TSS_TPQ_Entry (const ACE_TSS_TPQ_Entry &); - void operator= (const ACE_TSS_TPQ_Entry &); - - // = These are passed to the constructor of ACE_TPQ_Entry in - // make_TSS_TYPE - - /// Proxy. - const ACE_Token_Proxy *proxy_; - - /// Client_id. - const ACE_TCHAR *client_id_; -}; - -class ACE_Token_Proxy_Queue; - -// c.. -/** - * @class ACE_TPQ_Iterator - * - * @brief Iterates through ACE_Token_Proxy_Queues. - * - * Not a public interface. - */ -class ACE_Export ACE_TPQ_Iterator -{ -public: - /// Constructor. - ACE_TPQ_Iterator (ACE_Token_Proxy_Queue &q); - - /// Destructor. - ~ACE_TPQ_Iterator (void); - - /// Pass back the <next_item>. - int next (ACE_TPQ_Entry *&next_item); - - /// Returns 1 when all items have been seen, else 0. - int done (void) const; - - /// Move forward by one element in the queue. - void advance (void); - - /// Dump the state of an object. - void dump (void) const; - -private: - ACE_TPQ_Entry *current_; -}; - -// 4.. -/** - * @class ACE_Token_Proxy_Queue - * - * @brief Token waiter list. - * - * Not a public interface. - * This queue holds all the token proxies waiting for ownership - * of a token. Along with the proxy reference, it also stores - * the nesting level, client id, and a magic cookie from the - * proxy. This queue stores the ACE_TPQ_Entries by pointer - * values. It DOES NOT make copies. Thus, the user is - * responsible to ensure that the TPQ's stick around. This is - * motivated by the need to reduce dynamic memory allocation. - */ -class ACE_Export ACE_Token_Proxy_Queue -{ -public: - friend class ACE_TPQ_Iterator; - - /// Constructor. - ACE_Token_Proxy_Queue (void); - - /// Destructor. - ~ACE_Token_Proxy_Queue (void); - - /** - * Enqueue a proxy, nesting level, client_id, and a magic cookie at - * the given position in the list. If the position is -1, we - * enqueue at the end of the list (I think). - */ - void enqueue (ACE_TPQ_Entry* new_entry, - int position); - - /// Top of the queue. - const ACE_TPQ_Entry* head (void); - -// int member (const ACE_TCHAR *id); - // Is this id in the waiter list? - - /// Remove the top waiter. - void dequeue (void); - - /// Remove the waiter whose proxy ref matches @a remove_me. - void remove (const ACE_TPQ_Entry *remove_me); - - /// The number of waiters. - int size (void); - - /// Dump the state of the class. - void dump (void) const; - -protected: - /// Head. - ACE_TPQ_Entry *head_; - - /// Tail. - ACE_TPQ_Entry *tail_; - - /// Size. - int size_; -}; - -// 5.. -/** - * @class ACE_Tokens - * - * @brief Abstract representation of ACE tokens. - * - * Not a public interface. - * Currently, I don't see a reason for providing an abstract - * interface at this level of the library. As of yet, no one - * uses ACE_Tokens derivatives through this abstract interface - * except for ACE_Token_Manager. It only uses the statistical - * methods which are shared by all Tokens. For that reason, it - * still makes since to have a common base class. However, - * acquire, renew, and release do not need to have matching - * interfaces throughout all Tokens. - * To add a new type of token (e.g. semaphore), this class must - * be subtyped to define the new semantics. See - * ACE_Token_Manager for details. - */ -class ACE_Export ACE_Tokens -{ -public: - - /// Null constructor. - ACE_Tokens (void); - - /// Destructor - virtual ~ACE_Tokens (void); - - /// No implementation. - virtual int acquire (ACE_TPQ_Entry *caller, - int ignore_deadlock, - int notify) = 0; - - /// No implementation. - virtual int tryacquire (ACE_TPQ_Entry *caller) = 0; - - /// No implementation. - virtual int renew (ACE_TPQ_Entry *caller, - int requeue_position) = 0; - - /// No implementation. - virtual int release (ACE_TPQ_Entry *caller) = 0; - - /// Move the caller to the front of the waiter list. This is for use - /// with remote mutexes and shadow mutexes. - void make_owner (ACE_TPQ_Entry *caller); - - /// Remove the caller from the waiter list. - void remove (ACE_TPQ_Entry *caller); - - // = Accessor methods. - - /// Stack of owners. - typedef ACE_Unbounded_Stack<ACE_TPQ_Entry *> OWNER_STACK; - - /// 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 owners (OWNER_STACK &o, const ACE_TCHAR *id) = 0; - - /// Returns 1 if <id> is waiting for this token. 0 otherwise. - virtual int is_waiting_for (const ACE_TCHAR *id) = 0; - - /// Returns 1 if <id> is an owner of this token. 0 otherwise. - virtual int is_owner (const ACE_TCHAR *id) = 0; - - /// Return the queue of waiters. - virtual ACE_Token_Proxy_Queue *waiters (void); - - /// Return the number of proxies that are currently waiting to get - /// the token. - virtual int no_of_waiters (void); - - /// The current owner. - const ACE_TCHAR *owner_id (void); - - /// Token name. - const ACE_TCHAR* name (void); - - // = Reference counting. These are only called by the - // Token_Manager. - void inc_reference (void); - int dec_reference (void); - - /// Dump the state of the class. - void dump (void) const; - - /** - * These are the Token types supported by the library at ship time. - * There is no restriction on the number of Token types added by - * "3rd parties." These are only necessary for the Token Server. - */ - enum TOKEN_TYPES { MUTEX, RWLOCK }; - - /** - * Provides a manual RTTI mechanism. This method is used only by - * ACE_Token_Request so that the type of a token can be sent to a - * remote Token Server. - */ - virtual int type (void) const = 0; - - // = The following methods allow the deadlock detection algorithm to - // check if this token has been visited. - - /// Mark or unmark the token as visited. - void visit (int v); - - /// Check if the token has been visited. - int visited (void); - - /// All the data of the current owner. - ACE_TPQ_Entry *owner (void); - -protected: - - /// For the deadlock detection algorithm. - int visited_; - - /// Reference count. - int reference_count_; - - /// List of client's owning and waiting the token. - ACE_Token_Proxy_Queue waiters_; - - /// Name of token. - ACE_TCHAR token_name_[ACE_MAXTOKENNAMELEN]; -}; - -class ACE_Local_Mutex; - -// 6.. -/** - * @class ACE_Mutex_Token - * - * @brief 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). - */ -class ACE_Export ACE_Mutex_Token : public ACE_Tokens -{ -public: - /// Constructor - explicit ACE_Mutex_Token (const ACE_TCHAR* name); - - /// Destructor - virtual ~ACE_Mutex_Token (void); - - // = 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. - - /** - * 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 acquire (ACE_TPQ_Entry *caller, - int ignore_deadlock, - int notify); - - /// Same as acquire, but fails if would block - virtual int tryacquire (ACE_TPQ_Entry *caller); - - /** - * 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 renew (ACE_TPQ_Entry *caller, - int requeue_position); - - /** - * 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. - */ - virtual int release (ACE_TPQ_Entry *caller); - - /// Dump the state of the class. - void dump (void) const; - - /// Returns ACE_Tokens::MUTEX. - virtual int type (void) const; - - /// 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 owners (OWNER_STACK &o, const ACE_TCHAR *id); - - /// Returns 1 if <id> is waiting for this token. 0 otherwise. - virtual int is_waiting_for (const ACE_TCHAR *id); - - /// Returns 1 if <id> is an owner of this token. 0 otherwise. - virtual int is_owner (const ACE_TCHAR *id); - -private: - /// ACE_Mutex_Token used to lock internal data structures. - ACE_TOKEN_CONST::MUTEX lock_; -}; - -// 12.. -/** - * @class ACE_RW_Token - * - * @brief 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). - */ -class ACE_Export ACE_RW_Token : public ACE_Tokens -{ -public: - /// Constructor. - explicit ACE_RW_Token (const ACE_TCHAR* name); - - /// Destructor. - virtual ~ACE_RW_Token (void); - - // = 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. - - /** - * 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 @a ignore_deadlock is passed as 1 and errnum - * == EDEADLK, then deadlock was detected via ACE_Token_Manager. - */ - virtual int acquire (ACE_TPQ_Entry *caller, - int ignore_deadlock, - int notify); - - /// Same as acquire except fails on would block - virtual int tryacquire (ACE_TPQ_Entry *caller); - - /** - * 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 renew (ACE_TPQ_Entry *caller, - int requeue_position); - - /** - * 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. - */ - virtual int release (ACE_TPQ_Entry *caller); - - /// Dump the state of the class. - void dump (void) const; - - /// These are the types that proxies can be. - enum PROXY_TYPE { READER, WRITER }; - - /// Returns READER or WRITER. - virtual int type (void) const; - - /// 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 owners (OWNER_STACK &o, const ACE_TCHAR *id); - - /// Returns 1 if <id> is waiting for this token. 0 otherwise. - virtual int is_waiting_for (const ACE_TCHAR *id); - - /// Returns 1 if <id> is an owner of this token. 0 otherwise. - virtual int is_owner (const ACE_TCHAR *id); - -protected: - /// The number of waiting writers. - int num_writers_; - - /// ACE_Mutex_Token used to lock internal data structures. - ACE_TOKEN_CONST::MUTEX lock_; - - /// Sets the new owner. - void notify_new_owner (ACE_TPQ_Entry *caller); -}; - -// a.. -/** - * @class ACE_Token_Name - * - * @brief Allows Token_Manger to identify tokens. - * - * For now, this is just a string. We need a string class - * anyway to use in <ACE_Map_Manager>. Having this class - * (instead of <ACE_SString>) allows us to easily change if - * needed. For instance, we may choose to identify tokens by - * name and *type* in the future. - */ -class ACE_Export ACE_Token_Name -{ -public: - /// Construction. - ACE_Token_Name (const ACE_TCHAR *token_name = 0); - - /// Copy construction. - ACE_Token_Name (const ACE_Token_Name &rhs); - - /// Destructor. - virtual ~ACE_Token_Name (void); - - /// Copy. - void operator= (const ACE_Token_Name &rhs); - - /// Comparison. - bool operator== (const ACE_Token_Name &rhs) const; - - /// Get the token name. - const ACE_TCHAR *name (void) const; - - /// Set the token name. - void name (const ACE_TCHAR *new_name); - - /// Dump the state of the class. - void dump (void) const; - -private: - /// Name of the token. - ACE_TCHAR token_name_[ACE_MAXTOKENNAMELEN]; -}; - -// 7.. -/** - * @class ACE_Token_Proxy - * - * @brief Abstract representation of ACE tokens. - * - * Interface for all Tokens in ACE. This class implements the - * synchronization needed for tokens (condition variables etc.) - * The algorithms for the operations (acquire, release, etc.) - * operate on the generic ACE_Tokens interface. Thus, the _type_ - * of token (mutex, rwlock) can be set at construction of - * ACE_Token_Proxy. You can use all Tokens in ACE through the - * ACE_Token_Proxy by passing the proper values at construction. - * Alternatively, there are class definitions which "know" how to - * do this (ACE_Local_Mutex, ACE_Local_RLock, ACE_Local_WLock). - * To add a new type of token (e.g. semaphore), this class is not - * changed. See ACE_Token_Manager for details. - * Tokens (e.g. ACE_Mutex_Token) assume that it can always call - * <ACE_Token_Proxy::token_acquired> on a new token owner. This - * is not a problem for synchronous use of token proxies (that is, - * when acquires block until successful.) However, for - * implementations of the Token Server, which may use asynch - * operations, the proxy can not go away after an acquire until - * the token is acquired. This is not really a problem, but - * should be understood. - */ -class ACE_Export ACE_Token_Proxy -{ -public: - friend class ACE_Token_Manager; - friend class ACE_Token_Invariant_Manager; // For testing. - - // Initialization and termination methods. - /// Construction. - ACE_Token_Proxy (void); - - /// Destructor. - virtual ~ACE_Token_Proxy (void); - - /** - * Open the <ACE_Token>. - * @param name The string uniquely identifying the token. - * @param ignore_deadlock Can be 1 to disable deadlock notifications. - * @param debug Prints debug messages. - */ - virtual int open (const ACE_TCHAR *name, - int ignore_deadlock = 0, - int debug = 0); - - // = The following methods have implementations which are - // independent of the token semantics (mutex, rwlock, etc.) They - // forward operations to the underlying token and perform the - // necessary blocking semantics for operations (condition variables - // etc.) This allows reuse of the blocking code as well as having - // multiple proxies to the same token. - - /// Calls acquire on the token. Blocks the calling thread if would - /// block. - virtual int acquire (int notify = 0, - void (*sleep_hook)(void *) = 0, - ACE_Synch_Options &options = - ACE_Synch_Options::defaults); - - /// Calls renew on the token. Blocks the calling thread if would block. - virtual int renew (int requeue_position = -1, - ACE_Synch_Options &options = - ACE_Synch_Options::defaults); - - /// Calls renew on the token. - virtual int tryacquire (void (*sleep_hook)(void *) = 0); - - /// Calls release on the token. - virtual int release (ACE_Synch_Options &options = - ACE_Synch_Options::defaults); - - /// Calls remove on the token. - virtual int remove (ACE_Synch_Options &options = - ACE_Synch_Options::defaults); - - /// Since the locking mechanism doesn't support read locks then this - /// just calls <acquire>. - virtual int acquire_read (int notify = 0, - void (*sleep_hook)(void *) = 0, - ACE_Synch_Options &options = - ACE_Synch_Options::defaults); - - /// Since the locking mechanism doesn't support write locks then this - /// just calls <acquire>. - virtual int acquire_write (int notify = 0, - void (*sleep_hook)(void *) = 0, - ACE_Synch_Options &options = - ACE_Synch_Options::defaults); - - /// Since the locking mechanism doesn't support read locks then this - /// just calls <tryacquire>. - virtual int tryacquire_read (void (*sleep_hook)(void *) = 0); - - /// Since the locking mechanism doesn't support write locks then this - /// just calls <tryacquire>. - virtual int tryacquire_write (void (*sleep_hook)(void *) = 0); - - // = Utility methods. - - /// Get the client id of the proxy. This is implemented as - /// thread-specific data. - virtual const ACE_TCHAR *client_id (void) const; - - /** - * Set the client_id for the calling thread. I strongly recommend - * that this not be used unless you really know what you're doing. - * I use this in the Token Server, and it caused many headaches. - */ - virtual void client_id (const ACE_TCHAR *client_id); - - /** - * Return the name of the token. This is important for use within - * the token servers (local and remote) as well as with token - * collections. So, all derivations of ACE_Token_Proxy must be able to - * stringify some name. The name must uniquely identify a token. - * So, for instance, the token within the reactor should probably be - * called "Reactor Token." - */ - virtual const ACE_TCHAR *name (void) const; - - /** - * This should really be called <someone_waiting>. This is called - * by ACE_Token_xx's when another proxy enters the waiting list and - * requests that the current token holder be notified. - */ - virtual void sleep_hook (void); - - /// This is called when a queued (waiting) proxy is removed from the - /// waiters list and given the token. - virtual void token_acquired (ACE_TPQ_Entry *); - - /// The client id of the current token holder - virtual const ACE_TCHAR *owner_id (void); - - /// Return a dynamically allocated clone of the derived class. - virtual ACE_Token_Proxy *clone (void) const = 0; - - /// Dump the state of the class. - void dump (void) const; - - /** - * This method can be used be Tokens (e.g. Readers/Writer Tokens) to - * distinguish between Proxy types. For instance a Reader proxy - * should return a different type value than a Writer proxy. The - * default implementation returns 0. - */ - virtual int type (void) const; - -protected: - /// Duplication. - ACE_Token_Proxy (const ACE_Token_Proxy &); - - /// If this is set, we ignore deadlock. - int ignore_deadlock_; - - /// Print a bunch of debug messages. - int debug_; - - /// Reference to the actual logical token. Many ACE_Local_Mutex - /// proxies can reference the same ACE_Mutex_Token. - ACE_Tokens *token_; - - /// Handles cond_var waits. - int handle_options (ACE_Synch_Options &options, - ACE_TOKEN_CONST::COND_VAR &cv); - - /// Waiter info used for asynchronous transactions. - ACE_TSS_TPQ_Entry waiter_; - - /// Make the correct type of ACE_Tokens. This is called by the Token - /// Manager. - virtual ACE_Tokens *create_token (const ACE_TCHAR *name) = 0; -}; - -// 8.. -/** - * @class ACE_Null_Token - * - * @brief No op class for nonthreaded platform protocols. - */ -class ACE_Export ACE_Null_Token : public ACE_Token_Proxy -{ -public: -#if defined (ACE_LACKS_INLINE_FUNCTIONS) - // @@ Hopefully, we can remove this ridicules ifdef when CE's compiler becomes more normal. - /// Construction. - ACE_Null_Token (void); - - /// Destructor. - ~ACE_Null_Token (void); -#endif /* ACE_LACKS_INLINE_FUNCTION */ - - /// Acquire. - virtual int acquire (int /* notify */ = 0, - void (* /* sleep_hook */ )(void *) = 0, - ACE_Synch_Options & /* options */ = - ACE_Synch_Options::defaults) { return 0; } - - /// Renew. - virtual int renew (int /* requeue_position */ = -1, - ACE_Synch_Options & /* options */ = - ACE_Synch_Options::defaults) { return 0; } - - /// Try acquire. - virtual int tryacquire (void (* /* sleep_hook */)(void *) = 0) { return 0; } - - /// Release. - virtual int release (ACE_Synch_Options & /* options */ = - ACE_Synch_Options::defaults) { return 0; } - - /// Remove. - virtual int remove (ACE_Synch_Options & /* options */ = - ACE_Synch_Options::defaults) { return 0; } - - /// Return a dynamically allocated clone of the derived class. - virtual ACE_Token_Proxy *clone (void) const { return new ACE_Null_Token; } - - /// Dump the state of the class. - void dump (void) const; - - /// Do not allow the Token Manager to create us. - virtual ACE_Tokens *create_token (const ACE_TCHAR *) { return 0; } -}; - -// 9.. -/** - * @class ACE_Local_Mutex - * - * @brief Class that acquires, renews, and releases a synchronization - * token local to the process. - * - * 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). Lastly, - * ACE_Local_Mutex performs deadlock detection on acquire calls. - * The interfaces for acquire, tryacquire, renew, release, - * etc. are defined in ACE_Token_Proxy. The semantics for - * ACE_Local_Mutex are that of a mutex. - */ -class ACE_Export ACE_Local_Mutex : public ACE_Token_Proxy -{ -public: - /** - * Constructor. - * @param token_name Uniquely id's the token. - * @param ignore_deadlock Will allow deadlock to occur (useful for testing). - * @param debug Prints a bunch of messages. - */ - ACE_Local_Mutex (const ACE_TCHAR *token_name = 0, - int ignore_deadlock = 0, - int debug = 0); - - /// Destructor - ~ACE_Local_Mutex (void); - - /// Dump the state of the class. - void dump (void) const; - - /// Return deep copy. - virtual ACE_Token_Proxy *clone (void) const; - -protected: - /// Return a new ACE_Local_Mutex. - virtual ACE_Tokens *create_token (const ACE_TCHAR *name); -}; - -// *. -/** - * @class ACE_Local_RLock - * - * @brief Class that acquires, renews, and releases a readers lock that - * is local to the process. - * - * This class implements the reader interface to canonical - * readers/writer locks. Multiple readers can hold the lock - * simultaneously when no writers have the lock. Alternatively, - * when a writer holds the lock, no other participants (readers - * or writers) may hold the lock. This class is a more - * general-purpose synchronization mechanism than SunOS 5.x - * RLocks. For example, it implements "recursive RLock" - * 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 RLockes don't strictly - * enforce an acquisition order). - * The interfaces for acquire, tryacquire, renew, release, - * etc. are defined in ACE_Token_Proxy. The semantics for - * ACE_Local_RLock are that of a readers/writers lock. Acquire - * for this class implies a reader acquisition. That is, - * multiple clients may acquire a lock for read only. - */ -class ACE_Export ACE_Local_RLock : public ACE_Token_Proxy -{ -public: - // = Initialization and termination. - - /** - * Constructor. - * @param token_name Uniquely id's the token. - * @param ignore_deadlock Will allow deadlock to occur (useful for testing). - * @param debug Prints a bunch of messages. - */ - ACE_Local_RLock (const ACE_TCHAR *token_name = 0, - int ignore_deadlock = 0, - int debug = 0); - - /// Destructor - ~ACE_Local_RLock (void); - - /// Dump the state of the class. - void dump (void) const; - - /// Returns ACE_RW_Token::RLOCK. - virtual int type (void) const; - - /// Return deep copy. - virtual ACE_Token_Proxy *clone (void) const; - -protected: - /// Return a new ACE_Local_Mutex. - virtual ACE_Tokens *create_token (const ACE_TCHAR *name); -}; - -// *. -/** - * @class ACE_Local_WLock - * - * @brief Class that acquires, renews, and releases a writer lock that - * is local to the process. - * - * This class implements the writer interface to canonical - * readers/writer locks. Multiple readers can hold the lock - * simultaneously when no writers have the lock. Alternatively, - * when a writer holds the lock, no other participants (readers - * or writers) may hold the lock. This class is a more - * general-purpose synchronization mechanism than SunOS 5.x - * WLock. For example, it implements "recursive WLock" - * 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 WLocks don't strictly - * enforce an acquisition order). - * The interfaces for acquire, tryacquire, renew, release, - * etc. are defined in ACE_Token_Proxy. The semantics for - * ACE_Local_WLock are that of a readers/writers lock. Acquire - * for this class implies a writer acquisition. That is, only - * one client may hold the lock for writing. - */ -class ACE_Export ACE_Local_WLock : public ACE_Token_Proxy -{ -public: - // = Initialization and termination. - - /** - * Constructor. - * @param token_name Uniquely id's the token. - * @param ignore_deadlock Will allow deadlock to occur (useful for testing). - * @param debug Prints a bunch of messages. - */ - ACE_Local_WLock (const ACE_TCHAR *token_name = 0, - int ignore_deadlock = 0, - int debug = 0); - - /// Destructor - ~ACE_Local_WLock (void); - - /// Dump the state of the class. - void dump (void) const; - - /// Returns ACE_RW_Token::WLOCK. - virtual int type (void) const; - - /// Return deep copy. - virtual ACE_Token_Proxy *clone (void) const; - -protected: - /// Return a new ACE_Local_Mutex. - ACE_Tokens *create_token (const ACE_TCHAR *name); -}; - -ACE_END_VERSIONED_NAMESPACE_DECL - -#endif /* ACE_HAS_TOKENS_LIBRARY */ - -#if defined (__ACE_INLINE__) -#include "ace/Local_Tokens.inl" -#endif /* __ACE_INLINE__ */ -#include /**/ "ace/post.h" -#endif /* ACE_LOCAL_MUTEX_H */ |