.. _spawn_tuple:

tmc::spawn_tuple()
-----------------------------------------------------------------------------------
``spawn_tuple()`` wraps multiple awaitables into a single awaitable, that completes when all of the wrapped awaitables complete.
The wrapped awaitables will be executed concurrently.

Each element of the awaitable parameter pack (or tuple parameter) will return its value to the the corresponding element in the result tuple.
If the result type of a particular awaitable parameter would be ``void``, its element in the result tuple will be a ``std::monostate`` instead.
If the result type of a particular awaitable parameter is not default-constructible, its element in the result tuple will be a ``std::optional<Result>``.

``spawn_tuple`` supports HALO if it is awaited directly as a prvalue. See :ref:`HALO<halo>` for details.

Awaitable Customizations
------------------------------------------------------------------------------------------------
The resulting awaitable supports these :ref:`Awaitable Customizations <awaitable_customizations>`:
:literal_ref:`run_on()<run_on>`,
:literal_ref:`resume_on()<resume_on>`,
:literal_ref:`with_priority()<with_priority>`,
:literal_ref:`co_await<co_await>`,
:literal_ref:`fork()<fork>`,
:literal_ref:`detach()<detach>`.

Additionally, it supports a special awaitable customization (execution mode):

``.result_each()``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Rather than waiting for all results at once, each result will be made
available immediately as it becomes ready. Each time this is co_awaited, it will return
the index of a single ready result. The result indexes correspond to the
indexes of the originally submitted tasks in the input argument list or tuple, and the values can be
accessed using ``.get<index>()``.
Results may become ready in any order, but
when awaited repeatedly, each index from `[0..task_count)` will be
returned exactly once. You must await this repeatedly until all tasks
are complete, at which point the index returned will be equal to the
value of `end()`.

A maximum of 63 (or 31, on 32-bit) tasks can be awaited via ``.result_each()``.

API Reference
------------------------------------------------------------------------------------------------

.. doxygenfunction:: tmc::spawn_tuple(Awaitable&&... Tasks)

.. doxygenfunction:: tmc::spawn_tuple(std::tuple<Awaitable...>&& Tasks)