mirror of
https://github.com/boostorg/fiber.git
synced 2026-02-02 20:52:21 +00:00
382 lines
9.2 KiB
Plaintext
382 lines
9.2 KiB
Plaintext
[/
|
|
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]
|