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