Class template future_selector

poet::future_selector — efficient repeated waits on a group of futures

Synopsis

template<typename T> 
class future_selector {
public:
  // types
  typedef future<T>      value_type;     
  typedef std::size_t    size_type;      
  typedef std::ptrdiff_t difference_type;

  // construct/copy/destruct
  future_selector();
  future_selector(const future_selector &);
  future_selector& operator=(const future_selector &);
  ~future_selector();

  // public member functions
  future<T> selected() const;
  void pop_selected();
  void push(const future<T> &);
  template<typename Converter, typename U> 
    void push(const Converter &, const ExceptionHandler &, const future<U> &);
  difference_type size() const;
  void reset();
  void swap(future_selector &);
};

// free functions
template<typename T> void swap(future_selector<T> &, future_selector<T> &);

Description

future_selector allows you to obtain futures which will become ready when any future in a group of futures becomes ready. It is more efficient than maintaining a separate container of futures and repeatedly passing them to future_select_range.

Most of the methods of future_selector are thread-safe. The exceptions to this rule are: reset, swap, and the assignment operator.

See also

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

  • future_barrier: construct a future which becomes ready when all of a group of futures are ready or one has an exception.

future_selector public construct/copy/destruct

  1. future_selector();

    Constructs a future_selector containing no futures. Futures may be added to the future_selector with the push method.

    Postconditions:

    size() == 0 

  2. future_selector(const future_selector & other);

    *this will receive a copy of all the futures in other. Copy construction has deep copy semantics, so calling methods such as push or pop_selected on a future_selector copy will not effect the original, and vice-versa.

    Postconditions:

    this->size() == other.size() 

  3. future_selector& operator=(const future_selector & rhs);

    Copy-constructs a temporary future_selector from rhs, then swaps it with *this.

    Postconditions:

    this->size() == rhs.size() 

  4. ~future_selector();

    Any futures contained in the future_selector at its time of destruction will be kept alive as long as needed and to fulfill any remaining "selected futures" previously obtained from calls to the selected method, even after the future_selector itself has been destroyed. However, any "selected futures" which no longer have any possibility of being fulfilled, due to an insufficient number of futures contained in the future_selector at the time of its destruction (that is, size returns a negative value), will be automatically reneged with an uncertain_future exception.

future_selector public member functions

  1. future<T> selected() const;

    Returns a future which will receive the value or exception of the next future in the future_selector to complete. The "selected future" returned will be fulfilled only after any selected futures obtained prior to the last pop_selected call are fulfilled. 

  2. void pop_selected();

    Removes a future from the future_selector, so subsequent calls to selected will return a different "selected future". The selected futures will be fulfilled in the order they were popped out of the future_selector.

    This method may be called before the future returned by selected is actually complete. It may even be called more times than the number of futures which have been pushed into the future_selector with the push method. This results in size returning a negative value, until more futures are pushed into the future_selector. 

  3. void push(const future<T> & f);
template<typename Converter, typename U> 
  void push(const Converter & converter, 
            const ExceptionHandler & exception_handler, const future<U> & f);

    Adds a future to the future_selector. When the added future becomes ready or gets an exception, it will be used to fulfill or renege the oldest "selected future" which has not yet completed.

    The 3 argument overload of this function is provided for convenience, and is equivalent to push(poet::future_combining_barrier<T>(converter, exception_handler, f)). 

  4. difference_type size() const;

    Returns:

    The number of times push has been called, minus the number of times pop_selected has been called, since the future_selector was default-constructed or reset. This value may be negative. 

  5. void reset();

    Default-constructs a temporary future_selector and swaps it with *this.

    Postconditions:

    size() == 0 

  6. void swap(future_selector & other);

    Swaps *this with other.

future_selector free functions

  1. template<typename T> void swap(future_selector<T> & a, future_selector<T> & b);

    Swaps future_selectors a and b.