ThreadSafety.h revision 6bcf27bb9a4b5c3f79cb44c0e4654a6d7619ad89 
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_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
26namespace clang {
27namespace 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.
31enum 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.
40enum LockKind {
41  LK_Shared, ///< Shared/reader lock of a mutex.
42  LK_Exclusive, ///< Exclusive/writer lock of a mutex.
43  LK_Generic  ///<  Can be either Shared or Exclusive
44};
45
46/// This enum distinguishes between different ways to access (read or write) a
47/// variable.
48enum AccessKind {
49  AK_Read, ///< Reading a variable.
50  AK_Written ///< Writing a variable.
51};
52
53/// This enum distinguishes between different situations where we warn due to
54/// inconsistent locking.
55/// \enum SK_LockedSomeLoopIterations -- a mutex is locked for some but not all
56/// loop iterations.
57/// \enum SK_LockedSomePredecessors -- a mutex is locked in some but not all
58/// predecessors of a CFGBlock.
59/// \enum SK_LockedAtEndOfFunction -- a mutex is still locked at the end of a
60/// function.
61enum LockErrorKind {
62  LEK_LockedSomeLoopIterations,
63  LEK_LockedSomePredecessors,
64  LEK_LockedAtEndOfFunction,
65  LEK_NotLockedAtEndOfFunction
66};
67
68/// Handler class for thread safety warnings.
69class ThreadSafetyHandler {
70public:
71  typedef StringRef Name;
72  ThreadSafetyHandler() : IssueBetaWarnings(false) { }
73  virtual ~ThreadSafetyHandler();
74
75  /// Warn about lock expressions which fail to resolve to lockable objects.
76  /// \param Kind -- the capability's name parameter (role, mutex, etc).
77  /// \param Loc -- the SourceLocation of the unresolved expression.
78  virtual void handleInvalidLockExp(StringRef Kind, SourceLocation Loc) {}
79
80  /// Warn about unlock function calls that do not have a prior matching lock
81  /// expression.
82  /// \param Kind -- the capability's name parameter (role, mutex, etc).
83  /// \param LockName -- A StringRef name for the lock expression, to be printed
84  /// in the error message.
85  /// \param Loc -- The SourceLocation of the Unlock
86  virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName,
87                                     SourceLocation Loc) {}
88
89  /// Warn about an unlock function call that attempts to unlock a lock with
90  /// the incorrect lock kind. For instance, a shared lock being unlocked
91  /// exclusively, or vice versa.
92  /// \param LockName -- A StringRef name for the lock expression, to be printed
93  /// in the error message.
94  /// \param Kind -- the capability's name parameter (role, mutex, etc).
95  /// \param Expected -- the kind of lock expected.
96  /// \param Received -- the kind of lock received.
97  /// \param Loc -- The SourceLocation of the Unlock.
98  virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName,
99                                         LockKind Expected, LockKind Received,
100                                         SourceLocation Loc) {}
101
102  /// Warn about lock function calls for locks which are already held.
103  /// \param Kind -- the capability's name parameter (role, mutex, etc).
104  /// \param LockName -- A StringRef name for the lock expression, to be printed
105  /// in the error message.
106  /// \param Loc -- The location of the second lock expression.
107  virtual void handleDoubleLock(StringRef Kind, Name LockName,
108                                SourceLocation Loc) {}
109
110  /// Warn about situations where a mutex is sometimes held and sometimes not.
111  /// The three situations are:
112  /// 1. a mutex is locked on an "if" branch but not the "else" branch,
113  /// 2, or a mutex is only held at the start of some loop iterations,
114  /// 3. or when a mutex is locked but not unlocked inside a function.
115  /// \param Kind -- the capability's name parameter (role, mutex, etc).
116  /// \param LockName -- A StringRef name for the lock expression, to be printed
117  /// in the error message.
118  /// \param LocLocked -- The location of the lock expression where the mutex is
119  ///               locked
120  /// \param LocEndOfScope -- The location of the end of the scope where the
121  ///               mutex is no longer held
122  /// \param LEK -- which of the three above cases we should warn for
123  virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName,
124                                         SourceLocation LocLocked,
125                                         SourceLocation LocEndOfScope,
126                                         LockErrorKind LEK) {}
127
128  /// Warn when a mutex is held exclusively and shared at the same point. For
129  /// example, if a mutex is locked exclusively during an if branch and shared
130  /// during the else branch.
131  /// \param Kind -- the capability's name parameter (role, mutex, etc).
132  /// \param LockName -- A StringRef name for the lock expression, to be printed
133  /// in the error message.
134  /// \param Loc1 -- The location of the first lock expression.
135  /// \param Loc2 -- The location of the second lock expression.
136  virtual void handleExclusiveAndShared(StringRef Kind, Name LockName,
137                                        SourceLocation Loc1,
138                                        SourceLocation Loc2) {}
139
140  /// Warn when a protected operation occurs while no locks are held.
141  /// \param Kind -- the capability's name parameter (role, mutex, etc).
142  /// \param D -- The decl for the protected variable or function
143  /// \param POK -- The kind of protected operation (e.g. variable access)
144  /// \param AK -- The kind of access (i.e. read or write) that occurred
145  /// \param Loc -- The location of the protected operation.
146  virtual void handleNoMutexHeld(StringRef Kind, const NamedDecl *D,
147                                 ProtectedOperationKind POK, AccessKind AK,
148                                 SourceLocation Loc) {}
149
150  /// Warn when a protected operation occurs while the specific mutex protecting
151  /// the operation is not locked.
152  /// \param Kind -- the capability's name parameter (role, mutex, etc).
153  /// \param D -- The decl for the protected variable or function
154  /// \param POK -- The kind of protected operation (e.g. variable access)
155  /// \param LockName -- A StringRef name for the lock expression, to be printed
156  /// in the error message.
157  /// \param LK -- The kind of access (i.e. read or write) that occurred
158  /// \param Loc -- The location of the protected operation.
159  virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D,
160                                  ProtectedOperationKind POK, Name LockName,
161                                  LockKind LK, SourceLocation Loc,
162                                  Name *PossibleMatch = nullptr) {}
163
164  /// Warn when a function is called while an excluded mutex is locked. For
165  /// example, the mutex may be locked inside the function.
166  /// \param Kind -- the capability's name parameter (role, mutex, etc).
167  /// \param FunName -- The name of the function
168  /// \param LockName -- A StringRef name for the lock expression, to be printed
169  /// in the error message.
170  /// \param Loc -- The location of the function call.
171  virtual void handleFunExcludesLock(StringRef Kind, Name FunName,
172                                     Name LockName, SourceLocation Loc) {}
173
174  bool issueBetaWarnings() { return IssueBetaWarnings; }
175  void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; }
176
177private:
178  bool IssueBetaWarnings;
179};
180
181/// \brief Check a function's CFG for thread-safety violations.
182///
183/// We traverse the blocks in the CFG, compute the set of mutexes that are held
184/// at the end of each block, and issue warnings for thread safety violations.
185/// Each block in the CFG is traversed exactly once.
186void runThreadSafetyAnalysis(AnalysisDeclContext &AC,
187                             ThreadSafetyHandler &Handler);
188
189/// \brief Helper function that returns a LockKind required for the given level
190/// of access.
191LockKind getLockKindFromAccessKind(AccessKind AK);
192
193}} // end namespace clang::thread_safety
194#endif
195