diff --git a/docs/howitworks.rst b/docs/howitworks.rst index 8dabfa88..16c8189a 100644 --- a/docs/howitworks.rst +++ b/docs/howitworks.rst @@ -338,8 +338,8 @@ Sentinel Value The special value :py:data:`econtext.core._DEAD` is used to signal disconnection or closure of the remote end. It is used internally by :py:class:`Channel ` and also passed to any function -still registered with :py:meth:`add_handle_cb() -` during Broker shutdown. +still registered with :py:meth:`add_handler() +` during Broker shutdown. Use of Pickle @@ -387,26 +387,23 @@ Twisted that we would like to use. Message Routing --------------- -At present routing is very simple, and assumes that it is impossible for a tree -of contexts to be constructed such that at least one of a context's indirect -parents will not know the ID of a target the context is attempting to +Routing assumes it is impossible to construct a tree such that one of a +context's parents will not know the ID of a target the context is attempting to communicate with. -When :py:class:`econtext.core.Router` receives a message, it first checks the -IDs associated with its directly connected streams for a potential route for -the message. If one of the streams matches, either because the stream directly -connects to the target ID, or the master has sent an ``ADD_ROUTE`` message -associating that stream with the target ID, then the message will be forwarded -down the tree using that stream. +When :py:class:`econtext.core.Router` receives a message, it checks the IDs +associated with its directly connected streams for a potential route. If any +stream matches, either because it directly connects to the target ID, or +because the master sent an ``ADD_ROUTE`` message associating it, then the +message will be forwarded down the tree using that stream. -If the message does not match any ``ADD_ROUTE`` message or directly connected -stream, instead it is forwarded upstream, first to the context's parent, and -recursively by the each parent context in turn, until some tree node is reached -that knows how to forward the message back down the tree. +If the message does not match any ``ADD_ROUTE`` message or stream, instead it +is forwarded upwards to the immediate parent, and recursively by each parent in +turn until one is reached that knows how to forward the message down the tree. When the master establishes a new context via an existing child context, it -takes care to send corresponding ``ADD_ROUTE`` messages to each indirect parent -up the tree. +sends corresponding ``ADD_ROUTE`` messages to each indirect parent between the +context and the root. Example