From d20d66dc2f96ceba9f4b6a2c715d99efdba1afac Mon Sep 17 00:00:00 2001 From: Martin Krizek Date: Mon, 3 Dec 2018 22:21:59 +0100 Subject: [PATCH] docs: try to clarify handlers a bit more (#49322) * docs: try to clarify handlers a bit more * docs: refines description of duplicate handler names --- docs/docsite/rst/user_guide/playbooks_intro.rst | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/docsite/rst/user_guide/playbooks_intro.rst b/docs/docsite/rst/user_guide/playbooks_intro.rst index 2ae924089c..09d9a63d22 100644 --- a/docs/docsite/rst/user_guide/playbooks_intro.rst +++ b/docs/docsite/rst/user_guide/playbooks_intro.rst @@ -166,7 +166,7 @@ You can also use keyword ``become`` on a particular task instead of the whole pl - hosts: webservers remote_user: yourname tasks: - - service: + - service: name: nginx state: started become: yes @@ -266,7 +266,7 @@ which is totally ok if the command is something like be used to make these modules also idempotent. Every task should have a ``name``, which is included in the output from -running the playbook. This is human readable output, and so it is +running the playbook. This is human readable output, and so it is useful to provide good descriptions of each task step. If the name is not provided though, the string fed to 'action' will be used for output. @@ -379,7 +379,7 @@ The things listed in the ``notify`` section of a task are called handlers. Handlers are lists of tasks, not really any different from regular -tasks, that are referenced by a globally unique name, and are notified +tasks, that are referenced by a globally unique name, and are notified by notifiers. If nothing notifies a handler, it will not run. Regardless of how many tasks notify a handler, it will run only once, after all of the tasks complete in a particular play. @@ -422,14 +422,14 @@ a shared source like Galaxy). .. note:: * Notify handlers are always run in the same order they are defined, `not` in the order listed in the notify-statement. This is also the case for handlers using `listen`. * Handler names and `listen` topics live in a global namespace. - * If two handler tasks have the same name, only one will run. - `* `_ + * Use unique handler names. If you trigger more than one handler with the same name, the first one(s) get overwritten. Only the last one defined will run. * You cannot notify a handler that is defined inside of an include. As of Ansible 2.1, this does work, however the include must be `static`. Roles are described later on, but it's worthwhile to point out that: -* handlers notified within ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatically flushed in the end of section where they were notified; -* handlers notified within ``roles`` section are automatically flushed in the end of ``tasks`` section, but before any ``tasks`` handlers. +* handlers notified within ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatically flushed in the end of section where they were notified, +* handlers notified within ``roles`` section are automatically flushed in the end of ``tasks`` section, but before any ``tasks`` handlers, +* handlers are play scoped and as such can be used outside of the role they are defined in. If you ever want to flush all the handler commands immediately you can do this:: @@ -506,6 +506,3 @@ can do this:: Complete end-to-end playbook examples `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups - - -