libunifex Documentation

async_pass (and nothrow_async_pass) provides a rendezvous point for synchronized cross-scheduler calls between a caller (producer) and an acceptor (consumer). Unlike a 1-element queue, the caller is guaranteed that the acceptor was ready and has accepted the call.

Key Concepts

• Arguments: Args... defines the value types of the sender returned by async_accept().
• nothrow_async_pass: Does not provide try_throw() or async_throw() and requires argument types to be nothrow (copy/move) constructible.
• Lifetime Requirement: Arguments passed to async_call() MUST NOT go out of scope until the resulting sender has started. In coroutines, this is handled by co_awaiting the sender immediately.

API Reference

• async_call(auto&&... args): Passes data to the acceptor. Completes when the acceptor accepts or is cancelled.
• async_call(auto&& fn): Deferred version. fn is a callback activated at rendezvous.
• async_throw(ex): Passes an exception to the acceptor.
• async_accept(): Completes when a caller calls async_call() or try_call().
• try_call(args...): Synchronously completes the rendezvous if an acceptor is waiting.
• try_call(fn): Deferred synchronous version.
• try_throw(ex): Synchronously passes an exception to an awaiting acceptor.
• try_accept(): Synchronously completes the rendezvous by returning data or throwing if a caller is waiting.
• try_accept(fn): Deferred synchronous version.
• is_idle(): Returns true if no one is awaiting.
• is_expecting_call(): Returns true if an acceptor is awaiting.
• is_expecting_accept(): Returns true if a caller is awaiting.

template <typename... Args> class async_pass;
template <typename... Args> class nothrow_async_pass;

// Example of a lifetime error to avoid:
auto sender = pass.async_call(Request{});
// Temporary Request{} is destroyed, but sender kept a reference to it
co_await std::move(sender);

In libunifex, type-erased wrappers use V-Tables to manage polymorphic behavior without standard C++ inheritance. A V-Table is constructed from a set of CPOs (Customization Point Objects) and consists of function pointers for each CPO.

Core Components

• unifex::detail::vtable_entry<CPO>: An individual entry in a V-Table holding a function pointer that type-erases a specific CPO implementation.
• unifex::detail::vtable<CPOs...>: An ordered collection of vtable_entry objects.

CPO Signature Requirements

To use a CPO in a V-Table, the CPO must define a type_erased_signature_t. This signature must be a function type containing exactly one argument that is either a unifex::this_ type (or a cv-qualified version) or an lvalue/xvalue reference to such a type.

Example CPO definition:

struct my_cpo {
  using type_erased_signature_t = void(const unifex::this_&, float, bool);
};

When a vtable_entry is invoked, it internally casts a void* (the managed object) back to the concrete type and replaces the unifex::this_ parameter with a reference to that concrete object.

Unifex uses a generic stop_token_concept to support the cancellation of asynchronous operations. A stop-token is passed to an operation to allow a request for that operation to stop executing (e.g., when its result is no longer needed).

Unlike standard C++20 std::stop_token, Unifex uses a concept-based approach to allow for more efficient implementations, such as avoiding heap allocation or reference counting in structured concurrency scenarios.

Key requirements for a type to satisfy stop_token_concept:

• Must be std::copyable and support no-throw copy/move construction.
• Must provide a nested template type alias: typename T::template callback_type<CallbackArchetype>.
• Must provide stop_requested() and stop_possible() methods that are noexcept.
• The callback_type must be destructible and support no-throw construction from the token and a callback archetype.

Note on std::stop_token compatibility: Currently, std::stop_token does not satisfy the Unifex stop_token_concept because it lacks the required nested callback_type template type alias.

namespace unifex
{
  struct __stop_token_callback_archetype {
    // These have no definitions.
    __stop_token_callback_archetype() noexcept;
    __stop_token_callback_archetype(__stop_token_callback_archetype&&) noexcept;
    __stop_token_callback_archetype(const __stop_token_callback_archetype&) noexcept;
    ~__stop_token_callback_archetype();
    void operator()() noexcept;
  };

  template<typename T>
  concept stop_token_concept = 
    std::copyable<T> &&
    std::is_nothrow_copy_constructible_v<T> &&
    std::is_nothrow_move_constructible_v<T> &&
    requires(const T token) {
      typename T::template callback_type<__stop_token_callback_archetype>;
      { token.stop_requested() ? (void)0 : (void)0 } noexcept;
      { token.stop_possible() ? (void)0 : (void)0 } noexcept;
    } &&
    std::destructible<
      typename T::template callback_type<__stop_token_callback_archetype>> &&
    std::is_nothrow_constructible_v(
      typename T::template callback_type<__stop_token_callback_archetype>,
      T, __stop_token_callback_archetype) &&
    std::is_nothrow_constructible_v(
      typename T::template callback_type<__stop_token_callback_archetype>,
      const T&, __stop_token_callback_archetype);
}

Libunifex provides several scheduler implementations for different concurrency needs:

A TypedSender is a Sender that provides nested template type-aliases to allow consumers to query the specific overloads of set_value() and set_error() it may call on a Receiver.

To implement a TypedSender, you must define:

• value_types: A template alias taking a Variant and a Tuple template. It produces a type representing all possible set_value call signatures.
• error_types: A template alias taking a Variant template. It produces a type representing all possible set_error call signatures.
• sends_done: A static constexpr bool indicating if the sender might call set_done().

When querying these properties, use unifex::sender_traits<Sender> rather than accessing the sender type directly.

struct some_typed_sender {
 template<template<typename...> class Variant,
          template<typename...> class Tuple>
 using value_types = Variant<Tuple<int>,
                             Tuple<std::string, int>,
                             Tuple<>>;

 template<template<typename...> class Variant>
 using error_types = Variant<std::exception_ptr>;

 static constexpr bool sends_done = true;
 ...
};

// To query:
// typename unifex::sender_traits<Sender>::template value_types<std::variant, std::tuple>