From bd71a2760e23679bc66aec2d375c5a531c028a5d Mon Sep 17 00:00:00 2001 From: David Wilson Date: Tue, 23 Oct 2018 23:16:48 +0100 Subject: [PATCH] docs: describe disconnect propagation; closes #76. --- docs/howitworks.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/howitworks.rst b/docs/howitworks.rst index 2a4623eb..66716124 100644 --- a/docs/howitworks.rst +++ b/docs/howitworks.rst @@ -551,6 +551,28 @@ and trigger ``DEL_ROUTE`` messages propagated upstream for each route associated with that stream if the stream is disconnected for any reason. +Disconnect Propagation +###################### + +To ensure timely shutdown when a failure occurs, where some context is awaiting +a response from another context that has become disconnected, +:class:`mitogen.core.Router` additionally records the destination context ID of +every message received on a particular stream. + +When ``DEL_ROUTE`` is generated locally or received on some other stream, +:class:`mitogen.parent.RouteMonitor` uses this to find every stream that ever +communicated with the route that is about to go away, and forwards the message +to each found. + +The recipient ``DEL_ROUTE`` handler in turn uses the message to find any +:class:`mitogen.core.Context` in the local process corresponding to the +disappearing route, and if found, fires a ``disconnected`` event on it. + +Any interested party, such as :class:`mitogen.core.Receiver`, may subscribe to +the event and use it to abort any threads that were asleep waiting for a reply +that will never arrive. + + Example #######