class promise_impl

Creates an empty promise without a continuation. A continuation must be assigned before the promise can be used.

Constructs the promise by taking the continuation from another promise, leaving the other promise empty.

Assigns the promise by taking the continuation from another promise, leaving the other promise empty.

Creates a promise with a continuation. If |continuation| equals nullptr then the promise is empty.

Converts from a promise holding a continuation that is assignable to to this promise's continuation type.

This is typically used to create a promise with a boxed continuation type (such as |fit::function|) from an unboxed promise produced by |fpromise::make_promise| or by combinators.

EXAMPLE

// f is a promise_impl with a complicated unboxed type auto f = fpromise::make_promise([] { ... });

// g wraps f's continuation fpromise::promise<> g = std::move(f);

Destroys the promise, releasing its continuation.

Returns true if the promise is non-empty (has a valid continuation).

Invokes the promise's continuation.

This method should be called by an executor to evaluate the promise. If the result's state is |result_state::pending| then the executor is responsible for arranging to invoke the promise's continuation again once it determines that it is possible to make progress towards completion of the promise encapsulated within the promise.

Once the continuation returns a result with status |result_state::ok| or |result_state::error|, the promise is assigned an empty continuation.

Asserts that the promise is non-empty.

Takes the promise's continuation, leaving it in an empty state. Asserts that the promise is non-empty.

Discards the promise's continuation, leaving it empty.

Assigns the promise's continuation.

Swaps the promises' continuations.

Returns an unboxed promise which invokes the specified handler function after this promise completes (successfully or unsuccessfully), passing its result.

The received result's state is guaranteed to be either |fpromise::result_state::ok| or |fpromise::result_state::error|, never |fpromise::result_state::pending|.

|handler| is a callable object (such as a lambda) which consumes the result of this promise and returns a new result with any value type and error type. Must not be null.

The handler must return one of the following types: - void - fpromise::result<new_value_type, new_error_type> - fpromise::ok<new_value_type> - fpromise::error<new_error_type> - fpromise::pending - fpromise::promise<new_value_type, new_error_type> - any callable or unboxed promise with the following signature: fpromise::result<new_value_type, new_error_type>(fpromise::context&)

The handler must accept one of the following argument lists: - (result_type&) - (const result_type&) - (fpromise::context&, result_type&) - (fpromise::context&, const result_type&)

Asserts that the promise is non-empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

auto f = fpromise::make_promise(...) .then([] (fpromise::result<int, std::string>& result) -> fpromise::result<std::string, void> { if (result.is_ok()) { printf("received value: %d\n", result.value()); if (result.value() % 15 == 0) return ::fpromise::ok("fizzbuzz"); if (result.value() % 3 == 0) return ::fpromise::ok("fizz"); if (result.value() % 5 == 0) return ::fpromise::ok("buzz"); return ::fpromise::ok(std::to_string(result.value())); } else { printf("received error: %s\n", result.error().c_str()); return ::fpromise::error(); } }) .then(...);

Returns an unboxed promise which invokes the specified handler function after this promise completes successfully, passing its resulting value.

|handler| is a callable object (such as a lambda) which consumes the result of this promise and returns a new result with any value type but the same error type. Must not be null.

The handler must return one of the following types: - void - fpromise::result<new_value_type, error_type> - fpromise::ok<new_value_type> - fpromise::error<error_type> - fpromise::pending - fpromise::promise<new_value_type, error_type> - any callable or unboxed promise with the following signature: fpromise::result<new_value_type, error_type>(fpromise::context&)

The handler must accept one of the following argument lists: - (value_type&) - (const value_type&) - (fpromise::context&, value_type&) - (fpromise::context&, const value_type&)

Asserts that the promise is non-empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

auto f = fpromise::make_promise(...) .and_then([] (const int& value) { printf("received value: %d\n", value); if (value % 15 == 0) return ::fpromise::ok("fizzbuzz"); if (value % 3 == 0) return ::fpromise::ok("fizz"); if (value % 5 == 0) return ::fpromise::ok("buzz"); return ::fpromise::ok(std::to_string(value)); }) .then(...);

Returns an unboxed promise which invokes the specified handler function after this promise completes with an error, passing its resulting error.

|handler| is a callable object (such as a lambda) which consumes the result of this promise and returns a new result with any error type but the same value type. Must not be null.

The handler must return one of the following types: - void - fpromise::result<value_type, new_error_type> - fpromise::ok<value_type> - fpromise::error<new_error_type> - fpromise::pending - fpromise::promise<value_type, new_error_type> - any callable or unboxed promise with the following signature: fpromise::result<value_type, new_error_type>(fpromise::context&)

The handler must accept one of the following argument lists: - (error_type&) - (const error_type&) - (fpromise::context&, error_type&) - (fpromise::context&, const error_type&)

Asserts that the promise is non-empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

auto f = fpromise::make_promise(...) .or_else([] (const std::string& error) { printf("received error: %s\n", error.c_str()); return ::fpromise::error(); }) .then(...);

Returns an unboxed promise which invokes the specified handler function after this promise completes (successfully or unsuccessfully), passing it the promise's result then delivering the result onwards to the next promise once the handler returns.

The handler receives a const reference, or non-const reference depending on the signature of the handler's last argument.

- Const references are especially useful for inspecting a result mid-stream without modification, such as printing it for debugging. - Non-const references are especially useful for synchronously modifying a result mid-stream, such as clamping its bounds or injecting a default value.

|handler| is a callable object (such as a lambda) which can examine or modify the incoming result. Unlike |then()|, the handler does not need to propagate the result onwards. Must not be null.

The handler must return one of the following types: - void

The handler must accept one of the following argument lists: - (result_type&) - (const result_type&) - (fpromise::context&, result_type&) - (fpromise::context&, const result_type&)

Asserts that the promise is non-empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

auto f = fpromise::make_promise(...) .inspect([] (const fpromise::result<int, std::string>& result) { if (result.is_ok()) printf("received value: %d\n", result.value()); else printf("received error: %s\n", result.error().c_str()); }) .then(...);

Returns an unboxed promise which discards the result of this promise once it completes, thereby always producing a successful result of type fpromise::result<void, void> regardless of whether this promise succeeded or failed.

Asserts that the promise is non-empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

auto f = fpromise::make_promise(...) .discard_result() .then(...);

Returns an unboxed promise which discards the value of this promise once it completes, thereby always producing a result of type fpromise::result<void, E> regardless of whether this promise succeeded or failed.

Asserts that the promise is non-empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

auto f = fpromise::make_promise(...) .discard_value() .and_then(...) .or_else(...);

Applies a |wrapper| to the promise. Invokes the wrapper's |wrap()| method, passes the promise to the wrapper by value followed by any additional |args| passed to |wrap_with()|, then returns the wrapper's result.

|Wrapper| is a type that implements a method called |wrap()| which accepts a promise as its argument and produces a wrapped result of any type, such as another promise.

Asserts that the promise is non-empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

In this example, |fpromise::sequencer| is a wrapper type that imposes FIFO execution order onto a sequence of wrapped promises.

// This wrapper type is intended to be applied to // a sequence of promises so we store it in a variable. fpromise::sequencer seq;

// This task consists of some amount of work that must be // completed sequentially followed by other work that can // happen in any order. We use |wrap_with()| to wrap the // sequential work with the sequencer. fpromise::promise<> perform_complex_task() { return fpromise::make_promise([] { /* do sequential work */ }) .then([] (fpromise::result<> result) { /* this will also be wrapped */ }) .wrap_with(seq) .then([] (fpromise::result<> result) { /* do more work */ }); }

This example can also be written without using |wrap_with()|. The behavior is equivalent but the syntax may seem more awkward.

fpromise::sequencer seq;

promise<> perform_complex_task() { return seq.wrap( fpromise::make_promise([] { /* sequential work */ }) ).then([] (fpromise::result<> result) { /* more work */ }); }

Wraps the promise's continuation into a |fit::function|.

A boxed promise is easier to store and pass around than the unboxed promises produced by |fpromise::make_promise()| and combinators, though boxing may incur a heap allocation.

It is a good idea to defer boxing the promise until after all desired combinators have been applied to prevent unnecessary heap allocation during intermediate states of the promise's construction.

Returns an empty promise if this promise is empty. This method consumes the promise's continuation, leaving it empty.

EXAMPLE

// f's is a fpromise::promise_impl<> whose continuation contains an // anonymous type (the lambda) auto f = fpromise::make_promise([] {});

// g's type will be fpromise::promise<> due to boxing auto boxed_f = f.box();

// alternately, we can get exactly the same effect by assigning // the unboxed promise to a variable of a named type instead of // calling box() fpromise::promise<> boxed_f = std::move(f);