EXPERIMENTAL A std::future-like class with more functionality.
A Future represents the results of a past or future computation. The Future API has two sides: a producer side and a consumer side.
The producer API allows creating a Future and setting its result or status, possibly after running a computation function.
The consumer API allows querying a Futureâs current state, wait for it to complete, and composing futures with callbacks.
Public Functions
Return the Futureâs current state.
A return value of PENDING is only indicative, as the Future can complete concurrently. A return value of FAILURE or SUCCESS is definitive, though.
Whether the Future is finished.
A false return value is only indicative, as the Future can complete concurrently. A true return value is definitive, though.
Returns an rvalue to the result.
This method is potentially unsafe
The future is not the unique owner of the result, copies of a future will also point to the same result. You must make sure that no other copies of the future exist. Attempts to add callbacks after you move the result will result in undefined behavior.
Future<T> is convertible to Future<>, which views only the Status of the original.
Marking the returned Future Finished is not supported.
Wait for the Future to complete.
Wait for the Future to complete, or for the timeout to expire.
true is returned if the Future completed, false if the timeout expired. Note a false value is only indicative, as the Future can complete concurrently.
Producer API: mark Future finished.
The Futureâs result is set to res.
Mark a Future<> completed with the provided Status.
Consumer API: Register a callback to run when this future completes.
The callback should receive the result of the future (const Result<T>&) For a void or statusy future this should be (const Status&)
There is no guarantee to the order in which callbacks will run. In particular, callbacks added while the future is being marked complete may be executed immediately, ahead of, or even the same time as, other callbacks that have been previously added.
WARNING: callbacks may hold arbitrary references, including cyclic references. Since callbacks will only be destroyed after they are invoked, this can lead to memory leaks if a Future is never marked finished (abandoned):
{ auto fut = Future<>::Make(); fut.AddCallback([fut]() {}); }
In this example fut falls out of scope but is not destroyed because it holds a cyclic reference to itself through the callback.
Overload of AddCallback that will return false instead of running synchronously.
This overload will guarantee the callback is never run synchronously. If the future is already finished then it will simply return false. This can be useful to avoid stack overflow in a situation where you have recursive Futures. For an example see the Loop function
Takes in a callback factory function to allow moving callbacks (the factory function will only be called if the callback can successfully be added)
Returns true if a callback was actually added and false if the callback failed to add because the future was marked complete.
Consumer API: Register a continuation to run when this future completes.
The continuation will run in the same thread that called MarkFinished (whatever callback is registered with this function will run before MarkFinished returns). Avoid long-running callbacks in favor of submitting a task to an Executor and returning the future.
Two callbacks are supported:
OnSuccess, called with the result (const ValueType&) on successful completion. for an empty future this will be called with nothing ()
OnFailure, called with the error (const Status&) on failed completion. This callback is optional and defaults to a passthru of any errors.
Then() returns a Future whose ValueType is derived from the return type of the callbacks. If a callback returns:
void, a Future<> will be returned which will completes successfully as soon as the callback runs.
Status, a Future<> will be returned which will complete with the returned Status as soon as the callback runs.
V or Result<V>, a Future<V> will be returned which will complete with the result of invoking the callback as soon as the callback runs.
Future<V>, a Future<V> will be returned which will be marked complete when the future returned by the callback completes (and will complete with the same result).
The continued Future type must be the same for both callbacks.
Note that OnFailure can swallow errors, allowing continued Futures to successfully complete even if this Future fails.
If this future is already completed then the callback will be run immediately and the returned future may already be marked complete.
See AddCallback for general considerations when writing callbacks.
Implicit constructor to create a finished future from a value.
Implicit constructor to create a future from a Result, enabling use of macros like ARROW_ASSIGN_OR_RAISE.
Implicit constructor to create a future from a Status, enabling use of macros like ARROW_RETURN_NOT_OK.
Public Static Functions
Producer API: instantiate a valid Future.
The Futureâs state is initialized with PENDING. If you are creating a future with this method you must ensure that future is eventually completed (with success or failure). Creating a future, returning it, and never completing the future can lead to memory leaks (for example, see Loop).
Producer API: instantiate a finished Future.
Make a finished Future<> with the provided Status.
If a Result<Future> holds an error instead of a Future, construct a finished Future holding that error.
Create a Future which completes when all of futures complete.
The futureâs result is a vector of the results of futures. Note that this future will never be marked âfailedâ; failed results will be stored in the result vector alongside successful results.
Create a Future which completes when all of futures complete.
The future will be marked complete if all futures complete successfully. Otherwise, it will be marked failed with the status of the first failing future.
Create a Future which completes when all of futures complete.
The future will finish with an ok status if all futures finish with an ok status. Otherwise, it will be marked failed with the status of one of the failing futures.
Unlike AllComplete this Future will not complete immediately when a failure occurs. It will wait until all futures have finished.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4