dep/ACE_wrappers/ace/Token_Invariants.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Token_Invariants.h
   6  *
   7  *  $Id: Token_Invariants.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Tim Harrison (harrison@cs.wustl.edu)
  10  *
  11  *   Allows applications to test that invariants are always
  12  *   satisfied.  Can test mutexes and readers/writer locks.  Does
  13  *   not test recursive acquisition.
  14  *
  15  *
  16  */
  17 //=============================================================================
  18
  19 #ifndef ACE_TOKEN_INVARIANTS_H
  20 #define ACE_TOKEN_INVARIANTS_H
  21 #include /**/ "ace/pre.h"
  22
  23 #include /**/ "ace/config-all.h"
  24
  25 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  26 # pragma once
  27 #endif /* ACE_LACKS_PRAGMA_ONCE */
  28
  29 #if defined (ACE_HAS_TOKENS_LIBRARY)
  30
  31 #include "ace/Map_Manager.h"
  32 #include "ace/Local_Tokens.h"
  33 #include "ace/Null_Mutex.h"
  34
  35 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  36
  37 /**
  38  * @class ACE_Mutex_Invariants
  39  *
  40  * @brief Mutex Invariants
  41  * = INVARIANTS
  42  * 1. Only one owner at a time.
  43  */
  44 class ACE_Export ACE_Mutex_Invariants
  45 {
  46 public:
  47   /// Default construction.
  48   ACE_Mutex_Invariants (void);
  49
  50   /// Returns 1 on success, 0 when an invariant has been violated and
  51   /// -1 on error.
  52   int acquired (void);
  53
  54   /// Updates internal database.
  55   void releasing (void);
  56
  57   // = Map_Manager operations.
  58
  59   /// Copy construction.
  60   ACE_Mutex_Invariants (const ACE_Mutex_Invariants &rhs);
  61
  62   /// Copy.
  63   void operator= (const ACE_Mutex_Invariants &rhs);
  64
  65   /// Dump the state of the class.
  66   void dump (void) const;
  67
  68 private:
  69   /// Number of owners.  This had better be 0 >= owners_ <= 1;
  70   int owners_;
  71 };
  72
  73 /**
  74  * @class ACE_RWLock_Invariants
  75  *
  76  * @brief RWLock Invariants
  77  *
  78  * Preserve the following invariants:
  79  * -# Only one writer at a time.
  80  * -# If there is an owning writer, there are no owning readers.
  81  */
  82 class ACE_Export ACE_RWLock_Invariants
  83 {
  84 public:
  85   /// Default construction.
  86   ACE_RWLock_Invariants (void);
  87
  88   /// Returns 1 on success, 0 when an invariant has been violated and
  89   /// -1 on error.
  90   int writer_acquired (void);
  91
  92   /// Returns 1 on success, 0 when an invariant has been violated and
  93   /// -1 on error.
  94   int reader_acquired (void);
  95
  96   /// Updates internal database.
  97   void releasing (void);
  98
  99   // = Map_Manager operations.
 100
 101   /// Copy construction.
 102   ACE_RWLock_Invariants (const ACE_RWLock_Invariants &rhs);
 103
 104   /// Copy.
 105   void operator= (const ACE_RWLock_Invariants &rhs);
 106
 107   /// Dump the state of the class.
 108   void dump (void) const;
 109
 110 private:
 111   /// Number of owning writers.
 112   int writers_;
 113
 114   /// Number of owning readers.
 115   int readers_;
 116 };
 117
 118 /**
 119  * @class ACE_Token_Invariant_Manager
 120  *
 121  * @brief Token Invariants
 122  *
 123  * The Token Invariant Manager allows applications to test that
 124  * invariants are always satisfied.  Currently, Token_Invariants
 125  * can test mutexes and readers/writer locks.  Does not test
 126  * recursive acquisition.
 127  * Note that this class does not ever clean its database.  Until
 128  * destroyed, it's size will forever increase.
 129  */
 130 class ACE_Export ACE_Token_Invariant_Manager : public ACE_Cleanup
 131 {
 132 public:
 133
 134   /// Singleton access point.
 135   static ACE_Token_Invariant_Manager *instance (void);
 136
 137   // = Polymorphic methods.  Just pass in the proxy and the method
 138   // figures out the type of the token.
 139
 140   /// Returns 1 on success, 0 when an invariant has been violated and
 141   /// -1 on error.
 142   int acquired (const ACE_Token_Proxy *proxy);
 143
 144   /// Updates internal database.
 145   void releasing (const ACE_Token_Proxy *proxy);
 146
 147   // = Explicit methods.  These to not require actual proxies in order
 148   // to test a scenario.
 149
 150   /// Returns 1 on success, 0 when an invariant has been violated and
 151   /// -1 on error.
 152   int mutex_acquired (const ACE_TCHAR *token_name);
 153
 154   /// Updates internal database.
 155   void mutex_releasing (const ACE_TCHAR *token_name);
 156
 157   /// Returns 1 on success, 0 when an invariant has been violated and
 158   /// -1 on error.
 159   int reader_acquired (const ACE_TCHAR *token_name);
 160
 161   /// Returns 1 on success, 0 when an invariant has been violated and
 162   /// -1 on error.
 163   int writer_acquired (const ACE_TCHAR *token_name);
 164
 165   /// Updates internal database.
 166   void rwlock_releasing (const ACE_TCHAR *token_name);
 167
 168   /// Dump the state of the class.
 169   void dump (void) const;
 170
 171   // = The following two method should be in the protected part of the
 172   //   class.  Bugs with certain compilers preclude this.
 173   /// Prevent non-singleton construction.
 174   ACE_Token_Invariant_Manager (void);
 175
 176   /// Destruction.
 177   virtual ~ACE_Token_Invariant_Manager (void);
 178
 179 protected:
 180   /// Return or create.
 181   int get_mutex (const ACE_TCHAR *token_name,
 182                  ACE_Mutex_Invariants *&inv);
 183
 184   /// Return or create.
 185   int get_rwlock (const ACE_TCHAR *token_name,
 186                   ACE_RWLock_Invariants *&inv);
 187
 188   /// ACE_Mutex_Token used to lock internal data structures.
 189   ACE_TOKEN_CONST::MUTEX lock_;
 190
 191   /// This may be changed to a template type.
 192   typedef ACE_Token_Name TOKEN_NAME;
 193
 194   /// COLLECTION maintains a mapping from token names to mutexes.
 195   typedef ACE_Map_Manager<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex>
 196     MUTEX_COLLECTION;
 197
 198   /// Allows iterations through collection.
 199   /**
 200    * @deprecated Deprecated typedef.  Use MUTEX_COLLECTION::ITERATOR trait
 201    * instead.
 202    */
 203   typedef MUTEX_COLLECTION::ITERATOR MUTEX_COLLECTION_ITERATOR;
 204
 205   /// Allows iterations through collection.
 206   /**
 207    * @deprecated Deprecated typedef.  Use MUTEX_COLLECTION::ENTRY trait
 208    * instead.
 209    */
 210   typedef MUTEX_COLLECTION::ENTRY MUTEX_COLLECTION_ENTRY;
 211
 212   /// MUTEX_COLLECTION maintains a mapping from token names to mutexes.
 213   MUTEX_COLLECTION mutex_collection_;
 214
 215   /// COLLECTION maintains a mapping from token names to mutexes.
 216   typedef ACE_Map_Manager<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex>
 217     RWLOCK_COLLECTION;
 218
 219   /// Allows iterations through collection.
 220   /**
 221    * @deprecated Deprecated typedef.  Use RWLOCK_COLLECTION::ITERATOR trait
 222    * instead.
 223    */
 224   typedef RWLOCK_COLLECTION::ITERATOR RWLOCK_COLLECTION_ITERATOR;
 225
 226   /// Allows iterations through collection.
 227   /**
 228    * @deprecated Deprecated typedef.  Use RWLOCK_COLLECTION::ENTRY trait
 229    * instead.
 230    */
 231   typedef RWLOCK_COLLECTION::ENTRY RWLOCK_COLLECTION_ENTRY;
 232
 233   /// MUTEX_COLLECTION maintains a mapping from token names to mutexes.
 234   RWLOCK_COLLECTION rwlock_collection_;
 235
 236   /// Singleton pointer.
 237   static ACE_Token_Invariant_Manager *instance_;
 238 };
 239
 240 ACE_END_VERSIONED_NAMESPACE_DECL
 241
 242 #endif /* ACE_HAS_TOKENS_LIBRARY */
 243
 244 #include /**/ "ace/post.h"
 245 #endif /* ACE_TOKEN_INVARIANTS_H */