Binary stream processors

Description

Processors for converting between events and binary data streams.

Functions
template<typename Event, typename Downstream>
auto	tcspc::batch_from_bytes (std::shared_ptr< bucket_source< Event > > buffer_provider, Downstream downstream)
	Create a processor that converts batches of bytes into batches of events.
template<typename Event, typename Downstream>
auto	tcspc::unbatch_from_bytes (Downstream downstream)
	Create a processor that converts batches of bytes into individual events.
template<typename Downstream>
auto	tcspc::view_as_bytes (Downstream downstream)
	Create a processor that views events as byte spans.

Function Documentation

batch_from_bytes()

template<typename Event, typename Downstream>

auto tcspc::batch_from_bytes	(	std::shared_ptr< bucket_source< Event > >	buffer_provider,
		Downstream	downstream )

Create a processor that converts batches of bytes into batches of events.

Copies incoming events (which must be a span, vector, or bucket of std::byte) into tcspc::bucket<Event>, provided by the given buffer_provider.

Any input bytes that do not make up a whole Event are stored and combined with subsequent input.

The output bucket size is variable and contains as many events as can be constructed from the buffered bytes and the input event.

See also

tcspc::unbatch_from_bytes()

Template Parameters

Event	the event type (must be a trivial type)
Downstream	downstream processor type

Parameters

buffer_provider	bucket source providing event buckets
downstream	downstream processor

Returns

processor

Events handled

• Contiguous container or span of std::byte or std::byte const: copy up to object boundary to tcspc::bucket<Event> and emit as batch
• Flush: throw std::runtime_error if bytes fewer than sizeof(Event) are left over; pass through

unbatch_from_bytes()

template<typename Event, typename Downstream>

auto tcspc::unbatch_from_bytes

(

Downstream

downstream

)

Create a processor that converts batches of bytes into individual events.

The incoming bytes are interpreted as a contiguous stream of Event objects, and emitted individually. The emitted events are aligned to alignof(Event) even if the input data is not aligned (by copying if necessary).

Any input bytes that do not make up a whole Event are stored and combined with subsequent input.

See also

tcspc::batch_from_bytes()

Template Parameters

Event	the event type (must be a trivial type)
Downstream	downstream processor type

Parameters

downstream

downstream processor

Returns

processor

Events handled

• Contiguous container or span of std::byte or std::byte const: collect bytes into Event objects and emit
• Flush: throw std::runtime_error if bytes fewer than sizeof(Event) are left over; pass through

view_as_bytes()

template<typename Downstream>

auto tcspc::view_as_bytes

(

Downstream

downstream

)

Create a processor that views events as byte spans.

This processor handles events of trivial types or buckets of trivial types and sends them, without copying, to the downstream processor as (const lvalue) bucket<std::byte>.

See also

tcspc::write_binary_stream()

Template Parameters

Downstream

downstream processor type

Parameters

downstream

downstream processor

Returns

processor

Events handled

• Any trivial type: emit its span as tcspc::bucket<std::byte>
• tcspc::bucket<T>: emit its data span as tcspc::bucket<std::byte>
• Flush: pass through with no action