diff --git a/docs/docsite/rst/user_guide/playbooks_async.rst b/docs/docsite/rst/user_guide/playbooks_async.rst index b17cfb5d723..b385749e19e 100644 --- a/docs/docsite/rst/user_guide/playbooks_async.rst +++ b/docs/docsite/rst/user_guide/playbooks_async.rst @@ -9,9 +9,19 @@ be running operations that take longer than the SSH timeout. To avoid blocking or timeout issues, you can use asynchronous mode to run all of your tasks at once and then poll until they are done. +The behaviour of asynchronous mode depends on the value of `poll`. + + +Avoid connection timeouts: poll > 0 +----------------------------------- + +When ``poll`` is a positive value, the playbook will *still* block on the task until it either completes, fails or times out. + +In this case, however, `async` explicitly sets the timeout you wish to apply to this task rather than being limited by the connection method timeout. + To launch a task asynchronously, specify its maximum runtime and how frequently you would like to poll for status. The default -poll value is 10 seconds if you do not specify a value for `poll`:: +poll value is 15 seconds if you do not specify a value for `poll`:: --- @@ -35,8 +45,21 @@ poll value is 10 seconds if you do not specify a value for `poll`:: task when run in check mode. See :doc:`playbooks_checkmode` on how to skip a task in check mode. -Alternatively, if you do not need to wait on the task to complete, you may -run the task asynchronously by specifying a poll value of 0:: + +Concurrent tasks: poll = 0 +-------------------------- + +When ``poll`` is 0, Ansible will start the task and immediately move on to the next one without waiting for a result. + +From the point of view of sequencing this is asynchronous programming: tasks may now run concurrently. + +The playbook run will end without checking back on async tasks. + +The async tasks will run until they either complete, fail or timeout according to their `async` value. + +If you need a synchronization point with a task, register it to obtain its job ID and use the :ref:`async_status ` module to observe it. + +You may run a task asynchronously by specifying a poll value of 0:: ---