Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Token_Invariants.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Token_Invariants.h
00006  *
00007  *  $Id: Token_Invariants.h,v 1.1.1.3 2001/12/04 14:33:11 chad Exp $
00008  *
00009  *  @author Tim Harrison (harrison@cs.wustl.edu)
00010  *
00011  *   Allows applications to test that invariants are always
00012  *   satisfied.  Can test mutexes and readers/writer locks.  Does
00013  *   not test recursive acquisition.
00014  *
00015  *
00016  */
00017 //=============================================================================
00018 
00019 #ifndef ACE_TOKEN_INVARIANTS_H
00020 #define ACE_TOKEN_INVARIANTS_H
00021 #include "ace/pre.h"
00022 
00023 #include "ace/Synch.h"
00024 
00025 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00026 # pragma once
00027 #endif /* ACE_LACKS_PRAGMA_ONCE */
00028 
00029 #include "ace/Map_Manager.h"
00030 #include "ace/Local_Tokens.h"
00031 
00032 #if defined (ACE_HAS_TOKENS_LIBRARY)
00033 
00034 /**
00035  * @class ACE_Mutex_Invariants
00036  *
00037  * @brief Mutex Invariants
00038  * = INVARIANTS
00039  * 1. Only one owner at a time.
00040  */
00041 class ACE_Export ACE_Mutex_Invariants
00042 {
00043 public:
00044   /// Default construction.
00045   ACE_Mutex_Invariants (void);
00046 
00047   /// Returns 1 on success, 0 when an invariant has been violated and
00048   /// -1 on error.
00049   int acquired (void);
00050 
00051   /// Updates internal database.
00052   void releasing (void);
00053 
00054   // = Map_Manager operations.
00055 
00056   /// Copy construction.
00057   ACE_Mutex_Invariants (const ACE_Mutex_Invariants &rhs);
00058 
00059   /// Copy.
00060   void operator= (const ACE_Mutex_Invariants &rhs);
00061 
00062   /// Dump the state of the class.
00063   void dump (void) const;
00064 
00065 private:
00066   /// Number of owners.  This had better be 0 >= owners_ <= 1;
00067   int owners_;
00068 };
00069 
00070 /**
00071  * @class ACE_RWLock_Invariants
00072  *
00073  * @brief RWLock Invariants
00074  *
00075  * Preserve the following invariants:
00076  * -# Only one writer at a time.
00077  * -# If there is an owning writer, there are no owning readers.
00078  */
00079 class ACE_Export ACE_RWLock_Invariants
00080 {
00081 public:
00082   /// Default construction.
00083   ACE_RWLock_Invariants (void);
00084 
00085   /// Returns 1 on success, 0 when an invariant has been violated and
00086   /// -1 on error.
00087   int writer_acquired (void);
00088 
00089   /// Returns 1 on success, 0 when an invariant has been violated and
00090   /// -1 on error.
00091   int reader_acquired (void);
00092 
00093   /// Updates internal database.
00094   void releasing (void);
00095 
00096   // = Map_Manager operations.
00097 
00098   /// Copy construction.
00099   ACE_RWLock_Invariants (const ACE_RWLock_Invariants &rhs);
00100 
00101   /// Copy.
00102   void operator= (const ACE_RWLock_Invariants &rhs);
00103 
00104   /// Dump the state of the class.
00105   void dump (void) const;
00106 
00107 private:
00108   /// Number of owning writers.
00109   int writers_;
00110 
00111   /// Number of owning readers.
00112   int readers_;
00113 };
00114 
00115 /**
00116  * @class ACE_Token_Invariant_Manager
00117  *
00118  * @brief Token Invariants
00119  *
00120  * The Token Invariant Manager allows applications to test that
00121  * invariants are always satisfied.  Currently, Token_Invariants
00122  * can test mutexes and readers/writer locks.  Does not test
00123  * recursive acquisition.
00124  * Note that this class does not ever clean its database.  Until
00125  * destroyed, it's size will forever increase.
00126  */
00127 class ACE_Export ACE_Token_Invariant_Manager : public ACE_Cleanup
00128 {
00129 public:
00130 
00131   /// Singleton access point.
00132   static ACE_Token_Invariant_Manager *instance (void);
00133 
00134   // = Polymorphic methods.  Just pass in the proxy and the method
00135   // figures out the type of the token.
00136 
00137   /// Returns 1 on success, 0 when an invariant has been violated and
00138   /// -1 on error.
00139   int acquired (const ACE_Token_Proxy *proxy);
00140 
00141   /// Updates internal database.
00142   void releasing (const ACE_Token_Proxy *proxy);
00143 
00144   // = Explicit methods.  These to not require actual proxies in order
00145   // to test a scenario.
00146 
00147   /// Returns 1 on success, 0 when an invariant has been violated and
00148   /// -1 on error.
00149   int mutex_acquired (const ACE_TCHAR *token_name);
00150 
00151   /// Updates internal database.
00152   void mutex_releasing (const ACE_TCHAR *token_name);
00153 
00154   /// Returns 1 on success, 0 when an invariant has been violated and
00155   /// -1 on error.
00156   int reader_acquired (const ACE_TCHAR *token_name);
00157 
00158   /// Returns 1 on success, 0 when an invariant has been violated and
00159   /// -1 on error.
00160   int writer_acquired (const ACE_TCHAR *token_name);
00161 
00162   /// Updates internal database.
00163   void rwlock_releasing (const ACE_TCHAR *token_name);
00164 
00165   /// Dump the state of the class.
00166   void dump (void) const;
00167 
00168   // = The following two method should be in the protected part of the
00169   //   class.  Bugs with certain compilers preclude this.
00170   /// Prevent non-singleton construction.
00171   ACE_Token_Invariant_Manager (void);
00172 
00173   /// Destruction.
00174   virtual ~ACE_Token_Invariant_Manager (void);
00175 
00176 protected:
00177   /// Return or create.
00178   int get_mutex (const ACE_TCHAR *token_name,
00179                  ACE_Mutex_Invariants *&inv);
00180 
00181   /// Return or create.
00182   int get_rwlock (const ACE_TCHAR *token_name,
00183                   ACE_RWLock_Invariants *&inv);
00184 
00185   /// ACE_Mutex_Token used to lock internal data structures.
00186   ACE_TOKEN_CONST::MUTEX lock_;
00187 
00188   /// This may be changed to a template type.
00189   typedef ACE_Token_Name TOKEN_NAME;
00190 
00191   /// COLLECTION maintains a mapping from token names to mutexes.
00192   typedef ACE_Map_Manager<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex>
00193     MUTEX_COLLECTION;
00194 
00195   /// Allows iterations through collection.
00196   typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex>
00197     MUTEX_COLLECTION_ITERATOR;
00198 
00199   /// Allows iterations through collection.
00200   typedef ACE_Map_Entry<TOKEN_NAME, ACE_Mutex_Invariants *>
00201     MUTEX_COLLECTION_ENTRY;
00202 
00203   /// MUTEX_COLLECTION maintains a mapping from token names to mutexes.
00204   MUTEX_COLLECTION mutex_collection_;
00205 
00206   /// COLLECTION maintains a mapping from token names to mutexes.
00207   typedef ACE_Map_Manager<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex>
00208     RWLOCK_COLLECTION;
00209 
00210   /// Allows iterations through collection.
00211   typedef ACE_Map_Iterator<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex>
00212     RWLOCK_COLLECTION_ITERATOR;
00213 
00214   /// Allows iterations through collection.
00215   typedef ACE_Map_Entry<TOKEN_NAME, ACE_RWLock_Invariants *>
00216     RWLOCK_COLLECTION_ENTRY;
00217 
00218   /// MUTEX_COLLECTION maintains a mapping from token names to mutexes.
00219   RWLOCK_COLLECTION rwlock_collection_;
00220 
00221   /// Singleton pointer.
00222   static ACE_Token_Invariant_Manager *instance_;
00223 };
00224 
00225 #endif /* ACE_HAS_TOKENS_LIBRARY */
00226 
00227 #include "ace/post.h"
00228 #endif /* ACE_TOKEN_INVARIANTS_H */

Generated on Mon Jun 16 11:21:57 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002