From 5a15ad5d15604515fffce38d6560445c6fff7c7a Mon Sep 17 00:00:00 2001
From: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Date: Wed, 8 Jul 2026 11:23:44 +0100
Subject: [PATCH] [mypyc] Document librt.threading

---
 mypyc/doc/index.rst           |  1 +
 mypyc/doc/librt.rst           |  2 ++
 mypyc/doc/librt_threading.rst | 54 +++++++++++++++++++++++++++++++++++
 3 files changed, 57 insertions(+)
 create mode 100644 mypyc/doc/librt_threading.rst

diff --git a/mypyc/doc/index.rst b/mypyc/doc/index.rst
index aacf275de9885..3f74595dd47fb 100644
--- a/mypyc/doc/index.rst
+++ b/mypyc/doc/index.rst
@@ -35,6 +35,7 @@ generate fast code.
    librt_base64
    librt_random
    librt_strings
+   librt_threading
    librt_time
    librt_vecs
 
diff --git a/mypyc/doc/librt.rst b/mypyc/doc/librt.rst
index 23206f8cfe806..681efe47e7603 100644
--- a/mypyc/doc/librt.rst
+++ b/mypyc/doc/librt.rst
@@ -30,6 +30,8 @@ Follow submodule links in the table to a detailed description of each submodule.
      - Pseudorandom number generation
    * - :doc:`librt.strings <librt_strings>`
      - String and bytes utilities
+   * - :doc:`librt.threading <librt_threading>`
+     - Threading primitives
    * - :doc:`librt.time <librt_time>`
      - Time utilities
    * - :doc:`librt.vecs <librt_vecs>`
diff --git a/mypyc/doc/librt_threading.rst b/mypyc/doc/librt_threading.rst
new file mode 100644
index 0000000000000..c6cb5c9e84e72
--- /dev/null
+++ b/mypyc/doc/librt_threading.rst
@@ -0,0 +1,54 @@
+.. _librt-threading:
+
+librt.threading
+===============
+
+The ``librt.threading`` module is part of the ``librt`` package on PyPI, and it includes
+threading primitives.
+
+Classes
+-------
+
+Lock
+^^^^
+
+.. class:: Lock
+
+   A fast mutual exclusion lock. This can be used as a faster replacement for
+   :py:class:`threading.Lock` in compiled code.
+
+   Like :py:class:`threading.Lock`, a ``Lock`` is *unowned*: it may be released by a thread
+   other than the one that acquired it, and it doesn't support reentrant (recursive) locking.
+   A newly created lock is unlocked.
+
+   ``Lock`` can be used as a context manager. The lock is acquired (blocking) on entry and
+   released on exit, including when the body raises an exception::
+
+       def example(lock: Lock) -> None:
+           with lock:
+               ...  # Critical section; the lock is held here.
+
+   ``Lock`` cannot be subclassed. ``Lock`` cannot be used with :py:class:`threading.Condition`.
+
+   .. method:: acquire(blocking: bool = True) -> bool
+
+      Acquire the lock.
+
+      When *blocking* is true (the default), block (if needed) until the lock is available,
+      acquire it, and return ``True``. When *blocking* is false, acquire the lock only if it
+      can be done without blocking: return ``True`` if the lock could be acquired, or
+      ``False`` otherwise (it was already locked by some thread).
+
+      Unlike :py:meth:`threading.Lock.acquire`, there is no *timeout* argument.
+
+   .. method:: release() -> None
+
+      Release the lock, allowing another thread (if any) that is blocked on :meth:`acquire`
+      to proceed. Since the lock is unowned, it may be released from a thread other than the
+      one that acquired it.
+
+      Raise :py:exc:`RuntimeError` if the lock is not currently held.
+
+   .. method:: locked() -> bool
+
+      Return ``True`` if the lock is currently held (by any thread).