Function future_combining_barrier

poet::future_combining_barrier — construct a future based on the values from a group of futures.

Synopsis

template<typename R, typename Combiner, typename ExceptionHandler, 
         typename T1> 
  future<R> future_combining_barrier(const Combiner & combiner, 
                                     const ExceptionHandler & exception_handler, 
                                     const future<T1> & f1);
template<typename R, typename Combiner, typename ExceptionHandler, 
         typename T1, typename T2> 
  future<R> future_combining_barrier(const Combiner & combiner, 
                                     const ExceptionHandler & exception_handler, 
                                     const future<T1> & f1, 
                                     const future<T1> & f2);
template<typename R, typename Combiner, typename ExceptionHandler, 
         typename T1, typename T2, ..., typename TN> 
  future<R> future_combining_barrier(const Combiner & combiner, 
                                     const ExceptionHandler & exception_handler, 
                                     const future<T1> & f1, 
                                     const future<T2> & f2, ..., 
                                     const future<TN> & fN);

Description

The future_combining_barrier function constructs a future which can be used to wait on a group of futures until they are all ready (or one has an exception). The user must specify the combiner and exception_handler functors, which are used to generate the value/exception for the returned future based on the values/exception of the input futures.

The template type parameter R determines the return type of the function, and must be manually specified when calling future_combining_barrier. The rest of the template type parameters may be deduced from the types of the input parameters.

If all the input futures sucessfully become ready, the returned future will become ready by obtaining its value from the return value of combiner(v1, v2, ..., vN) where the vN parameters are the values associated with the input futures. If any of the input futures is a future<void> (and thus has no value), the user's combiner functor will receive a placeholder value of type poet::null_type.

If any of the input futures has an exception, the returned future will receive an exception based on the return value of exception_handler(ex_ptr) where the ex_ptr parameter will be an exception_ptr holding the exception from the input future. The return value of the user's exception_handler functor should be of type exception_ptr and hold the exception which the user desires to be transported to the returned future.

By default, overloads which accept 1 to 10 future arguments are provided. The user may obtain more or fewer overloads by defining the macro POET_FUTURE_BARRIER_MAX_ARGS prior to including poet/future_barrier.hpp.

See also

  • future_combining_barrier_range: Same as future_combining_barrier except it takes iterators to a range of futures as its parameters.

  • future_barrier: A simpler, more limited version of future_combining_barrier which returns a future<void>.

  • future_select: construct a future which becomes ready when any of a group of futures is ready or has an exception.

Returns:

A future which becomes ready when all of the input futures either become ready or one has an exception.