Merging processors

Description

Processors for joining branches in the processing graph.

Functions
template<typename EventList, typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::merge (arg::max_buffered< std::size_t > max_buffered, Downstream downstream)
	Create a pair of processors that merge two event streams.
template<std::size_t N, typename EventList, typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::merge_n (arg::max_buffered< std::size_t > max_buffered, Downstream downstream)
	Create a processor that merges a given number of event streams.
template<std::size_t N = 2, typename Downstream>
auto	tcspc::merge_n_unsorted (Downstream downstream)
	Create a processor that merges a given number of event streams without sorting by abstime.

Function Documentation

merge()

template<typename EventList, typename DataTypes = default_data_types, typename Downstream>

auto tcspc::merge	(	arg::max_buffered< std::size_t >	max_buffered,
		Downstream	downstream )

Create a pair of processors that merge two event streams.

The merged stream will be produced in non-decreasing abstime order, provided that the two input streams have events in non-decreasing abstime order.

If events with the same abstime are received on both inputs, those received on input 0 are emitted before those received on input 1.

If one input falls far behind the other input (in terms of abstime), an undesirably large number of events may need to be buffered (undesirable either in terms of timely update of downstream or in terms of excessive memory use). The only way to prevent such a situation is to ensure that both inputs carry events at some minimal frequency, for example by injecting tcspc::time_reached_event (see tcspc::regulate_time_reached()).

See also

tcspc::merge_n()

Template Parameters

EventList	the event set handled by the merge processor
DataTypes	data type set specifying abstime_type
Downstream	downstream processor type (usually deduced)

Parameters

max_buffered	maximum capacity for buffered events
downstream	downstream processor

Returns

tuple-like of two input processors (0 and 1)

Events handled

• Types in EventList: pass through with buffering to ensure non-decreasing abstime order; throw tcspc::buffer_overflow_error if capacity exhausted
• Flush: pass through a single flush after both inputs flushed, after emitting any buffered events.

merge_n()

template<std::size_t N, typename EventList, typename DataTypes = default_data_types, typename Downstream>

auto tcspc::merge_n	(	arg::max_buffered< std::size_t >	max_buffered,
		Downstream	downstream )

Create a processor that merges a given number of event streams.

The merged stream will be produced in non-decreasing abstime order, provided that all input streams have events in non-decreasing abstime order.

This is useful when merging a (compile-time) variable number of similar streams. If the streams to be merged are dissimilar (have different pairwise time shift and especially event frequency), it may be more efficient to manually build a tree using the 2-way tcspc::merge() such that the streams with less frequent events are merged together first.

This processor does not guarantee any particular ordering for events of equal abstime.

If any input falls far behind the others (in terms of abstime), an undesirably large number of events may be buffered (undesirable either in terms of timely update of downstream or in terms of excessive memory use). The only way to prevent such a situation is to ensure that all inputs carry events at some minimal frequency, for example by injecting tcspc::time_reached_event (see tcspc::regulate_time_reached()).

See also

tcspc::merge()

tcspc::merge_n_unsorted()

Template Parameters

N	number of input streams
EventList	the event set handled by the merge processor
DataTypes	data type set specifying abstime_type
Downstream	downstream processor type

Parameters

max_buffered	maximum capacity for buffered events in each pairwise merge
downstream	downstream processor

Returns

tuple-like of N input processors

Events handled

• Types in EventList: pass through with buffering to ensure non-decreasing abstime order; throw tcspc::buffer_overflow_error if capacity exhausted
• Flush: pass through a single flush after all inputs flushed, after emitting any buffered events.

merge_n_unsorted()

template<std::size_t N = 2, typename Downstream>

auto tcspc::merge_n_unsorted

(

Downstream

downstream

)

Create a processor that merges a given number of event streams without sorting by abstime.

The merged stream will handle events in the temporal order they are passed from the upstreams.

This is useful when the events on the input streams are known to arrive in the correct order, or when order does not matter for downstream processing.

See also

tcspc::merge_n()

Template Parameters

N	number of input streams
Downstream	downstream processor type

Parameters

downstream

downstream processor

Returns

std::array of N input processors

Events handled

• All types: pass through with no action
• Flush: pass through a single flush once all inputs have been flushed