[clang] f702a6f - Thread safety analysis: Improve documentation for ASSERT_CAPABILITY

[Aaron Puchert via cfe-commits]

Author: Russell Yanofsky
Date: 2020-09-26T22:16:50+02:00
New Revision: f702a6fa7c9e4c0e2871b3d6657ce4dfa525ce52

URL: https://github.com/llvm/llvm-project/commit/f702a6fa7c9e4c0e2871b3d6657ce4dfa525ce52
DIFF: https://github.com/llvm/llvm-project/commit/f702a6fa7c9e4c0e2871b3d6657ce4dfa525ce52.diff

LOG: Thread safety analysis: Improve documentation for ASSERT_CAPABILITY

Previous description didn't actually state the effect the attribute has on
thread safety analysis (causing analysis to assume the capability is held).

Previous description was also ambiguous about (or slightly overstated) the
noreturn assumption made by thread safety analysis, implying the assumption had
to be true about the function's behavior in general, and not just its behavior
in places where it's used. Stating the assumption specifically should avoid a
perceived need to disable thread safety analysis in places where only asserting
that a specific capability is held would be better.

Reviewed By: aaronpuchert, vasild

Differential Revision: https://reviews.llvm.org/D87629

Added: 
    

Modified: 
    clang/docs/ThreadSafetyAnalysis.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/ThreadSafetyAnalysis.rst b/clang/docs/ThreadSafetyAnalysis.rst
index e4a3342c02bd..651229f01d03 100644
--- a/clang/docs/ThreadSafetyAnalysis.rst
+++ b/clang/docs/ThreadSafetyAnalysis.rst
@@ -144,6 +144,9 @@ and data members. Users are *strongly advised* to define macros for the various
 attributes; example definitions can be found in :ref:`mutexheader`, below.
 The following documentation assumes the use of macros.
 
+The attributes only control assumptions made by thread safety analysis and the
+warnings it issues.  They don't affect generated code or behavior at run-time.
+
 For historical reasons, prior versions of thread safety used macro names that
 were very lock-centric.  These macros have since been renamed to fit a more
 general capability model.  The prior names are still in use, and will be
@@ -447,10 +450,11 @@ ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)
 
 *Previously:*  ``ASSERT_EXCLUSIVE_LOCK``, ``ASSERT_SHARED_LOCK``
 
-These are attributes on a function or method that does a run-time test to see
-whether the calling thread holds the given capability.  The function is assumed
-to fail (no return) if the capability is not held.  See :ref:`mutexheader`,
-below, for example uses.
+These are attributes on a function or method which asserts the calling thread
+already holds the given capability, for example by performing a run-time test
+and terminating if the capability is not held.  Presence of this annotation
+causes the analysis to assume the capability is held after calls to the
+annotated function.  See :ref:`mutexheader`, below, for example uses.
 
 
 GUARDED_VAR and PT_GUARDED_VAR