From: Caitlin Sadowski Date: Wed, 14 Sep 2011 20:05:09 +0000 (+0000) Subject: Thread safety: adding additional documentation to the main thread safety interface... X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=19903465e960329c0d5d93327f4046d036b0bc75;p=clang Thread safety: adding additional documentation to the main thread safety interface, and making the destructor for the thread safety handler pure virtual git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@139722 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/include/clang/Analysis/Analyses/ThreadSafety.h b/include/clang/Analysis/Analyses/ThreadSafety.h index 6d13fb9975..a751f6efab 100644 --- a/include/clang/Analysis/Analyses/ThreadSafety.h +++ b/include/clang/Analysis/Analyses/ThreadSafety.h @@ -11,7 +11,8 @@ // A intra-procedural analysis for thread safety (e.g. deadlocks and race // conditions), based off of an annotation system. // -// See http://gcc.gnu.org/wiki/ThreadSafetyAnnotation for the gcc version. +// See http://clang.llvm.org/docs/LanguageExtensions.html#threadsafety for more +// information. // //===----------------------------------------------------------------------===// @@ -25,46 +26,130 @@ namespace clang { namespace thread_safety { +/// This enum distinguishes between different kinds of operations that may +/// need to be protected by locks. We use this enum in error handling. +/// \enum POK_VarDereference -- Dereferencing a variable (e.g. p in *p = 5;) +/// \enum POK_VarAccess -- Reading or writing a variable (e.g. x in x = 5;) +/// \enum POK_FunctionCall -- making a function call (e.g. fool()) enum ProtectedOperationKind { POK_VarDereference, POK_VarAccess, POK_FunctionCall }; +/// 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 LK_Shared -- Shared/reader lock of a mutex +/// \enum LK_Exclusive -- Exclusive/writer lock of a mutex enum LockKind { LK_Shared, LK_Exclusive }; +/// This enum distinguishes between different ways to access (read or write) a +/// variable. +/// \enum AK_Read -- reading a variable +/// \enum AK_Written -- writing a variable enum AccessKind { AK_Read, AK_Written }; +/// Handler class for thread safety warnings. class ThreadSafetyHandler { public: typedef llvm::StringRef Name; - ThreadSafetyHandler() {} - virtual ~ThreadSafetyHandler() {} + virtual ~ThreadSafetyHandler() = 0; + + /// 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 LockName -- A StringRef name for the lock expression, to be printed + /// in the error message. + /// \param Loc -- The SourceLocation of the Unlock virtual void handleUnmatchedUnlock(Name LockName, SourceLocation Loc) {} + + /// Warn about lock function calls for locks which are already held. + /// \param LockName -- A StringRef name for the lock expression, to be printed + /// in the error message. + /// \param Loc -- The Loc of the second lock expression. virtual void handleDoubleLock(Name LockName, SourceLocation Loc) {} + + /// Warn about situations where a mutex is sometimes held and sometimes not. + /// For example, a mutex is locked on an "if" branch but not the "else" + /// branch. + /// \param LockName -- A StringRef name for the lock expression, to be printed + /// in the error message. + /// \param Loc -- The Loc of the lock expression where the mutex is locked virtual void handleMutexHeldEndOfScope(Name LockName, SourceLocation Loc){} + + /// Warn when a mutex is only held at the start of some loop iterations. + /// \param LockName -- A StringRef name for the lock expression, to be printed + /// in the error message. + /// \param Loc -- The Loc of the lock expression. virtual void handleNoLockLoopEntry(Name LockName, SourceLocation Loc) {} + + /// Warn when a mutex is locked but not unlocked inside a function. + /// \param LockName -- A StringRef name for the lock expression, to be printed + /// in the error message. + /// \param FunName -- The name of the function + /// \param Loc -- The Loc of the lock expression virtual void handleNoUnlock(Name LockName, Name FunName, SourceLocation Loc) {} + + /// 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 LockName -- A StringRef name for the lock expression, to be printed + /// in the error message. + /// \param Loc1 -- The Loc of the first lock expression. + /// \param Loc2 -- The Loc of the second lock expression. virtual void handleExclusiveAndShared(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 Loc 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 LockName -- A StringRef name for the lock expression, to be printed + /// in the error message. + /// \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 Loc of the protected operation. virtual void handleMutexNotHeld(const NamedDecl *D, ProtectedOperationKind POK, Name LockName, LockKind LK, 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 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 Loc of the function call. virtual void handleFunExcludesLock(Name FunName, Name LockName, SourceLocation Loc) {} }; +/// \brief 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(AnalysisContext &AC, ThreadSafetyHandler &Handler); + +/// \brief Helper function that returns a LockKind required for the given level +/// of access. LockKind getLockKindFromAccessKind(AccessKind AK); }} // end namespace clang::thread_safety diff --git a/lib/Analysis/ThreadSafety.cpp b/lib/Analysis/ThreadSafety.cpp index f55211d3cb..233f58c432 100644 --- a/lib/Analysis/ThreadSafety.cpp +++ b/lib/Analysis/ThreadSafety.cpp @@ -10,7 +10,8 @@ // A intra-procedural analysis for thread safety (e.g. deadlocks and race // conditions), based off of an annotation system. // -// See http://gcc.gnu.org/wiki/ThreadSafetyAnnotation for the gcc version. +// See http://clang.llvm.org/docs/LanguageExtensions.html#threadsafety for more +// information. // //===----------------------------------------------------------------------===// @@ -36,6 +37,9 @@ using namespace clang; using namespace thread_safety; +// Key method definition +ThreadSafetyHandler::~ThreadSafetyHandler() {} + // Helper functions static Expr *getParent(Expr *Exp) { if (MemberExpr *ME = dyn_cast(Exp))