]> CyberLeo.Net >> Repos - FreeBSD/stable/9.git/blob - contrib/llvm/tools/clang/include/clang/Analysis/Analyses/ThreadSafety.h
MFC r244628:
[FreeBSD/stable/9.git] / 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 llvm::StringRef Name;
71   virtual ~ThreadSafetyHandler();
72
73   /// Warn about lock expressions which fail to resolve to lockable objects.
74   /// \param Loc -- the SourceLocation of the unresolved expression.
75   virtual void handleInvalidLockExp(SourceLocation Loc) {}
76
77   /// Warn about unlock function calls that do not have a prior matching lock
78   /// expression.
79   /// \param LockName -- A StringRef name for the lock expression, to be printed
80   /// in the error message.
81   /// \param Loc -- The SourceLocation of the Unlock
82   virtual void handleUnmatchedUnlock(Name LockName, SourceLocation Loc) {}
83
84   /// Warn about lock function calls for locks which are already held.
85   /// \param LockName -- A StringRef name for the lock expression, to be printed
86   /// in the error message.
87   /// \param Loc -- The location of the second lock expression.
88   virtual void handleDoubleLock(Name LockName, SourceLocation Loc) {}
89
90   /// Warn about situations where a mutex is sometimes held and sometimes not.
91   /// The three situations are:
92   /// 1. a mutex is locked on an "if" branch but not the "else" branch,
93   /// 2, or a mutex is only held at the start of some loop iterations,
94   /// 3. or when a mutex is locked but not unlocked inside a function.
95   /// \param LockName -- A StringRef name for the lock expression, to be printed
96   /// in the error message.
97   /// \param LocLocked -- The location of the lock expression where the mutex is
98   ///               locked
99   /// \param LocEndOfScope -- The location of the end of the scope where the
100   ///               mutex is no longer held
101   /// \param LEK -- which of the three above cases we should warn for
102   virtual void handleMutexHeldEndOfScope(Name LockName,
103                                          SourceLocation LocLocked,
104                                          SourceLocation LocEndOfScope,
105                                          LockErrorKind LEK){}
106
107   /// Warn when a mutex is held exclusively and shared at the same point. For
108   /// example, if a mutex is locked exclusively during an if branch and shared
109   /// during the else branch.
110   /// \param LockName -- A StringRef name for the lock expression, to be printed
111   /// in the error message.
112   /// \param Loc1 -- The location of the first lock expression.
113   /// \param Loc2 -- The location of the second lock expression.
114   virtual void handleExclusiveAndShared(Name LockName, SourceLocation Loc1,
115                                         SourceLocation Loc2) {}
116
117   /// Warn when a protected operation occurs while no locks are held.
118   /// \param D -- The decl for the protected variable or function
119   /// \param POK -- The kind of protected operation (e.g. variable access)
120   /// \param AK -- The kind of access (i.e. read or write) that occurred
121   /// \param Loc -- The location of the protected operation.
122   virtual void handleNoMutexHeld(const NamedDecl *D, ProtectedOperationKind POK,
123                                  AccessKind AK, SourceLocation Loc) {}
124
125   /// Warn when a protected operation occurs while the specific mutex protecting
126   /// the operation is not locked.
127   /// \param D -- The decl for the protected variable or function
128   /// \param POK -- The kind of protected operation (e.g. variable access)
129   /// \param LockName -- A StringRef name for the lock expression, to be printed
130   /// in the error message.
131   /// \param LK -- The kind of access (i.e. read or write) that occurred
132   /// \param Loc -- The location of the protected operation.
133   virtual void handleMutexNotHeld(const NamedDecl *D,
134                                   ProtectedOperationKind POK, Name LockName,
135                                   LockKind LK, SourceLocation Loc,
136                                   Name *PossibleMatch=0) {}
137
138   /// Warn when a function is called while an excluded mutex is locked. For
139   /// example, the mutex may be locked inside the function.
140   /// \param FunName -- The name of the function
141   /// \param LockName -- A StringRef name for the lock expression, to be printed
142   /// in the error message.
143   /// \param Loc -- The location of the function call.
144   virtual void handleFunExcludesLock(Name FunName, Name LockName,
145                                      SourceLocation Loc) {}
146 };
147
148 /// \brief Check a function's CFG for thread-safety violations.
149 ///
150 /// We traverse the blocks in the CFG, compute the set of mutexes that are held
151 /// at the end of each block, and issue warnings for thread safety violations.
152 /// Each block in the CFG is traversed exactly once.
153 void runThreadSafetyAnalysis(AnalysisDeclContext &AC,
154                              ThreadSafetyHandler &Handler);
155
156 /// \brief Helper function that returns a LockKind required for the given level
157 /// of access.
158 LockKind getLockKindFromAccessKind(AccessKind AK);
159
160 }} // end namespace clang::thread_safety
161 #endif