Async<T> is a container for coroutine-safe asynchronous read/write. More...

#include <async.hpp>

Public Types
using	value_type = T

Public Member Functions
	Async ()
	Initializes async state without constructing the stored value.

template<typename... Args> requires (std::constructible_from<T, Args...> && !is_async_alias_v<T>)
	Async (Args &&... args)
	Construct the stored value in place using forwarded arguments.

	Async (Async &&other) noexcept=default
	Move-construct from another Async<T> handle.

	Async (Async const &)=delete
	Forbid copying an independent async value whose payload cannot be copy-constructed.

	Async (Async const &rhs)
	Construct a new Async<T> by copying the value from another Async<T>.

	Async (Async const &rhs)
	Structurally copy an async alias handle.

	Async (async_do_not_start_t tag)
	Initializes async state without constructing the stored value or starting the queue.

template<typename U , typename... Args> requires (std::constructible_from<T, std::initializer_list<U>&, Args...> && !is_async_alias_v<T>)
	Async (std::initializer_list< U > init, Args &&... args)
	Construct the stored value in place from an initializer list.

template<typename U > requires (std::constructible_from<T, U> && (!std::convertible_to<U, T>) && !is_async_alias_v<T>)
	Async (U &&u)
	Explicitly construct from a value that requires explicit conversion.

template<typename U > requires (std::convertible_to<U, T> && !is_async_alias_v<T>)
	Async (U &&val)
	Construct from a value convertible to T.

Async &	debug_name (std::string const &label)
	Assign an optional debug label for task-registry graph output.

Async const &	debug_name (std::string const &label) const
	Assign an optional debug label for task-registry graph output.

T const &	get_wait () const
	Block the current thread until the value becomes available.

T const &	get_wait (IAsyncScheduler &sched) const
	Block using an explicit scheduler until the value is ready.

T	move_from_wait ()
	Block until the value is available, then move it out of the Async.

Async &	operator= (Async &&)=delete
	Forbid assignment to a read-only async alias.

Async &	operator= (Async &&other)
	Assign through a mutable async alias from an exact-type rvalue alias.

Async &	operator= (Async &&other) noexcept
	Rebind an independent async value from another Async<T> handle.

Async &	operator= (Async const &)=delete
	Forbid copy assignment when an independent payload cannot be copy-constructed.

Async &	operator= (Async const &)=delete
	Forbid assignment to a read-only async alias.

Async &	operator= (Async const &rhs)
	Copy-assign from another Async<T>, overwriting this instance's value timeline.

Async &	operator= (Async const &rhs)
	Assign through a mutable async alias from another exact-type alias.

template<typename U > requires detail::async_assignment_source<T, U>
Async &	operator= (U &&rhs)
	Assign an immediate or heterogeneous async value.

template<typename U > requires detail::async_assignment_source<T, U>
Async< T > &	operator= (U &&rhs)

EpochQueue const &	queue () const
	Inspect the shared epoch queue.

ReadBuffer< T >	read () const
	Begin an asynchronous read of the value.

shared_storage< T > const &	storage () const
	Access the shared storage control block.

T const *	storage_address () const noexcept
	Return the const address reserved for the contained value when constructing an alias descriptor.

T *	storage_address () noexcept
	Return the address reserved for the contained value when constructing an alias descriptor.

void	unsafe_set (T const &x)
	Overwrite the stored value directly.

T	unsafe_value () const
	Return a copy of the stored value.

T &	unsafe_value_ref ()
	Access the stored value without synchronization.

T const &	unsafe_value_ref () const
	Access the stored value without synchronization.

std::shared_ptr< T >	value_ptr ()
	Access the mutable stored value pointer with shared ownership semantics.

std::shared_ptr< T const >	value_ptr () const
	Access the const stored value pointer with shared ownership semantics.

void	wait () const
	Block the current thread until the value becomes available.

void	wait (IAsyncScheduler &sched) const
	Block using an explicit scheduler until the value is ready.

WriteBuffer< T >	write ()
	Begin exclusive asynchronous access to the payload.

	~Async ()=default

Friends
template<typename Alias , typename Parent , typename... Args>
Async< Alias >	make_async_alias (Async< Parent > const &parent, Args &&... args)
	Construct an async alias that retains a parent value and shares its epoch queue.

template<typename Alias , typename Parent , typename... Args>
Async< Alias >	make_async_alias_from_parent (Async< Parent > &parent, Args &&... args)
	Construct an async alias from a mutable parent descriptor.

template<typename Alias , typename Parent , typename... Args>
Async< Alias >	make_async_alias_from_parent (Async< Parent > const &parent, Args &&... args)
	Construct a read-only async alias from a parent descriptor.

class	ReverseValue< T >

Detailed Description

template<typename T>
class uni20::async::Async< T >

Async<T> is a container for coroutine-safe asynchronous read/write.

Async<T> stores a value of type T and mediates access through epoch-based coordination. The value, queue, and individual epoch contexts use shared ownership where required. Buffer handles retain their storage and selected epoch context, so they may outlive the owning Async container.

Note: Copy construction is a value-level operation by default. Types for which is_async_alias_v<T> is true copy the storage handle, lifetime owner, and dependency timeline instead.; Buffers maintain shared ownership of the internal state, so ReadBuffer<T> and WriteBuffer<T> may safely outlive the Async.; T need not be default-constructible, copyable, or movable. Individual operations participate only when their required construction or assignment expressions are available.

Template Parameters

T	Stored value type.

Member Typedef Documentation

◆ value_type

template<typename T >

using uni20::async::Async< T >::value_type = T

Constructor & Destructor Documentation

◆ Async() [1/10]

template<typename T >

uni20::async::Async< T >::Async ( )

inline

Initializes async state without constructing the stored value.

◆ Async() [2/10]

template<typename T >

uni20::async::Async< T >::Async ( async_do_not_start_t tag )

inline

Initializes async state without constructing the stored value or starting the queue.

Parameters

tag	Sentinel tag selecting non-starting construction.

◆ Async() [3/10]

template<typename T >

template<typename U >
requires (std::convertible_to<U, T> && !is_async_alias_v<T>)

uni20::async::Async< T >::Async ( U && val )

inline

Construct from a value convertible to T.

Template Parameters

U	Value type convertible to T.

Parameters

val	Initial value forwarded into the Async storage.

◆ Async() [4/10]

template<typename T >

template<typename U >
requires (std::constructible_from<T, U> && (!std::convertible_to<U, T>) && !is_async_alias_v<T>)

uni20::async::Async< T >::Async ( U && u )

inlineexplicit

Explicitly construct from a value that requires explicit conversion.

Template Parameters

U	Source type that can explicitly construct T.

Parameters

u	Value forwarded to construct the stored T instance.

◆ Async() [5/10]

template<typename T >

template<typename... Args>
requires (std::constructible_from<T, Args...> && !is_async_alias_v<T>)

uni20::async::Async< T >::Async ( Args &&... args )

inline

Construct the stored value in place using forwarded arguments.

Template Parameters

Args	Argument types forwarded to `T`'s constructor.

Parameters

args	Arguments used to initialize the contained value.

◆ Async() [6/10]

template<typename T >

template<typename U , typename... Args>
requires (std::constructible_from<T, std::initializer_list<U>&, Args...> && !is_async_alias_v<T>)

uni20::async::Async< T >::Async	(	std::initializer_list< U >	init,
		Args &&...	args
	)

inline

Construct the stored value in place from an initializer list.

Template Parameters

U	Element type accepted by `T`'s initializer list constructor.
Args	Additional argument types forwarded to `T`'s constructor.

Parameters

init	Initializer list forwarded to `T`.
args	Additional arguments forwarded to `T`.

Note: This mirrors similar constructors where std::in_place is used.

◆ Async() [7/10]

template<typename T >

uni20::async::Async< T >::Async ( Async< T > const & rhs )

inline

Construct a new Async<T> by copying the value from another Async<T>.

Note: This constructor schedules a coroutine that reads the current or eventual value of rhs and writes it into the initial epoch of the newly constructed *this.

Warning: This is not a structural copy — it does not replicate the state or dependencies of rhs. Coroutine handles, epoch queues, and computation histories are not copied.

See also: async_assign for explicit value-level copy scheduling.

◆ Async() [8/10]

template<typename T >

uni20::async::Async< T >::Async ( Async< T > const & )

delete

Forbid copying an independent async value whose payload cannot be copy-constructed.

◆ Async() [9/10]

template<typename T >

uni20::async::Async< T >::Async ( Async< T > const & rhs )

inline

Structurally copy an async alias handle.

Alias copies retain the same descriptor storage, lifetime owner, and epoch queue.

◆ Async() [10/10]

template<typename T >

uni20::async::Async< T >::Async ( Async< T > && other )

defaultnoexcept

Move-construct from another Async<T> handle.

Note: Move construction always transfers the handle. Independent-value move assignment also transfers the handle; alias move assignment remains write-through so an established alias is never retargeted.

Parameters

other Source Async.

◆ ~Async()

template<typename T >

uni20::async::Async< T >::~Async ( )

default

Member Function Documentation

◆ debug_name() [1/2]

template<typename T >

Async & uni20::async::Async< T >::debug_name ( std::string const & label )

inline

Assign an optional debug label for task-registry graph output.

Parameters

label Human-readable label used only by debug diagnostics.

Returns: Reference to this async value for call chaining.

◆ debug_name() [2/2]

template<typename T >

Async const & uni20::async::Async< T >::debug_name ( std::string const & label ) const

inline

Assign an optional debug label for task-registry graph output.

Parameters

label Human-readable label used only by debug diagnostics.

Returns: Constant reference to this async value for call chaining.

◆ get_wait() [1/2]

template<typename T >

T const & uni20::async::Async< T >::get_wait ( ) const

Block the current thread until the value becomes available.

Waits for the latest readable value and returns a const reference.

Returns: Reference to the stored value once the pending writers have completed.

Template Parameters

T	Async value type.

Returns: Reference to the materialized value.

◆ get_wait() [2/2]

template<typename T >

T const & uni20::async::Async< T >::get_wait ( IAsyncScheduler & sched ) const

Block using an explicit scheduler until the value is ready.

Waits for the latest readable value using an explicit scheduler.

The scheduler will be driven until all pending writers complete, then the value reference is returned. This overload is useful for deterministic execution in tests where the scheduling context must be controlled.

Parameters

sched Scheduler instance used to make progress while waiting.

Returns: Reference to the stored value once writes have finished.

Template Parameters

T	Async value type.

Parameters

sched Scheduler used to drive pending work.

Returns: Reference to the materialized value.

◆ move_from_wait()

template<typename T >
requires (!is_async_alias_v<T> && std::constructible_from<T, T &&>)

T uni20::async::Async< T >::move_from_wait ( )

Block until the value is available, then move it out of the Async.

Waits for write access and moves the current value out.

Returns: The stored value, moved out of the Async container.

Template Parameters

T	Async value type.

Returns: Moved value extracted from storage.

◆ operator=() [1/9]

template<typename T >

Async & uni20::async::Async< T >::operator= ( Async< T > && )

delete

Forbid assignment to a read-only async alias.

◆ operator=() [2/9]

template<typename T >

Async & uni20::async::Async< T >::operator= ( Async< T > && other )

inline

Assign through a mutable async alias from an exact-type rvalue alias.

Parameters

other Alias whose referenced value is the assignment source.

Returns: Reference to this alias.

◆ operator=() [3/9]

template<typename T >

Async & uni20::async::Async< T >::operator= ( Async< T > && other )

inlinenoexcept

Rebind an independent async value from another Async<T> handle.

Parameters

other Source Async.

Returns: Reference to *this after ownership transfer.

◆ operator=() [4/9]

template<typename T >

Async & uni20::async::Async< T >::operator= ( Async< T > const & )

delete

Forbid copy assignment when an independent payload cannot be copy-constructed.

◆ operator=() [5/9]

template<typename T >

Async & uni20::async::Async< T >::operator= ( Async< T > const & )

delete

Forbid assignment to a read-only async alias.

◆ operator=() [6/9]

template<typename T >

Async & uni20::async::Async< T >::operator= ( Async< T > const & rhs )

inline

Copy-assign from another Async<T>, overwriting this instance's value timeline.

Note: This operator first resets the internal epoch queue of *this by move-assigning a fresh Async<T>. It then schedules a coroutine that awaits rhs and writes its result to *this.

Warning: This operation does not preserve prior epochs or dependencies of *this. If you wish to serialize with prior writes, use async_assign(*this, rhs) directly.

Async<T> x, y;
x = y;              // copies value from y into x, resets x's causal history
 
x = Async<T>{};     // explicitly reset x
async_assign(x, y); // equivalent to copy-assignment

See also: Async::operator=(Async&&) for independent-value move rebinding; async_assign for explicit value-copy semantics

Parameters

rhs	Source Async whose value timeline is copied.

Returns: Reference to *this after scheduling the copy.

◆ operator=() [7/9]

template<typename T >

Async & uni20::async::Async< T >::operator= ( Async< T > const & rhs )

inline

Assign through a mutable async alias from another exact-type alias.

The destination descriptor, owner, and queue remain unchanged.

Parameters

rhs	Alias whose referenced value is the assignment source.

Returns: Reference to this alias.

◆ operator=() [8/9]

template<typename T >

template<typename U >
requires detail::async_assignment_source<T, U>

Async & uni20::async::Async< T >::operator= ( U && rhs )

Assign an immediate or heterogeneous async value.

Independent values detach onto fresh storage and a fresh epoch queue. Async aliases retain their descriptor, owner, and queue, and participate only when ADL finds a matching assign_through operation. Read-only aliases therefore have no assignment.

Template Parameters

U	Immediate value or heterogeneous async source type.

Parameters

rhs	Source expression.

Returns: Reference to this async handle.

◆ operator=() [9/9]

template<typename T >

template<typename U >
requires detail::async_assignment_source<T, U>

Async< T > & uni20::async::Async< T >::operator= ( U && rhs )

◆ queue()

template<typename T >

EpochQueue const & uni20::async::Async< T >::queue ( ) const

inline

Inspect the shared epoch queue.

Parent values and aliases share this exact mutable queue. Individual buffers retain their selected epoch contexts.

Returns: Access to the epoch queue implementation.

◆ read()

template<typename T >

ReadBuffer< T > uni20::async::Async< T >::read ( ) const

inline

Begin an asynchronous read of the value.

Returns: A ReadBuffer<T> which may be co_awaited.

◆ storage()

template<typename T >

shared_storage< T > const & uni20::async::Async< T >::storage ( ) const

inline

Access the shared storage control block.

Returns: Shared storage object for the contained value.

◆ storage_address() [1/2]

template<typename T >

T const * uni20::async::Async< T >::storage_address ( ) const

inlinenoexcept

Return the const address reserved for the contained value when constructing an alias descriptor.

Warning: The pointer does not grant synchronized access and must not be dereferenced outside an active buffer. It may identify reserved but unconstructed storage.

Returns: Const address reserved for the contained value.

◆ storage_address() [2/2]

template<typename T >

T * uni20::async::Async< T >::storage_address ( )

inlinenoexcept

Return the address reserved for the contained value when constructing an alias descriptor.

Warning: The pointer does not grant synchronized access and must not be dereferenced outside an active buffer. It may identify reserved but unconstructed storage.

Returns: Mutable address reserved for the contained value.

◆ unsafe_set()

template<typename T >

void uni20::async::Async< T >::unsafe_set ( T const & x )

inline

Overwrite the stored value directly.

Intended for debugging and test scaffolding where a synchronous update is acceptable. No synchronization with pending writers or readers is performed.

Parameters

x	New value to store.

◆ unsafe_value()

template<typename T >

T uni20::async::Async< T >::unsafe_value ( ) const

inline

Return a copy of the stored value.

This helper is primarily for diagnostics; it will throw if the value has not been initialized.

Returns: Copy of the contained value.

◆ unsafe_value_ref() [1/2]

template<typename T >

T & uni20::async::Async< T >::unsafe_value_ref ( )

inline

Access the stored value without synchronization.

Returns: Mutable reference to the stored value for diagnostic use.

◆ unsafe_value_ref() [2/2]

template<typename T >

T const & uni20::async::Async< T >::unsafe_value_ref ( ) const

inline

Access the stored value without synchronization.

Returns: Direct reference to stored value (for diagnostics only).

◆ value_ptr() [1/2]

template<typename T >

std::shared_ptr< T > uni20::async::Async< T >::value_ptr ( )

inline

Access the mutable stored value pointer with shared ownership semantics.

This overload is unavailable for not_assignable aliases.

The returned pointer retains the shared_storage control block so that the lifetime of the referenced value is tied to the same shared ownership as the Async container itself.

Returns: Mutable pointer retaining the shared_storage control block.

◆ value_ptr() [2/2]

template<typename T >

std::shared_ptr< T const > uni20::async::Async< T >::value_ptr ( ) const

inline

Access the const stored value pointer with shared ownership semantics.

Returns: Const pointer retaining the shared_storage control block.

◆ wait() [1/2]

template<typename T >

void uni20::async::Async< T >::wait ( ) const

Block the current thread until the value becomes available.

Waits for the latest readable value without retrieving it.

Template Parameters

T	Async value type.

◆ wait() [2/2]

template<typename T >

void uni20::async::Async< T >::wait ( IAsyncScheduler & sched ) const

Block using an explicit scheduler until the value is ready.

Waits for the latest readable value using an explicit scheduler without retrieving it.

The scheduler will be driven until all pending writers complete.

Parameters

sched Scheduler instance used to make progress while waiting.

Template Parameters

T	Async value type.

Parameters

sched Scheduler used to drive pending work.

◆ write()

template<typename T >

WriteBuffer< T > uni20::async::Async< T >::write ( )

inline

Begin exclusive asynchronous access to the payload.

The returned proxy is capability-aware. Independent values support replacement operations; aliases expose their descriptor read-only and support only matching write-through assignments.

Returns: Exclusive write buffer for the next epoch.

Friends And Related Symbol Documentation

◆ make_async_alias

template<typename T >

template<typename Alias , typename Parent , typename... Args>

Async< Alias > make_async_alias	(	Async< Parent > const &	parent,
		Args &&...	args
	)

friend

Construct an async alias that retains a parent value and shares its epoch queue.

◆ make_async_alias_from_parent [1/2]

template<typename T >

template<typename Alias , typename Parent , typename... Args>

Async< Alias > make_async_alias_from_parent	(	Async< Parent > &	parent,
		Args &&...	args
	)

friend

Construct an async alias from a mutable parent descriptor.

The alias constructor receives the address reserved for the parent value followed by args. The address may identify unconstructed storage and must not be dereferenced before the shared epoch is readable.

◆ make_async_alias_from_parent [2/2]

template<typename T >

template<typename Alias , typename Parent , typename... Args>

Async< Alias > make_async_alias_from_parent	(	Async< Parent > const &	parent,
		Args &&...	args
	)

friend

Construct a read-only async alias from a parent descriptor.

◆ ReverseValue< T >

template<typename T >

friend class ReverseValue< T >

friend

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

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ value_type

Constructor & Destructor Documentation

◆ Async() [1/10]

◆ Async() [2/10]

◆ Async() [3/10]

◆ Async() [4/10]

◆ Async() [5/10]

◆ Async() [6/10]

◆ Async() [7/10]

◆ Async() [8/10]

◆ Async() [9/10]

◆ Async() [10/10]

◆ ~Async()

Member Function Documentation

◆ debug_name() [1/2]

◆ debug_name() [2/2]

◆ get_wait() [1/2]

◆ get_wait() [2/2]

◆ move_from_wait()

◆ operator=() [1/9]

◆ operator=() [2/9]

◆ operator=() [3/9]

◆ operator=() [4/9]

◆ operator=() [5/9]

◆ operator=() [6/9]

◆ operator=() [7/9]

◆ operator=() [8/9]

◆ operator=() [9/9]

◆ queue()

◆ read()

◆ storage()

◆ storage_address() [1/2]

◆ storage_address() [2/2]

◆ unsafe_set()

◆ unsafe_value()

◆ unsafe_value_ref() [1/2]

◆ unsafe_value_ref() [2/2]

◆ value_ptr() [1/2]

◆ value_ptr() [2/2]

◆ wait() [1/2]

◆ wait() [2/2]

◆ write()

Friends And Related Symbol Documentation

◆ make_async_alias

◆ make_async_alias_from_parent [1/2]

◆ make_async_alias_from_parent [2/2]

◆ ReverseValue< T >