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#threadsafety for more 15 // information. 16 // 17 //===----------------------------------------------------------------------===// 18 19 #ifndef LLVM_CLANG_THREADSAFETY_H 20 #define LLVM_CLANG_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 thread_safety { 28 29 /// This enum distinguishes between different kinds of operations that may 30 /// need to be protected by locks. We use this enum in error handling. 31 enum ProtectedOperationKind { 32 POK_VarDereference, ///< Dereferencing a variable (e.g. p in *p = 5;) 33 POK_VarAccess, ///< Reading or writing a variable (e.g. x in x = 5;) 34 POK_FunctionCall ///< Making a function call (e.g. fool()) 35 }; 36 37 /// This enum distinguishes between different kinds of lock actions. For 38 /// example, it is an error to write a variable protected by shared version of a 39 /// mutex. 40 enum LockKind { 41 LK_Shared, ///< Shared/reader lock of a mutex. 42 LK_Exclusive ///< Exclusive/writer lock of a mutex. 43 }; 44 45 /// This enum distinguishes between different ways to access (read or write) a 46 /// variable. 47 enum AccessKind { 48 AK_Read, ///< Reading a variable. 49 AK_Written ///< Writing a variable. 50 }; 51 52 /// This enum distinguishes between different situations where we warn due to 53 /// inconsistent locking. 54 /// \enum SK_LockedSomeLoopIterations -- a mutex is locked for some but not all 55 /// loop iterations. 56 /// \enum SK_LockedSomePredecessors -- a mutex is locked in some but not all 57 /// predecessors of a CFGBlock. 58 /// \enum SK_LockedAtEndOfFunction -- a mutex is still locked at the end of a 59 /// function. 60 enum LockErrorKind { 61 LEK_LockedSomeLoopIterations, 62 LEK_LockedSomePredecessors, 63 LEK_LockedAtEndOfFunction, 64 LEK_NotLockedAtEndOfFunction 65 }; 66 67 /// Handler class for thread safety warnings. 68 class ThreadSafetyHandler { 69 public: 70 typedef StringRef Name; 71 ThreadSafetyHandler() : IssueBetaWarnings(false) { } 72 virtual ~ThreadSafetyHandler(); 73 74 /// Warn about lock expressions which fail to resolve to lockable objects. 75 /// \param Loc -- the SourceLocation of the unresolved expression. 76 virtual void handleInvalidLockExp(SourceLocation Loc) {} 77 78 /// Warn about unlock function calls that do not have a prior matching lock 79 /// expression. 80 /// \param LockName -- A StringRef name for the lock expression, to be printed 81 /// in the error message. 82 /// \param Loc -- The SourceLocation of the Unlock 83 virtual void handleUnmatchedUnlock(Name LockName, SourceLocation Loc) {} 84 85 /// Warn about lock function calls for locks which are already held. 86 /// \param LockName -- A StringRef name for the lock expression, to be printed 87 /// in the error message. 88 /// \param Loc -- The location of the second lock expression. 89 virtual void handleDoubleLock(Name LockName, SourceLocation Loc) {} 90 91 /// Warn about situations where a mutex is sometimes held and sometimes not. 92 /// The three situations are: 93 /// 1. a mutex is locked on an "if" branch but not the "else" branch, 94 /// 2, or a mutex is only held at the start of some loop iterations, 95 /// 3. or when a mutex is locked but not unlocked inside a function. 96 /// \param LockName -- A StringRef name for the lock expression, to be printed 97 /// in the error message. 98 /// \param LocLocked -- The location of the lock expression where the mutex is 99 /// locked 100 /// \param LocEndOfScope -- The location of the end of the scope where the 101 /// mutex is no longer held 102 /// \param LEK -- which of the three above cases we should warn for 103 virtual void handleMutexHeldEndOfScope(Name LockName, 104 SourceLocation LocLocked, 105 SourceLocation LocEndOfScope, 106 LockErrorKind LEK){} 107 108 /// Warn when a mutex is held exclusively and shared at the same point. For 109 /// example, if a mutex is locked exclusively during an if branch and shared 110 /// during the else branch. 111 /// \param LockName -- A StringRef name for the lock expression, to be printed 112 /// in the error message. 113 /// \param Loc1 -- The location of the first lock expression. 114 /// \param Loc2 -- The location of the second lock expression. 115 virtual void handleExclusiveAndShared(Name LockName, SourceLocation Loc1, 116 SourceLocation Loc2) {} 117 118 /// Warn when a protected operation occurs while no locks are held. 119 /// \param D -- The decl for the protected variable or function 120 /// \param POK -- The kind of protected operation (e.g. variable access) 121 /// \param AK -- The kind of access (i.e. read or write) that occurred 122 /// \param Loc -- The location of the protected operation. 123 virtual void handleNoMutexHeld(const NamedDecl *D, ProtectedOperationKind POK, 124 AccessKind AK, SourceLocation Loc) {} 125 126 /// Warn when a protected operation occurs while the specific mutex protecting 127 /// the operation is not locked. 128 /// \param D -- The decl for the protected variable or function 129 /// \param POK -- The kind of protected operation (e.g. variable access) 130 /// \param LockName -- A StringRef name for the lock expression, to be printed 131 /// in the error message. 132 /// \param LK -- The kind of access (i.e. read or write) that occurred 133 /// \param Loc -- The location of the protected operation. 134 virtual void handleMutexNotHeld(const NamedDecl *D, 135 ProtectedOperationKind POK, Name LockName, 136 LockKind LK, SourceLocation Loc, 137 Name *PossibleMatch=0) {} 138 139 /// Warn when a function is called while an excluded mutex is locked. For 140 /// example, the mutex may be locked inside the function. 141 /// \param FunName -- The name of the function 142 /// \param LockName -- A StringRef name for the lock expression, to be printed 143 /// in the error message. 144 /// \param Loc -- The location of the function call. 145 virtual void handleFunExcludesLock(Name FunName, Name LockName, 146 SourceLocation Loc) {} 147 148 bool issueBetaWarnings() { return IssueBetaWarnings; } 149 void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; } 150 151 private: 152 bool IssueBetaWarnings; 153 }; 154 155 /// \brief Check a function's CFG for thread-safety violations. 156 /// 157 /// We traverse the blocks in the CFG, compute the set of mutexes that are held 158 /// at the end of each block, and issue warnings for thread safety violations. 159 /// Each block in the CFG is traversed exactly once. 160 void runThreadSafetyAnalysis(AnalysisDeclContext &AC, 161 ThreadSafetyHandler &Handler); 162 163 /// \brief Helper function that returns a LockKind required for the given level 164 /// of access. 165 LockKind getLockKindFromAccessKind(AccessKind AK); 166 167 }} // end namespace clang::thread_safety 168 #endif 169
