[clang] 8544def - Thread safety analysis: Document how try-acquire is handled

[Aaron Puchert via cfe-commits]

Author: Aaron Puchert
Date: 2020-09-05T14:26:43+02:00
New Revision: 8544defdcb09bbbbc25c5958e5f5b5762e9b9046

URL: https://github.com/llvm/llvm-project/commit/8544defdcb09bbbbc25c5958e5f5b5762e9b9046
DIFF: https://github.com/llvm/llvm-project/commit/8544defdcb09bbbbc25c5958e5f5b5762e9b9046.diff

LOG: Thread safety analysis: Document how try-acquire is handled

I don't think this is obvious, since try-acquire seemingly contradicts
our usual requirements of "no conditional locking".

Reviewed By: aaron.ballman

Differential Revision: https://reviews.llvm.org/D87065

Added: 
    

Modified: 
    clang/docs/ThreadSafetyAnalysis.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/ThreadSafetyAnalysis.rst b/clang/docs/ThreadSafetyAnalysis.rst
index ea8e98a1884b..b8d7d24275b9 100644
--- a/clang/docs/ThreadSafetyAnalysis.rst
+++ b/clang/docs/ThreadSafetyAnalysis.rst
@@ -414,6 +414,26 @@ The first argument must be ``true`` or ``false``, to specify which return value
 indicates success, and the remaining arguments are interpreted in the same way
 as ``ACQUIRE``.  See :ref:`mutexheader`, below, for example uses.
 
+Because the analysis doesn't support conditional locking, a capability is
+treated as acquired after the first branch on the return value of a try-acquire
+function.
+
+.. code-block:: c++
+
+  Mutex mu;
+  int a GUARDED_BY(mu);
+
+  void foo() {
+    bool success = mu.TryLock();
+    a = 0;         // Warning, mu is not locked.
+    if (success) {
+      a = 0;       // Ok.
+      mu.Unlock();
+    } else {
+      a = 0;       // Warning, mu is not locked.
+    }
+  }
+
 
 ASSERT_CAPABILITY(...) and ASSERT_SHARED_CAPABILITY(...)
 --------------------------------------------------------