[clang][analyzer][NFC] Improve docs of alpha.unix.BlockInCriticalSection

[gamesh411]

• Enhanced descriptions for blocking and critical section functions
• Added an additional code sample highlighting interleaved C and C++
  style mutexes

[llvmbot]

@llvm/pr-subscribers-clang

Author: Endre Fülöp (gamesh411)

Changes

• Enhanced descriptions for blocking and critical section functions
• Added an additional code sample highlighting interleaved C and C++
  style mutexes
• Introduced a new section on limitations

---

Full diff: https://github.com/llvm/llvm-project/pull/93812.diff

1 Files Affected:

• (modified) clang/docs/analyzer/checkers.rst (+22-8)

diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index 3a31708a1e9de..58adc0e62173a 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3135,19 +3135,33 @@ alpha.unix
 alpha.unix.BlockInCriticalSection (C)
 """""""""""""""""""""""""""""""""""""
 Check for calls to blocking functions inside a critical section.
-Applies to: ``lock, unlock, sleep, getc, fgets, read, recv, pthread_mutex_lock,``
-`` pthread_mutex_unlock, mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock, lock_guard, unique_lock``
+Blocking functions detected by this checker: ``sleep, getc, fgets, read, recv``.
+Critical section handling functions modelled by this checker: ``lock, unlock, pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock, mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock, lock_guard, unique_lock``.
 
 .. code-block:: c
 
- void test() {
-   std::mutex m;
-   m.lock();
-   sleep(3); // warn: a blocking function sleep is called inside a critical
-             //       section
-   m.unlock();
+ void pthread_lock_example(pthread_mutex_t *m) {
+   pthread_mutex_lock(m); // note: entering critical section here
+   sleep(10); // warn: Call to blocking function 'sleep' inside of critical section
+   pthread_mutex_unlock(m);
+ }
+
+.. code-block:: cpp
+
+ void overlapping_critical_sections(mtx_t *m1, std::mutex &m2) {
+   std::lock_guard lg{m2}; // note: entering critical section here
+   mtx_lock(m1); // note: entering critical section here
+   sleep(10); // warn: Call to blocking function 'sleep' inside of critical section
+   mtx_unlock(m1);
+   sleep(10); // warn: Call to blocking function 'sleep' inside of critical section
+             // still inside of the critical section of the std::lock_guard
  }
 
+**Limitations**
+
+* The ``trylock`` and ``timedlock`` versions of acquiring locks are currently handled as if they always succeeded.
+  This can lead to false positives.
+
 .. _alpha-unix-Chroot:
 
 alpha.unix.Chroot (C)

[llvmbot]

@llvm/pr-subscribers-clang-static-analyzer-1

Author: Endre Fülöp (gamesh411)

Changes

• Enhanced descriptions for blocking and critical section functions
• Added an additional code sample highlighting interleaved C and C++
  style mutexes
• Introduced a new section on limitations

---

Full diff: https://github.com/llvm/llvm-project/pull/93812.diff

1 Files Affected:

• (modified) clang/docs/analyzer/checkers.rst (+22-8)

diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst
index 3a31708a1e9de..58adc0e62173a 100644
--- a/clang/docs/analyzer/checkers.rst
+++ b/clang/docs/analyzer/checkers.rst
@@ -3135,19 +3135,33 @@ alpha.unix
 alpha.unix.BlockInCriticalSection (C)
 """""""""""""""""""""""""""""""""""""
 Check for calls to blocking functions inside a critical section.
-Applies to: ``lock, unlock, sleep, getc, fgets, read, recv, pthread_mutex_lock,``
-`` pthread_mutex_unlock, mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock, lock_guard, unique_lock``
+Blocking functions detected by this checker: ``sleep, getc, fgets, read, recv``.
+Critical section handling functions modelled by this checker: ``lock, unlock, pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock, mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock, lock_guard, unique_lock``.
 
 .. code-block:: c
 
- void test() {
-   std::mutex m;
-   m.lock();
-   sleep(3); // warn: a blocking function sleep is called inside a critical
-             //       section
-   m.unlock();
+ void pthread_lock_example(pthread_mutex_t *m) {
+   pthread_mutex_lock(m); // note: entering critical section here
+   sleep(10); // warn: Call to blocking function 'sleep' inside of critical section
+   pthread_mutex_unlock(m);
+ }
+
+.. code-block:: cpp
+
+ void overlapping_critical_sections(mtx_t *m1, std::mutex &m2) {
+   std::lock_guard lg{m2}; // note: entering critical section here
+   mtx_lock(m1); // note: entering critical section here
+   sleep(10); // warn: Call to blocking function 'sleep' inside of critical section
+   mtx_unlock(m1);
+   sleep(10); // warn: Call to blocking function 'sleep' inside of critical section
+             // still inside of the critical section of the std::lock_guard
  }
 
+**Limitations**
+
+* The ``trylock`` and ``timedlock`` versions of acquiring locks are currently handled as if they always succeeded.
+  This can lead to false positives.
+
 .. _alpha-unix-Chroot:
 
 alpha.unix.Chroot (C)

[NagyDonat]

What's the relationship between this PR and #93799 ?

Otherwise, the change LGTM, but you might want to either unify these two NFC changes into a single commit or ensure that they're independent.

[gamesh411]

What's the relationship between this PR and #93799 ?

Otherwise, the change LGTM, but you might want to either unify these two NFC changes into a single commit or ensure that they're independent.

Thanks for checking this!
To be honest, I started working on this, and then it hit me that a test case for the limitation would be nice 😸
My intention was to ease the review as much as possible by cutting them into atomic parts.
They could indeed be independent; I will leave the limitation out of this and just introduce it in the other patch.

[NagyDonat]

My intention was to ease the review as much as possible by cutting them into atomic parts.

This is a good idea in general, but I feel that these two changes are so trivial, that they'd be very easy to review even together. Feel free to merge them both in whatever combination you would like.