tmc::spawn_func_many()

spawn_func_many() wraps multiple functors into a single awaitable, that completes when all of the wrapped functors complete.

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 Awaitable Customizations: run_on(), resume_on(), with_priority(), co_await, fork(), 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().

API Reference

template<size_t Count = 0, typename FuncIter, typename Functor = std::iter_value_t<FuncIter>, typename Result = std::invoke_result_t<Functor>>
aw_spawn_many<Result, Count, FuncIter, size_t, true> tmc::spawn_func_many(FuncIter &&FunctorIterator)

The single-argument form of spawn_func_many() has two overloads. If Count is non-zero (this overload), a fixed-size std::array<T, Count> will be allocated to return results in. The other overload (Count == 0) supports range-types.

Functor must be a copyable type that implements Result operator(). FuncIter must be an iterator type that implements operator*() and FuncIter& operator++().

Submits items in range [Begin, Begin + Count) to the executor.

template<size_t Count = 0, typename FuncRange, typename FuncIter = tmc::detail::range_iter<FuncRange>::type, typename Functor = std::iter_value_t<FuncIter>, typename Result = std::invoke_result_t<Functor>>
aw_spawn_many<Result, 0, FuncIter, FuncIter, true> tmc::spawn_func_many(FuncRange &&Range)

The single-argument form of spawn_func_many() has two overloads. If Count is zero (this overload), the single argument is treated as a range. The other overload (Count != 0) supports fixed-size awaitable groups.

FuncRange must implement begin() and end() functions which return an iterator type. The iterator type must implement operator*(), AwaitableIter& operator++(), and operator==(Awaitable const& rhs).

Functor must be a copyable type that implements Result operator().

Submits items in range [Range.begin(), Range.end()) to the executor.

template<typename FuncIter, typename Functor = std::iter_value_t<FuncIter>, typename Result = std::invoke_result_t<Functor>>
aw_spawn_many<Result, 0, FuncIter, size_t, true> tmc::spawn_func_many(FuncIter &&FunctorIterator, size_t FunctorCount)

For use when the number of items to spawn is a runtime parameter. Functor must be a copyable type that implements Result operator(). FuncIter must be an iterator type that implements operator*() and FuncIter& operator++(). FunctorCount must be non-zero.

Submits items in range [Begin, Begin + FunctorCount) to the executor.

template<size_t MaxCount = 0, typename FuncIter, typename Functor = std::iter_value_t<FuncIter>, typename Result = std::invoke_result_t<Functor>>
aw_spawn_many<Result, MaxCount, FuncIter, FuncIter, true> tmc::spawn_func_many(FuncIter &&Begin, FuncIter &&End)

For use when the number of items to spawn may be variable. Functor must be a copyable type that implements Result operator(). FuncIter must be an iterator type that implements operator*() and FuncIter& operator++().

• If MaxCount is non-zero, the return type will be a std::array<Result, MaxCount>. Up to MaxCount tasks will be consumed from the iterator. If the iterator produces less than MaxCount tasks, elements in the return array beyond the number of results actually produced by the iterator will be default-initialized. Submits items in range [Begin, min(Begin + MaxCount, End)) to the executor.

• If MaxCount is zero/not provided, the return type will be a right-sized std::vector<Result> with size and capacity equal to the number of tasks produced by the iterator. Submits items in range [Begin, End) to the executor.

template<typename FuncIter, typename Functor = std::iter_value_t<FuncIter>, typename Result = std::invoke_result_t<Functor>>
aw_spawn_many<Result, 0, FuncIter, FuncIter, true> tmc::spawn_func_many(FuncIter &&Begin, FuncIter &&End, size_t MaxCount)

For use when the number of items to spawn may be variable. Functor must be a copyable type that implements Result operator(). FuncIter must be an iterator type that implements operator*() and FuncIter& operator++().

• Up to MaxCount tasks will be consumed from the iterator.

• The iterator may produce less than MaxCount tasks.

• The return type will be a right-sized std::vector<Result> with size and capacity equal to the number of tasks consumed from the iterator.

Submits items in range [Begin, min(Begin + MaxCount, End)) to the executor.