Thread safety analysis: Test and document release_generic_capability

[aaronpuchert]

Summary

The old locking attributes had a generic release, but as it turns out
the capability-based attributes have it as well.

[aaron.ballman]

LGTM!

[aaronpuchert]

Add some prose, not just code. Otherwise our list of attributes would be incomplete.

@aaron.ballman, I think you should have another look. Sorry for missing that in my first patch.

[aaron.ballman]

LGTM!

clang/docs/ThreadSafetyAnalysis.rst

824

This is not something you should feel obligated to fix (esp not as part of this patch), but I just realized we have a naming-related UB here in C++ with the trailing double underscores: http://eel.is/c++draft/lex.name#3.1 We should probably pick a different identifier to use.

clang/docs/ThreadSafetyAnalysis.rst

.. code-block:: c++
 
   void test() {
     mu1.Lock();
     foo();         // Warning!  Requires mu2.
     mu1.Unlock();
   }
 
 
-ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...)
---------------------------------------------------------------------
+ACQUIRE(...), ACQUIRE_SHARED(...), RELEASE(...), RELEASE_SHARED(...), RELEASE_GENERIC(...)
+------------------------------------------------------------------------------------------
 
 *Previously*: ``EXCLUSIVE_LOCK_FUNCTION``, ``SHARED_LOCK_FUNCTION``,
 ``UNLOCK_FUNCTION``
 
-``ACQUIRE`` is an attribute on functions or methods, which
-declares that the function acquires a capability, but does not release it.  The
-caller must not hold the given capability on entry, and it will hold the
-capability on exit.  ``ACQUIRE_SHARED`` is similar.
-
-``RELEASE`` and ``RELEASE_SHARED`` declare that the function releases the given
-capability.  The caller must hold the capability on entry, and will no longer
-hold it on exit. It does not matter whether the given capability is shared or
-exclusive.
+``ACQUIRE`` and ``ACQUIRE_SHARED`` are attributes on functions or methods
+declaring that the function acquires a capability, but does not release it.
+The given capability must not be held on entry, and will be held on exit
+(exclusively for ``ACQUIRE``, shared for ``ACQUIRE_SHARED``).
+
+``RELEASE``, ``RELEASE_SHARED``, and ``RELEASE_GENERIC`` declare that the
+function releases the given capability.  The capability must be held on entry
+(exclusively for ``RELEASE``, shared for ``RELEASE_SHARED``, exclusively or
+shared for ``RELEASE_GENERIC``), and will no longer be held on exit.
 
 .. code-block:: c++
 
   Mutex mu;
   MyClass myObject GUARDED_BY(mu);
 
   void lockAndInit() ACQUIRE(mu) {
     mu.Lock();
#define ACQUIRE_SHARED(...) \
     THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))
 
   #define RELEASE(...) \
     THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))
 
   #define RELEASE_SHARED(...) \
     THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))
 
+  #define RELEASE_GENERIC(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(__VA_ARGS__))
+
   #define TRY_ACQUIRE(...) \
     THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))
 
   #define TRY_ACQUIRE_SHARED(...) \
     THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))
 
   #define EXCLUDES(...) \
     THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
public:
     void ReaderLock() ACQUIRE_SHARED();
 
     // Release/unlock an exclusive mutex.
     void Unlock() RELEASE();
 
     // Release/unlock a shared mutex.
     void ReaderUnlock() RELEASE_SHARED();
 
+    // Generic unlock, can unlock exclusive and shared mutexes.
+    void GenericUnlock() RELEASE_GENERIC();
+
     // Try to acquire the mutex.  Returns true on success, and false on failure.
     bool TryLock() TRY_ACQUIRE(true);
 
     // Try to acquire the mutex for read operations.
     bool ReaderTryLock() TRY_ACQUIRE_SHARED(true);
 
     // Assert that this mutex is currently held by the calling thread.
     void AssertHeld() ASSERT_CAPABILITY(this);

clang/test/SemaCXX/thread-safety-annotations.h

 // Macros to enable testing of both variants of the thread safety analysis.
 
 #if USE_CAPABILITY
 #define LOCKABLE                        __attribute__((capability("mutex")))
 #define ASSERT_EXCLUSIVE_LOCK(...)      __attribute__((assert_capability(__VA_ARGS__)))
 #define ASSERT_SHARED_LOCK(...)         __attribute__((assert_shared_capability(__VA_ARGS__)))
 #define EXCLUSIVE_LOCK_FUNCTION(...)    __attribute__((acquire_capability(__VA_ARGS__)))
 #define SHARED_LOCK_FUNCTION(...)       __attribute__((acquire_shared_capability(__VA_ARGS__)))
+#define UNLOCK_FUNCTION(...)            __attribute__((release_generic_capability(__VA_ARGS__)))
 #define EXCLUSIVE_TRYLOCK_FUNCTION(...) __attribute__((try_acquire_capability(__VA_ARGS__)))
 #define SHARED_TRYLOCK_FUNCTION(...)    __attribute__((try_acquire_shared_capability(__VA_ARGS__)))
 #define EXCLUSIVE_LOCKS_REQUIRED(...)   __attribute__((requires_capability(__VA_ARGS__)))
 #define SHARED_LOCKS_REQUIRED(...)      __attribute__((requires_shared_capability(__VA_ARGS__)))
 #else
 #define LOCKABLE                        __attribute__((lockable))
 #define ASSERT_EXCLUSIVE_LOCK(...)      __attribute__((assert_exclusive_lock(__VA_ARGS__)))
 #define ASSERT_SHARED_LOCK(...)         __attribute__((assert_shared_lock(__VA_ARGS__)))
 #define EXCLUSIVE_LOCK_FUNCTION(...)    __attribute__((exclusive_lock_function(__VA_ARGS__)))
 #define SHARED_LOCK_FUNCTION(...)       __attribute__((shared_lock_function(__VA_ARGS__)))
+#define UNLOCK_FUNCTION(...)            __attribute__((unlock_function(__VA_ARGS__)))
 #define EXCLUSIVE_TRYLOCK_FUNCTION(...) __attribute__((exclusive_trylock_function(__VA_ARGS__)))
 #define SHARED_TRYLOCK_FUNCTION(...)    __attribute__((shared_trylock_function(__VA_ARGS__)))
 #define EXCLUSIVE_LOCKS_REQUIRED(...)   __attribute__((exclusive_locks_required(__VA_ARGS__)))
 #define SHARED_LOCKS_REQUIRED(...)      __attribute__((shared_locks_required(__VA_ARGS__)))
 #endif
 
 // Lock semantics only
-#define UNLOCK_FUNCTION(...)            __attribute__((unlock_function(__VA_ARGS__)))
 #define GUARDED_VAR                     __attribute__((guarded_var))
 #define PT_GUARDED_VAR                  __attribute__((pt_guarded_var))
 
 // Capabilities only
 #define EXCLUSIVE_UNLOCK_FUNCTION(...)  __attribute__((release_capability(__VA_ARGS__)))
 #define SHARED_UNLOCK_FUNCTION(...)     __attribute__((release_shared_capability(__VA_ARGS__)))
 #define GUARDED_BY(x)                   __attribute__((guarded_by(x)))
 #define PT_GUARDED_BY(x)                __attribute__((pt_guarded_by(x)))
 
 // Common
 #define SCOPED_LOCKABLE                 __attribute__((scoped_lockable))
 #define ACQUIRED_AFTER(...)             __attribute__((acquired_after(__VA_ARGS__)))
 #define ACQUIRED_BEFORE(...)            __attribute__((acquired_before(__VA_ARGS__)))
 #define LOCK_RETURNED(x)                __attribute__((lock_returned(x)))
 #define LOCKS_EXCLUDED(...)             __attribute__((locks_excluded(__VA_ARGS__)))
 #define NO_THREAD_SAFETY_ANALYSIS       __attribute__((no_thread_safety_analysis))