docs: more updates.

- accurate description of Ansible timeouts
- rough detach() sketch

docs/ansible.rst

@@ -157,9 +157,16 @@ Noteworthy Differences
 * Performance does not scale perfectly linearly with target count. This will
   improve over time.
 
-* Timeouts normally apply to the combined runtime of the SSH and become steps
-  of a task. As Mitogen treats SSH and sudo distincly, during a failure the
-  effective timeout may appear to double.
+* SSH and ``become`` are treated distinctly when applying timeouts, and
+  timeouts apply up to the point when the new interpreter is ready to accept
+  messages. Ansible has two timeouts: ``ConnectTimeout`` for SSH, applying up
+  to when authentication completes, and a separate parallel timeout up to when
+  ``become`` authentication completes.
+
+  For busy targets, Ansible may successfully execute a module where Mitogen
+  would fail without increasing the timeout. For sick targets, Ansible may hang
+  indefinitely after authentication without executing a command, for example
+  due to a stuck filesystem IO appearing in ``$HOME/.profile``.
 
 
 New Features & Notes

docs/index.rst

@@ -242,10 +242,25 @@ Detached Subtrees
 
 .. image:: images/detached-subtree.png
 
-It is possible to dynamically construct and decouple individual contexts from
-the lifecycle of the running program without terminating them, while enabling
-communication with any descendents in the subtree to be maintained. This is
-intended to support implementing background tasks.
+Contexts may detach from and outlive the running program, while maintaining
+communication with descendents in their subtree. This enables persistent
+background tasks that reuse Mitogen features.
+
+.. code::
+
+    @mitogen.core.takes_econtext
+    def become_monitoring_master(children, econtext):
+        kill_old_process('/var/run/mydaemon.pid')
+        write_pid_file('/var/run/mydaemon.pid')
+        econtext.detach()
+
+        while True:
+            for child in children:
+                if child.call(get_cpu_load) > 0.9:
+                    alert_operator('Child is too busy! ' + str(child))
+            time.sleep(1)
+
+    dc1.call_async(become_monitoring_master, children)
 
 
 Blocking Code Friendly