[clang] Thread Safety Analysis: Support reentrant capabilities (PR #137133)

[Aaron Puchert via cfe-commits]

================
@@ -434,6 +434,16 @@ class can be used as a capability.  The string argument specifies the kind of
 capability in error messages, e.g. ``"mutex"``.  See the ``Container`` example
 given above, or the ``Mutex`` class in :ref:`mutexheader`.
 
+REENTRANT
+---------
+
+``REENTRANT`` is an attribute on capability classes, denoting that they are
+reentrant. Marking a capability as reentrant means that acquiring the same
+capability multiple times is safe.
+
+Note that acquiring the same capability with different access privileges
+(exclusive vs. shared) again is not considered reentrant by the analysis.
----------------
aaronpuchert wrote:

Perhaps we could add a sentence that this is usually not needed, because the analysis will only complain about double locking that's provably unnecessary. It's only in cases where  locking is happening through abstractions that double locking might be hard to prevent.

https://github.com/llvm/llvm-project/pull/137133