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   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