[/
          Copyright Oliver Kowalke 2013.
 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:future Future]

A future provides a mechanism to access the result of an asynchronous operation.

[#class_future_status]
[heading Enumeration `future_status`]

Timed wait-operations (__wait_for__ and __wait_until__) return the state of the future.

        enum class future_status
        {
            ready,
            timeout,
            deferred
        };

[heading `ready`]
[variablelist
[[Effects:] [The shared state is ready.]]
]

[heading `timeout`]
[variablelist
[[Effects:] [The shared state did not become ready before timeout has passed.]]
]

[heading `deferred`]
[variablelist
[[Effects:] [The function is deferred, e.g. result will be computed only when explictly requested.]]
]


[template_heading future]

A __future__ contains a shared state which is not shared with any other future.

        template< typename R >
        class future
        {
        public:
            future() noexcept;

            future( future && other) noexcept;

            future( future const& other) = delete;

            ~future();

            future & operator=( future && other) noexcept;

            future & operator=( future const& other) = delete;

            void swap( future & other) noexcept;

            operator safe_bool() const noexcept;

            bool operator!() const noexcept;

            bool valid() const noexcept;

            shared_future< R > share();

            R get();

            void wait() const;

            template< class Rep, class Period >
            future_status wait_for( chrono::duration< Rep, Period > const& timeout_duration) const;

            future_status wait_until( clock_type::time_point const& timeout_time) const;
        };

[heading Default constructor]

        future();

[variablelist
[[Effects:] [Creates a future with no shared state.
After construction is `false == vaild()`.]]
[[Throws:] [Nothing.]]
]

[heading Move constructor]

        future( future && other) noexcept;

[variablelist
[[Effects:] [Constructs a future with the shared state of other.
After construction is `false == other.valid()`]]
[[Throws:] [Nothing.]]
]

[heading Destructor]

        ~future();

[variablelist
[[Effects:] [Destructs the future; ownership is abandoned.]]
[[Throws:] [Nothing.]]
]

[operator_heading future..operator_assign..operator=]

        future & operator=( future && other) noexcept;

[variablelist
[[Effects:] [Moves the shared state of other to `this`.
After construction is `false == other.valid()`]]
[[Throws:] [Nothing.]]
]

[member_heading future..swap]

        void swap( future & other) noexcept;

[variablelist
[[Effects:] [Swaps the shared state between other and `this`.]]
[[Throws:] [Nothing.]]
]

[member_heading future..operator safe_bool]

        operator safe_bool() const noexcept;

[variablelist
[[Effects:] [Returns `true` if future is valid.]]
[[Throws:] [Nothing.]]
]

[operator_heading future..operator_not..operator!]

        bool operator!() const noexcept;

[variablelist
[[Effects:] [Returns `false` if future is valid.]]
[[Throws:] [Nothing.]]
]

[member_heading future..valid]

        bool valid() const noexcept;

[variablelist
[[Effects:] [Returns `true` if future contains a shared state.]]
[[Throws:] [Nothing.]]
]

[member_heading future..share]

        shared_future< R > share();

[variablelist
[[Effects:] [Move the state to a __shared_future__.]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[member_heading future..get]

        R get();

[variablelist
[[Precondition:] [`true == valid()`]]
[[Effects:] [Returns the result.]]
[[Postcondition:] [`false == valid()`]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[member_heading future..wait]

        void wait();

[variablelist
[[Effects:] [Waits for the result will become available.]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[template_member_heading future..wait_for]

        template< class Rep, class Period >
        future_status wait_for( chrono::duration< Rep, Period > const& timeout_duration) const;

[variablelist
[[Effects:] [Waits for the result will become available or `timeout_duration` has passed.]]
[[Result:] [A `future_status` is returned indicating the reason for returning.]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[member_heading future..wait_until]

        future_status wait_until( clock_type::time_point const& timeout_time) const;

[variablelist
[[Effects:] [Waits for the result will become available or `timeout_time` has passed.]]
[[Result:] [A `future_status` is returned indicating the reason for returning.]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]


[template_heading shared_future]

A __shared_future__ contains a shared state which might be shared with other futures.

        template< typename R >
        class shared_future
        {
        public:
            shared_future() noexcept;

            ~shared_future();

            shared_future( shared_future const& other);

            shared_future( future< R > && other) noexcept;

            shared_future( shared_future && other) noexcept;

            shared_future & operator=( shared_future && other) noexcept;

            shared_future & operator=( future && other) noexcept;

            shared_future & operator=( shared_future const& other) noexcept;

            void swap( shared_future & other) noexcept;

            operator safe_bool() const noexcept;

            bool operator!() const noexcept;

            bool valid() const noexcept;

            R get();

            void wait() const;

            template< class Rep, class Period >
            future_status wait_for( chrono::duration< Rep, Period > const& timeout_duration) const;

            future_status wait_until( clock_type::time_point const& timeout_time) const;
        };

[heading Default constructor]

        shared_future();

[variablelist
[[Effects:] [Creates a future with no shared state.
After construction is `false == vaild()`.]]
[[Throws:] [Nothing.]]
]

[heading Move constructor]

        shared_future( future && other) noexcept;
        shared_future( shared_future && other) noexcept;

[variablelist
[[Effects:] [Constructs a future with the shared state of other.
After construction is `false == other.valid()`.]]
[[Throws:] [Nothing.]]
]

[heading Copy constructor]

        shared_future( shared_future cosnt& other) noexcept;

[variablelist
[[Effects:] [Constructs a future with the shared state of other.
After construction is `true == other.valid()`.]]
[[Throws:] [Nothing.]]
]

[heading Destructor]

        ~shared_future();

[variablelist
[[Effects:] [Destructs the future; ownership is abandoned if not shared.]]
[[Throws:] [Nothing.]]
]

[operator_heading shared_future..operator_assign..operator=]

        shared_future & operator=( future && other) noexcept;
        shared_future & operator=( shared_future && other) noexcept;
        shared_future & operator=( shared_future const& other) noexcept;

[variablelist
[[Effects:] [Transfers the ownership of shared state according to: ``
shared_future tmp( other);
swap( tmp);
return * this;
``
]]
[[Throws:] [Nothing.]]
]

[member_heading shared_future..swap]

        void swap( shared_future & other) noexcept;

[variablelist
[[Effects:] [Swaps the shared state between other and `this`.]]
[[Throws:] [Nothing.]]
]

[member_heading shared_future..operator safe_bool]

        operator safe_bool() const noexcept;

[variablelist
[[Effects:] [Returns `true` if future is valid.]]
[[Throws:] [Nothing.]]
]

[operator_heading shared_future..operator_not..operator!]

        bool operator!() const noexcept;

[variablelist
[[Effects:] [Returns `false` if future is valid.]]
[[Throws:] [Nothing.]]
]

[member_heading shared_future..valid]

        bool valid() const noexcept;

[variablelist
[[Effects:] [Returns `true` if future contains a shared state.]]
[[Throws:] [Nothing.]]
]

[member_heading shared_future..get]

        R get();

[variablelist
[[Precondition:] [`true == valid()`]]
[[Effects:] [Returns the result.]]
[[Postcondition:] [`false == valid()`]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[member_heading shared_future..wait]

        void wait();

[variablelist
[[Effects:] [Waits for the result will become available.]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[template_member_heading shared_future..wait_for]

        template< class Rep, class Period >
        future_status wait_for( chrono::duration< Rep, Period > const& timeout_duration) const;

[variablelist
[[Effects:] [Waits for the result will become available or `timeout_duration` has passed.]]
[[Result:] [A `future_status` is returned indicating the reason for returning.]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[member_heading shared_future..wait_until]

        future_status wait_until( clock_type::time_point const& timeout_time) const;

[variablelist
[[Effects:] [Waits for the result will become available or `timeout_time` has passed.]]
[[Result:] [A `future_status` is returned indicating the reason for returning.]]
[[Throws:] [__future_error__ with error condition __no_state__.]]
]

[endsect]