Timing signal processors

Description

Processors for transforming timing signal events.

Topics
	Timing signal modeling processors
	Processors for fitting and extrapolating timing models.

Functions
template<typename TickEvent, typename FireEvent, typename ResetEvent, bool FireAfterTick, typename Downstream>
auto	tcspc::count_down_to (arg::threshold< u64 > threshold, arg::limit< u64 > limit, arg::initial_count< u64 > initial_count, Downstream downstream)
	Like tcspc::count_up_to(), but decrement the count on each tick event.
template<typename TickEvent, typename FireEvent, typename ResetEvent, bool FireAfterTick, typename Downstream>
auto	tcspc::count_up_to (arg::threshold< u64 > threshold, arg::limit< u64 > limit, arg::initial_count< u64 > initial_count, Downstream downstream)
	Create a processor that counts a specific event and emits an event when the count reaches a threshold.
template<typename TriggerEvent, typename OutputEvent, typename TimingGenerator, typename Downstream>
auto	tcspc::generate (TimingGenerator generator, Downstream downstream)
	Create a processor that generates a pattern of timing events in response to a trigger.
template<typename Event, typename OutEvent, typename Matcher, typename Downstream>
auto	tcspc::match (Matcher matcher, Downstream downstream)
	Create a processor that detects events matching a criterion.
template<typename Event, typename OutEvent, typename Matcher, typename Downstream>
auto	tcspc::match_replace (Matcher matcher, Downstream downstream)
	Like tcspc::match(), but do not pass through matched events.

Function Documentation

count_down_to()

template<typename TickEvent, typename FireEvent, typename ResetEvent, bool FireAfterTick, typename Downstream>

auto tcspc::count_down_to	(	arg::threshold< u64 >	threshold,
		arg::limit< u64 >	limit,
		arg::initial_count< u64 >	initial_count,
		Downstream	downstream )

Like tcspc::count_up_to(), but decrement the count on each tick event.

All behavior is symmetric to tcspc::count_up_to(). limit must be less than initial_count.

See also

tcspc::count_up_to()

count_up_to()

template<typename TickEvent, typename FireEvent, typename ResetEvent, bool FireAfterTick, typename Downstream>

auto tcspc::count_up_to	(	arg::threshold< u64 >	threshold,
		arg::limit< u64 >	limit,
		arg::initial_count< u64 >	initial_count,
		Downstream	downstream )

Create a processor that counts a specific event and emits an event when the count reaches a threshold.

All events (including TickEvent and ResetEvent) are passed through.

TickEvent and FireEvent must have an abstime field. FireEvent must be brace-initializable with abstime (as in FireEvent{123}).

The internal counter starts at initial_count and is incremented when a TickEvent is passed through. Just before or after the TickEvent is emitted (depending on whether FireAfterTick is false or true), the count is compared to the threshold and if equal, FireEvent is emitted. The abstime of the FireEvent is set equal to that of the TickEvent that triggered it.

After incrementing the count and processing the threshold, if the count equals limit, then the count is reset to initial_count. Automatic resetting can be effectively disabled by setting limit to std::numeric_limits<tcspc::u64>::max().

The limit must be greater than initial_count. When FireAfterTick is false, threshold should be greater than or equal to initial_count and less than limit; otherwise FireEvent is never emitted. When FireAfterTick is true, threshold should be greater than initial_count and less than or equal to limit; otherwise FireEvent is never emitted.

When a ResetEvent is received (and passed through), the count is reset to initial_count. No FireEvent is emitted on reset, but if FireAfterTick is false and threshold is set equal to initial_count, then a FireEvent is emitted on the next TickEvent received.

Remarks

Applications of this processor include converting fast raster clocks (e.g., pixel clock) to slower ones (e.g., line clock) or detecting when a desired number of detection events have been accumulated.

See also

tcspc::count_down_to()

Template Parameters

TickEvent	the event type to count
FireEvent	the event type to emit when the count reaches threshold
ResetEvent	an event type that causes the count to be reset to initial_count
FireAfterTick	whether to emit FireEvent after passing through TickEvent, rather than before
Downstream	downstream processor type

Parameters

threshold	the count value at which to emit FireEvent
limit	the count value at which to reset to initial_count; must be greater than initial_count
initial_count	the value at which the count starts and to which it is reset
downstream	downstream processor

Returns

processor

Events handled

• TickEvent: increment counter; pass through; before or after doing so, emit FireEvent if at threshold; if at limit reset counter
• ResetEvent: reset counter; pass through
• All other types: pass through with no action
• Flush: pass through with no action

generate()

template<typename TriggerEvent, typename OutputEvent, typename TimingGenerator, typename Downstream>

auto tcspc::generate	(	TimingGenerator	generator,
		Downstream	downstream )

Create a processor that generates a pattern of timing events in response to a trigger.

All events are passed through.

Every time a TriggerEvent is received, generation of a pattern of timing events of type OutputEvent is started according to the given generator (see Timing generators).

Timing events are generated just before an event with an equal or greater abstime is passed through. In particular, timing events beyond the last-passed-through event are not generated.

If the next TriggerEvent is received before the current pattern has been completed, any remaining timing events in the pattern with abstime strictly greater than that of the new TriggerEvent are suppressed; pending events whose abstime equals that of the new TriggerEvent are emitted before the trigger is passed through.

Attention

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

Template Parameters

TriggerEvent	event type that triggers a new round of timing generation by resetting the timing generator
OutputEvent	event type to generate, which must have an abstime field whose type matches that of TriggerEvent
TimingGenerator	timing generator type (usually deduced)
Downstream	downstream processor type (usually deduced)

Parameters

generator	the timing generator
downstream	downstream processor

Returns

processor

Events handled

• TriggerEvent: emit any generated OutputEvents based on the previous trigger and with earlier or equal abstime; discard any remaining OutputEvents that the previous trigger would have produced; set up new round of generation; pass through
• All other types with abstime field: emit any generated events based on the previous trigger and with earlier or equal abstime; pass through
• Flush: passed through without action

match()

template<typename Event, typename OutEvent, typename Matcher, typename Downstream>

auto tcspc::match	(	Matcher	matcher,
		Downstream	downstream )

Create a processor that detects events matching a criterion.

All events are passed through.

Any event of type Event is tested by the given matcher (see Matchers). If it is a match, an OutEvent is generated with the same abstime as the Event.

Both Event and OutEvent must have an abstime field.

See also

tcspc::match_replace()

Template Parameters

Event	event type to match
OutEvent	event type to emit on match
Matcher	type of matcher (usually deduced)
Downstream	downstream processor type (usually deduced)

Parameters

matcher	the matcher
downstream	downstream processor

Returns

processor

Events handled

• Event: pass through; if a match, emit OutEvent
• All other types: pass through with no action
• Flush: pass through with no action

match_replace()

template<typename Event, typename OutEvent, typename Matcher, typename Downstream>

auto tcspc::match_replace	(	Matcher	matcher,
		Downstream	downstream )

Like tcspc::match(), but do not pass through matched events.

All behavior is the same as tcspc::match(), except that input events that are matched are discarded.

See also

tcspc::match()

Events handled

• Event: pass through only if not a match; if a match, emit OutEvent
• All other types: pass through with no action
• Flush: pass through with no action