diff --git a/docs/howitworks.rst b/docs/howitworks.rst index c5197b18..c26c79d6 100644 --- a/docs/howitworks.rst +++ b/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 ####################### diff --git a/docs/internals.rst b/docs/internals.rst index 5dbf431f..84f70521 100644 --- a/docs/internals.rst +++ b/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 ----------