docs: another round of docstring cleanups.

docs/api.rst

@@ -96,8 +96,12 @@ Router Class
     :members:
 
 
-.. currentmodule:: mitogen.master
+.. currentmodule:: mitogen.parent
+.. autoclass:: Router
+   :members:
+
 
+.. currentmodule:: mitogen.master
 .. autoclass:: Router (broker=None)
    :members:
 
@@ -553,11 +557,11 @@ Context Class
 
 
 .. currentmodule:: mitogen.parent
-
-.. autoclass:: CallChain
+.. autoclass:: Context
     :members:
 
-.. autoclass:: Context
+.. currentmodule:: mitogen.parent
+.. autoclass:: CallChain
     :members:
 
 

docs/howitworks.rst

@@ -346,11 +346,15 @@ Masters listen on the following handles:
 .. currentmodule:: mitogen.core
 .. data:: ALLOCATE_ID
 
-    Replies to any message sent to it with a newly allocated range of context
-    IDs, to allow children to safely start their own contexts. Presently IDs
-    are allocated in batches of 1000 from a 32 bit range, allowing up to 4.2
-    million parent contexts to be created and destroyed before the associated
-    Router must be recreated.
+   Replies to any message sent to it with a newly allocated range of context
+   IDs, to allow children to safely start their own contexts. Presently IDs are
+   allocated in batches of 1000 from a 32 bit range, allowing up to 4.2 million
+   parent contexts to be created and destroyed before the associated Router
+   must be recreated.
+
+   This is handled by :class:`mitogen.master.IdAllocator` in the master
+   process, and messages are sent to it from
+   :class:`mitogen.parent.ChildIdAllocator` in children.
 
 Children listen on the following handles:
 

docs/internals.rst

@@ -99,7 +99,7 @@ Stream, Side & Protocol
    :members:
 
 
-Connection / Options
+Connection & Options
 ====================
 
 .. currentmodule:: mitogen.fork
@@ -191,6 +191,18 @@ Timer Management
    :members:
 
 
+Context ID Allocation
+=====================
+
+.. currentmodule:: mitogen.master
+.. autoclass:: IdAllocator
+   :members:
+
+.. currentmodule:: mitogen.parent
+.. autoclass:: ChildIdAllocator
+   :members:
+
+
 Child Implementation
 ====================
 

mitogen/core.py

@@ -2733,7 +2733,12 @@ class Router(object):
     **Note:** This is the somewhat limited core version of the Router class
     used by child contexts. The master subclass is documented below this one.
     """
+    #: The :class:`mitogen.core.Context` subclass to use when constructing new
+    #: :class:`Context` objects in :meth:`myself` and :meth:`context_by_id`.
+    #: Permits :class:`Router` subclasses to extend the :class:`Context`
+    #: interface, as done in :class:`mitogen.parent.Router`.
     context_class = Context
+
     max_message_size = 128 * 1048576
 
     #: When :data:`True`, permit children to only communicate with the current
@@ -2829,7 +2834,9 @@ class Router(object):
 
     def myself(self):
         """
-        Return a :class:`Context` referring to the current process.
+        Return a :class:`Context` referring to the current process. Since
+        :class:`Context` is serializable, this is convenient to use in remote
+        function call parameter lists.
         """
         return self.context_class(
             router=self,
@@ -2839,8 +2846,25 @@ class Router(object):
 
     def context_by_id(self, context_id, via_id=None, create=True, name=None):
         """
-        Messy factory/lookup function to find a context by its ID, or construct
-        it. This will eventually be replaced by a more sensible interface.
+        Return or construct a :class:`Context` given its ID. An internal
+        mapping of ID to the canonical :class:`Context` representing that ID,
+        so that :ref:`signals` can be raised.
+
+        This may be called from any thread, lookup and construction are atomic.
+
+        :param int context_id:
+            The context ID to look up.
+        :param int via_id:
+            If the :class:`Context` does not already exist, set its
+            :attr:`Context.via` to the :class:`Context` matching this ID.
+        :param bool create:
+            If the :class:`Context` does not already exist, create it.
+        :param str name:
+            If the :class:`Context` does not already exist, set its name.
+
+        :returns:
+            :class:`Context`, or return :data:`None` if `create` is
+            :data:`False` and no :class:`Context` previously existed.
         """
         context = self._context_by_id.get(context_id)
         if context:
@@ -2885,7 +2909,13 @@ class Router(object):
         """
         Return the :class:`Stream` that should be used to communicate with
         `dst_id`. If a specific route for `dst_id` is not known, a reference to
-        the parent context's stream is returned.
+        the parent context's stream is returned. If the parent is disconnected,
+        or when running in the master context, return :data:`None` instead.
+
+        This can be used from any thread, but its output is only meaningful
+        from the context of the :class:`Broker` thread, as disconnection or
+        replacement could happen in parallel on the broker thread at any
+        moment. 
         """
         return (
             self._stream_by_id.get(dst_id) or
@@ -2996,7 +3026,7 @@ class Router(object):
     def on_shutdown(self, broker):
         """
         Called during :meth:`Broker.shutdown`, informs callbacks registered
-        with :meth:`add_handle_cb` the connection is dead.
+        with :meth:`add_handler` the connection is dead.
         """
         _v and LOG.debug('%r: shutting down', self, broker)
         fire(self, 'shutdown')

mitogen/master.py

@@ -1228,6 +1228,21 @@ class Router(mitogen.parent.Router):
 
 
 class IdAllocator(object):
+    """
+    Allocate IDs for new contexts constructed locally, and blocks of IDs for
+    children to allocate their own IDs using
+    :class:`mitogen.parent.ChildIdAllocator` without risk of conflict, and
+    without necessitating network round-trips for each new context.
+
+    This class responds to :data:`mitogen.core.ALLOCATE_ID` messages received
+    from children by replying with fresh block ID allocations.
+
+    The master's :class:`IdAllocator` instance can be accessed via
+    :attr:`mitogen.master.Router.id_allocator`.
+    """
+    #: Block allocations are made in groups of 1000 by default.
+    BLOCK_SIZE = 1000
+
     def __init__(self, router):
         self.router = router
         self.next_id = 1
@@ -1240,14 +1255,12 @@ class IdAllocator(object):
     def __repr__(self):
         return 'IdAllocator(%r)' % (self.router,)
 
-    BLOCK_SIZE = 1000
-
     def allocate(self):
         """
-        Arrange for a unique context ID to be allocated and associated with a
-        route leading to the active context. In masters, the ID is generated
-        directly, in children it is forwarded to the master via a
-        :data:`mitogen.core.ALLOCATE_ID` message.
+        Allocate a context ID by directly incrementing an internal counter.
+
+        :returns:
+            The new context ID.
         """
         self.lock.acquire()
         try:
@@ -1258,6 +1271,15 @@ class IdAllocator(object):
             self.lock.release()
 
     def allocate_block(self):
+        """
+        Allocate a block of IDs for use in a child context.
+
+        This function is safe to call from any thread.
+
+        :returns:
+            Tuple of the form `(id, end_id)` where `id` is the first usable ID
+            and `end_id` is the last usable ID.
+        """
         self.lock.acquire()
         try:
             id_ = self.next_id

mitogen/parent.py

@@ -1252,6 +1252,10 @@ class Options(object):
 
 class Connection(object):
     """
+    Manage the lifetime of a set of :class:`Streams <Stream>` connecting to a
+    remote Python interpreter, including bootstrap, disconnection, and external
+    tool integration.
+
     Base for streams capable of starting children.
     """
     options_class = Options
@@ -1597,12 +1601,28 @@ class Connection(object):
 
 
 class ChildIdAllocator(object):
+    """
+    Allocate new context IDs from a block of unique context IDs allocated by
+    the master process.
+    """
     def __init__(self, router):
         self.router = router
         self.lock = threading.Lock()
         self.it = iter(xrange(0))
 
     def allocate(self):
+        """
+        Allocate an ID, requesting a fresh block from the master if the
+        existing block is exhausted.
+
+        :returns:
+            The new context ID.
+
+        .. warning::
+
+            This method is not safe to call from the :class:`Broker` thread, as
+            it may block on IO of its own.
+        """
         self.lock.acquire()
         try:
             for id_ in self.it:
@@ -2193,7 +2213,8 @@ class Router(mitogen.core.Router):
 
     def get_streams(self):
         """
-        Return a snapshot of all streams in existence at time of call.
+        Return an atomic snapshot of all streams in existence at time of call.
+        This is safe to call from any thread.
         """
         self._write_lock.acquire()
         try:
@@ -2220,11 +2241,18 @@ class Router(mitogen.core.Router):
 
     def add_route(self, target_id, stream):
         """
-        Arrange for messages whose `dst_id` is `target_id` to be forwarded on
-        the directly connected stream for `via_id`. This method is called
-        automatically in response to :data:`mitogen.core.ADD_ROUTE` messages,
-        but remains public while the design has not yet settled, and situations
-        may arise where routing is not fully automatic.
+        Arrange for messages whose `dst_id` is `target_id` to be forwarded on a
+        directly connected :class:`Stream`. Safe to call from any thread.
+
+        This is called automatically by :class:`RouteMonitor` in response to
+        :data:`mitogen.core.ADD_ROUTE` messages, but remains public while the
+        design has not yet settled, and situations may arise where routing is
+        not fully automatic.
+
+        :param int target_id:
+            Target context ID to add a route for.
+        :param mitogen.core.Stream stream:
+            Stream over which messages to the target should be routed.
         """
         LOG.debug('%r: adding route to context %r via %r',
                   self, target_id, stream)
@@ -2238,6 +2266,19 @@ class Router(mitogen.core.Router):
             self._write_lock.release()
 
     def del_route(self, target_id):
+        """
+        Delete any route that exists for `target_id`. It is not an error to
+        delete a route that does not currently exist. Safe to call from any
+        thread.
+
+        This is called automatically by :class:`RouteMonitor` in response to
+        :data:`mitogen.core.DEL_ROUTE` messages, but remains public while the
+        design has not yet settled, and situations may arise where routing is
+        not fully automatic.
+
+        :param int target_id:
+            Target context ID to delete route for.
+        """
         LOG.debug('%r: deleting route to %r', self, target_id)
         # DEL_ROUTE may be sent by a parent if it knows this context sent
         # messages to a peer that has now disconnected, to let us raise