Add experimental::parallel_group to the overview.

doc/overview.qbk

@@ -39,6 +39,7 @@
   * [link boost_asio.overview.composition.cpp20_coroutines C++20 Coroutines Support]
   * [link boost_asio.overview.composition.coro Resumable C++20 Coroutines (experimental)]
   * [link boost_asio.overview.composition.deferred Deferred Operations (experimental)]
+  * [link boost_asio.overview.composition.parallel_group Co-ordinating Parallel Operations (experimental)]
 * [link boost_asio.overview.networking Networking]
   * [link boost_asio.overview.networking.protocols TCP, UDP and ICMP]
   * [link boost_asio.overview.networking.other_protocols Support for Other Protocols]
@@ -106,13 +107,15 @@
 * [link boost_asio.overview.composition.cpp20_coroutines C++20 Coroutines Support]
 * [link boost_asio.overview.composition.coro Resumable C++20 Coroutines (experimental)]
 * [link boost_asio.overview.composition.deferred Deferred Operations (experimental)]
+* [link boost_asio.overview.composition.parallel_group Co-ordinating Parallel Operations (experimental)]
 
 [include overview/coroutine.qbk]
 [include overview/spawn.qbk]
 [include overview/futures.qbk]
 [include overview/cpp20_coroutines.qbk]
 [include overview/coro.qbk]
 [include overview/deferred.qbk]
+[include overview/parallel_group.qbk]
 
 [endsect]
 

doc/overview/parallel_group.qbk

@@ -0,0 +1,65 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:parallel_group Co-ordinating Parallel Operations]
+
+[note This is an experimental feature.]
+
+The [link boost_asio.reference.experimental__make_parallel_group
+`experimental::make_parallel_group`] function may be used to launch work that
+is performed in parallel, and wait for one or all of the operations to
+complete. A `parallel_group` implements automatic cancellation of incomplete
+operations. For example:
+
+  experimental::make_parallel_group(
+      [&](auto token)
+      {
+        return stream.async_read_some(boost::asio::buffer(data), token);
+      },
+      [&](auto token)
+      {
+        return timer.async_wait(token);
+      }
+    ).async_wait(
+      experimental::wait_for_one(),
+      [](
+          std::array<std::size_t, 2> completion_order,
+          boost::system::error_code ec1, std::size_t n1,
+          boost::system::error_code ec2
+      )
+      {
+        // ...
+      }
+    );
+
+The conditions for completion of the group may be specified using one of the
+four provided function objects [link boost_asio.reference.experimental__wait_for_all
+`wait_for_all`], [link boost_asio.reference.experimental__wait_for_one
+`wait_for_one`], [link boost_asio.reference.experimental__wait_for_one_success
+`wait_for_one_success`], [link boost_asio.reference.experimental__wait_for_one_error
+`wait_for_one_error`], or with a custom function.
+
+The `parallel_group` facility can also be combined with [link
+boost_asio.reference.experimental__deferred `experimental::deferred`] as follows:
+
+  experimental::make_parallel_group(
+      stream.async_read_some(boost::asio::buffer(data), experimental::deferred),
+      timer.async_wait(experimental::deferred)
+    ).async_wait(
+      // ...
+    );
+
+Note: for maximum flexibility, `parallel_group` does not propagate the
+executor automatically to the operations within the group.
+
+[heading See Also]
+
+[link boost_asio.reference.experimental__make_parallel_group experimental::make_parallel_group],
+[link boost_asio.reference.experimental__parallel_group experimental::parallel_group],
+[link boost_asio.examples.cpp14_examples.parallel_groups Parallel Groups examples (C++14)].
+
+[endsect]