Docs for multiple asynchronous tasks (#24457)

* Add docs on the behavior of with_items flattening and nested lists

* Add docs on limiting the amount of concurrent async tasks

docs/docsite/rst/playbooks_async.rst

@@ -79,6 +79,47 @@ following::
    "check on it later" task to fail because the temporary status file that
    the ``async_status:`` is looking for will not have been written or no longer exist 
 
+If you would like to run multiple asynchronous tasks while limiting the amount
+of tasks running concurrently, you can do it this way::
+
+    #####################
+    # main.yml
+    #####################
+    - name: Run items asynchronously in batch of two items
+      vars:
+        sleep_durations:
+          - 1
+          - 2
+          - 3
+          - 4
+          - 5
+        durations: "{{ item }}"
+      include: execute_batch.yml
+      with_items:
+        - "{{ sleep_durations | batch(2) | list }}"
+
+    #####################
+    # execute_batch.yml
+    #####################
+    - name: Async sleeping for batched_items
+      command: sleep {{ async_item }}
+      async: 45
+      poll: 0
+      with_items: "{{ durations }}"
+      loop_control:
+        loop_var: "async_item"
+      register: async_results
+
+    - name: Check sync status
+      async_status:
+        jid: "{{ async_result_item.ansible_job_id }}"
+      with_items: "{{ async_results.results }}"
+      loop_control:
+        loop_var: "async_result_item"
+      register: async_poll_results
+      until: async_poll_results.finished
+      retries: 30
+
 .. seealso::
 
    :doc:`playbooks`

docs/docsite/rst/playbooks_loops.rst

@@ -59,6 +59,31 @@ Also be aware that when combining `when` with `with_items` (or any other loop st
 
 Loops are actually a combination of things `with_` + `lookup()`, so any lookup plugin can be used as a source for a loop, 'items' is lookup.
 
+Please note that ``with_items`` flattens the first depth of the list it is
+provided and can yield unexpected results if you pass a list which is composed
+of lists. You can work around this by wrapping your nested list inside a list::
+
+    # This will run debug three times since the list is flattened
+    - debug:
+        msg: "{{ item }}"
+      vars:
+        nested_list:
+          - - one
+            - two
+            - three
+      with_items: "{{ nested_list }}"
+
+    # This will run debug once with the three items
+    - debug:
+        msg: "{{ item }}"
+      vars:
+        nested_list:
+          - - one
+            - two
+            - three
+      with_items:
+        - "{{ nested_list }}"
+
 .. _nested_loops:
 
 Nested Loops