[/
 / Copyright (c) 2003-2023 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.deferred `deferred`] as follows:

  experimental::make_parallel_group(
      stream.async_read_some(boost::asio::buffer(data), 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.cpp11_examples.parallel_groups Parallel Groups examples (C++11)],
[link boost_asio.examples.cpp14_examples.parallel_groups Parallel Groups examples (C++14)].

[endsect]