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() = 0;
  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 Loc -- The location of the lock expression where the mutex is locked
  97   /// \param LEK -- which of the three above cases we should warn for
  98   virtual void handleMutexHeldEndOfScope(Name LockName, SourceLocation Loc,
  99                                          LockErrorKind LEK){}
 100
 101   /// Warn when a mutex is held exclusively and shared at the same point. For
 102   /// example, if a mutex is locked exclusively during an if branch and shared
 103   /// during the else branch.
 104   /// \param LockName -- A StringRef name for the lock expression, to be printed
 105   /// in the error message.
 106   /// \param Loc1 -- The location of the first lock expression.
 107   /// \param Loc2 -- The location of the second lock expression.
 108   virtual void handleExclusiveAndShared(Name LockName, SourceLocation Loc1,
 109                                         SourceLocation Loc2) {}
 110
 111   /// Warn when a protected operation occurs while no locks are held.
 112   /// \param D -- The decl for the protected variable or function
 113   /// \param POK -- The kind of protected operation (e.g. variable access)
 114   /// \param AK -- The kind of access (i.e. read or write) that occurred
 115   /// \param Loc -- The location of the protected operation.
 116   virtual void handleNoMutexHeld(const NamedDecl *D, ProtectedOperationKind POK,
 117                                  AccessKind AK, SourceLocation Loc) {}
 118
 119   /// Warn when a protected operation occurs while the specific mutex protecting
 120   /// the operation is not locked.
 121   /// \param LockName -- A StringRef name for the lock expression, to be printed
 122   /// in the error message.
 123   /// \param D -- The decl for the protected variable or function
 124   /// \param POK -- The kind of protected operation (e.g. variable access)
 125   /// \param AK -- The kind of access (i.e. read or write) that occurred
 126   /// \param Loc -- The location of the protected operation.
 127   virtual void handleMutexNotHeld(const NamedDecl *D,
 128                                   ProtectedOperationKind POK, Name LockName,
 129                                   LockKind LK, SourceLocation Loc) {}
 130
 131   /// Warn when a function is called while an excluded mutex is locked. For
 132   /// example, the mutex may be locked inside the function.
 133   /// \param FunName -- The name of the function
 134   /// \param LockName -- A StringRef name for the lock expression, to be printed
 135   /// in the error message.
 136   /// \param Loc -- The location of the function call.
 137   virtual void handleFunExcludesLock(Name FunName, Name LockName,
 138                                      SourceLocation Loc) {}
 139 };
 140
 141 /// \brief Check a function's CFG for thread-safety violations.
 142 ///
 143 /// We traverse the blocks in the CFG, compute the set of mutexes that are held
 144 /// at the end of each block, and issue warnings for thread safety violations.
 145 /// Each block in the CFG is traversed exactly once.
 146 void runThreadSafetyAnalysis(AnalysisContext &AC, ThreadSafetyHandler &Handler);
 147
 148 /// \brief Helper function that returns a LockKind required for the given level
 149 /// of access.
 150 LockKind getLockKindFromAccessKind(AccessKind AK);
 151
 152 }} // end namespace clang::thread_safety
 153 #endif