cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Clarify poll value behaviour in playbook async doc (#54929)

Browse source 
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>
This commit is contained in:
tacatac 2019-04-25 22:23:13 +00:00 committed by Alicia Cozine
parent 9c038b210b
commit dbc64ae64c
1 changed files with 26 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
docs/docsite/rst/user_guide/playbooks_async.rst
View file

@ -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 <async_status_module>` module to observe it.
You may run a task asynchronously by specifying a poll value of 0::
---