docs: mitogen.core.Latch docs

docs/howitworks.rst

@@ -813,6 +813,8 @@ on Windows. When that happens, it would be nice if the process model on Windows
 and UNIX did not differ, and in fact the code used on both were identical.
 
 
+.. _waking-sleeping-threads:
+
 Waking Sleeping Threads
 #######################
 

docs/internals.rst

@@ -7,6 +7,65 @@ mitogen.core
 ============
 
 
+Latch Class
+-----------
+
+.. currentmodule:: mitogen.core
+
+.. class:: Latch ()
+
+    A latch is a :py:class:`Queue.Queue`-like object that supports mutation and
+    waiting from multiple threads, however unlike :py:class:`Queue.Queue`,
+    waiting threads always remain interruptible, so CTRL+C always succeeds, and
+    waits where a timeout is set experience no wake up latency. These
+    properties are not possible in combination using the built-in threading
+    primitives available in Python 2.x.
+
+    Latches implement queues using the UNIX self-pipe trick, and a per-thread
+    :py:func:`socket.socketpair` that is lazily created the first time any
+    latch attempts to sleep on a thread, and dynamically associated with the
+    waiting Latch only for duration of the wait.
+
+    See :ref:`waking-sleeping-threads` for further discussion.
+
+    .. method:: empty ()
+
+        Return :py:data:`True` if calling :py:meth:`get` would block.
+
+        As with :py:class:`Queue.Queue`, :py:data:`True` may be returned even
+        though a subsequent call to :py:meth:`get` will succeed, since a
+        message may be posted at any moment between :py:meth:`empty` and
+        :py:meth:`get`.
+
+        As with :py:class:`Queue.Queue`, :py:data:`False` may be returned even
+        though a subsequent call to :py:meth:`get` will block, since another
+        waiting thread may be woken at any moment between :py:meth:`empty` and
+        :py:meth:`get`.
+
+    .. method:: get (timeout=None, block=True)
+
+        Return the next object enqueued on this latch, or sleep waiting for
+        one.
+
+        :param float timeout:
+            If not :py:data:`None`, specifies a timeout in seconds.
+
+        :param bool block:
+            If :py:data:`False`, immediately raise
+            :py:class:`mitogen.core.TimeoutError` if the latch is empty.
+
+        :raises mitogen.core.TimeoutError:
+            Timeout was reached.
+
+        :returns:
+            The de-queued object.
+
+    .. method:: put (obj)
+
+        Enquue an object on this latch, waking the first thread that is asleep
+        waiting for a result, if one exists.
+
+
 Side Class
 ----------