314 lines
14 KiB
C++
314 lines
14 KiB
C++
//===- ThreadSafety.h -------------------------------------------*- C++ -*-===//
|
|
//
|
|
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
|
|
// See https://llvm.org/LICENSE.txt for license information.
|
|
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
//
|
|
//
|
|
// A intra-procedural analysis for thread safety (e.g. deadlocks and race
|
|
// conditions), based off of an annotation system.
|
|
//
|
|
// See http://clang.llvm.org/docs/LanguageExtensions.html#thread-safety-annotation-checking
|
|
// for more information.
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#ifndef LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
|
|
#define LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
|
|
|
|
#include "clang/Basic/SourceLocation.h"
|
|
#include "llvm/ADT/StringRef.h"
|
|
|
|
namespace clang {
|
|
|
|
class AnalysisDeclContext;
|
|
class FunctionDecl;
|
|
class NamedDecl;
|
|
|
|
namespace threadSafety {
|
|
|
|
class BeforeSet;
|
|
|
|
/// This enum distinguishes between different kinds of operations that may
|
|
/// need to be protected by locks. We use this enum in error handling.
|
|
enum ProtectedOperationKind {
|
|
/// Dereferencing a variable (e.g. p in *p = 5;)
|
|
POK_VarDereference,
|
|
|
|
/// Reading or writing a variable (e.g. x in x = 5;)
|
|
POK_VarAccess,
|
|
|
|
/// Making a function call (e.g. fool())
|
|
POK_FunctionCall,
|
|
|
|
/// Passing a guarded variable by reference.
|
|
POK_PassByRef,
|
|
|
|
/// Passing a pt-guarded variable by reference.
|
|
POK_PtPassByRef,
|
|
|
|
/// Returning a guarded variable by reference.
|
|
POK_ReturnByRef,
|
|
|
|
/// Returning a pt-guarded variable by reference.
|
|
POK_PtReturnByRef,
|
|
|
|
/// Passing pointer to a guarded variable.
|
|
POK_PassPointer,
|
|
|
|
/// Passing a pt-guarded pointer.
|
|
POK_PtPassPointer,
|
|
|
|
/// Returning pointer to a guarded variable.
|
|
POK_ReturnPointer,
|
|
|
|
/// Returning a pt-guarded pointer.
|
|
POK_PtReturnPointer,
|
|
};
|
|
|
|
/// This enum distinguishes between different kinds of lock actions. For
|
|
/// example, it is an error to write a variable protected by shared version of a
|
|
/// mutex.
|
|
enum LockKind {
|
|
/// Shared/reader lock of a mutex.
|
|
LK_Shared,
|
|
|
|
/// Exclusive/writer lock of a mutex.
|
|
LK_Exclusive,
|
|
|
|
/// Can be either Shared or Exclusive.
|
|
LK_Generic
|
|
};
|
|
|
|
/// This enum distinguishes between different ways to access (read or write) a
|
|
/// variable.
|
|
enum AccessKind {
|
|
/// Reading a variable.
|
|
AK_Read,
|
|
|
|
/// Writing a variable.
|
|
AK_Written
|
|
};
|
|
|
|
/// This enum distinguishes between different situations where we warn due to
|
|
/// inconsistent locking.
|
|
enum LockErrorKind {
|
|
/// A capability is locked for some but not all loop iterations.
|
|
LEK_LockedSomeLoopIterations,
|
|
/// A capability is locked in some but not all predecessors of a CFGBlock.
|
|
LEK_LockedSomePredecessors,
|
|
/// A capability is still locked at the end of a function.
|
|
LEK_LockedAtEndOfFunction,
|
|
/// Expecting a capability to be held at the end of function.
|
|
LEK_NotLockedAtEndOfFunction
|
|
};
|
|
|
|
/// Handler class for thread safety warnings.
|
|
class ThreadSafetyHandler {
|
|
public:
|
|
using Name = StringRef;
|
|
|
|
ThreadSafetyHandler() = default;
|
|
virtual ~ThreadSafetyHandler();
|
|
|
|
/// Warn about lock expressions which fail to resolve to lockable objects.
|
|
/// \param Loc -- the SourceLocation of the unresolved expression.
|
|
virtual void handleInvalidLockExp(SourceLocation Loc) {}
|
|
|
|
/// Warn about unlock function calls that do not have a prior matching lock
|
|
/// expression.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param LockName -- A StringRef name for the lock expression, to be printed
|
|
/// in the error message.
|
|
/// \param Loc -- The SourceLocation of the Unlock
|
|
/// \param LocPreviousUnlock -- If valid, the location of a previous Unlock.
|
|
virtual void handleUnmatchedUnlock(StringRef Kind, Name LockName,
|
|
SourceLocation Loc,
|
|
SourceLocation LocPreviousUnlock) {}
|
|
|
|
/// Warn about an unlock function call that attempts to unlock a lock with
|
|
/// the incorrect lock kind. For instance, a shared lock being unlocked
|
|
/// exclusively, or vice versa.
|
|
/// \param LockName -- A StringRef name for the lock expression, to be printed
|
|
/// in the error message.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param Expected -- the kind of lock expected.
|
|
/// \param Received -- the kind of lock received.
|
|
/// \param LocLocked -- The SourceLocation of the Lock.
|
|
/// \param LocUnlock -- The SourceLocation of the Unlock.
|
|
virtual void handleIncorrectUnlockKind(StringRef Kind, Name LockName,
|
|
LockKind Expected, LockKind Received,
|
|
SourceLocation LocLocked,
|
|
SourceLocation LocUnlock) {}
|
|
|
|
/// Warn about lock function calls for locks which are already held.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param LockName -- A StringRef name for the lock expression, to be printed
|
|
/// in the error message.
|
|
/// \param LocLocked -- The location of the first lock expression.
|
|
/// \param LocDoubleLock -- The location of the second lock expression.
|
|
virtual void handleDoubleLock(StringRef Kind, Name LockName,
|
|
SourceLocation LocLocked,
|
|
SourceLocation LocDoubleLock) {}
|
|
|
|
/// Warn about situations where a mutex is sometimes held and sometimes not.
|
|
/// The three situations are:
|
|
/// 1. a mutex is locked on an "if" branch but not the "else" branch,
|
|
/// 2, or a mutex is only held at the start of some loop iterations,
|
|
/// 3. or when a mutex is locked but not unlocked inside a function.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param LockName -- A StringRef name for the lock expression, to be printed
|
|
/// in the error message.
|
|
/// \param LocLocked -- The location of the lock expression where the mutex is
|
|
/// locked
|
|
/// \param LocEndOfScope -- The location of the end of the scope where the
|
|
/// mutex is no longer held
|
|
/// \param LEK -- which of the three above cases we should warn for
|
|
/// \param ReentrancyMismatch -- mismatching reentrancy depth
|
|
virtual void handleMutexHeldEndOfScope(StringRef Kind, Name LockName,
|
|
SourceLocation LocLocked,
|
|
SourceLocation LocEndOfScope,
|
|
LockErrorKind LEK,
|
|
bool ReentrancyMismatch = false) {}
|
|
|
|
/// Warn when a mutex is held exclusively and shared at the same point. For
|
|
/// example, if a mutex is locked exclusively during an if branch and shared
|
|
/// during the else branch.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param LockName -- A StringRef name for the lock expression, to be printed
|
|
/// in the error message.
|
|
/// \param Loc1 -- The location of the first lock expression.
|
|
/// \param Loc2 -- The location of the second lock expression.
|
|
virtual void handleExclusiveAndShared(StringRef Kind, Name LockName,
|
|
SourceLocation Loc1,
|
|
SourceLocation Loc2) {}
|
|
|
|
/// Warn when a protected operation occurs while no locks are held.
|
|
/// \param D -- The decl for the protected variable or function
|
|
/// \param POK -- The kind of protected operation (e.g. variable access)
|
|
/// \param AK -- The kind of access (i.e. read or write) that occurred
|
|
/// \param Loc -- The location of the protected operation.
|
|
virtual void handleNoMutexHeld(const NamedDecl *D, ProtectedOperationKind POK,
|
|
AccessKind AK, SourceLocation Loc) {}
|
|
|
|
/// Warn when a protected operation occurs while the specific mutex protecting
|
|
/// the operation is not locked.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param D -- The decl for the protected variable or function
|
|
/// \param POK -- The kind of protected operation (e.g. variable access)
|
|
/// \param LockName -- A StringRef name for the lock expression, to be printed
|
|
/// in the error message.
|
|
/// \param LK -- The kind of access (i.e. read or write) that occurred
|
|
/// \param Loc -- The location of the protected operation.
|
|
virtual void handleMutexNotHeld(StringRef Kind, const NamedDecl *D,
|
|
ProtectedOperationKind POK, Name LockName,
|
|
LockKind LK, SourceLocation Loc,
|
|
Name *PossibleMatch = nullptr) {}
|
|
|
|
/// Warn when acquiring a lock that the negative capability is not held.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param LockName -- The name for the lock expression, to be printed in the
|
|
/// diagnostic.
|
|
/// \param Neg -- The name of the negative capability to be printed in the
|
|
/// diagnostic.
|
|
/// \param Loc -- The location of the protected operation.
|
|
virtual void handleNegativeNotHeld(StringRef Kind, Name LockName, Name Neg,
|
|
SourceLocation Loc) {}
|
|
|
|
/// Warn when calling a function that a negative capability is not held.
|
|
/// \param D -- The decl for the function requiring the negative capability.
|
|
/// \param LockName -- The name for the lock expression, to be printed in the
|
|
/// diagnostic.
|
|
/// \param Loc -- The location of the protected operation.
|
|
virtual void handleNegativeNotHeld(const NamedDecl *D, Name LockName,
|
|
SourceLocation Loc) {}
|
|
|
|
/// Warn when a function is called while an excluded mutex is locked. For
|
|
/// example, the mutex may be locked inside the function.
|
|
/// \param Kind -- the capability's name parameter (role, mutex, etc).
|
|
/// \param FunName -- The name of the function
|
|
/// \param LockName -- A StringRef name for the lock expression, to be printed
|
|
/// in the error message.
|
|
/// \param Loc -- The location of the function call.
|
|
virtual void handleFunExcludesLock(StringRef Kind, Name FunName,
|
|
Name LockName, SourceLocation Loc) {}
|
|
|
|
/// Warn when an actual underlying mutex of a scoped lockable does not match
|
|
/// the expected.
|
|
/// \param Loc -- The location of the call expression.
|
|
/// \param DLoc -- The location of the function declaration.
|
|
/// \param ScopeName -- The name of the scope passed to the function.
|
|
/// \param Kind -- The kind of the expected mutex.
|
|
/// \param Expected -- The name of the expected mutex.
|
|
/// \param Actual -- The name of the actual mutex.
|
|
virtual void handleUnmatchedUnderlyingMutexes(SourceLocation Loc,
|
|
SourceLocation DLoc,
|
|
Name ScopeName, StringRef Kind,
|
|
Name Expected, Name Actual) {}
|
|
|
|
/// Warn when we get fewer underlying mutexes than expected.
|
|
/// \param Loc -- The location of the call expression.
|
|
/// \param DLoc -- The location of the function declaration.
|
|
/// \param ScopeName -- The name of the scope passed to the function.
|
|
/// \param Kind -- The kind of the expected mutex.
|
|
/// \param Expected -- The name of the expected mutex.
|
|
virtual void handleExpectMoreUnderlyingMutexes(SourceLocation Loc,
|
|
SourceLocation DLoc,
|
|
Name ScopeName, StringRef Kind,
|
|
Name Expected) {}
|
|
|
|
/// Warn when we get more underlying mutexes than expected.
|
|
/// \param Loc -- The location of the call expression.
|
|
/// \param DLoc -- The location of the function declaration.
|
|
/// \param ScopeName -- The name of the scope passed to the function.
|
|
/// \param Kind -- The kind of the actual mutex.
|
|
/// \param Actual -- The name of the actual mutex.
|
|
virtual void handleExpectFewerUnderlyingMutexes(SourceLocation Loc,
|
|
SourceLocation DLoc,
|
|
Name ScopeName,
|
|
StringRef Kind, Name Actual) {
|
|
}
|
|
|
|
/// Warn that L1 cannot be acquired before L2.
|
|
virtual void handleLockAcquiredBefore(StringRef Kind, Name L1Name,
|
|
Name L2Name, SourceLocation Loc) {}
|
|
|
|
/// Warn that there is a cycle in acquired_before/after dependencies.
|
|
virtual void handleBeforeAfterCycle(Name L1Name, SourceLocation Loc) {}
|
|
|
|
/// Called by the analysis when starting analysis of a function.
|
|
/// Used to issue suggestions for changes to annotations.
|
|
virtual void enterFunction(const FunctionDecl *FD) {}
|
|
|
|
/// Called by the analysis when finishing analysis of a function.
|
|
virtual void leaveFunction(const FunctionDecl *FD) {}
|
|
|
|
bool issueBetaWarnings() { return IssueBetaWarnings; }
|
|
void setIssueBetaWarnings(bool b) { IssueBetaWarnings = b; }
|
|
|
|
private:
|
|
bool IssueBetaWarnings = false;
|
|
};
|
|
|
|
/// Check a function's CFG for thread-safety violations.
|
|
///
|
|
/// We traverse the blocks in the CFG, compute the set of mutexes that are held
|
|
/// at the end of each block, and issue warnings for thread safety violations.
|
|
/// Each block in the CFG is traversed exactly once.
|
|
void runThreadSafetyAnalysis(AnalysisDeclContext &AC,
|
|
ThreadSafetyHandler &Handler,
|
|
BeforeSet **Bset);
|
|
|
|
void threadSafetyCleanup(BeforeSet *Cache);
|
|
|
|
/// Helper function that returns a LockKind required for the given level
|
|
/// of access.
|
|
LockKind getLockKindFromAccessKind(AccessKind AK);
|
|
|
|
} // namespace threadSafety
|
|
} // namespace clang
|
|
|
|
#endif // LLVM_CLANG_ANALYSIS_ANALYSES_THREADSAFETY_H
|