ChangeLogTag:Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu>

1 files changed, 92 insertions, 88 deletions

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<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex>
     MUTEX_COLLECTION;
-  // COLLECTION maintains a mapping from token names to mutexes.
 
+  /// Allows iterations through collection.
   typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex>
     MUTEX_COLLECTION_ITERATOR;
-  // Allows iterations through collection.
 
+  /// Allows iterations through collection.
   typedef ACE_Map_Entry<TOKEN_NAME, ACE_Mutex_Invariants *>
     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<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex>
     RWLOCK_COLLECTION;
-  // COLLECTION maintains a mapping from token names to mutexes.
 
+  /// Allows iterations through collection.
   typedef ACE_Map_Iterator<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex>
     RWLOCK_COLLECTION_ITERATOR;
-  // Allows iterations through collection.
 
+  /// Allows iterations through collection.
   typedef ACE_Map_Entry<TOKEN_NAME, ACE_RWLock_Invariants *>
     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"