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