Histogramming processors

Description

Processors for histogramming.

Topics
	Binning processors
	Processors for binning data for histogramming.

Functions
template<histogram_policy Policy = histogram_policy::default_policy, typename ResetEvent = never_event, typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::histogram (arg::num_bins< std::size_t > num_bins, arg::max_per_bin< typename DataTypes::bin_type > max_per_bin, std::shared_ptr< bucket_source< typename DataTypes::bin_type > > buffer_provider, Downstream downstream)
	Create a processor that collects a histogram.
template<histogram_policy Policy = histogram_policy::default_policy, typename ResetEvent = never_event, typename DataTypes = default_data_types, typename Downstream>
auto	tcspc::scan_histograms (arg::num_elements< std::size_t > num_elements, arg::num_bins< std::size_t > num_bins, arg::max_per_bin< typename DataTypes::bin_type > max_per_bin, std::shared_ptr< bucket_source< typename DataTypes::bin_type > > buffer_provider, Downstream downstream)
	Create a processor that scans over an array of histograms, updating each with the received bin increment clusters.

Function Documentation

histogram()

template<histogram_policy Policy = histogram_policy::default_policy, typename ResetEvent = never_event, typename DataTypes = default_data_types, typename Downstream>

auto tcspc::histogram	(	arg::num_bins< std::size_t >	num_bins,
		arg::max_per_bin< typename DataTypes::bin_type >	max_per_bin,
		std::shared_ptr< bucket_source< typename DataTypes::bin_type > >	buffer_provider,
		Downstream	downstream )

Create a processor that collects a histogram.

The processor fills a histogram (held in a tcspc::bucket<DataTypes::bin_type> provided by buffer_provider) by incrementing the bin given by each incoming tcspc::bin_increment_event.

A round of accumulation is ended by resetting, for example by receiving a ResetEvent. After a reset, the histogram is replaced with a new bucket and a new round is started.

The value of Policy can modify behavior and specify what happens when a histogram bin overflows; see tcspc::histogram_policy for details.

The result is emitted in 2 ways:

• A tcspc::histogram_event<DataTypes> is emitted on each bin increment, carrying a view of the histogram.
• If requested (i.e., Policy contains tcspc::histogram_policy::emit_concluding_events), a tcspc::concluding_histogram_event<DataTypes> is emitted upon each reset. This event carries a bucket with extractable storage.

Attention

Behavior is undefined if an incoming tcspc::bin_increment_event contains a bin index beyond the size of the histogram. The bin mapper should be chosen so that this does not occur.

Template Parameters

Policy	policy specifying behavior of the processor
ResetEvent	type of event causing a new round to start
DataTypes	data type set specifying bin_index_type and bin_type
Downstream	downstream processor type (usually deduced)

Parameters

num_bins	number of bins in the histogram (must match the bin mapper used upstream)
max_per_bin	maximum value allowed in each bin
buffer_provider	bucket source providing series of buffers (a new bucket is used after every reset)
downstream	downstream processor

Returns

processor

Events handled

• tcspc::bin_increment_event<DT>: apply the increment to the histogram and, if there is no bin overflow, emit (const) tcspc::histogram_event<DataTypes>. If a bin overflowed, behavior depends on the value of Policy & tcspc::histogram_policy::overflow_mask:
  • If tcspc::histogram_policy::error_on_overflow (the default), throw tcspc::histogram_overflow_error
  • If tcspc::histogram_policy::stop_on_overflow, emit tcspc::concluding_histogram_event<DataTypes> if Policy has tcspc::histogram_policy::emit_concluding_events set, then flush the downstream and throw tcspc::end_of_processing
  • If tcspc::histogram_policy::saturate_on_overflow, emit a tcspc::warning_event (but only if this is the first overflow in the current round); then ignore the increment but do proceed to emit tcspc::histogram_event<DataTypes>
  • If tcspc::histogram_policy::reset_on_overflow, perform a reset, as if a ResetEvent was received just prior to the current event; then, in the fresh histogram, reapply the current event (but throw tcspc::histogram_overflow_error if max_per_bin equals 0)
• ResetEvent: if Policy has tcspc::histogram_policy::emit_concluding_events set, emit (rvalue) tcspc::concluding_histogram_event<DataTypes> with the current histogram; pass through; then start a new round by arranging to switch to a new bucket for the histogram on the next tcspc::bin_increment_event
• All other types: pass through with no action
• Flush: pass through with no action

scan_histograms()

template<histogram_policy Policy = histogram_policy::default_policy, typename ResetEvent = never_event, typename DataTypes = default_data_types, typename Downstream>

auto tcspc::scan_histograms	(	arg::num_elements< std::size_t >	num_elements,
		arg::num_bins< std::size_t >	num_bins,
		arg::max_per_bin< typename DataTypes::bin_type >	max_per_bin,
		std::shared_ptr< bucket_source< typename DataTypes::bin_type > >	buffer_provider,
		Downstream	downstream )

Create a processor that scans over an array of histograms, updating each with the received bin increment clusters.

The processor fills an array of histograms (held in a tcspc::bucket<DataTypes::bin_type> provided by buffer_provider) by sequentially visiting its elements (each a histogram) on each incoming tcspc::bin_increment_cluster_event. One such iteration over the array is termed a scan. After a scan, the processor returns to the first element of the array and continues to add increments (by default adding to the previous scans).

A round consisting of multiple scans is ended by resetting, for example by receiving a ResetEvent. After a reset, the histogram array is replaced with a new bucket and a new round is started, in which handling of subsequent bin increment clusters begins at the first element of the array.

The value of Policy can modify behavior (including disabling the accumulating behavior) and specify what happens when a histogram bin overflows; see tcspc::histogram_policy for details.

The result is emitted in 3 ways:

• A tcspc::histogram_array_progress_event<DataTypes> is emitted on each bin increment cluster. It carries a view of the whole array and indicates how far the current scan has progressed.
• A tcspc::histogram_array_event<DataTypes> is emitted as soon as each scan is finished, carrying a view of the histogram array.
• If requested (i.e., Policy contains tcspc::histogram_policy::emit_concluding_events), a tcspc::concluding_histogram_array_event<DataTypes> is emitted upon each reset, but only after rolling back any incomplete scan, such that every element of the array contains counts from the same number of scans. This event carries a bucket with extractable storage.

Attention

Behavior is undefined if an incoming tcspc::bin_increment_cluster_event contains a bin index beyond the size of the histogram. The bin mapper should be chosen so that this does not occur.

Template Parameters

Policy	policy specifying behavior of the processor
ResetEvent	type of event causing a new round to start
DataTypes	data type set specifying bin_index_type and bin_type
Downstream	downstream processor type (usually deduced)

Parameters

num_elements	the number of elements (each a histogram) in the array
num_bins	the number of bins in each histogram (must match the bin mapper used upstream)
max_per_bin	maximum value allowed in each bin
buffer_provider	bucket source providing series of buffers for each histogram array
downstream	downstream processor

Returns

processor

Events handled

• tcspc::bin_increment_cluster_event<DT>: apply the increments to the next element histogram of the array (after clearing it if this is the first scan of a round or Policy has tcspc::histogram_policy::clear_every_scan set) and, if there is no bin overflow, emit (const) tcspc::histogram_array_progress_event<DataTypes>; if the cluster was for the last element of the array (end of a scan), also emit (const) tcspc::histogram_array_event<DataTypes> and if, in addition, Policy has tcspc::histogram_policy::reset_after_scan set, perform a reset as if a ResetEvent was received. If a bin overflowed, behavior depends on the value of Policy & tcspc::histogram_policy::overflow_mask:
  • If tcspc::histogram_policy::error_on_overflow (the default), throw tcspc::histogram_overflow_error
  • If tcspc::histogram_policy::stop_on_overflow, roll back the current scan and emit tcspc::concluding_histogram_array_event<DataTypes> if Policy has tcspc::histogram_policy::emit_concluding_events set, then flush the downstream and throw tcspc::end_of_processing
  • If tcspc::histogram_policy::saturate_on_overflow, emit a tcspc::warning_event (but only if this is the first overflow in the current round); then ignore all increments that would result in overflow, but do apply non-overflowing increments and proceed to emit tcspc::histogram_array_progress_event<DataTypes>
  • If tcspc::histogram_policy::reset_on_overflow, perform a reset, as if a ResetEvent was received just prior to the current event; then, in the fresh array, replay any partial scan that was rolled back during the reset, and reapply the current event (but throw tcspc::histogram_overflow_error if the overflow occurred during the first scan of the round, so that there is no infinite recursion)
• ResetEvent: if Policy has tcspc::histogram_policy::emit_concluding_events set, roll back any partial scan and emit (rvalue) tcspc::concluding_histogram_array_event<DataTypes>; pass through; then start a new round by arranging to switch to a new bucket for the histogram array on the next tcspc::bin_increment_cluster_event
• All other types: pass through with no action
• Flush: pass through with no action