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 22 #include "clang/Analysis/AnalysisContext.h" 23 #include "clang/Basic/SourceLocation.h" 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. 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. 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. 65 enum LockErrorKind { 66 LEK_LockedSomeLoopIterations, 67 LEK_LockedSomePredecessors, 68 LEK_LockedAtEndOfFunction, 69 LEK_NotLockedAtEndOfFunction 70 }; 71 72 /// Handler class for thread safety warnings. 73 class ThreadSafetyHandler { 74 public: 75 typedef StringRef Name; ThreadSafetyHandler()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. handleInvalidLockExp(StringRef Kind,SourceLocation Loc)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 handleUnmatchedUnlock(StringRef Kind,Name LockName,SourceLocation Loc)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. handleIncorrectUnlockKind(StringRef Kind,Name LockName,LockKind Expected,LockKind Received,SourceLocation Loc)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. handleDoubleLock(StringRef Kind,Name LockName,SourceLocation Loc)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 handleMutexHeldEndOfScope(StringRef Kind,Name LockName,SourceLocation LocLocked,SourceLocation LocEndOfScope,LockErrorKind LEK)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. handleExclusiveAndShared(StringRef Kind,Name LockName,SourceLocation Loc1,SourceLocation Loc2)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. handleNoMutexHeld(StringRef Kind,const NamedDecl * D,ProtectedOperationKind POK,AccessKind AK,SourceLocation Loc)150 virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D, 151 ProtectedOperationKind POK, AccessKind AK, 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. handleNegativeNotHeld(StringRef Kind,Name LockName,Name Neg,SourceLocation Loc)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. handleFunExcludesLock(StringRef Kind,Name FunName,Name LockName,SourceLocation Loc)185 virtual void handleFunExcludesLock(StringRef Kind, Name FunName, 186 Name LockName, SourceLocation Loc) {} 187 188 189 /// Warn that L1 cannot be acquired before L2. handleLockAcquiredBefore(StringRef Kind,Name L1Name,Name L2Name,SourceLocation Loc)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. handleBeforeAfterCycle(Name L1Name,SourceLocation Loc)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. enterFunction(const FunctionDecl * FD)198 virtual void enterFunction(const FunctionDecl *FD) {} 199 200 /// Called by the analysis when finishing analysis of a function. leaveFunction(const FunctionDecl * FD)201 virtual void leaveFunction(const FunctionDecl *FD) {} 202 issueBetaWarnings()203 bool issueBetaWarnings() { return IssueBetaWarnings; } setIssueBetaWarnings(bool b)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. 215 void runThreadSafetyAnalysis(AnalysisDeclContext &AC, 216 ThreadSafetyHandler &Handler, 217 BeforeSet **Bset); 218 219 void threadSafetyCleanup(BeforeSet *Cache); 220 221 /// \brief Helper function that returns a LockKind required for the given level 222 /// of access. 223 LockKind getLockKindFromAccessKind(AccessKind AK); 224 225 }} // end namespace clang::threadSafety 226 #endif 227