From 53284e215e3d3351a7d7e9c4b68f14b427fb4377 Mon Sep 17 00:00:00 2001 From: coryan Date: Wed, 1 Nov 2000 22:17:39 +0000 Subject: ChangeLogTag:Wed Nov 1 14:11:48 2000 Carlos O'Ryan --- ace/Token_Invariants.h | 180 +++++++++++++++++++++++++------------------------ 1 file changed, 92 insertions(+), 88 deletions(-) (limited to 'ace/Token_Invariants.h') diff --git a/ace/Token_Invariants.h b/ace/Token_Invariants.h index 3bda6f2b572..2be2d194017 100644 --- a/ace/Token_Invariants.h +++ b/ace/Token_Invariants.h @@ -1,23 +1,21 @@ /* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// Token_Invariants.h -// -// = AUTHOR -// Tim Harrison (harrison@cs.wustl.edu) -// -// = DESCRIPTION -// Allows applications to test that invariants are always -// satisfied. Can test mutexes and readers/writer locks. Does -// not test recursive acquisition. -// -// ============================================================================ + +//============================================================================= +/** + * @file Token_Invariants.h + * + * $Id$ + * + * @author Tim Harrison (harrison@cs.wustl.edu) + * + * Allows applications to test that invariants are always + * satisfied. Can test mutexes and readers/writer locks. Does + * not test recursive acquisition. + * + * + */ +//============================================================================= + #ifndef ACE_TOKEN_INVARIANTS_H #define ACE_TOKEN_INVARIANTS_H @@ -32,189 +30,195 @@ #include "ace/Map_Manager.h" #include "ace/Local_Tokens.h" +/** + * @class ACE_Mutex_Invariants + * + * @brief Mutex Invariants + * = INVARIANTS + * 1. Only one owner at a time. + */ class ACE_Export ACE_Mutex_Invariants { - // = TITLE - // Mutex Invariants - // - // = INVARIANTS - // 1. Only one owner at a time. public: + /// Default construction. ACE_Mutex_Invariants (void); - // Default construction. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int acquired (void); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void releasing (void); - // Updates internal database. // = Map_Manager operations. + /// Copy construction. ACE_Mutex_Invariants (const ACE_Mutex_Invariants &rhs); - // Copy construction. + /// Copy. void operator= (const ACE_Mutex_Invariants &rhs); - // Copy. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. private: + /// Number of owners. This had better be 0 >= owners_ <= 1; int owners_; - // Number of owners. This had better be 0 >= owners_ <= 1; }; +/** + * @class ACE_RWLock_Invariants + * + * @brief RWLock Invariants + * + * Preserve the following invariants: + * -# Only one writer at a time. + * -# If there is an owning writer, there are no owning readers. + */ class ACE_Export ACE_RWLock_Invariants { - // = TITLE - // RWLock Invariants - // - // = INVARIANTS - // 1. Only one writer at a time. - // 2. If there is an owning writer, there are no owning readers. public: + /// Default construction. ACE_RWLock_Invariants (void); - // Default construction. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int writer_acquired (void); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int reader_acquired (void); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void releasing (void); - // Updates internal database. // = Map_Manager operations. + /// Copy construction. ACE_RWLock_Invariants (const ACE_RWLock_Invariants &rhs); - // Copy construction. + /// Copy. void operator= (const ACE_RWLock_Invariants &rhs); - // Copy. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. private: + /// Number of owning writers. int writers_; - // Number of owning writers. + /// Number of owning readers. int readers_; - // Number of owning readers. }; +/** + * @class ACE_Token_Invariant_Manager + * + * @brief Token Invariants + * + * The Token Invariant Manager allows applications to test that + * invariants are always satisfied. Currently, Token_Invariants + * can test mutexes and readers/writer locks. Does not test + * recursive acquisition. + * Note that this class does not ever clean its database. Until + * destroyed, it's size will forever increase. + */ class ACE_Export ACE_Token_Invariant_Manager : public ACE_Cleanup { - // = TITLE - // Token Invariants - // - // = DESCRIPTION - // The Token Invariant Manager allows applications to test that - // invariants are always satisfied. Currently, Token_Invariants - // can test mutexes and readers/writer locks. Does not test - // recursive acquisition. - // - // Note that this class does not ever clean its database. Until - // destroyed, it's size will forever increase. public: + /// Singleton access point. static ACE_Token_Invariant_Manager *instance (void); - // Singleton access point. // = Polymorphic methods. Just pass in the proxy and the method // figures out the type of the token. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int acquired (const ACE_Token_Proxy *proxy); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void releasing (const ACE_Token_Proxy *proxy); - // Updates internal database. // = Explicit methods. These to not require actual proxies in order // to test a scenario. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int mutex_acquired (const ACE_TCHAR *token_name); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void mutex_releasing (const ACE_TCHAR *token_name); - // Updates internal database. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int reader_acquired (const ACE_TCHAR *token_name); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Returns 1 on success, 0 when an invariant has been violated and + /// -1 on error. int writer_acquired (const ACE_TCHAR *token_name); - // Returns 1 on success, 0 when an invariant has been violated and - // -1 on error. + /// Updates internal database. void rwlock_releasing (const ACE_TCHAR *token_name); - // Updates internal database. + /// Dump the state of the class. void dump (void) const; - // Dump the state of the class. // = The following two method should be in the protected part of the // class. Bugs with certain compilers preclude this. + /// Prevent non-singleton construction. ACE_Token_Invariant_Manager (void); - // Prevent non-singleton construction. + /// Destruction. virtual ~ACE_Token_Invariant_Manager (void); - // Destruction. protected: + /// Return or create. int get_mutex (const ACE_TCHAR *token_name, ACE_Mutex_Invariants *&inv); - // Return or create. + /// Return or create. int get_rwlock (const ACE_TCHAR *token_name, ACE_RWLock_Invariants *&inv); - // Return or create. + /// ACE_Mutex_Token used to lock internal data structures. ACE_TOKEN_CONST::MUTEX lock_; - // ACE_Mutex_Token used to lock internal data structures. + /// This may be changed to a template type. typedef ACE_Token_Name TOKEN_NAME; - // This may be changed to a template type. + /// COLLECTION maintains a mapping from token names to mutexes. typedef ACE_Map_Manager MUTEX_COLLECTION; - // COLLECTION maintains a mapping from token names to mutexes. + /// Allows iterations through collection. typedef ACE_Map_Iterator MUTEX_COLLECTION_ITERATOR; - // Allows iterations through collection. + /// Allows iterations through collection. typedef ACE_Map_Entry MUTEX_COLLECTION_ENTRY; - // Allows iterations through collection. + /// MUTEX_COLLECTION maintains a mapping from token names to mutexes. MUTEX_COLLECTION mutex_collection_; - // MUTEX_COLLECTION maintains a mapping from token names to mutexes. + /// COLLECTION maintains a mapping from token names to mutexes. typedef ACE_Map_Manager RWLOCK_COLLECTION; - // COLLECTION maintains a mapping from token names to mutexes. + /// Allows iterations through collection. typedef ACE_Map_Iterator RWLOCK_COLLECTION_ITERATOR; - // Allows iterations through collection. + /// Allows iterations through collection. typedef ACE_Map_Entry RWLOCK_COLLECTION_ENTRY; - // Allows iterations through collection. + /// MUTEX_COLLECTION maintains a mapping from token names to mutexes. RWLOCK_COLLECTION rwlock_collection_; - // MUTEX_COLLECTION maintains a mapping from token names to mutexes. + /// Singleton pointer. static ACE_Token_Invariant_Manager *instance_; - // Singleton pointer. }; #include "ace/post.h" -- cgit v1.2.1