maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

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
This commit is contained in:
Russell Yanofsky 2020-09-26 22:11:43 +02:00 committed by Aaron Puchert
parent c2921d148e
commit f702a6fa7c
1 changed files with 8 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
clang/docs/ThreadSafetyAnalysis.rst
View File

@ -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