[PR #597/74b2c95d backport][stable-2.15] Add details of interactions between notifications and loops

docs/docsite/rst/playbook_guide/playbooks_handlers.rst

@@ -79,6 +79,40 @@ Tasks can instruct one or more handlers to execute using the ``notify`` keyword.
 In the above example, the handlers are executed on task change in the following order: ``Restart memcached``, ``Restart apache``. Handlers are executed in the order they are defined in the ``handlers`` section, not in the order listed in the ``notify`` statement. Notifying the same handler multiple times will result in executing the handler only once regardless of how many tasks notify it. For example, if multiple tasks update a configuration file and notify a handler to restart Apache, Ansible only bounces Apache once to avoid unnecessary restarts.
 
 
+Notifying and loops
+-------------------
+
+Tasks can use loops to notify handlers. This is particularly useful when combined with variables to trigger multiple dynamic notifications.
+
+Note that the handlers are triggered if the task as a whole is changed. When a loop is used the changed state is set if any of the loop items are changed.  That is, any change triggers all of the handlers.
+
+.. code-block:: yaml
+
+    tasks:
+    - name: Template services
+      ansible.builtin.template:
+        src: "{{ item }}.j2"
+        dest: /etc/systemd/system/{{ item }}.service
+      # Note: if *any* loop iteration triggers a change, *all* handlers are run
+      notify: Restart {{ item }}
+      loop:
+        - memcached
+        - apache
+
+    handlers:
+      - name: Restart memcached
+        ansible.builtin.service:
+          name: memcached
+          state: restarted
+
+      - name: Restart apache
+        ansible.builtin.service:
+          name: apache
+          state: restarted
+
+In the above example both memcached and apache will be restarted if either template file is changed, neither will be restarted if no file changes.
+
+
 Naming handlers
 ---------------