[PATCH] D87629: Thread safety analysis: Improve documentation for ASSERT_CAPABILITY
Russell Yanofsky via Phabricator via cfe-commits
cfe-commits at lists.llvm.org
Thu Sep 17 11:58:29 PDT 2020
ryanofsky updated this revision to Diff 292576.
ryanofsky added a comment.
Removed bad information about exceptions, added sentence to clarify what it means for the analysis to "assume" something, tweaked description to only say asserts affect assumptions after calls instead of at or before calls, dropped "no return" sentence because it's redundant and could still imply annotation shouldn't be used with NDEBUG asserts that do return
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D87629/new/
https://reviews.llvm.org/D87629
Files:
clang/docs/ThreadSafetyAnalysis.rst
Index: clang/docs/ThreadSafetyAnalysis.rst
===================================================================
--- clang/docs/ThreadSafetyAnalysis.rst
+++ clang/docs/ThreadSafetyAnalysis.rst
@@ -144,6 +144,9 @@
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 @@
*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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D87629.292576.patch
Type: text/x-patch
Size: 1507 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20200917/0387e6c5/attachment.bin>
More information about the cfe-commits
mailing list