Home | History | Annotate | Download | only in Analyses
      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#thread-safety-annotation-checking
     15 // for more information.
     16 //
     17 //===----------------------------------------------------------------------===//
     18 
     19 #ifndef LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
     20 #define LLVM_CLANG_ANALYSIS_ANALYSES_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 threadSafety {
     28 
     29 class BeforeSet;
     30 
     31 /// This enum distinguishes between different kinds of operations that may
     32 /// need to be protected by locks. We use this enum in error handling.
     33 enum ProtectedOperationKind {
     34   POK_VarDereference, ///< Dereferencing a variable (e.g. p in *p = 5;)
     35   POK_VarAccess, ///< Reading or writing a variable (e.g. x in x = 5;)
     36   POK_FunctionCall, ///< Making a function call (e.g. fool())
     37   POK_PassByRef, ///< Passing a guarded variable by reference.
     38   POK_PtPassByRef,  ///< Passing a pt-guarded variable by reference.
     39 };
     40 
     41 /// This enum distinguishes between different kinds of lock actions. For
     42 /// example, it is an error to write a variable protected by shared version of a
     43 /// mutex.
     44 enum LockKind {
     45   LK_Shared,    ///< Shared/reader lock of a mutex.
     46   LK_Exclusive, ///< Exclusive/writer lock of a mutex.
     47   LK_Generic    ///< Can be either Shared or Exclusive
     48 };
     49 
     50 /// This enum distinguishes between different ways to access (read or write) a
     51 /// variable.
     52 enum AccessKind {
     53   AK_Read, ///< Reading a variable.
     54   AK_Written ///< Writing a variable.
     55 };
     56 
     57 /// This enum distinguishes between different situations where we warn due to
     58 /// inconsistent locking.
     59 /// \enum SK_LockedSomeLoopIterations -- a mutex is locked for some but not all
     60 /// loop iterations.
     61 /// \enum SK_LockedSomePredecessors -- a mutex is locked in some but not all
     62 /// predecessors of a CFGBlock.
     63 /// \enum SK_LockedAtEndOfFunction -- a mutex is still locked at the end of a
     64 /// function.
     65 enum LockErrorKind {
     66   LEK_LockedSomeLoopIterations,
     67   LEK_LockedSomePredecessors,
     68   LEK_LockedAtEndOfFunction,
     69   LEK_NotLockedAtEndOfFunction
     70 };
     71 
     72 /// Handler class for thread safety warnings.
     73 class ThreadSafetyHandler {
     74 public:
     75   typedef StringRef Name;
     76   ThreadSafetyHandler() : IssueBetaWarnings(false) { }
     77   virtual ~ThreadSafetyHandler();
     78 
     79   /// Warn about lock expressions which fail to resolve to lockable objects.
     80   /// \param Kind -- the capability's name parameter (role, mutex, etc).
     81   /// \param Loc -- the SourceLocation of the unresolved expression.
     82   virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc) {}
     83 
     84   /// Warn about unlock function calls that do not have a prior matching lock
     85   /// expression.
     86   /// \param Kind -- the capability's name parameter (role, mutex, etc).
     87   /// \param LockName -- A StringRef name for the lock expression, to be printed
     88   /// in the error message.
     89   /// \param Loc -- The SourceLocation of the Unlock
     90   virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName,
     91                                      SourceLocation Loc) {}
     92 
     93   /// Warn about an unlock function call that attempts to unlock a lock with
     94   /// the incorrect lock kind. For instance, a shared lock being unlocked
     95   /// exclusively, or vice versa.
     96   /// \param LockName -- A StringRef name for the lock expression, to be printed
     97   /// in the error message.
     98   /// \param Kind -- the capability's name parameter (role, mutex, etc).
     99   /// \param Expected -- the kind of lock expected.
    100   /// \param Received -- the kind of lock received.
    101   /// \param Loc -- The SourceLocation of the Unlock.
    102   virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName,
    103                                          LockKind Expected, LockKind Received,
    104                                          SourceLocation Loc) {}
    105 
    106   /// Warn about lock function calls for locks which are already held.
    107   /// \param Kind -- the capability's name parameter (role, mutex, etc).
    108   /// \param LockName -- A StringRef name for the lock expression, to be printed
    109   /// in the error message.
    110   /// \param Loc -- The location of the second lock expression.
    111   virtual void handleDoubleLock(StringRef Kind, Name LockName,
    112                                 SourceLocation Loc) {}
    113 
    114   /// Warn about situations where a mutex is sometimes held and sometimes not.
    115   /// The three situations are:
    116   /// 1. a mutex is locked on an "if" branch but not the "else" branch,
    117   /// 2, or a mutex is only held at the start of some loop iterations,
    118   /// 3. or when a mutex is locked but not unlocked inside a function.
    119   /// \param Kind -- the capability's name parameter (role, mutex, etc).
    120   /// \param LockName -- A StringRef name for the lock expression, to be printed
    121   /// in the error message.
    122   /// \param LocLocked -- The location of the lock expression where the mutex is
    123   ///               locked
    124   /// \param LocEndOfScope -- The location of the end of the scope where the
    125   ///               mutex is no longer held
    126   /// \param LEK -- which of the three above cases we should warn for
    127   virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName,
    128                                          SourceLocation LocLocked,
    129                                          SourceLocation LocEndOfScope,
    130                                          LockErrorKind LEK) {}
    131 
    132   /// Warn when a mutex is held exclusively and shared at the same point. For
    133   /// example, if a mutex is locked exclusively during an if branch and shared
    134   /// during the else branch.
    135   /// \param Kind -- the capability's name parameter (role, mutex, etc).
    136   /// \param LockName -- A StringRef name for the lock expression, to be printed
    137   /// in the error message.
    138   /// \param Loc1 -- The location of the first lock expression.
    139   /// \param Loc2 -- The location of the second lock expression.
    140   virtual void handleExclusiveAndShared(StringRef Kind, Name LockName,
    141                                         SourceLocation Loc1,
    142                                         SourceLocation Loc2) {}
    143 
    144   /// Warn when a protected operation occurs while no locks are held.
    145   /// \param Kind -- the capability's name parameter (role, mutex, etc).
    146   /// \param D -- The decl for the protected variable or function
    147   /// \param POK -- The kind of protected operation (e.g. variable access)
    148   /// \param AK -- The kind of access (i.e. read or write) that occurred
    149   /// \param Loc -- The location of the protected operation.
    150   virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D,
    151                                  ProtectedOperationKind POK, AccessKind AK,
    152                                  SourceLocation Loc) {}
    153 
    154   /// Warn when a protected operation occurs while the specific mutex protecting
    155   /// the operation is not locked.
    156   /// \param Kind -- the capability's name parameter (role, mutex, etc).
    157   /// \param D -- The decl for the protected variable or function
    158   /// \param POK -- The kind of protected operation (e.g. variable access)
    159   /// \param LockName -- A StringRef name for the lock expression, to be printed
    160   /// in the error message.
    161   /// \param LK -- The kind of access (i.e. read or write) that occurred
    162   /// \param Loc -- The location of the protected operation.
    163   virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D,
    164                                   ProtectedOperationKind POK, Name LockName,
    165                                   LockKind LK, SourceLocation Loc,
    166                                   Name *PossibleMatch = nullptr) {}
    167 
    168   /// Warn when acquiring a lock that the negative capability is not held.
    169   /// \param Kind -- the capability's name parameter (role, mutex, etc).
    170   /// \param LockName -- The name for the lock expression, to be printed in the
    171   /// diagnostic.
    172   /// \param Neg -- The name of the negative capability to be printed in the
    173   /// diagnostic.
    174   /// \param Loc -- The location of the protected operation.
    175   virtual void handleNegativeNotHeld(StringRef Kind, Name LockName, Name Neg,
    176                                      SourceLocation Loc) {}
    177 
    178   /// Warn when a function is called while an excluded mutex is locked. For
    179   /// example, the mutex may be locked inside the function.
    180   /// \param Kind -- the capability's name parameter (role, mutex, etc).
    181   /// \param FunName -- The name of the function
    182   /// \param LockName -- A StringRef name for the lock expression, to be printed
    183   /// in the error message.
    184   /// \param Loc -- The location of the function call.
    185   virtual void handleFunExcludesLock(StringRef Kind, Name FunName,
    186                                      Name LockName, SourceLocation Loc) {}
    187 
    188 
    189   /// Warn that L1 cannot be acquired before L2.
    190   virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name,
    191                                         Name L2Name, SourceLocation Loc) {}
    192 
    193   /// Warn that there is a cycle in acquired_before/after dependencies.
    194   virtual void handleBeforeAfterCycle(Name L1Name, SourceLocation Loc) {}
    195 
    196   /// Called by the analysis when starting analysis of a function.
    197   /// Used to issue suggestions for changes to annotations.
    198   virtual void enterFunction(const FunctionDecl *FD) {}
    199 
    200   /// Called by the analysis when finishing analysis of a function.
    201   virtual void leaveFunction(const FunctionDecl *FD) {}
    202 
    203   bool issueBetaWarnings() { return IssueBetaWarnings; }
    204   void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; }
    205 
    206 private:
    207   bool IssueBetaWarnings;
    208 };
    209 
    210 /// \brief Check a function's CFG for thread-safety violations.
    211 ///
    212 /// We traverse the blocks in the CFG, compute the set of mutexes that are held
    213 /// at the end of each block, and issue warnings for thread safety violations.
    214 /// Each block in the CFG is traversed exactly once.
    215 void runThreadSafetyAnalysis(AnalysisDeclContext &AC,
    216                              ThreadSafetyHandler &Handler,
    217                              BeforeSet **Bset);
    218 
    219 void threadSafetyCleanup(BeforeSet *Cache);
    220 
    221 /// \brief Helper function that returns a LockKind required for the given level
    222 /// of access.
    223 LockKind getLockKindFromAccessKind(AccessKind AK);
    224 
    225 }} // end namespace clang::threadSafety
    226 #endif
    227