[PATCH] D87629: Thread safety analysis: Improve documentation for ASSERT_CAPABILITY

[Russell Yanofsky via Phabricator via cfe-commits]

ryanofsky created this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.
ryanofsky requested review of this revision.

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. (For an example, see
https://github.com/bitcoin/bitcoin/pull/19929)


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D87629

Files:
  clang/docs/ThreadSafetyAnalysis.rst


Index: clang/docs/ThreadSafetyAnalysis.rst
===================================================================
--- clang/docs/ThreadSafetyAnalysis.rst
+++ clang/docs/ThreadSafetyAnalysis.rst
@@ -447,10 +447,14 @@
 
 *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 or throwing if the capability is not held.  Presence of this
+annotation causes the analysis to assume the capability is held at the point of
+the call. See :ref:`mutexheader`, below, for example uses.
+
+The given capability must be held on entry to the function, or the function is
+assumed to fail (no return).
 
 
 GUARDED_VAR and PT_GUARDED_VAR


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D87629.291658.patch
Type: text/x-patch
Size: 1071 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20200914/f90aa68b/attachment.bin>