From cf3c77661bd6f4d9d8dbd0ada75c3146e0aa5ea5 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Sat, 20 Apr 2013 18:10:01 -0400 Subject: [PATCH] Document the new handler flushing system. --- docsite/latest/rst/playbooks.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docsite/latest/rst/playbooks.rst b/docsite/latest/rst/playbooks.rst index c57e6db1c1f..3eccc2e4108 100644 --- a/docsite/latest/rst/playbooks.rst +++ b/docsite/latest/rst/playbooks.rst @@ -269,9 +269,12 @@ As we've mentioned, modules are written to be 'idempotent' and can relay when they have made a change on the remote system. Playbooks recognize this and have a basic event system that can be used to respond to change. -These 'notify' actions are triggered at the end of each 'play' in a playbook, and -trigger only once each. For instance, multiple resources may indicate -that apache needs to be restarted, but apache will only be bounced once. +These 'notify' actions are triggered at the end of each block of tasks in a playbook, and will only be +triggered once even if notified by multiple different tasks. + +For instance, multiple resources may indicate +that apache needs to be restarted because they have changed a config file, +but apache will only be bounced once to avoid unneccessary restarts. Here's an example of restarting two services when the contents of a file change, but only if the file changes:: @@ -305,6 +308,19 @@ won't need them for much else. .. note:: Notify handlers are always run in the order written. +Roles are described later on. It's worth while to point out that handlers are +automatically processed between 'pre_tasks', 'roles', 'tasks', and 'post_tasks' +sections. If you ever want to flush all the handler commands immediately though, +in 1.2 and later, you can:: + + tasks: + - shell: some tasks go here + - meta: flush_handlers + - shell: some other tasks + +In the above example any queued up handlers would be processed early when the 'meta' +statement was reached. This is a bit of a niche case but can come in handy from +time to time. Task Include Files And Encouraging Reuse ````````````````````````````````````````