ACE/ace/Token_Invariants.h

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