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