Acquisition processors

Description

Processors for acquiring data from hardware devices.

Functions
template<typename T, typename Reader, typename Downstream>
auto	tcspc::acquire (Reader reader, std::shared_ptr< bucket_source< T > > buffer_provider, arg::batch_size< std::size_t > batch_size, access_tracker< acquire_access > tracker, Downstream downstream)
	Create a processor that acquires data into buckets.
template<typename T, typename Reader, typename LiveDownstream, typename BatchDownstream>
auto	tcspc::acquire_full_buckets (Reader reader, std::shared_ptr< bucket_source< T > > buffer_provider, arg::batch_size< std::size_t > batch_size, access_tracker< acquire_access > tracker, LiveDownstream live_downstream, BatchDownstream batch_downstream)
	Create a processor that acquires data into buckets, ensuring that each bucket is filled to a fixed size but also providing views of partial buckets in real time.
template<typename T, typename Downstream>
auto	tcspc::copy_to_buckets (std::shared_ptr< bucket_source< T > > buffer_provider, Downstream downstream)
	Create a processor that copies batches of data into buckets.
template<typename T, typename LiveDownstream, typename BatchDownstream>
auto	tcspc::copy_to_full_buckets (std::shared_ptr< bucket_source< T > > buffer_provider, arg::batch_size< std::size_t > batch_size, LiveDownstream live_downstream, BatchDownstream batch_downstream)
	Create a processor that copies data into buckets, ensuring that each bucket is filled to a fixed size but also providing views of partial buckets in real time.

Function Documentation

acquire()

template<typename T, typename Reader, typename Downstream>

auto tcspc::acquire	(	Reader	reader,
		std::shared_ptr< bucket_source< T > >	buffer_provider,
		arg::batch_size< std::size_t >	batch_size,
		access_tracker< acquire_access >	tracker,
		Downstream	downstream )

Create a processor that acquires data into buckets.

This processor is used to integrate a pull-style device API (i.e., one in which we make a function call into the driver to fill our buffer with acquired data) as a data source for libtcspc. Data is acquired by the provided reader (see Readers for acquisition).

Every read from the reader uses an empty bucket; if any elements were read, the bucket is passed downstream. In general, therefore, the buckets are partially filled.

Template Parameters

T	the element type of the acquired data (usually a byte or integer type)
Reader	type of reader (usually deduced)
Downstream	downstream processor type (usually deduced)

Parameters

reader	reader
buffer_provider	bucket source providing event buffers
batch_size	number of elements (T) to collect in each bucket
tracker	access tracker for later access
downstream	downstream processor

Returns

processor

Events handled

• Flush: read from the reader until the end of stream, or until there is an error, or until halted, and emit (rvalue) tcspc::bucket<T> on each read. If end of stream is indicated by the reader, flush the downstream.

acquire_full_buckets()

template<typename T, typename Reader, typename LiveDownstream, typename BatchDownstream>

auto tcspc::acquire_full_buckets	(	Reader	reader,
		std::shared_ptr< bucket_source< T > >	buffer_provider,
		arg::batch_size< std::size_t >	batch_size,
		access_tracker< acquire_access >	tracker,
		LiveDownstream	live_downstream,
		BatchDownstream	batch_downstream )

Create a processor that acquires data into buckets, ensuring that each bucket is filled to a fixed size but also providing views of partial buckets in real time.

This processor is used to integrate a pull-style device API (i.e., one in which we make a function call into the driver to fill our buffer with acquired data) as a data source for libtcspc. Data is acquired by the provided reader (see Readers for acquisition).

The processor attaches two downstream processors. The live_downstream receives newly acquired data as soon as it is available, but in the form of a const view bucket. This is typically used for live processing and display.

The batch_downstream receives the same data, but only as each batch fills up to the given batch_size (except for the last batch, which may be smaller). This is typically used for saving the raw data to disk.

The two streams share the underlying bucket storage.

Template Parameters

T	the element type of the acquired data (usually a byte or integer type)
Reader	type of reader (usually deduced)
LiveDownstream	type of the "live" downstream processor (usually deduced)
BatchDownstream	type of the "batch" downstream processor (usually deduced)

Parameters

reader	reader
buffer_provider	bucket source providing event buffers (must support shared views unless LiveDownstream is tcspc::null_sink)
batch_size	number of elements (T) to collect in each bucket
tracker	access tracker for later access
live_downstream	downstream processor receiving read-only views of data per each read
batch_downstream	downstream processor receiving full buckets

Returns

processor

Events handled

• Flush: read from the reader until the end of stream, or until there is an error, or until halted, and emit (rvalue) tcspc::bucket<T const> to live_downstream on each read; emit (rvalue) tcspc::bucket<T> when batch_size elements have been collected, to batch_downstream. If end of stream is indicated by the reader, flush the downstreams.

copy_to_buckets()

template<typename T, typename Downstream>

auto tcspc::copy_to_buckets	(	std::shared_ptr< bucket_source< T > >	buffer_provider,
		Downstream	downstream )

Create a processor that copies batches of data into buckets.

This processor is used to integrate a push-style device API (i.e., one in which the driver API calls our callback with acquired data) as a data source for libtcspc that can be buffered.

The contents of events explicitly convertible to std::span<T const> are copied to bucket<T> (of variable size) obtained from the given buffer_provider.

Events other than those explicitly convertible to std::span<T const> are passed through. This can be used to transmit out-of-band timing events.

Template Parameters

T	the element type of the data (usually a byte or integer type)
Downstream	downstream processor type (usually deduced)

Parameters

buffer_provider	bucket source providing event buffers
downstream	downstream processor

Returns

processor

Events handled

• Contiguous container or span of T const: copy to a tcspc::bucket<T> of matching size and emit
• All other types: pass through without action
• Flush: pass through without action

copy_to_full_buckets()

template<typename T, typename LiveDownstream, typename BatchDownstream>

auto tcspc::copy_to_full_buckets	(	std::shared_ptr< bucket_source< T > >	buffer_provider,
		arg::batch_size< std::size_t >	batch_size,
		LiveDownstream	live_downstream,
		BatchDownstream	batch_downstream )

Create a processor that copies data into buckets, ensuring that each bucket is filled to a fixed size but also providing views of partial buckets in real time.

This processor is used to integrate a push-style device API (i.e., one in which the driver API calls our callback with acquired data) as a data source for libtcspc that can be buffered.

The contents of events explicitly convertible to std::span<T const> are copied to fixed-size buckets.

The processor attaches two downstream processors. The live_downstream receives newly copied data as soon as it is available, but in the form of a const view bucket. This is typically used for live processing and display.

The batch_downstream receives the same data, but only as each batch fills up to the given batch_size (except for the last batch, which may be smaller). This is typically used for saving the raw data to disk.

The two streams share the underlying bucket storage.

Events other than those explicitly convertible to std::span<T const> are passed through only to the live_downstream. Thus, their order relative to the data batches is preserved. This can be used to transmit out-of-band timing events.

Template Parameters

T	the element type of the data (usually a byte or integer type)
LiveDownstream	type of the "live" downstream processor (usually deduced)
BatchDownstream	type of the "batch" downstream processor (usually deduced)

Parameters

buffer_provider	bucket source providing event buffers (must support shared views unless LiveDownstream is tcspc::null_sink)
batch_size	number of elements (T) to collect in each bucket
live_downstream	downstream processor receiving read-only views of data per each read
batch_downstream	downstream processor receiving full buckets

Returns

processor

Events handled

• Contiguous container or span of T const: copy into successive tcspc::bucket<T>s of size batch_size, emitting the copied portion to live_downstream as (rvalue) tcspc::bucket<T const> and any full buckets to batch_downstream as (rvalue) tcspc::bucket<T>.
• All other types: pass through without action
• Flush: emit any pending non-full bucket to batch_downstream; pass through