thread/doc/future_ref.qbk

[/
  (C) Copyright 2008-11 Anthony Williams.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:reference Futures Reference]

  //#include <boost/thread/futures.hpp>

  namespace boost 
  {
  #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
    namespace future_state
    {
        enum state {uninitialized, waiting, ready, moved};
    }
  #endif

    enum class future_errc
    {
      broken_promise,
      future_already_retrieved,
      promise_already_satisfied,
      no_state
    };

    namespace system
    {
      template <>
      struct is_error_code_enum<future_errc> : public true_type {};

      error_code make_error_code(future_errc e);

      error_condition make_error_condition(future_errc e);
    }

    const system::error_category& future_category();

    class future_error;

    template <typename R>
    class promise;

    template <typename R>
    void swap(promise<R>& x, promise<R>& y) noexcept;

    namespace container {
      template <class R, class Alloc> 
      struct uses_allocator<promise<R>, Alloc>:: true_type;
    }

    template <typename R>
    class future;

    template <typename R>
    class shared_future;

    template <typename R>
    class packaged_task;
    template <class R> void swap(packaged_task<R>&, packaged_task<R>&) noexcept;

    //template <class R, class Alloc> 
    //struct uses_allocator<packaged_task <R>, Alloc>; // NOT YET IMPLEMENTED

    // template <class F, class... Args> 
    // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type> 
    // async(F&& f, Args&&... args); // NOT YET IMPLEMENTED
    // template <class F, class... Args> 
    // future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type> 
    // async(launch policy, F&& f, Args&&... args); // NOT YET IMPLEMENTED


    template<typename Iterator>
    void wait_for_all(Iterator begin,Iterator end); // EXTENSION

    template<typename F1,typename... FS>
    void wait_for_all(F1& f1,Fs&... fs); // EXTENSION

    template<typename Iterator>
    Iterator wait_for_any(Iterator begin,Iterator end);

    template<typename F1,typename... Fs>
    unsigned wait_for_any(F1& f1,Fs&... fs);


[section:future_state Enumeration `state`]

    namespace future_state
    {
        enum state {uninitialized, waiting, ready, moved};
    }


[endsect]


[section:future_errc Enumeration `future_errc `]

  enum class future_errc
  {
    broken_promise,
    future_already_retrieved,
    promise_already_satisfied,
    no_state
  }

[endsect]
[section:is_error_code_enum Specialization `is_error_code_enum<future_errc>`]

  namespace system
  {
    template <>
    struct is_error_code_enum<future_errc> : public true_type {};

  }

[endsect]
[section:make_error_code Non-member function `make_error_code()`]

  namespace system
  {
    error_code make_error_code(future_errc e);
  }

[endsect]
[section:make_error_condition Non-member function `make_error_condition()`]

  namespace system
  {
    error_condition make_error_condition(future_errc e);
  }

[endsect]
[section:future_category Non-member function `future_category()`]

  const system::error_category& future_category();

[endsect]
[section:future_error Class `future_error`]

  class future_error
      : public std::logic_error
  {
  public:
      future_error(system::error_code ec);

      const system::error_code& code() const no_except;
  };

[endsect]

[section:future_status Enumeration `future_status`]

  enum class future_status { 
    ready,  timeout, deferred
  };

[endsect]

[section:unique_future `unique_future` class template]

    template <typename R>
    class unique_future
    {

    public:
        unique_future(unique_future & rhs);// = delete;
        unique_future& operator=(unique_future& rhs);// = delete;

        unique_future() noexcept;
        ~unique_future();

        // move support
        unique_future(unique_future && other) noexcept;
        unique_future& operator=(unique_future && other) noexcept;
	shared_future<R> share();

        void swap(unique_future& other) noexcept; // EXTENSION

        // retrieving the value
        R&& get();        

        // functions to check state
        bool valid() const;        
        bool is_ready() const; // EXTENSION        
        bool has_exception() const; // EXTENSION        
        bool has_value() const; // EXTENSION        

        // waiting for the result to be ready
        void wait() const;       
        template <class Rep, class Period>
        future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
        template <class Clock, class Duration>
        future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const; 

    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
        template<typename Duration>
        bool timed_wait(Duration const& rel_time) const;
        bool timed_wait_until(boost::system_time const& abs_time) const; 
    #endif
    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
        typedef future_state::state state;
        state get_state() const;
    #endif
    };

[section:default_constructor Default Constructor]

    unique_future();

[variablelist

[[Effects:] [Constructs an uninitialized future.]]

[[Postconditions:] [[unique_future_is_ready_link `this->is_ready`] returns `false`. [unique_future_get_state_link
`this->get_state()`] returns __uninitialized__.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:destructor Destructor]

    ~unique_future();

[variablelist

[[Effects:] [Destroys `*this`.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:move_constructor Move Constructor]

    unique_future(unique_future && other);

[variablelist

[[Effects:] [Constructs a new future, and transfers ownership of the asynchronous result associated with `other` to `*this`.]]

[[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
call. `other->get_state()` returns __uninitialized__. If `other` was associated with an asynchronous result, that result is now
associated with `*this`. `other` is not associated with any asynchronous result.]]

[[Throws:] [Nothing.]]

[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]

]

[endsect]

[section:move_assignment Move Assignment Operator]

    unique_future& operator=(unique_future && other);

[variablelist

[[Effects:] [Transfers ownership of the asynchronous result associated with `other` to `*this`.]]

[[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
call. `other->get_state()` returns __uninitialized__. If `other` was associated with an asynchronous result, that result is now
associated with `*this`. `other` is not associated with any asynchronous result. If `*this` was associated with an asynchronous
result prior to the call, that result no longer has an associated __unique_future__ instance.]]

[[Throws:] [Nothing.]]

[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]

]

[endsect]

[section:swap Member function `swap()`]

    void swap(unique_future & other) no_except;

[variablelist

[[Effects:] [Swaps ownership of the asynchronous results associated with `other` and `*this`.]]

[[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
call. `other->get_state()` returns the value of `this->get_state()` prior to the call. If `other` was associated with an
asynchronous result, that result is now associated with `*this`, otherwise `*this` has no associated result. If `*this` was
associated with an asynchronous result, that result is now associated with `other`, otherwise `other` has no associated result.]]

[[Throws:] [Nothing.]]

]

[endsect]


[section:get Member function `get()`]

    R&& get();
    R& unique_future<R&>::get();
    void unique_future<void>::get();

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready as-if by a call to
__unique_future_wait__, and retrieves the result (whether that is a value or an exception).]]

[[Returns:] [If the result type `R` is a reference, returns the stored reference. If `R` is `void`, there is no return
value. Otherwise, returns an rvalue-reference to the value stored in the asynchronous result.]]

[[Postconditions:] [[unique_future_is_ready_link `this->is_ready()`] returns `true`. [unique_future_get_state_link
`this->get_state()`] returns __ready__.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception stored in the
asynchronous result in place of a value.]]

[[Notes:] [`get()` is an ['interruption point].]]

]

[endsect]

[section:wait Member function `wait()`]

    void wait();

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready. If the result is not ready on
entry, and the result has a ['wait callback] set, that callback is invoked prior to waiting.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
['wait callback] if such a callback is called.]]

[[Postconditions:] [[unique_future_is_ready_link `this->is_ready()`] returns `true`. [unique_future_get_state_link
`this->get_state()`] returns __ready__.]]

[[Notes:] [`wait()` is an ['interruption point].]]

]

[endsect]

[section:timed_wait_duration Member function `timed_wait()`]

    template<typename Duration>
    bool timed_wait(Duration const& wait_duration);

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time specified by
`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
invoked prior to waiting.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready before the specified time has
elapsed, `false` otherwise.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
['wait callback] if such a callback is called.]]

[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
[unique_future_get_state_link `this->get_state()`] returns __ready__.]]

[[Notes:] [`timed_wait()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]

]

[endsect]

[section:timed_wait_absolute Member function `timed_wait()`]

    bool timed_wait(boost::system_time const& wait_timeout);

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time point specified by
`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
prior to waiting.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready before the specified time has
passed, `false` otherwise.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
['wait callback] if such a callback is called.]]

[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
[unique_future_get_state_link `this->get_state()`] returns __ready__.]]

[[Notes:] [`timed_wait()` is an ['interruption point].]]

]

[endsect]


[section:is_ready Member function `is_ready()` EXTENSION]

    bool is_ready();

[variablelist

[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready for retrieval, `false`
otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:has_value Member function `has_value()` EXTENSION]

    bool has_value();

[variablelist

[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with a value rather than an exception.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
stored value, `false` otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:has_exception Member function `has_exception()` EXTENSION]

    bool has_exception();

[variablelist

[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with an exception rather than a value.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
stored exception, `false` otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:get_state Member function `get_state()`]

    future_state::state get_state();

[variablelist

[[Effects:] [Determine the state of the asynchronous result associated with `*this`, if any.]]

[[Returns:] [__uninitialized__ if `*this` is not associated with an asynchronous result. __ready__ if the asynchronous result
associated with `*this` is ready for retrieval, __waiting__ otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]


[endsect]

[section:shared_future `shared_future` class template]

    template <typename R>
    class shared_future
    {
    public:
        typedef future_state::state state; // EXTENSION

        shared_future() noexcept;
        ~shared_future();

        // copy support
        shared_future(shared_future const& other);
        shared_future& operator=(shared_future const& other);

        // move support
        shared_future(shared_future && other) noexcept;
        shared_future(unique_future<R> && other) noexcept;
        shared_future& operator=(shared_future && other) noexcept;
        shared_future& operator=(unique_future<R> && other) noexcept;

        void swap(shared_future& other);

        // retrieving the value
        R get();
        
        // functions to check state, and wait for ready
        bool valid() const noexcept;
        bool is_ready() const noexcept; // EXTENSION
        bool has_exception() const noexcept; // EXTENSION
        bool has_value() const noexcept; // EXTENSION

        // waiting for the result to be ready
        void wait() const;        
        template <class Rep, class Period>
        future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
        template <class Clock, class Duration>
        future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const; 

    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0 || defined BOOST_THREAD_DONT_USE_CHRONO
        template<typename Duration>
        bool timed_wait(Duration const& rel_time) const;
        bool timed_wait_until(boost::system_time const& abs_time) const;
    #endif
    #if defined BOOST_THREAD_PROVIDES_DEPRECATED_FEATURES_SINCE_V3_0_0
        state get_state() const noexcept;
    #endif
    };

[section:default_constructor Default Constructor]

    shared_future();

[variablelist

[[Effects:] [Constructs an uninitialized future.]]

[[Postconditions:] [[shared_future_is_ready_link `this->is_ready`] returns `false`. [shared_future_get_state_link
`this->get_state()`] returns __uninitialized__.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:get Member function `get()`]

    const R& get();

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready as-if by a call to
__shared_future_wait__, and returns a `const` reference to the result.]]

[[Returns:] [If the result type `R` is a reference, returns the stored reference. If `R` is `void`, there is no return
value. Otherwise, returns a `const` reference to the value stored in the asynchronous result.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the
result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.]]

[[Notes:] [`get()` is an ['interruption point].]]

]

[endsect]

[section:wait Member function `wait()`]

    void wait();

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready. If the result is not ready on
entry, and the result has a ['wait callback] set, that callback is invoked prior to waiting.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
['wait callback] if such a callback is called.]]

[[Postconditions:] [[shared_future_is_ready_link `this->is_ready()`] returns `true`. [shared_future_get_state_link
`this->get_state()`] returns __ready__.]]

[[Notes:] [`wait()` is an ['interruption point].]]

]

[endsect]

[section:timed_wait_duration Member function `timed_wait()`]

    template<typename Duration>
    bool timed_wait(Duration const& wait_duration);

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time specified by
`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
invoked prior to waiting.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready before the specified time has
elapsed, `false` otherwise.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
['wait callback] if such a callback is called.]]

[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
[shared_future_get_state_link `this->get_state()`] returns __ready__.]]

[[Notes:] [`timed_wait()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]

]

[endsect]

[section:timed_wait_absolute Member function `timed_wait()`]

    bool timed_wait(boost::system_time const& wait_timeout);

[variablelist

[[Effects:] [If `*this` is associated with an asynchronous result, waits until the result is ready, or the time point specified by
`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
prior to waiting.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready before the specified time has
passed, `false` otherwise.]]

[[Throws:] [__future_uninitialized__ if `*this` is not associated with an asynchronous result. __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted. Any exception thrown by the
['wait callback] if such a callback is called.]]

[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
[shared_future_get_state_link `this->get_state()`] returns __ready__.]]

[[Notes:] [`timed_wait()` is an ['interruption point].]]

]

[endsect]

[section:is_ready Member function `is_ready()` EXTENSION]

    bool is_ready();

[variablelist

[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, and that result is ready for retrieval, `false`
otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:has_value Member function `has_value()` EXTENSION]

    bool has_value();

[variablelist

[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with a value rather than an exception.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
stored value, `false` otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:has_exception Member function `has_exception()` EXTENSION]

    bool has_exception();

[variablelist

[[Effects:] [Checks to see if the asynchronous result associated with `*this` is set with an exception rather than a value.]]

[[Returns:] [`true` if `*this` is associated with an asynchronous result, that result is ready for retrieval, and the result is a
stored exception, `false` otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:get_state Member function `get_state()`]

    future_state::state get_state();

[variablelist

[[Effects:] [Determine the state of the asynchronous result associated with `*this`, if any.]]

[[Returns:] [__uninitialized__ if `*this` is not associated with an asynchronous result. __ready__ if the asynchronous result
associated with `*this` is ready for retrieval, __waiting__ otherwise.]]

[[Throws:] [Nothing.]]

]

[endsect]


[endsect]

[section:promise `promise` class template]

    template <typename R>
    class promise
    {
    public:

        promise();
        template <class Allocator> 
        promise(allocator_arg_t, Allocator a);
        promise & operator=(const promise & rhs);// = delete;
        promise(const promise & rhs);// = delete;
        ~promise();

        // Move support
        promise(promise && rhs) noexcept;;
        promise & operator=(promise&& rhs) noexcept;;
        
        void swap(promise& other) noexcept;
        // Result retrieval
        unique_future<R> get_future();

        // Set the value
        void set_value(R& r);
        void set_value(R&& r);
        void set_exception(boost::exception_ptr e);

        // setting the result with deferred notification
        // void set_value_at_thread_exit(const R& r); // NOT YET IMPLEMENTED
        // void set_value_at_thread_exit(see below); // NOT YET IMPLEMENTED
        // void set_exception_at_thread_exit(exception_ptr p); // NOT YET IMPLEMENTED

        template<typename F>
        void set_wait_callback(F f); // EXTENSION       
    };

[section:default_constructor Default Constructor]

    promise();

[variablelist

[[Effects:] [Constructs a new __promise__ with no associated result.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:alloc_constructor Allocator Constructor]

        template <class Allocator> 
        promise(allocator_arg_t, Allocator a);

[variablelist

[[Effects:] [Constructs a new __promise__ with no associated result using the allocator `a`.]]

[[Throws:] [Nothing.]]

[[Notes:] [Available only if BOOST_THREAD_FUTURE_USES_ALLOCATORS is defined.]]

]

[endsect]



[section:move_constructor Move Constructor]

    promise(promise && other);

[variablelist

[[Effects:] [Constructs a new __promise__, and transfers ownership of the result associated with `other` to `*this`, leaving `other`
with no associated result.]]

[[Throws:] [Nothing.]]

[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]

]

[endsect]

[section:move_assignment Move Assignment Operator]

    promise& operator=(promise && other);

[variablelist

[[Effects:] [Transfers ownership of the result associated with `other` to `*this`, leaving `other` with no associated result. If there
was already a result associated with `*this`, and that result was not ['ready], sets any futures associated with that result to
['ready] with a __broken_promise__ exception as the result. ]]

[[Throws:] [Nothing.]]

[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]

]

[endsect]

[section:destructor Destructor]

    ~promise();

[variablelist

[[Effects:] [Destroys `*this`. If there was a result associated with `*this`, and that result is not ['ready], sets any futures
associated with that task to ['ready] with a __broken_promise__ exception as the result.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:get_future Member Function `get_future()`]

    unique_future<R> get_future();

[variablelist

[[Effects:] [If `*this` was not associated with a result, allocate storage for a new asynchronous result and associate it with
`*this`. Returns a __unique_future__ associated with the result associated with `*this`. ]]

[[Throws:] [__future_already_retrieved__ if the future associated with the task has already been retrieved. `std::bad_alloc` if any
memory necessary could not be allocated.]]

]

[endsect]

[section:set_value Member Function `set_value()`]

    void set_value(R&& r);
    void set_value(const R& r);
    void promise<R&>::set_value(R& r);
    void promise<void>::set_value();

[variablelist

[[Effects:] [If `*this` was not associated with a result, allocate storage for a new asynchronous result and associate it with
`*this`. Store the value `r` in the asynchronous result associated with `*this`. Any threads blocked waiting for the asynchronous
result are woken.]]

[[Postconditions:] [All futures waiting on the asynchronous result are ['ready] and __unique_future_has_value__ or
__shared_future_has_value__ for those futures shall return `true`.]]

[[Throws:] [__promise_already_satisfied__ if the result associated with `*this` is already ['ready]. `std::bad_alloc` if the memory
required for storage of the result cannot be allocated. Any exception thrown by the copy or move-constructor of `R`.]]

]

[endsect]

[section:set_exception Member Function `set_exception()`]

    void set_exception(boost::exception_ptr e);

[variablelist

[[Effects:] [If `*this` was not associated with a result, allocate storage for a new asynchronous result and associate it with
`*this`. Store the exception `e` in the asynchronous result associated with `*this`. Any threads blocked waiting for the asynchronous
result are woken.]]

[[Postconditions:] [All futures waiting on the asynchronous result are ['ready] and __unique_future_has_exception__ or
__shared_future_has_exception__ for those futures shall return `true`.]]

[[Throws:] [__promise_already_satisfied__ if the result associated with `*this` is already ['ready]. `std::bad_alloc` if the memory
required for storage of the result cannot be allocated.]]

]

[endsect]

[section:set_wait_callback Member Function `set_wait_callback()`]

    template<typename F>
    void set_wait_callback(F f);

[variablelist

[[Preconditions:] [The expression `f(t)` where `t` is a lvalue of type __promise__ shall be well-formed. Invoking a copy of
`f` shall have the same effect as invoking `f`]]

[[Effects:] [Store a copy of `f` with the asynchronous result associated with `*this` as a ['wait callback]. This will replace any
existing wait callback store alongside that result. If a thread subsequently calls one of the wait functions on a __unique_future__
or __shared_future__ associated with this result, and the result is not ['ready], `f(*this)` shall be invoked.]]

[[Throws:] [`std::bad_alloc` if memory cannot be allocated for the required storage.]]

]

[endsect]

[endsect]

[section:packaged_task `packaged_task` class template]

    template<typename R
      // , class... ArgTypes // NOT YET IMPLEMENTED
    >
    class packaged_task
    {
    public:
        typedef R result_type;

        packaged_task(packaged_task&);// = delete;
        packaged_task& operator=(packaged_task&);// = delete;

        // construction and destruction
        packaged_task() noexcept;

        explicit packaged_task(R(*f)());
        
        template <class F>
        explicit packaged_task(F&& f);

        template <class F, class Allocator>
        packaged_task(allocator_arg_t, Allocator a, F&& f);

        ~packaged_task()
        {}

        // move support
        packaged_task(packaged_task&& other) noexcept;
        packaged_task& operator=(packaged_task&& other) noexcept;

        void swap(packaged_task& other) noexcept;

        bool valid() const noexcept;
        // result retrieval
        unique_future<R> get_future();        

        // execution
        void operator()();
        // void operator()(ArgTypes... );  // NOT YET IMPLEMENTED
        // void make_ready_at_thread_exit(ArgTypes...); // NOT YET IMPLEMENTED

        void reset();
        template<typename F>
        void set_wait_callback(F f);  // EXTENSION   
    };

[section:task_constructor Task Constructor]

    packaged_task(R(*f)());

    template<typename F>
    packaged_task(F&&f);

[variablelist

[[Preconditions:] [`f()` is a valid expression with a return type convertible to `R`. Invoking a copy of `f` shall behave the same
as invoking `f`.]]

[[Effects:] [Constructs a new __packaged_task__ with `boost::forward<F>(f)` stored as the associated task.]]

[[Throws:] [Any exceptions thrown by the copy (or move) constructor of `f`. `std::bad_alloc` if memory for the internal data
structures could not be allocated.]]

[[Notes:] [The R(*f)()) overload to allow passing a function without needing to use `&`.]]

]

[endsect]

[section:alloc_constructor Allocator Constructor]

        template <class Allocator>
        packaged_task(allocator_arg_t, Allocator a, R(*f)());
        template <class F, class Allocator>
        packaged_task(allocator_arg_t, Allocator a, F&& f);

[variablelist

[[Preconditions:] [`f()` is a valid expression with a return type convertible to `R`. Invoking a copy of `f` shall behave the same
as invoking `f`.]]

[[Effects:] [Constructs a new __packaged_task with `boost::forward<F>(f)` stored as the associated task using the allocator `a`.]]

[[Throws:] [Any exceptions thrown by the copy (or move) constructor of `f`. `std::bad_alloc` if memory for the internal data
structures could not be allocated.]]

[[Notes:] [Available only if BOOST_THREAD_FUTURE_USES_ALLOCATORS is defined.]]
[[Notes:] [The R(*f)()) overload to allow passing a function without needing to use `&`.]]

]

[endsect]

[section:move_constructor Move Constructor]

    packaged_task(packaged_task && other);

[variablelist

[[Effects:] [Constructs a new __packaged_task__, and transfers ownership of the task associated with `other` to `*this`, leaving `other`
with no associated task.]]

[[Throws:] [Nothing.]]

[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]

]

[endsect]


[section:move_assignment Move Assignment Operator]

    packaged_task& operator=(packaged_task && other);

[variablelist

[[Effects:] [Transfers ownership of the task associated with `other` to `*this`, leaving `other` with no associated task. If there
was already a task associated with `*this`, and that task has not been invoked, sets any futures associated with that task to
['ready] with a __broken_promise__ exception as the result. ]]

[[Throws:] [Nothing.]]

[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]

]

[endsect]

[section:destructor Destructor]

    ~packaged_task();

[variablelist

[[Effects:] [Destroys `*this`. If there was a task associated with `*this`, and that task has not been invoked, sets any futures
associated with that task to ['ready] with a __broken_promise__ exception as the result.]]

[[Throws:] [Nothing.]]

]

[endsect]

[section:get_future Member Function `get_future()`]

    unique_future<R> get_future();

[variablelist

[[Effects:] [Returns a __unique_future__ associated with the result of the task associated with `*this`. ]]

[[Throws:] [__task_moved__ if ownership of the task associated with `*this` has been moved to another instance of
__packaged_task__. __future_already_retrieved__ if the future associated with the task has already been retrieved.]]

]

[endsect]

[section:call_operator Member Function `operator()()`]

    void operator()();

[variablelist

[[Effects:] [Invoke the task associated with `*this` and store the result in the corresponding future. If the task returns normally,
the return value is stored as the asynchronous result, otherwise the exception thrown is stored. Any threads blocked waiting for the
asynchronous result associated with this task are woken.]]

[[Postconditions:] [All futures waiting on the asynchronous result are ['ready]]]

[[Throws:] [__task_moved__ if ownership of the task associated with `*this` has been moved to another instance of
__packaged_task__. __task_already_started__ if the task has already been invoked.]]

]

[endsect]

[section:reset Member Function `reset()`]

        void reset();

[variablelist

[[Effects:] [Reset the state of the packaged_task so that it can be called again.]]

[[Throws:] [__task_moved__ if ownership of the task associated with `*this` has been moved to another instance of
__packaged_task__.]]

]

[endsect]

[section:set_wait_callback Member Function `set_wait_callback()` EXTENSION]

    template<typename F>
    void set_wait_callback(F f);

[variablelist

[[Preconditions:] [The expression `f(t)` where `t` is a lvalue of type __packaged_task__ shall be well-formed. Invoking a copy of
`f` shall have the same effect as invoking `f`]]

[[Effects:] [Store a copy of `f` with the task associated with `*this` as a ['wait callback]. This will replace any existing wait
callback store alongside that task. If a thread subsequently calls one of the wait functions on a __unique_future__ or
__shared_future__ associated with this task, and the result of the task is not ['ready], `f(*this)` shall be invoked.]]

[[Throws:] [__task_moved__ if ownership of the task associated with `*this` has been moved to another instance of
__packaged_task__.]]

]

[endsect]


[endsect]

[section:wait_for_any Non-member function `wait_for_any()`]

    template<typename Iterator>
    Iterator wait_for_any(Iterator begin,Iterator end);

    template<typename F1,typename F2>
    unsigned wait_for_any(F1& f1,F2& f2);

    template<typename F1,typename F2,typename F3>
    unsigned wait_for_any(F1& f1,F2& f2,F3& f3);

    template<typename F1,typename F2,typename F3,typename F4>
    unsigned wait_for_any(F1& f1,F2& f2,F3& f3,F4& f4);

    template<typename F1,typename F2,typename F3,typename F4,typename F5>
    unsigned wait_for_any(F1& f1,F2& f2,F3& f3,F4& f4,F5& f5);

[variablelist

[[Preconditions:] [The types `Fn` shall be specializations of
__unique_future__ or __shared_future__, and `Iterator` shall be a
forward iterator with a `value_type` which is a specialization of
__unique_future__ or __shared_future__.]]

[[Effects:] [Waits until at least one of the specified futures is ['ready].]]

[[Returns:] [The range-based overload returns an `Iterator` identifying the first future in the range that was detected as
['ready]. The remaining overloads return the zero-based index of the first future that was detected as ['ready] (first parameter =>
0, second parameter => 1, etc.).]]

[[Throws:] [__thread_interrupted__ if the current thread is interrupted. Any exception thrown by the ['wait callback] associated
with any of the futures being waited for.  `std::bad_alloc` if memory could not be allocated for the internal wait structures.]]

[[Notes:] [`wait_for_any()` is an ['interruption point].]]

]


[endsect]

[section:wait_for_all Non-member function `wait_for_all()`]

    template<typename Iterator>
    void wait_for_all(Iterator begin,Iterator end);

    template<typename F1,typename F2>
    void wait_for_all(F1& f1,F2& f2);

    template<typename F1,typename F2,typename F3>
    void wait_for_all(F1& f1,F2& f2,F3& f3);

    template<typename F1,typename F2,typename F3,typename F4>
    void wait_for_all(F1& f1,F2& f2,F3& f3,F4& f4);

    template<typename F1,typename F2,typename F3,typename F4,typename F5>
    void wait_for_all(F1& f1,F2& f2,F3& f3,F4& f4,F5& f5);

[variablelist

[[Preconditions:] [The types `Fn` shall be specializations of
__unique_future__ or __shared_future__, and `Iterator` shall be a
forward iterator with a `value_type` which is a specialization of
__unique_future__ or __shared_future__.]]

[[Effects:] [Waits until all of the specified futures are ['ready].]]

[[Throws:] [Any exceptions thrown by a call to `wait()` on the specified futures.]]

[[Notes:] [`wait_for_all()` is an ['interruption point].]]

]


[endsect]


[endsect]