summaryrefslogtreecommitdiff
path: root/ace/Token_Invariants.h
blob: 3bda6f2b5723ea80ae6f97c7198a5f225d94797f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
/* -*- 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.
//
// ============================================================================

#ifndef ACE_TOKEN_INVARIANTS_H
#define ACE_TOKEN_INVARIANTS_H
#include "ace/pre.h"

#include "ace/Synch.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#include "ace/Map_Manager.h"
#include "ace/Local_Tokens.h"

class ACE_Export ACE_Mutex_Invariants
{
  // = TITLE
  //     Mutex Invariants
  //
  // = INVARIANTS
  //     1. Only one owner at a time.
public:
  ACE_Mutex_Invariants (void);
  // Default construction.

  int acquired (void);
  // Returns 1 on success, 0 when an invariant has been violated and
  // -1 on error.

  void releasing (void);
  // Updates internal database.

  // = Map_Manager operations.

  ACE_Mutex_Invariants (const ACE_Mutex_Invariants &rhs);
  // Copy construction.

  void operator= (const ACE_Mutex_Invariants &rhs);
  // Copy.

  void dump (void) const;
  // Dump the state of the class.

private:
  int owners_;
  // Number of owners.  This had better be 0 >= owners_ <= 1;
};

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:
  ACE_RWLock_Invariants (void);
  // Default construction.

  int writer_acquired (void);
  // 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.

  void releasing (void);
  // Updates internal database.

  // = Map_Manager operations.

  ACE_RWLock_Invariants (const ACE_RWLock_Invariants &rhs);
  // Copy construction.

  void operator= (const ACE_RWLock_Invariants &rhs);
  // Copy.

  void dump (void) const;
  // Dump the state of the class.

private:
  int writers_;
  // Number of owning writers.

  int readers_;
  // Number of owning readers.
};

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:

  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.

  int acquired (const ACE_Token_Proxy *proxy);
  // Returns 1 on success, 0 when an invariant has been violated and
  // -1 on error.

  void releasing (const ACE_Token_Proxy *proxy);
  // Updates internal database.

  // = Explicit methods.  These to not require actual proxies in order
  // to test a scenario.

  int mutex_acquired (const ACE_TCHAR *token_name);
  // Returns 1 on success, 0 when an invariant has been violated and
  // -1 on error.

  void mutex_releasing (const ACE_TCHAR *token_name);
  // Updates internal database.

  int reader_acquired (const ACE_TCHAR *token_name);
  // 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.

  void rwlock_releasing (const ACE_TCHAR *token_name);
  // Updates internal database.

  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.
  ACE_Token_Invariant_Manager (void);
  // Prevent non-singleton construction.

  virtual ~ACE_Token_Invariant_Manager (void);
  // Destruction.

protected:
  int get_mutex (const ACE_TCHAR *token_name,
                 ACE_Mutex_Invariants *&inv);
  // Return or create.

  int get_rwlock (const ACE_TCHAR *token_name,
                  ACE_RWLock_Invariants *&inv);
  // Return or create.

  ACE_TOKEN_CONST::MUTEX lock_;
  // ACE_Mutex_Token used to lock internal data structures.

  typedef ACE_Token_Name TOKEN_NAME;
  // This may be changed to a template type.

  typedef ACE_Map_Manager<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex>
    MUTEX_COLLECTION;
  // COLLECTION maintains a mapping from token names to mutexes.

  typedef ACE_Map_Iterator<TOKEN_NAME, ACE_Mutex_Invariants *, ACE_Null_Mutex>
    MUTEX_COLLECTION_ITERATOR;
  // Allows iterations through collection.

  typedef ACE_Map_Entry<TOKEN_NAME, ACE_Mutex_Invariants *>
    MUTEX_COLLECTION_ENTRY;
  // Allows iterations through collection.

  MUTEX_COLLECTION mutex_collection_;
  // MUTEX_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.

  typedef ACE_Map_Iterator<TOKEN_NAME, ACE_RWLock_Invariants *, ACE_Null_Mutex>
    RWLOCK_COLLECTION_ITERATOR;
  // Allows iterations through collection.

  typedef ACE_Map_Entry<TOKEN_NAME, ACE_RWLock_Invariants *>
    RWLOCK_COLLECTION_ENTRY;
  // Allows iterations through collection.

  RWLOCK_COLLECTION rwlock_collection_;
  // MUTEX_COLLECTION maintains a mapping from token names to mutexes.

  static ACE_Token_Invariant_Manager *instance_;
  // Singleton pointer.
};

#include "ace/post.h"
#endif /* ACE_TOKEN_INVARIANTS_H */