clang  8.0.0svn
ThreadSafety.h
Go to the documentation of this file.
1 //===- ThreadSafety.h -------------------------------------------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 //
11 // A intra-procedural analysis for thread safety (e.g. deadlocks and race
12 // conditions), based off of an annotation system.
13 //
14 // See http://clang.llvm.org/docs/LanguageExtensions.html#thread-safety-annotation-checking
15 // for more information.
16 //
17 //===----------------------------------------------------------------------===//
18 
19 #ifndef LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
20 #define LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
21 
23 #include "llvm/ADT/StringRef.h"
24 
25 namespace clang {
26 
27 class AnalysisDeclContext;
28 class FunctionDecl;
29 class NamedDecl;
30 
31 namespace threadSafety {
32 
33 class BeforeSet;
34 
35 /// This enum distinguishes between different kinds of operations that may
36 /// need to be protected by locks. We use this enum in error handling.
38  /// Dereferencing a variable (e.g. p in *p = 5;)
40 
41  /// Reading or writing a variable (e.g. x in x = 5;)
43 
44  /// Making a function call (e.g. fool())
46 
47  /// Passing a guarded variable by reference.
49 
50  /// Passing a pt-guarded variable by reference.
52 };
53 
54 /// This enum distinguishes between different kinds of lock actions. For
55 /// example, it is an error to write a variable protected by shared version of a
56 /// mutex.
57 enum LockKind {
58  /// Shared/reader lock of a mutex.
60 
61  /// Exclusive/writer lock of a mutex.
63 
64  /// Can be either Shared or Exclusive.
66 };
67 
68 /// This enum distinguishes between different ways to access (read or write) a
69 /// variable.
70 enum AccessKind {
71  /// Reading a variable.
73 
74  /// Writing a variable.
76 };
77 
78 /// This enum distinguishes between different situations where we warn due to
79 /// inconsistent locking.
80 /// \enum SK_LockedSomeLoopIterations -- a mutex is locked for some but not all
81 /// loop iterations.
82 /// \enum SK_LockedSomePredecessors -- a mutex is locked in some but not all
83 /// predecessors of a CFGBlock.
84 /// \enum SK_LockedAtEndOfFunction -- a mutex is still locked at the end of a
85 /// function.
91 };
92 
93 /// Handler class for thread safety warnings.
95 public:
96  using Name = StringRef;
97 
98  ThreadSafetyHandler() = default;
99  virtual ~ThreadSafetyHandler();
100 
101  /// Warn about lock expressions which fail to resolve to lockable objects.
102  /// \param Kind -- the capability's name parameter (role, mutex, etc).
103  /// \param Loc -- the SourceLocation of the unresolved expression.
104  virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc) {}
105 
106  /// Warn about unlock function calls that do not have a prior matching lock
107  /// expression.
108  /// \param Kind -- the capability's name parameter (role, mutex, etc).
109  /// \param LockName -- A StringRef name for the lock expression, to be printed
110  /// in the error message.
111  /// \param Loc -- The SourceLocation of the Unlock
112  virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName,
113  SourceLocation Loc) {}
114 
115  /// Warn about an unlock function call that attempts to unlock a lock with
116  /// the incorrect lock kind. For instance, a shared lock being unlocked
117  /// exclusively, or vice versa.
118  /// \param LockName -- A StringRef name for the lock expression, to be printed
119  /// in the error message.
120  /// \param Kind -- the capability's name parameter (role, mutex, etc).
121  /// \param Expected -- the kind of lock expected.
122  /// \param Received -- the kind of lock received.
123  /// \param Loc -- The SourceLocation of the Unlock.
124  virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName,
125  LockKind Expected, LockKind Received,
126  SourceLocation Loc) {}
127 
128  /// Warn about lock function calls for locks which are already held.
129  /// \param Kind -- the capability's name parameter (role, mutex, etc).
130  /// \param LockName -- A StringRef name for the lock expression, to be printed
131  /// in the error message.
132  /// \param Loc -- The location of the second lock expression.
133  virtual void handleDoubleLock(StringRef Kind, Name LockName,
134  SourceLocation Loc) {}
135 
136  /// Warn about situations where a mutex is sometimes held and sometimes not.
137  /// The three situations are:
138  /// 1. a mutex is locked on an "if" branch but not the "else" branch,
139  /// 2, or a mutex is only held at the start of some loop iterations,
140  /// 3. or when a mutex is locked but not unlocked inside a function.
141  /// \param Kind -- the capability's name parameter (role, mutex, etc).
142  /// \param LockName -- A StringRef name for the lock expression, to be printed
143  /// in the error message.
144  /// \param LocLocked -- The location of the lock expression where the mutex is
145  /// locked
146  /// \param LocEndOfScope -- The location of the end of the scope where the
147  /// mutex is no longer held
148  /// \param LEK -- which of the three above cases we should warn for
149  virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName,
150  SourceLocation LocLocked,
151  SourceLocation LocEndOfScope,
152  LockErrorKind LEK) {}
153 
154  /// Warn when a mutex is held exclusively and shared at the same point. For
155  /// example, if a mutex is locked exclusively during an if branch and shared
156  /// during the else branch.
157  /// \param Kind -- the capability's name parameter (role, mutex, etc).
158  /// \param LockName -- A StringRef name for the lock expression, to be printed
159  /// in the error message.
160  /// \param Loc1 -- The location of the first lock expression.
161  /// \param Loc2 -- The location of the second lock expression.
162  virtual void handleExclusiveAndShared(StringRef Kind, Name LockName,
163  SourceLocation Loc1,
164  SourceLocation Loc2) {}
165 
166  /// Warn when a protected operation occurs while no locks are held.
167  /// \param Kind -- the capability's name parameter (role, mutex, etc).
168  /// \param D -- The decl for the protected variable or function
169  /// \param POK -- The kind of protected operation (e.g. variable access)
170  /// \param AK -- The kind of access (i.e. read or write) that occurred
171  /// \param Loc -- The location of the protected operation.
172  virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D,
174  SourceLocation Loc) {}
175 
176  /// Warn when a protected operation occurs while the specific mutex protecting
177  /// the operation is not locked.
178  /// \param Kind -- the capability's name parameter (role, mutex, etc).
179  /// \param D -- The decl for the protected variable or function
180  /// \param POK -- The kind of protected operation (e.g. variable access)
181  /// \param LockName -- A StringRef name for the lock expression, to be printed
182  /// in the error message.
183  /// \param LK -- The kind of access (i.e. read or write) that occurred
184  /// \param Loc -- The location of the protected operation.
185  virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D,
186  ProtectedOperationKind POK, Name LockName,
187  LockKind LK, SourceLocation Loc,
188  Name *PossibleMatch = nullptr) {}
189 
190  /// Warn when acquiring a lock that the negative capability is not held.
191  /// \param Kind -- the capability's name parameter (role, mutex, etc).
192  /// \param LockName -- The name for the lock expression, to be printed in the
193  /// diagnostic.
194  /// \param Neg -- The name of the negative capability to be printed in the
195  /// diagnostic.
196  /// \param Loc -- The location of the protected operation.
197  virtual void handleNegativeNotHeld(StringRef Kind, Name LockName, Name Neg,
198  SourceLocation Loc) {}
199 
200  /// Warn when a function is called while an excluded mutex is locked. For
201  /// example, the mutex may be locked inside the function.
202  /// \param Kind -- the capability's name parameter (role, mutex, etc).
203  /// \param FunName -- The name of the function
204  /// \param LockName -- A StringRef name for the lock expression, to be printed
205  /// in the error message.
206  /// \param Loc -- The location of the function call.
207  virtual void handleFunExcludesLock(StringRef Kind, Name FunName,
208  Name LockName, SourceLocation Loc) {}
209 
210  /// Warn that L1 cannot be acquired before L2.
211  virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name,
212  Name L2Name, SourceLocation Loc) {}
213 
214  /// Warn that there is a cycle in acquired_before/after dependencies.
215  virtual void handleBeforeAfterCycle(Name L1Name, SourceLocation Loc) {}
216 
217  /// Called by the analysis when starting analysis of a function.
218  /// Used to issue suggestions for changes to annotations.
219  virtual void enterFunction(const FunctionDecl *FD) {}
220 
221  /// Called by the analysis when finishing analysis of a function.
222  virtual void leaveFunction(const FunctionDecl *FD) {}
223 
224  bool issueBetaWarnings() { return IssueBetaWarnings; }
225  void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; }
226 
227 private:
228  bool IssueBetaWarnings = false;
229 };
230 
231 /// Check a function's CFG for thread-safety violations.
232 ///
233 /// We traverse the blocks in the CFG, compute the set of mutexes that are held
234 /// at the end of each block, and issue warnings for thread safety violations.
235 /// Each block in the CFG is traversed exactly once.
237  ThreadSafetyHandler &Handler,
238  BeforeSet **Bset);
239 
241 
242 /// Helper function that returns a LockKind required for the given level
243 /// of access.
245 
246 } // namespace threadSafety
247 } // namespace clang
248 
249 #endif // LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D, ProtectedOperationKind POK, AccessKind AK, SourceLocation Loc)
Warn when a protected operation occurs while no locks are held.
Definition: ThreadSafety.h:172
Represents a function declaration or definition.
Definition: Decl.h:1732
Passing a guarded variable by reference.
Definition: ThreadSafety.h:48
TypePropertyCache< Private > Cache
Definition: Type.cpp:3465
virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName, SourceLocation Loc)
Warn about unlock function calls that do not have a prior matching lock expression.
Definition: ThreadSafety.h:112
LockKind getLockKindFromAccessKind(AccessKind AK)
Helper function that returns a LockKind required for the given level of access.
Writing a variable.
Definition: ThreadSafety.h:75
Exclusive/writer lock of a mutex.
Definition: ThreadSafety.h:62
ProtectedOperationKind
This enum distinguishes between different kinds of operations that may need to be protected by locks...
Definition: ThreadSafety.h:37
void threadSafetyCleanup(BeforeSet *Cache)
LockKind
This enum distinguishes between different kinds of lock actions.
Definition: ThreadSafety.h:57
AnalysisDeclContext contains the context data for the function or method under analysis.
virtual void enterFunction(const FunctionDecl *FD)
Called by the analysis when starting analysis of a function.
Definition: ThreadSafety.h:219
virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc)
Warn about lock expressions which fail to resolve to lockable objects.
Definition: ThreadSafety.h:104
virtual void handleNegativeNotHeld(StringRef Kind, Name LockName, Name Neg, SourceLocation Loc)
Warn when acquiring a lock that the negative capability is not held.
Definition: ThreadSafety.h:197
Shared/reader lock of a mutex.
Definition: ThreadSafety.h:59
Passing a pt-guarded variable by reference.
Definition: ThreadSafety.h:51
Handler class for thread safety warnings.
Definition: ThreadSafety.h:94
Dereferencing a variable (e.g. p in *p = 5;)
Definition: ThreadSafety.h:39
virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name, Name L2Name, SourceLocation Loc)
Warn that L1 cannot be acquired before L2.
Definition: ThreadSafety.h:211
virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName, LockKind Expected, LockKind Received, SourceLocation Loc)
Warn about an unlock function call that attempts to unlock a lock with the incorrect lock kind...
Definition: ThreadSafety.h:124
AccessKind
This enum distinguishes between different ways to access (read or write) a variable.
Definition: ThreadSafety.h:70
virtual void handleFunExcludesLock(StringRef Kind, Name FunName, Name LockName, SourceLocation Loc)
Warn when a function is called while an excluded mutex is locked.
Definition: ThreadSafety.h:207
Making a function call (e.g. fool())
Definition: ThreadSafety.h:45
Kind
Reading or writing a variable (e.g. x in x = 5;)
Definition: ThreadSafety.h:42
Encodes a location in the source.
virtual void handleBeforeAfterCycle(Name L1Name, SourceLocation Loc)
Warn that there is a cycle in acquired_before/after dependencies.
Definition: ThreadSafety.h:215
Dataflow Directional Tag Classes.
virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D, ProtectedOperationKind POK, Name LockName, LockKind LK, SourceLocation Loc, Name *PossibleMatch=nullptr)
Warn when a protected operation occurs while the specific mutex protecting the operation is not locke...
Definition: ThreadSafety.h:185
void runThreadSafetyAnalysis(AnalysisDeclContext &AC, ThreadSafetyHandler &Handler, BeforeSet **Bset)
Check a function&#39;s CFG for thread-safety violations.
Reading a variable.
Definition: ThreadSafety.h:72
virtual void handleExclusiveAndShared(StringRef Kind, Name LockName, SourceLocation Loc1, SourceLocation Loc2)
Warn when a mutex is held exclusively and shared at the same point.
Definition: ThreadSafety.h:162
virtual void handleDoubleLock(StringRef Kind, Name LockName, SourceLocation Loc)
Warn about lock function calls for locks which are already held.
Definition: ThreadSafety.h:133
Defines the clang::SourceLocation class and associated facilities.
virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName, SourceLocation LocLocked, SourceLocation LocEndOfScope, LockErrorKind LEK)
Warn about situations where a mutex is sometimes held and sometimes not.
Definition: ThreadSafety.h:149
virtual void leaveFunction(const FunctionDecl *FD)
Called by the analysis when finishing analysis of a function.
Definition: ThreadSafety.h:222
This represents a decl that may have a name.
Definition: Decl.h:248
Can be either Shared or Exclusive.
Definition: ThreadSafety.h:65