Base module

provides classes and functions to create continuable_base objects.

Contents

Classes

template<typename Data, typename Annotation>
class cti::continuable_base
The main class of the continuable library, it provides the functionality for chaining callbacks and continuations together to a unified hierarchy.
template<typename Data, typename Hint>
class cti::promise_base
The promise_base makes it possible to resolve an asynchronous continuable through it's result or through an error type.

Typedefs

using dispatch_error_tag = detail::types::dispatch_error_tag
Represents a tag which can be placed first in a signature in order to overload callables with the asynchronous result as well as an error.
using error_type = detail::types::error_type
Represents the type that is used as error type.
template<typename T>
using is_continuable = detail::base::is_continuable<T>
Deduces to a true_type if the given type is a continuable_base.

Functions

template<typename... Args, typename Continuation>
auto make_continuable(Continuation&& continuation) -> auto constexpr
Creates a continuable_base from a promise/callback taking function.
template<typename... Args>
auto make_ready_continuable() -> auto constexpr
Returns a continuable_base with no result which instantly resolves the promise with no values.
template<typename Result>
auto make_ready_continuable(Result&& result) -> auto constexpr
Returns a continuable_base with one result value which instantly resolves the promise with the given value.
template<typename FirstResult, typename SecondResult, typename... Rest>
auto make_ready_continuable(FirstResult&& first_result, SecondResult&& second_result, Rest&&... rest) -> auto constexpr
Returns a continuable_base with multiple result values which instantly resolves the promise with the given values.
template<typename... Signature, typename Exception>
auto make_exceptional_continuable(Exception&& exception) -> auto constexpr
Returns a continuable_base with the parameterized result which instantly resolves the promise with the given error type.

Typedef documentation

using dispatch_error_tag = detail::types::dispatch_error_tag

Represents a tag which can be placed first in a signature in order to overload callables with the asynchronous result as well as an error.

See the example below:

struct my_callable {
  void operator() (std::string result) {
    // ...
  }
  void operator() (cti::dispatch_error_tag, cti::error_type) {
    // ...
  }
};

// Will receive errors and results
continuable.next(my_callable{});

using error_type = detail::types::error_type

Represents the type that is used as error type.

By default this type deduces to std::exception_ptr. If CONTINUABLE_WITH_NO_EXCEPTIONS is defined the type will be a std::error_condition. A custom error type may be set through defining CONTINUABLE_WITH_CUSTOM_ERROR_TYPE.

template<typename T>
using is_continuable = detail::base::is_continuable<T>

Deduces to a true_type if the given type is a continuable_base.

Function documentation

template<typename... Args, typename Continuation>
auto make_continuable(Continuation&& continuation) constexpr

Creates a continuable_base from a promise/callback taking function.

Template parameters
Args

The types (signature hint) the given promise is resolved with.

  • Some arguments indicate the types the promise will be invoked with.

    auto ct = cti::make_continuable<int, std::string>([](auto&& promise) {
  promise.set_value(200, "<html>...</html>");
});

  • void as argument indicates that the promise will be invoked with no arguments:

    auto ct = cti::make_continuable<void>([](auto&& promise) {
  promise.set_value();
});

  • No arguments Since version 3.0.0 make_continuable always requires to be given valid arguments! You should always give the type hint a callback is called with because it's required for intermediate actions like connecting continuables. You may omit the signature hint if you are erasing the type of the continuable right after creation.

    // This won't work because the arguments are missing:
auto ct = cti::make_continuable([](auto&& promise) {
  promise.set_value(0.f, 'c');
});

// However, you are allowed to do this:
cti::continuable<float, char> ct = [](auto&& promise) {
  promise.set_value(callback)(0.f, 'c');
};
Continuation
Parameters
continuation

The continuation the continuable is created from. The continuation must be a callable type accepting a callback parameter which represents the object invokable with the asynchronous result of this continuable.

auto ct = cti::make_continuable<std::string>([](auto&& promise) {
  promise.set_value("result");
});

The callback may be stored or moved. In some cases the callback may be copied if supported by the underlying callback chain, in order to invoke the call chain multiple times. It's recommended to accept any callback instead of erasing it.

// Good practice:
auto ct = cti::make_continuable<std::string>([](auto&& promise) {
  promise.set_value("result");
});

// Good practice using a callable object:
struct Continuation {
  template<typename T>
  void operator() (T&& continuation) && {
    // ...
  }
}

auto ct = cti::make_continuable<std::string>(Continuation{});

// Bad practice (because of unnecessary type erasure):
auto ct = cti::make_continuable<std::string>(
  [](cti::promise<std::string> promise) {
    promise.set_value("result");
  });
Returns A continuable_base with unspecified template parameters which wraps the given continuation. In order to convert the continuable_base to a known type you need to apply type erasure through the continuable or promise facilities.

template<typename... Args>
auto make_ready_continuable() constexpr

Returns a continuable_base with no result which instantly resolves the promise with no values.

template<typename Result>
auto make_ready_continuable(Result&& result) constexpr

Returns a continuable_base with one result value which instantly resolves the promise with the given value.

template<typename FirstResult, typename SecondResult, typename... Rest>
auto make_ready_continuable(FirstResult&& first_result, SecondResult&& second_result, Rest&&... rest) constexpr

Returns a continuable_base with multiple result values which instantly resolves the promise with the given values.

template<typename... Signature, typename Exception>
auto make_exceptional_continuable(Exception&& exception) constexpr

Returns a continuable_base with the parameterized result which instantly resolves the promise with the given error type.

Template parameters
Signature The fake signature of the returned continuable.
Exception

See an example below:

std::logic_error exception("Some issue!");
auto ptr = std::make_exception_ptr(exception);
auto ct = cti::make_exceptional_continuable<int>(ptr);