Clarify the documentation for `async` and `poll`; describe the behavior when `poll` = 0 and when it does not.
* Update docs/docsite/rst/user_guide/playbooks_async.rst
* Update the default poll value in async doc
Co-Authored-By: tacatac <taca@kadisius.eu>
@ -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.
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
To launch a task asynchronously, specify its maximum runtime
and how frequently you would like to poll for status. The default
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
task when run in check mode. See :doc:`playbooks_checkmode` on how to
skip a task in check mode.
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 <async_status_module>` module to observe it.
You may run a task asynchronously by specifying a poll value of 0::