clang  6.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 
24 #include "llvm/ADT/StringRef.h"
25 
26 namespace clang {
27 namespace threadSafety {
28 
29 class BeforeSet;
30 
31 /// This enum distinguishes between different kinds of operations that may
32 /// need to be protected by locks. We use this enum in error handling.
34  POK_VarDereference, ///< Dereferencing a variable (e.g. p in *p = 5;)
35  POK_VarAccess, ///< Reading or writing a variable (e.g. x in x = 5;)
36  POK_FunctionCall, ///< Making a function call (e.g. fool())
37  POK_PassByRef, ///< Passing a guarded variable by reference.
38  POK_PtPassByRef, ///< Passing a pt-guarded variable by reference.
39 };
40 
41 /// This enum distinguishes between different kinds of lock actions. For
42 /// example, it is an error to write a variable protected by shared version of a
43 /// mutex.
44 enum LockKind {
45  LK_Shared, ///< Shared/reader lock of a mutex.
46  LK_Exclusive, ///< Exclusive/writer lock of a mutex.
47  LK_Generic ///< Can be either Shared or Exclusive
48 };
49 
50 /// This enum distinguishes between different ways to access (read or write) a
51 /// variable.
52 enum AccessKind {
53  AK_Read, ///< Reading a variable.
54  AK_Written ///< Writing a variable.
55 };
56 
57 /// This enum distinguishes between different situations where we warn due to
58 /// inconsistent locking.
59 /// \enum SK_LockedSomeLoopIterations -- a mutex is locked for some but not all
60 /// loop iterations.
61 /// \enum SK_LockedSomePredecessors -- a mutex is locked in some but not all
62 /// predecessors of a CFGBlock.
63 /// \enum SK_LockedAtEndOfFunction -- a mutex is still locked at the end of a
64 /// function.
70 };
71 
72 /// Handler class for thread safety warnings.
74 public:
75  typedef StringRef Name;
76  ThreadSafetyHandler() : IssueBetaWarnings(false) { }
77  virtual ~ThreadSafetyHandler();
78 
79  /// Warn about lock expressions which fail to resolve to lockable objects.
80  /// \param Kind -- the capability's name parameter (role, mutex, etc).
81  /// \param Loc -- the SourceLocation of the unresolved expression.
82  virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc) {}
83 
84  /// Warn about unlock function calls that do not have a prior matching lock
85  /// expression.
86  /// \param Kind -- the capability's name parameter (role, mutex, etc).
87  /// \param LockName -- A StringRef name for the lock expression, to be printed
88  /// in the error message.
89  /// \param Loc -- The SourceLocation of the Unlock
90  virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName,
91  SourceLocation Loc) {}
92 
93  /// Warn about an unlock function call that attempts to unlock a lock with
94  /// the incorrect lock kind. For instance, a shared lock being unlocked
95  /// exclusively, or vice versa.
96  /// \param LockName -- A StringRef name for the lock expression, to be printed
97  /// in the error message.
98  /// \param Kind -- the capability's name parameter (role, mutex, etc).
99  /// \param Expected -- the kind of lock expected.
100  /// \param Received -- the kind of lock received.
101  /// \param Loc -- The SourceLocation of the Unlock.
102  virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName,
103  LockKind Expected, LockKind Received,
104  SourceLocation Loc) {}
105 
106  /// Warn about lock function calls for locks which are already held.
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 location of the second lock expression.
111  virtual void handleDoubleLock(StringRef Kind, Name LockName,
112  SourceLocation Loc) {}
113 
114  /// Warn about situations where a mutex is sometimes held and sometimes not.
115  /// The three situations are:
116  /// 1. a mutex is locked on an "if" branch but not the "else" branch,
117  /// 2, or a mutex is only held at the start of some loop iterations,
118  /// 3. or when a mutex is locked but not unlocked inside a function.
119  /// \param Kind -- the capability's name parameter (role, mutex, etc).
120  /// \param LockName -- A StringRef name for the lock expression, to be printed
121  /// in the error message.
122  /// \param LocLocked -- The location of the lock expression where the mutex is
123  /// locked
124  /// \param LocEndOfScope -- The location of the end of the scope where the
125  /// mutex is no longer held
126  /// \param LEK -- which of the three above cases we should warn for
127  virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName,
128  SourceLocation LocLocked,
129  SourceLocation LocEndOfScope,
130  LockErrorKind LEK) {}
131 
132  /// Warn when a mutex is held exclusively and shared at the same point. For
133  /// example, if a mutex is locked exclusively during an if branch and shared
134  /// during the else branch.
135  /// \param Kind -- the capability's name parameter (role, mutex, etc).
136  /// \param LockName -- A StringRef name for the lock expression, to be printed
137  /// in the error message.
138  /// \param Loc1 -- The location of the first lock expression.
139  /// \param Loc2 -- The location of the second lock expression.
140  virtual void handleExclusiveAndShared(StringRef Kind, Name LockName,
141  SourceLocation Loc1,
142  SourceLocation Loc2) {}
143 
144  /// Warn when a protected operation occurs while no locks are held.
145  /// \param Kind -- the capability's name parameter (role, mutex, etc).
146  /// \param D -- The decl for the protected variable or function
147  /// \param POK -- The kind of protected operation (e.g. variable access)
148  /// \param AK -- The kind of access (i.e. read or write) that occurred
149  /// \param Loc -- The location of the protected operation.
150  virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D,
152  SourceLocation Loc) {}
153 
154  /// Warn when a protected operation occurs while the specific mutex protecting
155  /// the operation is not locked.
156  /// \param Kind -- the capability's name parameter (role, mutex, etc).
157  /// \param D -- The decl for the protected variable or function
158  /// \param POK -- The kind of protected operation (e.g. variable access)
159  /// \param LockName -- A StringRef name for the lock expression, to be printed
160  /// in the error message.
161  /// \param LK -- The kind of access (i.e. read or write) that occurred
162  /// \param Loc -- The location of the protected operation.
163  virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D,
164  ProtectedOperationKind POK, Name LockName,
165  LockKind LK, SourceLocation Loc,
166  Name *PossibleMatch = nullptr) {}
167 
168  /// Warn when acquiring a lock that the negative capability is not held.
169  /// \param Kind -- the capability's name parameter (role, mutex, etc).
170  /// \param LockName -- The name for the lock expression, to be printed in the
171  /// diagnostic.
172  /// \param Neg -- The name of the negative capability to be printed in the
173  /// diagnostic.
174  /// \param Loc -- The location of the protected operation.
175  virtual void handleNegativeNotHeld(StringRef Kind, Name LockName, Name Neg,
176  SourceLocation Loc) {}
177 
178  /// Warn when a function is called while an excluded mutex is locked. For
179  /// example, the mutex may be locked inside the function.
180  /// \param Kind -- the capability's name parameter (role, mutex, etc).
181  /// \param FunName -- The name of the function
182  /// \param LockName -- A StringRef name for the lock expression, to be printed
183  /// in the error message.
184  /// \param Loc -- The location of the function call.
185  virtual void handleFunExcludesLock(StringRef Kind, Name FunName,
186  Name LockName, SourceLocation Loc) {}
187 
188 
189  /// Warn that L1 cannot be acquired before L2.
190  virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name,
191  Name L2Name, SourceLocation Loc) {}
192 
193  /// Warn that there is a cycle in acquired_before/after dependencies.
194  virtual void handleBeforeAfterCycle(Name L1Name, SourceLocation Loc) {}
195 
196  /// Called by the analysis when starting analysis of a function.
197  /// Used to issue suggestions for changes to annotations.
198  virtual void enterFunction(const FunctionDecl *FD) {}
199 
200  /// Called by the analysis when finishing analysis of a function.
201  virtual void leaveFunction(const FunctionDecl *FD) {}
202 
203  bool issueBetaWarnings() { return IssueBetaWarnings; }
204  void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; }
205 
206 private:
207  bool IssueBetaWarnings;
208 };
209 
210 /// \brief Check a function's CFG for thread-safety violations.
211 ///
212 /// We traverse the blocks in the CFG, compute the set of mutexes that are held
213 /// at the end of each block, and issue warnings for thread safety violations.
214 /// Each block in the CFG is traversed exactly once.
216  ThreadSafetyHandler &Handler,
217  BeforeSet **Bset);
218 
220 
221 /// \brief Helper function that returns a LockKind required for the given level
222 /// of access.
224 
225 }} // end namespace clang::threadSafety
226 #endif
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:150
FunctionDecl - An instance of this class is created to represent a function declaration or definition...
Definition: Decl.h:1631
Passing a guarded variable by reference.
Definition: ThreadSafety.h:37
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:90
TypePropertyCache< Private > Cache
Definition: Type.cpp:3362
LockKind getLockKindFromAccessKind(AccessKind AK)
Helper function that returns a LockKind required for the given level of access.
Writing a variable.
Definition: ThreadSafety.h:54
Exclusive/writer lock of a mutex.
Definition: ThreadSafety.h:46
ProtectedOperationKind
This enum distinguishes between different kinds of operations that may need to be protected by locks...
Definition: ThreadSafety.h:33
void threadSafetyCleanup(BeforeSet *Cache)
LockKind
This enum distinguishes between different kinds of lock actions.
Definition: ThreadSafety.h:44
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:198
virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc)
Warn about lock expressions which fail to resolve to lockable objects.
Definition: ThreadSafety.h:82
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:175
Shared/reader lock of a mutex.
Definition: ThreadSafety.h:45
Passing a pt-guarded variable by reference.
Definition: ThreadSafety.h:38
Handler class for thread safety warnings.
Definition: ThreadSafety.h:73
Dereferencing a variable (e.g. p in *p = 5;)
Definition: ThreadSafety.h:34
virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name, Name L2Name, SourceLocation Loc)
Warn that L1 cannot be acquired before L2.
Definition: ThreadSafety.h:190
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:102
AccessKind
This enum distinguishes between different ways to access (read or write) a variable.
Definition: ThreadSafety.h:52
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:185
Making a function call (e.g. fool())
Definition: ThreadSafety.h:36
#define false
Definition: stdbool.h:33
Kind
Reading or writing a variable (e.g. x in x = 5;)
Definition: ThreadSafety.h:35
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:194
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:163
void runThreadSafetyAnalysis(AnalysisDeclContext &AC, ThreadSafetyHandler &Handler, BeforeSet **Bset)
Check a function&#39;s CFG for thread-safety violations.
Reading a variable.
Definition: ThreadSafety.h:53
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:140
virtual void handleDoubleLock(StringRef Kind, Name LockName, SourceLocation Loc)
Warn about lock function calls for locks which are already held.
Definition: ThreadSafety.h:111
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:127
virtual void leaveFunction(const FunctionDecl *FD)
Called by the analysis when finishing analysis of a function.
Definition: ThreadSafety.h:201
NamedDecl - This represents a decl with a name.
Definition: Decl.h:213
Can be either Shared or Exclusive.
Definition: ThreadSafety.h:47