Skip to content

concurencpp::future

Jump to bottom
David Haim edited this page Dec 14, 2017 · 11 revisions

General notes:

  1. All memory allocations done from this object are from and to a memory pool for better performance.
  2. Synchronization is done on this object using a fast recursive spinlock instead of the heavy std::mutex

changes from the standard:

  1. this future doesn't block on destruction. if the futuristic value/exception isn't extracted via get() / then() / co_await, it's lost.
  2. this future doesn't exhibit any undefined behavior when "empty". if this future doesn't hold any sate and is accessed, it will throw std::future_error exception.
  3. this future supports the future::then method.
  4. this future supports co_await operations.

Method description:

future() noexcept = default;

Default constructor. builds empty future with no associated state. this future can be "filled" by assigning non empty future to it.

May throw:
This method never throws.

Return Value:
this method doesn't return any value.

future(future&& rhs) noexcept = default;

Move constructor. transfers the associated state of rhs into this future, leaving rhs empty.

May throw:
This method never throws.

Return Value:
this method doesn't return any value.

future& operator = (future&& rhs) noexcept = default;

Move assignment operator. transfers the associated state of rhs into this future, leaving rhs empty. if *this holds an associated state, it's deleted and lost (as the associated state is reference-counted, it's still valid to set an asynchronous value/exception to it by the equivilant concurrencpp::promise).

May throw:
This method never throws.

Return Value:
return *this

bool valid() const noexcept

Checks if *this holds an associated state. if so, one can call get,wait,wait_for,then and co_await safety on the future. if not, an std::future_error is thrown.

May throw:
This method never throws.

Return Value:
true if *thisholds an associated state,false` otherwise.

void wait()

Waits for the asynchronous result or exception to be set. if *this refers to a deferred task (by calling concurrencpp::async with the right flag), it is executed synchronously. if the asynchronous result or exception are not set yet, the calling thread blocks until one of them is set. if the asynchronous result or exceptions is set, the function returns immediately.

May throw:

  • std::future_error if *this doesn't hold an associated state.
  • std::system_error if the underlying std::condition_variable could not be awaited on.
  • if *this refers to some deferred task, any exception that may be thrown from that task.

Return Value:
this method doesn't return any value.

template<class duration_unit, class ratio>
::std::future_status wait_for(std::chrono::duration<duration_unit, ratio> duration) const

Waits for the asynchronous result or exception to be set for a period of duration.

  • if *this refers to a deferred task (by calling concurrencpp::async with the right flag), the function immediately returns ::std::future_status::deferred.
  • if the asynchronous value/exception is already set, the function immediately returns ::std::future_status::ready
  • if the asynchronous result or exception are not set yet, the calling thread blocks for a maximum period of duration. If within that time, the asynchronous value/exception is set, the function returns early with the value of ::std::future_status::ready. otherwise, the function blocks for a period of duration and eventually returns the value of std::future_status::timeout.

May throw:

  • std::future_error if *this doesn't hold an associated state.
  • std::system_error if the underlying std::condition_variable could not be awaited on.

Return Value:
any of the possible values of ::std::future_status.

template <class clock, class duration>
std::future_status wait_until(const std::chrono::time_point<clock, duration>& timeout_time) const

Waits for the asynchronous result or exception to be set until timeout_time is reached.

  • if *this refers to a deferred task (by calling concurrencpp::async with the right flag), the function immediately returns ::std::future_status::deferred.
  • if the asynchronous value/exception is already set, the function immediately returns ::std::future_status::ready
  • if the asynchronous result or exception are not set yet, the calling thread blocks until timeout_time is reached or an asynchronous value/exception is set. If within that time, the asynchronous value/exception is set, the function returns early with the value of ::std::future_status::ready. otherwise, the function until timeout_time is reached and eventually returns the value of std::future_status::timeout.

May throw:

  • std::future_error if *this doesn't hold an associated state.
  • std::system_error if the underlying std::condition_variable could not be awaited on.

Return Value:
any of the possible values of ::std::future_status.

T get()

Returns the asynchronous value, if exists. re-throws the asynchronous exception, if exists. blocks until an asynchronous value or exception is set, otherwise.

  • if *this refers to a deferred task (by calling concurrencpp::async with the right flag), the function executes the deferred task synchronously, returning its value, or letting an exception to propagate to the calling thread.
  • if the asynchronous value/exception is already set, the function immediately returns it by using move semantics.
  • if the asynchronous result or exception are not set yet, the calling thread blocks until one of them is set. then the function returns the asynchronous value if exists, or re-throws the asynchronous exception otherwise.

May throw:

  • std::future_error if *this doesn't hold an associated state.
  • std::system_error if the underlying std::condition_variable could not be awaited on.
  • if *this refers to some deferred task, any exception that may be thrown from that task.

Return Value:
the asynchronous value.

Clone this wiki locally