Emitter API

<amongoc/emitter.h> (header file)

<amongoc/emitter.hpp> (header file)

Contains types and functions for working with emitters

<amongoc/emitter_result.hpp> (header file)

Contains the definition of amongoc::emitter_result

Types

C Types

struct [[zero_initializable]] amongoc_emitter

amongoc_emitter is the core of the amongoc asynchronous design.

C++ API:

amongoc::unique_emitter

Header:

amongoc/emitter.h

type T

(Exposition-only for [[type(…)]]) The result type of the emitter.

type UserData

(Exposition-only for [[type(…)]]) The type contained within userdata.

See also

Our Asynchrony Model

When an amongoc_emitter return value or parameter is annotated with [[type(…)]], the attribute specifies the type that will be stored in the amongoc_box result value if the emitter resolves successfully.

amongoc_box [[type(UserData)]] userdata

Arbitrary data associated with the emitter

amongoc_emitter_vtable const *vtable

Virtual method table for the emitter.

amongoc::unique_emitter as_unique() &&

(C++) Move the emitter into an amongoc::unique_emitter to be managed automatically.

struct amongoc_emitter_vtable

Virtual method table to be used with an amongoc_emitter. The functions described below are function pointers that should be provided by the user.

Header:

amongoc/emitter.h

amongoc_operation connect(

amongoc_box [[transfer, type(UserData)]] userdata,

amongoc_handler [[transfer, type(T)]] handler,

)

Backing implementation for amongoc_emitter_connect_handler(). Connects an amongoc_emitter to the handler handler.

Parameters:

• userdata – The amongoc_emitter::userdata value.

• handler – [[type(…)]] The amongoc_handler for the operation.

Returns:

A new amongoc_operation object.

Note

It is important that the implementation of connect() call not initiate any asynchronous operations: that must be deferred until the invocation of amongoc_start() on the returned operation object.

If the returned operation object is destroyed with amongoc_operation_delete() without ever being started with amongoc_start(), then there must be no observable effect.

C++ Types

class amongoc::unique_emitter

Provides move-only ownership semantics around an amongoc_emitter, preventing programmer error and ensuring destruction if the emitter is discarded.

Header:

amongoc/emitter.hpp

unique_emitter(amongoc_emitter&&)

Take ownership of the given C emitter object.

unique_emitter(unique_emitter&&)

unique_emitter &operator=(unique_emitter&&)

The unique_emitter is a move-only type.

amongoc_emitter release() &&

Relinquish ownership of the wrapped C emitter and return it to the caller. This function is used to interface with C APIs that want to [[transfer]] an amongoc_emitter.

template<typename F>
static unique_emitter from_connector(

mlib::allocator<> alloc,

F &&fn,

)

Create an emitter from a connector function object.

Parameters:

• alloc – The allocator to use for the state.

• fn – The object must support a call signature of unique_operation(unique_handler). That is: It must be callable with a unique_handler argument and return a new unique_operation object representing the composed operation.

Returns:

A new emitter for the connected operation.

unique_operation connect(unique_handler &&[[type(T)]] hnd) &&

C API:

amongoc_emitter_connect_handler()

template<typename F>
unique_operation bind_allocator_connect(

allocator<> a,

F &&fn,

) &&

Creates an invocable object with unique_handler::from() and calls connect() with that new handler.

Parameters:

• a – The allocator to be bound with the new handler. See: The Handler-Associated Allocator

• fn – The function that implements the handler callback. Must accept an emitter_result argument.

class amongoc::emitter_result

Encapsulates the pair of status+value when an emitter completes.

Header:

amongoc/emitter_result.hpp

emitter_result() [[1]]

explicit emitter_result(amongoc_status s) [[2]]

explicit emitter_result(amongoc_status s, unique_box &&v) [[3]]

Initialize the attrributes of the emitter_result()

Overloads

1. Initializes status with amongoc_okay and value with amongoc_nil.

2. Initializes status with s and value with amongoc_nil.

3. Initializes status with s and value with v

amongoc_status status

unique_box value

The result status and result value for an emitter.

Functions & Macros

amongoc_operation amongoc_emitter_connect_handler(

amongoc_emitter [[transfer, type(T)]] em,

amongoc_handler [[transfer, type(T)]] hnd,

)

Connect an emitter with a handler. Calls amongoc_emitter_vtable::connect().

C++ API:

amongoc::unique_emitter::connect()

Header:

amongoc/emitter.h

Hint

This is a very low-level API. In general, users should be composing emitters using high-level APIs such as those in the amongoc/async.h header.

void amongoc_emitter_delete(amongoc_emitter [[transfer]] em)

Discard an unused emitter object without connecting it to anything. The associated asynchronous operation will never be launched, but associated prepared data will be freed.

C++ API:

Use amongoc::unique_emitter

Header:

amongoc/emitter.h