Skip to content

Commit

Permalink
Clarify poll value behaviour in playbook async doc (ansible#54929)
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
tacatac authored and acozine committed Apr 25, 2019
1 parent 9c038b2 commit dbc64ae
Showing 1 changed file with 26 additions and 3 deletions.
29 changes: 26 additions & 3 deletions docs/docsite/rst/user_guide/playbooks_async.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`::

---

Expand All @@ -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::

---

Expand Down

0 comments on commit dbc64ae

Please sign in to comment.