Timeline processors

Description

Processors for managing and manipulating the absolute timeline.

Functions
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::delay (arg::delta< typename DataTypes::abstime_type > delta, Downstream downstream)
	Create a processor that applies an abstime offset to all events.
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::regulate_time_reached (arg::interval_threshold< typename DataTypes::abstime_type > interval_threshold, arg::count_threshold< std::size_t > count_threshold, Downstream downstream)
	Create a processor that regulates the frequency of time-reached events.
template<typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::zero_base_abstime (Downstream downstream)
	Create a processor that offsets abstime so that the first event is at time zero.

Function Documentation

delay()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::delay	(	arg::delta< typename DataTypes::abstime_type >	delta,
		Downstream	downstream )

Create a processor that applies an abstime offset to all events.

All events processed must have an abstime field, and no other fields derived from the abstime (because only the abstime field will be adjusted). Even if the abstime_type is a signed integer type, wrap-around is handled correctly.

Template Parameters

DataTypes	data type set specifying abstime_type
Downstream	downstream processor type

Parameters

delta	abstime offset to apply (can be negative)
downstream	downstream processor

Returns

processor

Events handled

• All types with abstime field: pass through with delta added to abstime
• Flush: pass through with no action

regulate_time_reached()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::regulate_time_reached	(	arg::interval_threshold< typename DataTypes::abstime_type >	interval_threshold,
		arg::count_threshold< std::size_t >	count_threshold,
		Downstream	downstream )

Create a processor that regulates the frequency of time-reached events.

This processor can be used to ensure that the event stream contains tcspc::time_reached_event at reasonable abstime intervals (to keep live displays responsive) and at reasonable frequency in terms of event count (to prevent unbounded growth of buffer size at merge processors). It also removes excess time-reached events based on the same criteria.

This type of regulation is necessary when there is no guarantee that the upstream input contains time-reached events at regular intervals and there are processors downstream that sort events from multiple streams by abstime: specifically, tcspc::merge() or tcspc::merge_n(). This is because merge processors are unable to emit the buffered events until they know that all earlier upstream events have been seen.

Processors that have multiple downstreams (such as tcspc::route()) should broadcast time-reached events so that each branch carries information about elapsed time, allowing merging processors to limit buffering to reasonable latency and capacity.

Note that the abstime-based criterion is not perfect and depends on the upstream containing (any) events at reasonable abstime intervals, because the time-reached event is only emitted upon receiving an upstream event past the interval threshold.

When processing stored data, or when live display update is not a requirement, the interval_threshold can be set to the maximum value of the abstime_type to disable the criterion, relying solely on the count_threshold. It is recommended that count_threshold be set to a reasonable limit even when interval_threshold is used as the main criterion.

Attention

The abstime of incoming events must be monotonically non-decreasing and must not wrap around.

Template Parameters

DataTypes	data type set specifying abstime_type
Downstream	downstream processor type

Parameters

interval_threshold	a time-reached event is emitted at the next opportunity if at least this abstime interval has elapsed since the previously emitted time-reached event
count_threshold	a time-reached event is emitted when this many events have been emitted since the previously emitted time-reached event
downstream	downstream processor

Returns

processor

Events handled

• tcspc::time_reached_event<DT>: emit as tcspc::time_reached_event<DataTypes> with rate limiting
• All types with abstime field: passed through, possibly followed by tcspc::time_reached_event<DataTypes>
• Flush: emit tcspc::time_reached_event<DataTypes> with time of last passed event; pass through

zero_base_abstime()

template<typename DataTypes = default_data_types, typename Downstream>

auto tcspc::zero_base_abstime

(

Downstream

downstream

)

Create a processor that offsets abstime so that the first event is at time zero.

This can be used to ensure that downstream processing will not encounter integer overflow within a moderate amount of time. Even if the abstime_type is a signed integer type, wrap-around is handled correctly.

See also

delay

Template Parameters

DataTypes	data type set specifying abstime_type
Downstream	downstream processor type

Parameters

downstream

downstream processor

Returns

processor

Events handled

• All types with abstime field: pass through with the abstime made relative to the first event encountered
• Flush: pass through with no action