1 //===- ThreadSafety.h ------------------------------------------*- C++ --*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
11 // A intra-procedural analysis for thread safety (e.g. deadlocks and race
12 // conditions), based off of an annotation system.
14 // See http://clang.llvm.org/docs/LanguageExtensions.html#thread-safety-annotation-checking
15 // for more information.
17 //===----------------------------------------------------------------------===//
19 #ifndef LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
20 #define LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
22 #include "clang/Analysis/AnalysisDeclContext.h"
23 #include "clang/Basic/SourceLocation.h"
24 #include "llvm/ADT/StringRef.h"
27 namespace threadSafety {
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.
33 enum ProtectedOperationKind {
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.
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
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
50 /// This enum distinguishes between different ways to access (read or write) a
53 AK_Read, ///< Reading a variable.
54 AK_Written ///< Writing a variable.
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
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
66 LEK_LockedSomeLoopIterations,
67 LEK_LockedSomePredecessors,
68 LEK_LockedAtEndOfFunction,
69 LEK_NotLockedAtEndOfFunction
72 /// Handler class for thread safety warnings.
73 class ThreadSafetyHandler {
75 typedef StringRef Name;
76 ThreadSafetyHandler() : IssueBetaWarnings(false) { }
77 virtual ~ThreadSafetyHandler();
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) {}
84 /// Warn about unlock function calls that do not have a prior matching lock
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) {}
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) {}
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) {}
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
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) {}
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,
142 SourceLocation Loc2) {}
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,
151 ProtectedOperationKind POK, AccessKind AK,
152 SourceLocation Loc) {}
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) {}
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
172 /// \param Neg -- The name of the negative capability to be printed in the
174 /// \param Loc -- The location of the protected operation.
175 virtual void handleNegativeNotHeld(StringRef Kind, Name LockName, Name Neg,
176 SourceLocation Loc) {}
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) {}
189 /// Warn that L1 cannot be acquired before L2.
190 virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name,
191 Name L2Name, SourceLocation Loc) {}
193 /// Warn that there is a cycle in acquired_before/after dependencies.
194 virtual void handleBeforeAfterCycle(Name L1Name, SourceLocation Loc) {}
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) {}
200 /// Called by the analysis when finishing analysis of a function.
201 virtual void leaveFunction(const FunctionDecl *FD) {}
203 bool issueBetaWarnings() { return IssueBetaWarnings; }
204 void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; }
207 bool IssueBetaWarnings;
210 /// \brief Check a function's CFG for thread-safety violations.
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.
215 void runThreadSafetyAnalysis(AnalysisDeclContext &AC,
216 ThreadSafetyHandler &Handler,
219 void threadSafetyCleanup(BeforeSet *Cache);
221 /// \brief Helper function that returns a LockKind required for the given level
223 LockKind getLockKindFromAccessKind(AccessKind AK);
225 }} // end namespace clang::threadSafety