1402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski//===- ThreadSafety.h ------------------------------------------*- C++ --*-===// 2402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// 3402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// The LLVM Compiler Infrastructure 4402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// 5402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// This file is distributed under the University of Illinois Open Source 6402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// License. See LICENSE.TXT for details. 7402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// 8402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski//===----------------------------------------------------------------------===// 9402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// 10402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// 11402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// A intra-procedural analysis for thread safety (e.g. deadlocks and race 12402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// conditions), based off of an annotation system. 13402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// 14eb7c6f3c49b4b3c2b01aeeed54bf5915fbf9b021Aaron Ballman// See http://clang.llvm.org/docs/LanguageExtensions.html#thread-safety-annotation-checking 15eb7c6f3c49b4b3c2b01aeeed54bf5915fbf9b021Aaron Ballman// for more information. 16402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski// 17402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski//===----------------------------------------------------------------------===// 18402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 19402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski#ifndef LLVM_CLANG_THREADSAFETY_H 20402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski#define LLVM_CLANG_THREADSAFETY_H 21402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 22d5b16055782034ca90153880c36bd88b59c63aa0Caitlin Sadowski#include "clang/Analysis/AnalysisContext.h" 23402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski#include "clang/Basic/SourceLocation.h" 24402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski#include "llvm/ADT/StringRef.h" 25402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 26402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowskinamespace clang { 27402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowskinamespace thread_safety { 28402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 2919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// This enum distinguishes between different kinds of operations that may 3019903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// need to be protected by locks. We use this enum in error handling. 31402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowskienum ProtectedOperationKind { 32959dc8475fc20ce8c3fd55021cb9f02a531cddc5Dmitri Gribenko POK_VarDereference, ///< Dereferencing a variable (e.g. p in *p = 5;) 33959dc8475fc20ce8c3fd55021cb9f02a531cddc5Dmitri Gribenko POK_VarAccess, ///< Reading or writing a variable (e.g. x in x = 5;) 34959dc8475fc20ce8c3fd55021cb9f02a531cddc5Dmitri Gribenko POK_FunctionCall ///< Making a function call (e.g. fool()) 35402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski}; 36402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 3719903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// This enum distinguishes between different kinds of lock actions. For 3819903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// example, it is an error to write a variable protected by shared version of a 3919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// mutex. 40402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowskienum LockKind { 41959dc8475fc20ce8c3fd55021cb9f02a531cddc5Dmitri Gribenko LK_Shared, ///< Shared/reader lock of a mutex. 42651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines LK_Exclusive, ///< Exclusive/writer lock of a mutex. 43651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines LK_Generic ///< Can be either Shared or Exclusive 44402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski}; 45402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 4619903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// This enum distinguishes between different ways to access (read or write) a 4719903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// variable. 48402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowskienum AccessKind { 49959dc8475fc20ce8c3fd55021cb9f02a531cddc5Dmitri Gribenko AK_Read, ///< Reading a variable. 50959dc8475fc20ce8c3fd55021cb9f02a531cddc5Dmitri Gribenko AK_Written ///< Writing a variable. 51402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski}; 52402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 534e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// This enum distinguishes between different situations where we warn due to 544e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// inconsistent locking. 554e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// \enum SK_LockedSomeLoopIterations -- a mutex is locked for some but not all 564e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// loop iterations. 574e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// \enum SK_LockedSomePredecessors -- a mutex is locked in some but not all 584e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// predecessors of a CFGBlock. 594e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// \enum SK_LockedAtEndOfFunction -- a mutex is still locked at the end of a 604e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski/// function. 614e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowskienum LockErrorKind { 624e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski LEK_LockedSomeLoopIterations, 634e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski LEK_LockedSomePredecessors, 64879a4334e4c4cab0c22ba91492ffc2838bbc21fcDeLesley Hutchins LEK_LockedAtEndOfFunction, 65879a4334e4c4cab0c22ba91492ffc2838bbc21fcDeLesley Hutchins LEK_NotLockedAtEndOfFunction 664e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski}; 674e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski 6819903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// Handler class for thread safety warnings. 69402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowskiclass ThreadSafetyHandler { 70402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowskipublic: 71cfa88f893915ceb8ae4ce2f17c46c24a4d67502fDmitri Gribenko typedef StringRef Name; 72fb4afc2fc659faff43a6df4c1d0e07df9c90479dDeLesley Hutchins ThreadSafetyHandler() : IssueBetaWarnings(false) { } 739f80a97408ee0da939654d851ff42ad07d47e9c7DeLesley Hutchins virtual ~ThreadSafetyHandler(); 7419903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 7519903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn about lock expressions which fail to resolve to lockable objects. 76651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 7719903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param Loc -- the SourceLocation of the unresolved expression. 78651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc) {} 7919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 8019903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn about unlock function calls that do not have a prior matching lock 8119903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// expression. 82651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 8319903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param LockName -- A StringRef name for the lock expression, to be printed 8419903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// in the error message. 8519903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param Loc -- The SourceLocation of the Unlock 86651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName, 87651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines SourceLocation Loc) {} 88651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines 89651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// Warn about an unlock function call that attempts to unlock a lock with 90651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// the incorrect lock kind. For instance, a shared lock being unlocked 91651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// exclusively, or vice versa. 92651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param LockName -- A StringRef name for the lock expression, to be printed 93651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// in the error message. 94651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 95651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Expected -- the kind of lock expected. 96651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Received -- the kind of lock received. 97651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Loc -- The SourceLocation of the Unlock. 98651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName, 99651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines LockKind Expected, LockKind Received, 100651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines SourceLocation Loc) {} 10119903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 10219903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn about lock function calls for locks which are already held. 103651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 10419903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param LockName -- A StringRef name for the lock expression, to be printed 10519903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// in the error message. 106b50dd472cd6c8b13213626f13a928dbe41581f09Caitlin Sadowski /// \param Loc -- The location of the second lock expression. 107651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleDoubleLock(StringRef Kind, Name LockName, 108651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines SourceLocation Loc) {} 10919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 11019903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn about situations where a mutex is sometimes held and sometimes not. 1114e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski /// The three situations are: 1124e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski /// 1. a mutex is locked on an "if" branch but not the "else" branch, 1134e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski /// 2, or a mutex is only held at the start of some loop iterations, 1144e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski /// 3. or when a mutex is locked but not unlocked inside a function. 115651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 11619903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param LockName -- A StringRef name for the lock expression, to be printed 11719903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// in the error message. 1182e5156274b8051217565b557bfa14c80f7990e9cRichard Smith /// \param LocLocked -- The location of the lock expression where the mutex is 119ba243b59a1074e0962f6abfa3bb9aa984eac1245David Blaikie /// locked 1202e5156274b8051217565b557bfa14c80f7990e9cRichard Smith /// \param LocEndOfScope -- The location of the end of the scope where the 1212e5156274b8051217565b557bfa14c80f7990e9cRichard Smith /// mutex is no longer held 1224e4bc75d3570835e13183c66ac08974cdc016007Caitlin Sadowski /// \param LEK -- which of the three above cases we should warn for 123651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName, 1242e5156274b8051217565b557bfa14c80f7990e9cRichard Smith SourceLocation LocLocked, 1252e5156274b8051217565b557bfa14c80f7990e9cRichard Smith SourceLocation LocEndOfScope, 126651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines LockErrorKind LEK) {} 12719903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 12819903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn when a mutex is held exclusively and shared at the same point. For 12919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// example, if a mutex is locked exclusively during an if branch and shared 13019903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// during the else branch. 131651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 13219903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param LockName -- A StringRef name for the lock expression, to be printed 13319903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// in the error message. 134b50dd472cd6c8b13213626f13a928dbe41581f09Caitlin Sadowski /// \param Loc1 -- The location of the first lock expression. 135b50dd472cd6c8b13213626f13a928dbe41581f09Caitlin Sadowski /// \param Loc2 -- The location of the second lock expression. 136651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleExclusiveAndShared(StringRef Kind, Name LockName, 137651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines SourceLocation Loc1, 138402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski SourceLocation Loc2) {} 13919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 14019903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn when a protected operation occurs while no locks are held. 141651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 14219903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param D -- The decl for the protected variable or function 14319903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param POK -- The kind of protected operation (e.g. variable access) 14419903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param AK -- The kind of access (i.e. read or write) that occurred 145b50dd472cd6c8b13213626f13a928dbe41581f09Caitlin Sadowski /// \param Loc -- The location of the protected operation. 146651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D, 147651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines ProtectedOperationKind POK, AccessKind AK, 148651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines SourceLocation Loc) {} 14919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 15019903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn when a protected operation occurs while the specific mutex protecting 15119903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// the operation is not locked. 152651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 15319903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param D -- The decl for the protected variable or function 15419903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param POK -- The kind of protected operation (e.g. variable access) 155edd6d40770c9010883307b195acea6e9d732263aJames Dennett /// \param LockName -- A StringRef name for the lock expression, to be printed 156edd6d40770c9010883307b195acea6e9d732263aJames Dennett /// in the error message. 157edd6d40770c9010883307b195acea6e9d732263aJames Dennett /// \param LK -- The kind of access (i.e. read or write) that occurred 158b50dd472cd6c8b13213626f13a928dbe41581f09Caitlin Sadowski /// \param Loc -- The location of the protected operation. 159651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D, 160402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski ProtectedOperationKind POK, Name LockName, 1613f0ec5209726641782468bd4c7597e79dda78b15DeLesley Hutchins LockKind LK, SourceLocation Loc, 1626bcf27bb9a4b5c3f79cb44c0e4654a6d7619ad89Stephen Hines Name *PossibleMatch = nullptr) {} 16319903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 16419903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// Warn when a function is called while an excluded mutex is locked. For 16519903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// example, the mutex may be locked inside the function. 166651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines /// \param Kind -- the capability's name parameter (role, mutex, etc). 16719903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param FunName -- The name of the function 16819903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// \param LockName -- A StringRef name for the lock expression, to be printed 16919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski /// in the error message. 170b50dd472cd6c8b13213626f13a928dbe41581f09Caitlin Sadowski /// \param Loc -- The location of the function call. 171651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines virtual void handleFunExcludesLock(StringRef Kind, Name FunName, 172651f13cea278ec967336033dd032faef0e9fc2ecStephen Hines Name LockName, SourceLocation Loc) {} 173fb4afc2fc659faff43a6df4c1d0e07df9c90479dDeLesley Hutchins 174fb4afc2fc659faff43a6df4c1d0e07df9c90479dDeLesley Hutchins bool issueBetaWarnings() { return IssueBetaWarnings; } 175fb4afc2fc659faff43a6df4c1d0e07df9c90479dDeLesley Hutchins void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; } 176fb4afc2fc659faff43a6df4c1d0e07df9c90479dDeLesley Hutchins 177fb4afc2fc659faff43a6df4c1d0e07df9c90479dDeLesley Hutchinsprivate: 178fb4afc2fc659faff43a6df4c1d0e07df9c90479dDeLesley Hutchins bool IssueBetaWarnings; 179402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski}; 180402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 18119903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// \brief Check a function's CFG for thread-safety violations. 18219903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// 18319903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// We traverse the blocks in the CFG, compute the set of mutexes that are held 18419903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// at the end of each block, and issue warnings for thread safety violations. 18519903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// Each block in the CFG is traversed exactly once. 186ba243b59a1074e0962f6abfa3bb9aa984eac1245David Blaikievoid runThreadSafetyAnalysis(AnalysisDeclContext &AC, 187ba243b59a1074e0962f6abfa3bb9aa984eac1245David Blaikie ThreadSafetyHandler &Handler); 18819903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski 18919903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// \brief Helper function that returns a LockKind required for the given level 19019903465e960329c0d5d93327f4046d036b0bc75Caitlin Sadowski/// of access. 191402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin SadowskiLockKind getLockKindFromAccessKind(AccessKind AK); 192402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski 193402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski}} // end namespace clang::thread_safety 194402aa0698fec81e574818a0a6c2000fac0b2c4c6Caitlin Sadowski#endif 195