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 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
