jh::async::listener< T > Class Template Reference

A one-shot inbox that serves as the fan-in aggregation point. More...

#include <jh/asynchronous/slot.h>

Public Types
using	value_type = T
	The type of value delivered to this listener.

Public Member Functions
bool	await_ready () const noexcept
	Check if the coroutine should resume immediately.
void	await_suspend (std::coroutine_handle<> h) noexcept
	Register coroutine handle for resumption.
T	await_resume ()
	Resume coroutine and consume the value.
template<typename... Args>
bool	invoke (Args &&... args)
	Deliver a new value to this listener.

Friends
class	slot_hub
	Enables slot_hub to create listeners.

Detailed Description

template<typename T>
class jh::async::listener< T >

A one-shot inbox that serves as the fan-in aggregation point.

Construction

A listener cannot be created directly.
It must always be constructed through slot_hub::make_listener<T>().

This restriction is intentional: a listener without an associated slot_hub is semantically meaningless. A listener's fundamental responsibilities—synchronous delivery, timed-mutex protection, and slot resumption—require a slot_hub context. Thus, its constructor is private and slot_hub acts as the factory and parent domain.

Positioning

A listener represents a single suspension point for the slot. It aggregates events coming from one or more event_signal objects and delivers them synchronously to the slot.

Fan-in Capabilities

A listener supports:

• Single-source binding: one event_signal<T> → listener<T>
• Multi-source equivalent binding: many event_signal<T> → same listener<T> (sources are indistinguishable)
• Multi-source fan-in with identification:
  • listener<std::tuple<ID, T>>
  • listener<std::tuple<ID, std::variant<T...>>>
  Sources can be distinguished inside the slot.

Inbox Semantics

• Holds at most one value.
• Value is consumed during await_resume().
• No buffering or overwriting.
• Write + resume is atomic under slot_hub mutex.
• Rejection happens only when the mutex cannot be acquired within timeout.

Template Parameters

T	Payload type delivered to the slot.

Note

A slot must only await one listener at a time. Parallel awaits violate the asynchronous semantics and are strongly discouraged.

Warning

The listener must share lifetime with its slot_hub and slot.

Member Function Documentation

await_ready()

template<typename T>

bool jh::async::listener< T >::await_ready ( ) const

inlinenodiscardnoexcept

Check if the coroutine should resume immediately.

Always returns false to suspend the coroutine.

Returns

false

await_resume()

template<typename T>

T jh::async::listener< T >::await_resume ( )

inline

Resume coroutine and consume the value.

Extracts the stored value from the inbox and clears it.

Returns

The value of type T delivered by a signal.

await_suspend()

template<typename T>

void jh::async::listener< T >::await_suspend ( std::coroutine_handle<> h )

inlinenoexcept

Register coroutine handle for resumption.

Stores the coroutine handle to resume later when value is delivered.

Parameters

h	Coroutine handle.

invoke()

template<typename T>

template<typename... Args>

bool jh::async::listener< T >::invoke ( Args &&... args )

inline

Deliver a new value to this listener.

Attempts to acquire the mutex, store the value, and resume the attached slot.

Template Parameters

Args	Constructor arguments for T.

Parameters

args	Arguments to construct the value.

Returns

true if the value was accepted and slot resumed, false otherwise.

---

The documentation for this class was generated from the following file:

• include/jh/asynchronous/slot.h