async_combinators

The contents of this module can be included with the header hpx/modules/async_combinators.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/async_combinators.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx
namespace lcos

Functions

template<typename Future, typename F>
std::enable_if<!std::is_void<typename traits::future_traits<Future>::type>::value, std::size_t>::type wait(Future &&f1, F &&f)

The one argument version is special in the sense that it returns the expected value directly (without wrapping it into a tuple).

template<typename Future, typename F>
std::enable_if<std::is_void<typename traits::future_traits<Future>::type>::value, std::size_t>::type wait(Future &&f1, F &&f)
template<typename Future, typename F>
std::size_t wait(std::vector<Future> &lazy_values, F &&f, std::int32_t = 10)
template<typename Future, typename F>
std::size_t wait(std::vector<Future> &&lazy_values, F &&f, std::int32_t suspend_for = 10)
template<typename Future, typename F>
std::size_t wait(std::vector<Future> const &lazy_values, F &&f, std::int32_t = 10)
namespace hpx

Functions

template<typename ...Ts>
tuple<future<Ts>...> split_future(future<tuple<Ts...>> &&f)

The function split_future is an operator allowing to split a given future of a sequence of values (any tuple, std::pair, or std::array) into an equivalent container of futures where each future represents one of the values from the original future. In some sense this function provides the inverse operation of when_all.

Return

Returns an equivalent container (same container type as passed as the argument) of futures, where each future refers to the corresponding value in the input parameter. All of the returned futures become ready once the input future has become ready. If the input future is exceptional, all output futures will be exceptional as well.

Note

The following cases are special: 

tuple<future<void> > split_future(future<tuple<> > && f);
array<future<void>, 1> split_future(future<array<T, 0> > && f);
here the returned futures are directly representing the futures which were passed to the function.

Parameters

  • f: [in] A future holding an arbitrary sequence of values stored in a tuple-like container. This facility supports hpx::tuple<>, std::pair<T1, T2>, and std::array<T, N>

template<typename T>
std::vector<future<T>> split_future(future<std::vector<T>> &&f, std::size_t size)

The function split_future is an operator allowing to split a given future of a sequence of values (any std::vector) into a std::vector of futures where each future represents one of the values from the original std::vector. In some sense this function provides the inverse operation of when_all.

Return

Returns a std::vector of futures, where each future refers to the corresponding value in the input parameter. All of the returned futures become ready once the input future has become ready. If the input future is exceptional, all output futures will be exceptional as well.

Parameters

  • f: [in] A future holding an arbitrary sequence of values stored in a std::vector.

  • size: [in] The number of elements the vector will hold once the input future has become ready

namespace hpx

Functions

template<typename InputIter>
void wait_all(InputIter first, InputIter last)

The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.

Note

The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns. Exceptional futures will not cause wait_all to throw an exception.

Parameters

  • first: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_all should wait.

  • last: The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_all should wait.

template<typename R>
void wait_all(std::vector<future<R>> &&futures)

The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.

Note

The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns. Exceptional futures will not cause wait_all to throw an exception.

Parameters

  • futures: A vector or array holding an arbitrary amount of future or shared_future objects for which wait_all should wait.

template<typename R, std::size_t N>
void wait_all(std::array<future<R>, N> &&futures)

The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.

Note

The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns. Exceptional futures will not cause wait_all to throw an exception.

Parameters

  • futures: A vector or array holding an arbitrary amount of future or shared_future objects for which wait_all should wait.

template<typename ...T>
void wait_all(T&&... futures)

The function wait_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.

Note

The function wait_all returns after all futures have become ready. All input futures are still valid after wait_all returns. Exceptional futures will not cause wait_all to throw an exception.

Parameters

  • futures: An arbitrary number of future or shared_future objects, possibly holding different types for which wait_all should wait.

template<typename InputIter>
InputIter wait_all_n(InputIter begin, std::size_t count)

The function wait_all_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing.

Return

The function wait_all_n will return an iterator referring to the first element in the input sequence after the last processed element.

Note

The function wait_all_n returns after all futures have become ready. All input futures are still valid after wait_all_n returns. Exceptional futures will not cause wait_all to throw an exception.

Parameters

  • begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_all_n should wait.

  • count: The number of elements in the sequence starting at first.

namespace hpx

Functions

template<typename InputIter>
void wait_any(InputIter first, InputIter last, error_code &ec = throws)

The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.

Note

The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_any should wait.

  • last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_any should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename R>
void wait_any(std::vector<future<R>> &futures, error_code &ec = throws)

The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.

Note

The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • futures: [in] A vector holding an arbitrary amount of future or shared_future objects for which wait_any should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename R, std:;size_t N>void hpx::wait_any(std::array< future< R >, N > & futures, error_code & ec = throws)

The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.

Note

The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • futures: [in] Amn array holding an arbitrary amount of future or shared_future objects for which wait_any should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename ...T>
void wait_any(error_code &ec, T&&... futures)

The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.

Note

The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which wait_any should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename ...T>
void wait_any(T&&... futures)

The function wait_any is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.

Note

The function wait_any returns after at least one future has become ready. All input futures are still valid after wait_any returns.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which wait_any should wait.

template<typename InputIter>
InputIter wait_any_n(InputIter first, std::size_t count, error_code &ec = throws)

The function wait_any_n is a non-deterministic choice operator. It OR-composes all future objects given and returns after one future of that list finishes execution.

Note

The function wait_any_n returns after at least one future has become ready. All input futures are still valid after wait_any_n returns.

Return

The function wait_all_n will return an iterator referring to the first element in the input sequence after the last processed element.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_any_n should wait.

  • count: [in] The number of elements in the sequence starting at first.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

namespace hpx

Functions

template<typename F, typename Future>
void wait_each(F &&f, std::vector<Future> &&futures)

The function wait_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready. wait_each returns after all futures have been become ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • futures: A vector holding an arbitrary amount of future or shared_future objects for which wait_each should wait.

template<typename F, typename Iterator>
void wait_each(F &&f, Iterator begin, Iterator end)

The function wait_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready. wait_each returns after all futures have been become ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each should wait.

  • end: The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_each should wait.

template<typename F, typename ...T>
void wait_each(F &&f, T&&... futures)

The function wait_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready. wait_each returns after all futures have been become ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • futures: An arbitrary number of future or shared_future objects, possibly holding different types for which wait_each should wait.

template<typename F, typename Iterator>
void wait_each_n(F &&f, Iterator begin, std::size_t count)

The function wait_each is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns after they finished executing. Additionally, the supplied function is called for each of the passed futures as soon as the future has become ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each_n should wait.

  • count: The number of elements in the sequence starting at first.

namespace hpx

Functions

template<typename InputIter>
future<vector<future<typename std::iterator_traits<InputIter>::value_type>>> wait_some(std::size_t n, Iterator first, Iterator last, error_code &ec = throws)

The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The future returned by the function wait_some becomes ready when at least n argument futures have become ready.

Return

Returns a future holding the same list of futures as has been passed to wait_some.

  • future<vector<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type.

Note

Calling this version of wait_some where first == last, returns a future with an empty vector that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.

  • last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_all should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename R>
void wait_some(std::size_t n, std::vector<future<R>> &&futures, error_code &ec = throws)

The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.

Note

Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • futures: [in] A vector holding an arbitrary amount of future or shared_future objects for which wait_some should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename R, std::size_t N>
void wait_some(std::size_t n, std::array<future<R>, N> &&futures, error_code &ec = throws)

The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.

Note

Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • futures: [in] An array holding an arbitrary amount of future or shared_future objects for which wait_some should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename ...T>
void wait_some(std::size_t n, T&&... futures, error_code &ec = throws)

The function wait_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.

Note

Calling this version of wait_some where first == last, returns a future with an empty vector that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which wait_some should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename InputIter>
InputIter wait_some_n(std::size_t n, Iterator first, std::size_t count, error_code &ec = throws)

The function wait_some_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The function wait_all returns after n futures have become ready. All input futures are still valid after wait_all returns.

Return

This function returns an Iterator referring to the first element after the last processed input element.

Note

Calling this version of wait_some_n where count == 0, returns a future with the same elements as the arguments that is immediately ready. Possibly none of the futures in that vector are ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by wait_some_n will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.

  • count: [in] The number of elements in the sequence starting at first.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

namespace hpx

Functions

template<typename InputIter, typename Container = vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<Container> when_all(InputIter first, InputIter last)

The function when_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.

Return

Returns a future holding the same list of futures as has been passed to when_all.

  • future<Container<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.

Note

Calling this version of when_all where first == last, returns a future with an empty container that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_all will not throw an exception, but the futures held in the output collection may.

Parameters

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.

  • last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_all should wait.

template<typename Range>
future<Range> when_all(Range &&values)

The function when_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.

Return

Returns a future holding the same list of futures as has been passed to when_all.

  • future<Container<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type.

Note

Calling this version of when_all where the input container is empty, returns a future with an empty container that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_all will not throw an exception, but the futures held in the output collection may.

Parameters

  • values: [in] A range holding an arbitrary amount of future or shared_future objects for which when_all should wait.

template<typename ...T>
future<tuple<future<T>...>> when_all(T&&... futures)

The function when_all is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.

Return

Returns a future holding the same list of futures as has been passed to when_all.

  • future<tuple<future<T0>, future<T1>, future<T2>…>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.

  • future<tuple<>> if when_all is called with zero arguments. The returned future will be initially ready.

Note

Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_all will not throw an exception, but the futures held in the output collection may.

Parameters

  • futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_all should wait.

template<typename InputIter, typename Container = vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<Container> when_all_n(InputIter begin, std::size_t count)

The function when_all_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after they finished executing.

Return

Returns a future holding the same list of futures as has been passed to when_all_n.

  • future<Container<future<R>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output vector will be the same as given by the input iterator.

Note

As long as ec is not pre-initialized to hpx::throws this function doesn’t throw but returns the result code using the parameter ec. Otherwise it throws an instance of hpx::exception.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • begin: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_all_n should wait.

  • count: [in] The number of elements in the sequence starting at first.

Exceptions

  • This: function will throw errors which are encountered while setting up the requested operation only. Errors encountered while executing the operations delivering the results to be stored in the futures are reported through the futures themselves.

namespace hpx

Functions

template<typename InputIter, typename Container = vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_any_result<Container>> when_any(InputIter first, InputIter last)

The function when_any is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.

Return

Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future.

  • future<when_any_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.

Parameters

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_any should wait.

  • last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_any should wait.

template<typename Range>
future<when_any_result<Range>> when_any(Range &values)

The function when_any is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.

Return

Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future.

  • future<when_any_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.

Parameters

  • values: [in] A range holding an arbitrary amount of futures or shared_future objects for which when_any should wait.

template<typename ...T>
future<when_any_result<tuple<future<T>...>>> when_any(T&&... futures)

The function when_any is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.

Return

Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future..

  • future<when_any_result<tuple<future<T0>, future<T1>…>>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.

  • future<when_any_result<tuple<>>> if when_any is called with zero arguments. The returned future will be initially ready.

Parameters

  • futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_any should wait.

template<typename InputIter, typename Container = vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_any_result<Container>> when_any_n(InputIter first, std::size_t count)

The function when_any_n is a non-deterministic choice operator. It OR-composes all future objects given and returns a new future object representing the same list of futures after one future of that list finishes execution.

Return

Returns a when_any_result holding the same list of futures as has been passed to when_any and an index pointing to a ready future.

  • future<when_any_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.

Note

None of the futures in the input sequence are invalidated.

Parameters

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_any_n should wait.

  • count: [in] The number of elements in the sequence starting at first.

template<typename Sequence>
struct when_any_result
#include <when_any.hpp>

Result type for when_any, contains a sequence of futures and an index pointing to a ready future.

Public Members

std::size_t index

The index of a future which has become ready.

Sequence futures

The sequence of futures as passed to hpx::when_any.

namespace hpx

Functions

template<typename F, typename Future>
future<void> when_each(F &&f, std::vector<Future> &&futures)

The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Return

Returns a future representing the event of all input futures being ready.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • futures: A vector holding an arbitrary amount of future or shared_future objects for which wait_each should wait.

template<typename F, typename Iterator>
future<Iterator> when_each(F &&f, Iterator begin, Iterator end)

The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Return

Returns a future representing the event of all input futures being ready.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each should wait.

  • end: The iterator pointing to the last element of a sequence of future or shared_future objects for which wait_each should wait.

template<typename F, typename ...Ts>
future<void> when_each(F &&f, Ts&&... futures)

The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Return

Returns a future representing the event of all input futures being ready.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • futures: An arbitrary number of future or shared_future objects, possibly holding different types for which wait_each should wait.

template<typename F, typename Iterator>
future<Iterator> when_each_n(F &&f, Iterator begin, std::size_t count)

The function when_each is an operator allowing to join on the results of all given futures. It AND-composes all future objects given and returns a new future object representing the event of all those futures having finished executing. It also calls the supplied callback for each of the futures which becomes ready.

Note

This function consumes the futures as they are passed on to the supplied function. The callback should take one or two parameters, namely either a future to be processed or a type that std::size_t is implicitly convertible to as the first parameter and the future as the second parameter. The first parameter will correspond to the index of the current future in the collection.

Return

Returns a future holding the iterator pointing to the first element after the last one.

Parameters

  • f: The function which will be called for each of the input futures once the future has become ready.

  • begin: The iterator pointing to the first element of a sequence of future or shared_future objects for which wait_each_n should wait.

  • count: The number of elements in the sequence starting at first.

namespace hpx

Functions

template<typename InputIter, typename Container = vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_some_result<Container>> when_some(std::size_t n, Iterator first, Iterator last, error_code &ec = throws)

The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The future returned by the function when_some becomes ready when at least n argument futures have become ready.

Return

Returns a when_some_result holding the same list of futures as has been passed to when_some and indices pointing to ready futures.

  • future<when_some_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.

Note

Calling this version of when_some where first == last, returns a future with an empty container that is immediately ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.

  • last: [in] The iterator pointing to the last element of a sequence of future or shared_future objects for which when_all should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename Range>
future<when_some_result<Range>> when_some(std::size_t n, Range &&futures, error_code &ec = throws)

The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The future returned by the function when_some becomes ready when at least n argument futures have become ready.

Return

Returns a when_some_result holding the same list of futures as has been passed to when_some and indices pointing to ready futures.

  • future<when_some_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.

Note

Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • futures: [in] A container holding an arbitrary amount of future or shared_future objects for which when_some should wait.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename ...T>
future<when_some_result<tuple<future<T>...>>> when_some(std::size_t n, error_code &ec, T&&... futures)

The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The future returned by the function when_some becomes ready when at least n argument futures have become ready.

Return

Returns a when_some_result holding the same list of futures as has been passed to when_some and an index pointing to a ready future..

  • future<when_some_result<tuple<future<T0>, future<T1>…>>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.

  • future<when_some_result<tuple<>>> if when_some is called with zero arguments. The returned future will be initially ready.

Note

Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

  • futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_some should wait.

template<typename ...T>
future<when_some_result<tuple<future<T>...>>> when_some(std::size_t n, T&&... futures)

The function when_some is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The future returned by the function when_some becomes ready when at least n argument futures have become ready.

Return

Returns a when_some_result holding the same list of futures as has been passed to when_some and an index pointing to a ready future..

  • future<when_some_result<tuple<future<T0>, future<T1>…>>>: If inputs are fixed in number and are of heterogeneous types. The inputs can be any arbitrary number of future objects.

  • future<when_some_result<tuple<>>> if when_some is called with zero arguments. The returned future will be initially ready.

Note

Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • futures: [in] An arbitrary number of future or shared_future objects, possibly holding different types for which when_some should wait.

template<typename InputIter, typename Container = vector<future<typename std::iterator_traits<InputIter>::value_type>>>
future<when_some_result<Container>> when_some_n(std::size_t n, Iterator first, std::size_t count, error_code &ec = throws)

The function when_some_n is an operator allowing to join on the result of all given futures. It AND-composes all future objects given and returns a new future object representing the same list of futures after n of them finished executing.

Note

The future returned by the function when_some_n becomes ready when at least n argument futures have become ready.

Return

Returns a when_some_result holding the same list of futures as has been passed to when_some and indices pointing to ready futures.

  • future<when_some_result<Container<future<R>>>>: If the input cardinality is unknown at compile time and the futures are all of the same type. The order of the futures in the output container will be the same as given by the input iterator.

Note

Calling this version of when_some_n where count == 0, returns a future with the same elements as the arguments that is immediately ready. Possibly none of the futures in that container are ready. Each future and shared_future is waited upon and then copied into the collection of the output (returned) future, maintaining the order of the futures in the input collection. The future returned by when_some_n will not throw an exception, but the futures held in the output collection may.

Parameters

  • n: [in] The number of futures out of the arguments which have to become ready in order for the returned future to get ready.

  • first: [in] The iterator pointing to the first element of a sequence of future or shared_future objects for which when_all should wait.

  • count: [in] The number of elements in the sequence starting at first.

  • ec: [in,out] this represents the error status on exit, if this is pre-initialized to hpx::throws the function will throw on error instead.

template<typename Sequence>
struct when_some_result
#include <when_some.hpp>

Result type for when_some, contains a sequence of futures and indices pointing to ready futures.

Public Members

std::vector<std::size_t> indices

List of indices of futures which became ready.

Sequence futures

The sequence of futures as passed to hpx::when_some.