From a0264813969975549942f3c34b4b355a05fe5dcc Mon Sep 17 00:00:00 2001 From: James Cammarata Date: Mon, 20 Jun 2016 09:29:52 -0500 Subject: Adding docs for handler listen feature and CHANGELOG entry for same --- CHANGELOG.md | 1 + docsite/rst/playbooks_intro.rst | 26 +++++++++++++++++++++----- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a5c627cfd..11dc06c1c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ Ansible Changes By Release ###Major Changes: +* Added the `listen` feature for modules. This feature allows tasks to more easily notify multiple handlers, as well as making it easier for handlers from decoupled roles to be notified. * Added support for binary modules * The service module has been changed to use system specific modules if they exist and fallback to the old service module if they cannot be found or detected. diff --git a/docsite/rst/playbooks_intro.rst b/docsite/rst/playbooks_intro.rst index 1f24250d07..87ebf9bb2b 100644 --- a/docsite/rst/playbooks_intro.rst +++ b/docsite/rst/playbooks_intro.rst @@ -378,15 +378,31 @@ Here's an example handlers section:: - name: restart apache service: name=apache state=restarted -Handlers are best used to restart services and trigger reboots. You probably -won't need them for much else. +As of Ansible 2.1, handlers can also "listen" to generic topics, and tasks can notify those topics as follows:: + + handlers: + - name: restart memcached + service: name=memcached state=restarted + listen: "restart web services" + - name: restart apache + service: name=apache state=restarted + listen: "restart web services" + + tasks: + - name: restart everything + command: echo "this task will restart the web services" + notify: "restart web services" + +This use makes it much easier to trigger multiple handlers. It also decouples handlers from their names, +making it easier to share handlers among playbooks and roles (especially when using 3rd party roles from +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. - * Handler names live in a global namespace. + * 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. `* `_ - * You cannot notify a handler that is defined inside of an include + * 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: -- cgit v1.2.1