contrib/llvm/tools/clang/include/clang/Analysis/Analyses/ThreadSafety.h

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