ThreadSafety.h revision fb4afc2fc659faff43a6df4c1d0e07df9c90479d 
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
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};
44
45/// This enum distinguishes between different ways to access (read or write) a
46/// variable.
47enum 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.
60enum LockErrorKind {
61  LEK_LockedSomeLoopIterations,
62  LEK_LockedSomePredecessors,
63  LEK_LockedAtEndOfFunction,
64  LEK_NotLockedAtEndOfFunction
65};
66
67/// Handler class for thread safety warnings.
68class ThreadSafetyHandler {
69public:
70  typedef llvm::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
151private:
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.
160void runThreadSafetyAnalysis(AnalysisDeclContext &AC,
161                             ThreadSafetyHandler &Handler);
162
163/// \brief Helper function that returns a LockKind required for the given level
164/// of access.
165LockKind getLockKindFromAccessKind(AccessKind AK);
166
167}} // end namespace clang::thread_safety
168#endif
169