Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify poll value behaviour in playbook async doc #54929

Open
wants to merge 5 commits into
base: devel
from

Conversation

Projects
None yet
5 participants
@tacatac
Copy link
Contributor

commented Apr 5, 2019

SUMMARY

The documentation for async and poll is ambiguous and does not make
the playbook behaviour obvious. The word "asynchronous" is applied to
the host connection and to task ordering.

For example lines 12 and 39 both explain how to run a task
"asynchronously", but don't describe the difference very well.

This commit tries to clarify the difference in behaviour that hinges on
whether poll = 0 or not.

ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

playbooks_async.rst

Clarify poll value behaviour in playbook async doc
The documentation for `async` and `poll` is ambiguous and does not make
the playbook behaviour obvious. The word "asynchronous" is applied to
the host connection and to task ordering.

For example lines 12 and 39 both explain how to run a task
"asynchronously", but don't describe the difference very well.

This commit tries to clarify the difference in behaviour that hinges on
whether `poll` = 0 or not.
@ansibot

This comment has been minimized.

Copy link
Contributor

commented Apr 5, 2019

Show resolved Hide resolved docs/docsite/rst/user_guide/playbooks_async.rst Outdated
Show resolved Hide resolved docs/docsite/rst/user_guide/playbooks_async.rst Outdated

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 `async_status` module to observe it.

This comment has been minimized.

Copy link
@gundalow

gundalow Apr 17, 2019

Contributor

Link to module doc for async_status

This comment has been minimized.

Copy link
@tacatac

tacatac Apr 18, 2019

Author Contributor

Thank you, I had thought of it but wasn't sure how to format the reference. Hope this is the right way.

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`::

This comment has been minimized.

Copy link
@gundalow

gundalow Apr 17, 2019

Contributor

DEFAULT_POLL_INTERVAL ony affects 'adhoc'i.e ansible -a 'find /' --async
while 10s is default for async in plays'

This comment has been minimized.

Copy link
@tacatac

tacatac Apr 18, 2019

Author Contributor

I've updated the sentence to say 15.

@bcoca

bcoca approved these changes Apr 17, 2019

Copy link
Member

left a comment

Just reviewing 'the technical side', lgtm

@ansibot ansibot added the stale_ci label Apr 17, 2019

@acozine

This comment has been minimized.

Copy link
Contributor

commented Apr 17, 2019

@tacatac thank you for clarifying this behavior in the Ansible docs - we'll take another look once you've had a chance to respond to the suggestions above.

@bcoca

This comment has been minimized.

Copy link
Member

commented Apr 17, 2019

I actually went opposite route #55470

gundalow and others added some commits Apr 18, 2019

Update docs/docsite/rst/user_guide/playbooks_async.rst
Co-Authored-By: tacatac <taca@kadisius.eu>
Update docs/docsite/rst/user_guide/playbooks_async.rst
Co-Authored-By: tacatac <taca@kadisius.eu>

@ansibot ansibot removed the stale_ci label Apr 18, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.