From 89220a418a522a33a3bbc45667784719fae9e853 Mon Sep 17 00:00:00 2001
From: David Wilson <dw@botanicus.net>
Date: Thu, 28 Sep 2017 14:14:50 +0530
Subject: [PATCH] Document Sender and Receiver classes.

---
 docs/api.rst    | 119 +++++++++++++++++++++++++++++++++++++++++++++---
 mitogen/core.py |   2 -
 2 files changed, 112 insertions(+), 9 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index c75f5d37..a9e922cf 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -192,24 +192,129 @@ Broker Class
 
 
 Context Class
-=============
+-------------
 
 .. autoclass:: mitogen.master.Context
    :members:
    :inherited-members:
 
 
-Channel Class
--------------
+Receiver Class
+--------------
 
-.. autoclass:: mitogen.core.Channel
-   :members:
+.. class:: mitogen.core.Receiver (router, handle=None, persist=True, respondent=None)
 
+    Receivers are used to wait for pickled responses from another context to be
+    sent to a handle registered in this context. A receiver may be single-use
+    (as in the case of :py:meth:`mitogen.master.Context.call_async`) or
+    multiple use.
 
-Context Class
+    :param mitogen.core.Router router:
+        Router to register the handler on.
+
+    :param int handle:
+        If not ``None``, an explicit handle to register, otherwise an unused
+        handle is chosen.
+
+    :param bool persist:
+        If ``True``, do not unregister the receiver's handler after the first
+        message.
+
+    :param mitogen.core.Context respondent:
+        Reference to the context this receiver is receiving from. If not
+        ``None``, arranges for the receiver to receive
+        :py:data:`mitogen.core._DEAD` if messages can no longer be routed to
+        the context, due to disconnection or exit.
+
+    .. attribute:: notify = None
+
+        If not ``None``, a reference to a function invoked as
+        `notify(receiver)` when a new message is delivered to this receiver.
+        Used by :py:class:`mitogen.master.Select` to implement waiting on
+        multiple receivers.
+
+    .. py:method:: empty ()
+
+        Return ``True`` if calling :py:meth:`get` would block.
+
+        As with :py:class:`Queue.Queue`, ``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`.
+
+        :py:meth:`empty` is only useful to avoid a race while installing
+        :py:attr:`notify`:
+
+        .. code-block:: python
+
+            recv.notify = _my_notify_function
+            if not recv.empty():
+                _my_notify_function(recv)
+
+            # It is guaranteed the receiver was empty after the notification
+            # function was installed, or that it was non-empty and the
+            # notification function was invoked.
+
+    .. py:method:: close ()
+
+        Cause :py:class:`mitogen.core.ChannelError` to be raised in any thread
+        waiting in :py:meth:`get` on this receiver.
+
+    .. py:method:: get (timeout=None)
+
+        Sleep waiting for a message to arrive on this receiver.
+
+        :param float timeout:
+            If not ``None``, specifies a timeout in seconds.
+
+        :raises mitogen.core.ChannelError:
+            The remote end indicated the channel should be closed, or
+            communication with its parent context was lost.
+
+        :raises mitogen.core.TimeoutError:
+            Timeout was reached.
+
+        :returns:
+            `(msg, data)` tuple, where `msg` is the
+            :py:class:`mitogen.core.Message` that was received, and `data` is
+            its unpickled data part.
+
+    .. py:method:: get_data (timeout=None)
+
+        Like :py:meth:`get`, except only return the data part.
+
+    .. py:method:: __iter__ ()
+
+        Block and yield `(msg, data)` pairs delivered to this receiver until
+        :py:class:`mitogen.core.ChannelError` is raised.
+
+
+Sender Class
+------------
+
+.. class:: mitogen.core.Sender (context, dst_handle)
+
+    Senders are used to send pickled messages to a handle in another context,
+    it is the inverse of :py:class:`mitogen.core.Sender`.
+
+    :param mitogen.core.Context context:
+        Context to send messages to.
+    :param int dst_handle:
+        Destination handle to send messages to.
+
+    .. py:method:: close ()
+
+        Send :py:data:`mitogen.core._DEAD` to the remote end, causing
+        :py:meth:`ChannelError` to be raised in any waiting thread.
+
+    .. py:method:: put (data)
+
+        Send `data` to the remote end.
+
+
+Channel Class
 -------------
 
-.. autoclass:: mitogen.master.Context
+.. autoclass:: mitogen.core.Channel
    :members:
 
 
diff --git a/mitogen/core.py b/mitogen/core.py
index 770dcb9b..db2ce8c1 100644
--- a/mitogen/core.py
+++ b/mitogen/core.py
@@ -309,7 +309,6 @@ class Receiver(object):
         return self._queue.empty()
 
     def get(self, timeout=None):
-        """Receive an object, or ``None`` if `timeout` is reached."""
         IOLOG.debug('%r.on_receive(timeout=%r)', self, timeout)
 
         msg = _queue_interruptible_get(self._queue, timeout)
@@ -332,7 +331,6 @@ class Receiver(object):
         return self.get(timeout)[1]
 
     def __iter__(self):
-        """Yield objects from this channel until it is closed."""
         while True:
             try:
                 yield self.get()