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 26namespace clang { 27namespace 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. 31enum 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. 40enum 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. 47enum 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. 60enum LockErrorKind { 61 LEK_LockedSomeLoopIterations, 62 LEK_LockedSomePredecessors, 63 LEK_LockedAtEndOfFunction, 64 LEK_NotLockedAtEndOfFunction 65}; 66 67/// Handler class for thread safety warnings. 68class ThreadSafetyHandler { 69public: 70 typedef llvm::StringRef Name; 71 virtual ~ThreadSafetyHandler(); 72 73 /// Warn about lock expressions which fail to resolve to lockable objects. 74 /// \param Loc -- the SourceLocation of the unresolved expression. 75 virtual void handleInvalidLockExp(SourceLocation Loc) {} 76 77 /// Warn about unlock function calls that do not have a prior matching lock 78 /// expression. 79 /// \param LockName -- A StringRef name for the lock expression, to be printed 80 /// in the error message. 81 /// \param Loc -- The SourceLocation of the Unlock 82 virtual void handleUnmatchedUnlock(Name LockName, SourceLocation Loc) {} 83 84 /// Warn about lock function calls for locks which are already held. 85 /// \param LockName -- A StringRef name for the lock expression, to be printed 86 /// in the error message. 87 /// \param Loc -- The location of the second lock expression. 88 virtual void handleDoubleLock(Name LockName, SourceLocation Loc) {} 89 90 /// Warn about situations where a mutex is sometimes held and sometimes not. 91 /// The three situations are: 92 /// 1. a mutex is locked on an "if" branch but not the "else" branch, 93 /// 2, or a mutex is only held at the start of some loop iterations, 94 /// 3. or when a mutex is locked but not unlocked inside a function. 95 /// \param LockName -- A StringRef name for the lock expression, to be printed 96 /// in the error message. 97 /// \param LocLocked -- The location of the lock expression where the mutex is 98 /// locked 99 /// \param LocEndOfScope -- The location of the end of the scope where the 100 /// mutex is no longer held 101 /// \param LEK -- which of the three above cases we should warn for 102 virtual void handleMutexHeldEndOfScope(Name LockName, 103 SourceLocation LocLocked, 104 SourceLocation LocEndOfScope, 105 LockErrorKind LEK){} 106 107 /// Warn when a mutex is held exclusively and shared at the same point. For 108 /// example, if a mutex is locked exclusively during an if branch and shared 109 /// during the else branch. 110 /// \param LockName -- A StringRef name for the lock expression, to be printed 111 /// in the error message. 112 /// \param Loc1 -- The location of the first lock expression. 113 /// \param Loc2 -- The location of the second lock expression. 114 virtual void handleExclusiveAndShared(Name LockName, SourceLocation Loc1, 115 SourceLocation Loc2) {} 116 117 /// Warn when a protected operation occurs while no locks are held. 118 /// \param D -- The decl for the protected variable or function 119 /// \param POK -- The kind of protected operation (e.g. variable access) 120 /// \param AK -- The kind of access (i.e. read or write) that occurred 121 /// \param Loc -- The location of the protected operation. 122 virtual void handleNoMutexHeld(const NamedDecl *D, ProtectedOperationKind POK, 123 AccessKind AK, SourceLocation Loc) {} 124 125 /// Warn when a protected operation occurs while the specific mutex protecting 126 /// the operation is not locked. 127 /// \param D -- The decl for the protected variable or function 128 /// \param POK -- The kind of protected operation (e.g. variable access) 129 /// \param LockName -- A StringRef name for the lock expression, to be printed 130 /// in the error message. 131 /// \param LK -- The kind of access (i.e. read or write) that occurred 132 /// \param Loc -- The location of the protected operation. 133 virtual void handleMutexNotHeld(const NamedDecl *D, 134 ProtectedOperationKind POK, Name LockName, 135 LockKind LK, SourceLocation Loc, 136 Name *PossibleMatch=0) {} 137 138 /// Warn when a function is called while an excluded mutex is locked. For 139 /// example, the mutex may be locked inside the function. 140 /// \param FunName -- The name of the function 141 /// \param LockName -- A StringRef name for the lock expression, to be printed 142 /// in the error message. 143 /// \param Loc -- The location of the function call. 144 virtual void handleFunExcludesLock(Name FunName, Name LockName, 145 SourceLocation Loc) {} 146}; 147 148/// \brief Check a function's CFG for thread-safety violations. 149/// 150/// We traverse the blocks in the CFG, compute the set of mutexes that are held 151/// at the end of each block, and issue warnings for thread safety violations. 152/// Each block in the CFG is traversed exactly once. 153void runThreadSafetyAnalysis(AnalysisDeclContext &AC, 154 ThreadSafetyHandler &Handler); 155 156/// \brief Helper function that returns a LockKind required for the given level 157/// of access. 158LockKind getLockKindFromAccessKind(AccessKind AK); 159 160}} // end namespace clang::thread_safety 161#endif 162