docs: try to clarify handlers a bit more (#49322)

* docs: try to clarify handlers a bit more
* docs: refines description of duplicate handler names
This commit is contained in:
Martin Krizek 2018-12-03 22:21:59 +01:00 committed by Alicia Cozine
parent e2f85b3f6c
commit d20d66dc2f

View file

@ -166,7 +166,7 @@ You can also use keyword ``become`` on a particular task instead of the whole pl
- hosts: webservers - hosts: webservers
remote_user: yourname remote_user: yourname
tasks: tasks:
- service: - service:
name: nginx name: nginx
state: started state: started
become: yes become: yes
@ -266,7 +266,7 @@ which is totally ok if the command is something like
be used to make these modules also idempotent. be used to make these modules also idempotent.
Every task should have a ``name``, which is included in the output from 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 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 is not provided though, the string fed to 'action' will be used for
output. output.
@ -379,7 +379,7 @@ The things listed in the ``notify`` section of a task are called
handlers. handlers.
Handlers are lists of tasks, not really any different from regular 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 by notifiers. If nothing notifies a handler, it will not
run. Regardless of how many tasks notify a handler, it will run only run. Regardless of how many tasks notify a handler, it will run only
once, after all of the tasks complete in a particular play. once, after all of the tasks complete in a particular play.
@ -422,14 +422,14 @@ a shared source like Galaxy).
.. note:: .. 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`. * 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. * 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.
`* <https://github.com/ansible/ansible/issues/4943>`_
* 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`. * 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: 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 ``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 ``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:: 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 Complete end-to-end playbook examples
`Mailing List <https://groups.google.com/group/ansible-project>`_ `Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups Questions? Help? Ideas? Stop by the list on Google Groups