|
|
|
The future status of a scheduled asynchronous operation. More...
Public Member Functions | |
| future (dispatcher *parent, size_t id, shared_future< handle_ptr > handle, stl_future< T > result, bool check_handle=true, bool validate=true) | |
| future (future< void > &&o, stl_future< T > &&result) | |
| bool | valid (bool just_handle=false) const noexcept |
| True if this future is valid. | |
| T | get () |
| Waits for the future to become ready, returning any value or rethrowing any exception found. Throws a `future_errc::no_state` if this future is invalid. | |
| template<class U > | |
| auto | then (U &&f)-> typename detail |
| Schedules a callable to be invoked after this future becomes ready. If this future is null, use the current async file i/o dispatcher. | |
The future status of a scheduled asynchronous operation.
| T | Any returned result. Note this is defaulted to `void` for you, so usually you write `future<>`. As of v1.4 of the AFIO engine, the legacy `async_io_op` struct has been replaced with this custom future type based on the lightweight future-promise factory toolkit in forthcoming Boost.Monad. This custom future type consists of two pieces of future data each with different semantics: |
1. A `handle_ptr` retrieved using `get_handle()`, `operator*` and `operator->` - this is the shared i/o handle returned by the asynchronous operation. This has non-consuming semantics i.e. you can call `get_handle()` as many times as you like. Note that for legacy compatibility reasons, calling `get_handle()` on an invalid instance returns a null shared pointer instead of an exception throw.
2. If T is non-void, any type `T` - this is any additional data returned by an asynchronous operation above and beyond the i/o handle (e.g. `enumerate()` returns a `std::pair<std::vector<directory_entry>, bool>`. This has *consuming* semantics, so calling `get()` returns the result exactly once.
The reason for the difference in semantics is because it is very common that you need access to an earlier i/o handle in a sequence if some operation returns an error, and besides the shared pointer encapsulation makes non-consumption cost free.
Other than the fact that `get()` returns a `T` and `get_handle()` returns a handle, the errored and excepted state for both is identical and non-consuming for both.
Finally, note that there is a freely available type slice from `future<T>` to `future<void>` which moves/copies only the `future<void>` part of the `future<T>`, leaving the `T` behind. This is because the AFIO engine resides behind a stable ABI layer which cannot know anything about arbitrary types, and therefore it accepts only `future<void>`. Equally, this means you can supply a `future<T>` as a precondition to another op safe in the knowledge that any `T` part will remain untouched for later consumption.
| boost::afio::future< T >::future | ( | dispatcher * | parent, |
| size_t | id, | ||
| shared_future< handle_ptr > | handle, | ||
| stl_future< T > | result, | ||
| bool | check_handle = true, |
||
| bool | validate = true |
||
| ) |
Constructs an instance.
| parent | The dispatcher this op belongs to. |
| id | The unique non-zero id of this op. |
| handle | A shared_future to shared state between all instances of this reference. |
| result | A future to any result from the operation. |
| check_handle | Whether to have validation additionally check if a handle is not null |
| validate | Whether to check the inputs and shared state for valid (and not errored) values |
| boost::afio::future< T >::future | ( | future< void > && | o, |
| stl_future< T > && | result | ||
| ) |
Constructs an instance from an existing future<void>
| o | The future<void> |
| result | The future<T> to add |
| bool boost::afio::future< T >::valid | ( | bool | just_handle = false | ) | const |
| T boost::afio::future< T >::get | ( | ) |
|
January, 2014 |
Copyright © 2013-2014 Niall Douglas, Cork, Ireland Copyright © 2013 Paul Kirth, California |