Merge #19249: Add means to handle negative capabilities in the Clang Thread Safety annotations

f8213c05f0 Add means to handle negative capabilities in thread safety annotations (Hennadii Stepanov)

Pull request description:

  This commit is separated from #19238, and it adds support of [Negative Capabilities](https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#negative) in the Clang Thread Safety Analysis attributes.

  > Negative requirements are an alternative `EXCLUDES` [`LOCKS_EXCLUDED`] that provide a stronger safety guarantee. A negative requirement uses the `REQUIRES` [`EXCLUSIVE_LOCKS_REQUIRED`] attribute, in conjunction with the ! operator, to indicate that a capability should not be held.

  Examples of usage:
  - #19238 (for a class)
  - https://github.com/hebasto/bitcoin/tree/200610-addrman-tsn (for the whole code base)

ACKs for top commit:
  MarcoFalke:
    Approach ACK f8213c05f0
  vasild:
    ACK f8213c05

Tree-SHA512: 86d992826b87579661bd228712ae5ee6acca6f70b885ef7e96458974eac184e4874a525c669607ba6b6c861aa4806409a8792d100e6914c858bcab43d31cfb1b

src/sync.h

@@ -103,6 +103,12 @@ public:
     }
 
     using UniqueLock = std::unique_lock<PARENT>;
+#ifdef __clang__
+    //! For negative capabilities in the Clang Thread Safety Analysis.
+    //! A negative requirement uses the EXCLUSIVE_LOCKS_REQUIRED attribute, in conjunction
+    //! with the ! operator, to indicate that a mutex should not be held.
+    const AnnotatedMixin& operator!() const { return *this; }
+#endif // __clang__
 };
 
 /**

src/threadsafety.h

@@ -60,6 +60,13 @@
 // and should only be used when sync.h Mutex/LOCK/etc are not usable.
 class LOCKABLE StdMutex : public std::mutex
 {
+public:
+#ifdef __clang__
+    //! For negative capabilities in the Clang Thread Safety Analysis.
+    //! A negative requirement uses the EXCLUSIVE_LOCKS_REQUIRED attribute, in conjunction
+    //! with the ! operator, to indicate that a mutex should not be held.
+    const StdMutex& operator!() const { return *this; }
+#endif // __clang__
 };
 
 // StdLockGuard provides an annotated version of std::lock_guard for us,