.. _spawn_func_many:

tmc::spawn_func_many()
-----------------------------------------------------------------------------------
``spawn_func_many()`` wraps multiple functors into a single awaitable, that completes when all of the wrapped functors complete.
The wrapped functors will be executed concurrently. Unlike ``spawn_func()``, it requires that the provided functors take no arguments.

All overloads expect a forward iterator of functors, and an end iterator (sentinel), or element count.
Some overloads support a ``Count`` or ``MaxCount`` template parameter.
If you provide this parameter, any results will be returned in a ``std::array<Result, Count>``.
Otherwise, they will be returned in a ``std::vector<Result>``.

An overload that directly accepts a range-type (which exposes .begin() and .end() member functions) is also provided.

If the Result type is not default-constructible, each value will be wrapped into a ``std::optional<Result>``.
Thus, the entire result type will be ``std::array<std::optional<Result>, Count>`` or ``std::vector<std::optional<Result>>``.

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:

``.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 iterator, and the values can be
accessed using ``operator[]``.
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_func_many(FuncIter&& FunctorIterator)

.. doxygenfunction:: tmc::spawn_func_many(FuncRange&& Range)

.. doxygenfunction:: tmc::spawn_func_many(FuncIter&& FunctorIterator, size_t FunctorCount)

.. doxygenfunction:: tmc::spawn_func_many(FuncIter&& Begin, FuncIter&& End)

.. doxygenfunction:: tmc::spawn_func_many(FuncIter&& Begin, FuncIter&& End, size_t MaxCount)