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);