diff --git a/docs/ansible.rst b/docs/ansible.rst index 9e03b190..e08fca9b 100644 --- a/docs/ansible.rst +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index a693fc15..62158736 100644 --- a/docs/index.rst +++ b/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