channel

Detailed Description

Process-oriented channels (sender/receiver) and related types.

See the @file narrative in channel.hpp for CSP semantics, processing graphs, and composition (zip, zip_with, merge_channel). Types and free functions in this group are declared in that header.

Classes
class	stlab::sender< typename, typename >
class	stlab::receiver< T >
	Receiving end of a CSP channel. More...
class	stlab::channel_error
	Exception type for channel usage errors (broken channel, process already running, etc.). More...
struct	stlab::identity
struct	stlab::result_of_< typename >
struct	stlab::result_of_< R(Args...)>
struct	stlab::first_< T1, T >
struct	stlab::argument_of< typename >
struct	stlab::argument_of< R(Arg)>
struct	stlab::unordered_t
	Merge strategy for merge_channel: invoke the process in arbitrary order as values arrive. More...
struct	stlab::round_robin_t
	Merge strategy for merge_channel: round-robin among upstream senders. More...
struct	stlab::zip_with_t
	Merge strategy for merge_channel / zip_with: wait for one value from each upstream, then invoke with the full argument set. More...
struct	stlab::buffer_size
	Per-process input queue capacity for flow control (combine with a process via operator&). More...
class	stlab::sender< T, enable_if_copyable< T > >
	Sending end of a CSP channel (copyable T). More...
class	stlab::sender< T, enable_if_not_copyable< T > >
	Sending end of a CSP channel (move-only T; not copyable). More...
struct	stlab::function_process< F >
	Adapts a std::function into a channel process with await / yield / state. More...
struct	stlab::function_process< R(Args...)>
	Function-object process: binds arguments in await, runs the call in yield. More...

Typedefs
using	stlab::process_state_scheduled
	process_state plus a deadline returned from process::state().
template<typename F>
using	stlab::result_of_t_
template<typename... T>
using	stlab::first_t
template<typename T>
using	stlab::argument_of_t

Enumerations
enum class	stlab::process_state : std::uint8_t { await , yield }
	Scheduling hint for a process: wait for input (await) or run to produce output (yield).
enum class	stlab::message_t : std::uint8_t { argument , error }
	Discriminator for tuple elements that carry either a value or an exception pointer.
enum class	stlab::channel_error_codes : std::uint8_t { broken_channel , process_already_running , no_state }
	Error codes reported by channel_error.

Functions
template<typename I, typename N, typename F>
auto	stlab::for_each_n (I p, N n, F f) -> I
template<typename T, typename E>
auto	stlab::channel (E executor)
	Creates a sender/receiver pair on executor (receiver<void> only when T is void).
template<typename S, typename F, typename... R>
auto	stlab::join (S s, F f, R... upstream_receiver)
template<typename S, typename F, typename... R>
auto	stlab::merge (S s, F f, R... upstream_receiver)
template<typename M, typename S, typename F, typename... R>
auto	stlab::merge_channel (S s, F f, R &&... upstream_receiver)
	Creates a receiver that merges upstream channels using merge strategy M.
template<typename S, typename F, typename... R>
auto	stlab::zip_with (S s, F f, const R &... upstream_receiver)
	Creates a receiver that runs f when each upstream has produced one value.
template<typename S, typename... R>
auto	stlab::zip (S s, const R &... r)
	Zips upstream receivers in step; yields std::tuple<T...> of their result_types.
auto	stlab::operator& (buffer_size bs, const executor &e) -> detail::annotations
auto	stlab::operator& (buffer_size bs, executor &&e) -> detail::annotations
auto	stlab::operator& (const executor &e, buffer_size bs) -> detail::annotations
auto	stlab::operator& (executor &&e, buffer_size bs) -> detail::annotations
template<typename F, std::enable_if_t<!std::is_enum_v< std::remove_reference_t< F > >, int > = 0>
auto	stlab::operator& (buffer_size bs, F &&f) -> detail::annotated_process< F >
template<typename F, std::enable_if_t<!std::is_enum_v< std::remove_reference_t< F > >, int > = 0>
auto	stlab::operator& (F &&f, buffer_size bs) -> detail::annotated_process< F >
template<typename F>
auto	stlab::operator& (executor_task_pair< F > &&etp, buffer_size bs) -> detail::annotated_process< F >
template<typename F>
auto	stlab::operator& (buffer_size bs, executor_task_pair< F > &&etp) -> detail::annotated_process< F >
template<typename F, std::enable_if_t<!std::is_enum_v< std::remove_reference_t< F > >, int > = 0>
auto	stlab::operator& (detail::annotations &&a, F &&f) -> detail::annotated_process< F >
template<typename F, std::enable_if_t<!std::is_enum_v< std::remove_reference_t< F > >, int > = 0>
auto	stlab::operator& (F &&f, detail::annotations &&a) -> detail::annotated_process< F >
template<typename F>
auto	stlab::operator& (detail::annotated_process< F > &&a, executor &&e) -> detail::annotated_process< F >
template<typename F>
auto	stlab::operator& (detail::annotated_process< F > &&a, buffer_size bs) -> detail::annotated_process< F >

Variables
constexpr process_state_scheduled	stlab::await_forever
	Always await the next upstream value (no yield timeout).
constexpr process_state_scheduled	stlab::yield_immediate
	Yield as soon as the scheduler permits.

Typedef Documentation

process_state_scheduled

using stlab::process_state_scheduled

process_state plus a deadline returned from process::state().

The runtime uses the pair to choose await vs yield() and optional timers. If first is yield and the time point is in the past, yield() runs next; if it is in the future, a timer fires yield() when it expires. For await, a past/now time point can trigger yield() when no value arrives; a future time point starts a timeout that yields if no value arrives before it expires (cancelled when a value does arrive). Optional close() is invoked when upstream closes while awaiting; optional set_error(exception_ptr) receives upstream exceptions.

Function Documentation

join()

template<typename S, typename F, typename... R>

auto stlab::join	(	S	s,
		F	f,
		R...	upstream_receiver )

Creates a new receiver and attaches process f. Upstream values are not delivered one-by-one; the last value from the slowest upstream triggers f with the complete argument set (same synchronization model as zip_with).

merge()

template<typename S, typename F, typename... R>

auto stlab::merge	(	S	s,
		F	f,
		R...	upstream_receiver )

Creates a receiver whose process runs whenever any upstream provides a value; there is no defined order among upstream values.

merge_channel()

template<typename M, typename S, typename F, typename... R>

auto stlab::merge_channel	(	S	s,
		F	f,
		R &&...	upstream_receiver )

Creates a receiver that merges upstream channels using merge strategy M.

M is one of unordered_t, round_robin_t, or zip_with_t. Callable f must accept values from the upstream processes (single argument for unordered/round-robin, or one argument per upstream for zip_with_t).

zip()

template<typename S, typename... R>

auto stlab::zip	(	S	s,
		const R &...	r )

Zips upstream receivers in step; yields std::tuple<T...> of their result_types.

Whenever a complete set of values from each upstream has arrived, the tuple is passed downstream. (Behavior changed after release 1.2.0; prefer this over the deprecated join.)

zip_with()

template<typename S, typename F, typename... R>

auto stlab::zip_with	(	S	s,
		F	f,
		const R &...	upstream_receiver )

Creates a receiver that runs f when each upstream has produced one value.

Upstream values are collected; when every upstream has contributed, f is invoked with that complete set. Returns receiver<T> where T is the result type of f.