C# Class GSF.TimeSeries.ConcentratorBase

Measurement concentrator base class.

This class synchronizes (i.e., sorts by timestamp) real-time measurements.

Note that your lag time should be defined as it relates to the rate at which data data is coming into the concentrator. Make sure you allow enough time for transmission of data over the network allowing any needed time for possible network congestion. Lead time should be defined as your confidence in the accuracy of your local clock (e.g., if you set lead time to 2, this means you trust that your local clock is within plus or minus 2 seconds of real-time.)

This concentrator is designed to sort measurements being transmitted in real-time for data being sent at rates of at least 1 sample per second. Slower rates (e.g., once every few seconds) are not supported since sorting data at these speeds would be trivial. There is no defined maximum number of supported samples per second - but keep in mind that CPU utilization will increase as the measurement volume and frame rate increase.

Inheritance: IDisposable
Exibir arquivo Open project: GridProtectionAlliance/gsf

Public Methods

Method Description
Dispose ( ) : void

Releases all the resources used by the ConcentratorBase object.
MillisecondsFromRealTime ( Ticks timestamp ) : double

Returns the deviation, in milliseconds, that the given number of ticks is from real-time (i.e., ConcentratorBase.RealTime).
ResetStatistics ( ) : void

Resets the statistics of the concentrator.
SecondsFromRealTime ( Ticks timestamp ) : double

Returns the deviation, in seconds, that the given number of ticks is from real-time (i.e., ConcentratorBase.RealTime).
SortMeasurement ( IMeasurement measurement ) : void

Sorts the IMeasurement placing the data point in its proper IFrame.
SortMeasurements ( IEnumerable measurements ) : void

Sorts each IMeasurement placing each data point in its proper IFrame.
Start ( ) : void

Starts the concentrator, if it is not already running.

Concentrator must be started by calling ConcentratorBase.Start method or setting ConcentratorBase.Enabled = true) before concentration will begin.

Stop ( ) : void

Stops the concentrator.

Protected Methods

Method Description
AssignMeasurementToFrame ( IFrame frame, IMeasurement measurement ) : void

Assigns IMeasurement to its associated IFrame.

Derived classes can choose to override this method to handle custom assignment of a IMeasurement to its IFrame. Default behavior simply assigns measurement to frame's keyed measurement dictionary: frame.Measurements[measurement.Key] = measurement;

ConcentratorBase ( ) : System

Creates a new ConcentratorBase.

Concentration will not begin until consumer "Starts" concentrator (i.e., calling ConcentratorBase.Start method or setting ConcentratorBase.Enabled = true).

ConcentratorBase ( int framesPerSecond, double lagTime, double leadTime ) : System

Creates a new ConcentratorBase from specified parameters.

framesPerSecond must be greater then 0.

lagTime must be greater than zero, but can be specified in sub-second intervals (e.g., set to .25 for a quarter-second lag time). Note that this defines time sensitivity to past timestamps.

leadTime must be greater than zero, but can be specified in sub-second intervals (e.g., set to .5 for a half-second lead time). Note that this defines time sensitivity to future timestamps.

Concentration will not begin until consumer "Starts" concentrator (i.e., calling ConcentratorBase.Start method or setting ConcentratorBase.Enabled = true).

CreateNewFrame ( Ticks timestamp ) : IFrame

Creates a new IFrame for the given timestamp.

Derived classes can override this method to create a new custom IFrame. Default behavior creates a basic Frame to hold synchronized measurements.

Dispose ( bool disposing ) : void

Releases the unmanaged resources used by the ConcentratorBase object and optionally releases the managed resources.
OnDiscardingMeasurements ( IEnumerable measurements ) : void

Raises the DiscardingMeasurements event.

Allows derived classes to raise a discarding measurements event.

OnProcessException ( MessageLevel level, Exception exception, string eventName = null, MessageFlags flags = MessageFlags.None ) : void

Raises the ProcessException event.

should be a constant string value associated with what type of message is being generated. In general, there should only be a few dozen distinct event names per class. Exceeding this threshold will cause the EventName to be replaced with a general warning that a usage issue has occurred.

OnUnpublishedSamples ( int seconds ) : void

Raises the UnpublishedSamples event.
PublishFrame ( IFrame frame, int index ) : void

Publish IFrame of time-aligned collection of IMeasurement values that arrived within the concentrator's defined ConcentratorBase.LagTime.

If user implemented publication function consistently exceeds available publishing time (i.e., 1 / ConcentratorBase.FramesPerSecond seconds), concentration will fall behind. A small amount of this time is required by the ConcentratorBase for processing overhead, so actual total time available for user function process will always be slightly less than 1 / ConcentratorBase.FramesPerSecond seconds.

Private Methods

Method Description
AttachToFrameRateTimer ( int framesPerSecond, int processingInterval ) : void
DetachFromFrameRateTimer ( int framesPerSecond, int processingInterval ) : void
MonitorUnpublishedSamples ( object sender, EventArgs e ) : void
OnProcessException ( Exception ex ) : void
PublishFrames ( ) : void
StartFramePublication ( object sender, EventArgs e ) : void

Method Details

AssignMeasurementToFrame() protected method

Assigns IMeasurement to its associated IFrame.
Derived classes can choose to override this method to handle custom assignment of a IMeasurement to its IFrame. Default behavior simply assigns measurement to frame's keyed measurement dictionary: frame.Measurements[measurement.Key] = measurement;
protected AssignMeasurementToFrame ( IFrame frame, IMeasurement measurement ) : void
frame IFrame The that is used.
measurement IMeasurement The type of to use."/>
return void

ConcentratorBase() protected method

Creates a new ConcentratorBase.
Concentration will not begin until consumer "Starts" concentrator (i.e., calling ConcentratorBase.Start method or setting ConcentratorBase.Enabled = true).
protected ConcentratorBase ( ) : System
return System

ConcentratorBase() protected method

Creates a new ConcentratorBase from specified parameters.

framesPerSecond must be greater then 0.

lagTime must be greater than zero, but can be specified in sub-second intervals (e.g., set to .25 for a quarter-second lag time). Note that this defines time sensitivity to past timestamps.

leadTime must be greater than zero, but can be specified in sub-second intervals (e.g., set to .5 for a half-second lead time). Note that this defines time sensitivity to future timestamps.

Concentration will not begin until consumer "Starts" concentrator (i.e., calling ConcentratorBase.Start method or setting ConcentratorBase.Enabled = true).

Specified argument is outside of allowed value range (see remarks).
protected ConcentratorBase ( int framesPerSecond, double lagTime, double leadTime ) : System
framesPerSecond int Number of frames to publish per second.
lagTime double Past time deviation tolerance, in seconds - this becomes the amount of time to wait before publishing begins.
leadTime double Future time deviation tolerance, in seconds - this becomes the tolerated +/- accuracy of the local clock to real-time.
return System

CreateNewFrame() protected method

Creates a new IFrame for the given timestamp.
Derived classes can override this method to create a new custom IFrame. Default behavior creates a basic Frame to hold synchronized measurements.
protected CreateNewFrame ( Ticks timestamp ) : IFrame
timestamp Ticks Timestamp for new in .
return IFrame

Dispose() public method

Releases all the resources used by the ConcentratorBase object.
public Dispose ( ) : void
return void

Dispose() protected method

Releases the unmanaged resources used by the ConcentratorBase object and optionally releases the managed resources.
protected Dispose ( bool disposing ) : void
disposing bool true to release both managed and unmanaged resources; false to release only unmanaged resources.
return void

MillisecondsFromRealTime() public method

Returns the deviation, in milliseconds, that the given number of ticks is from real-time (i.e., ConcentratorBase.RealTime).
public MillisecondsFromRealTime ( Ticks timestamp ) : double
timestamp Ticks Timestamp to calculate distance from real-time.
return double

OnDiscardingMeasurements() protected method

Raises the DiscardingMeasurements event.
Allows derived classes to raise a discarding measurements event.
protected OnDiscardingMeasurements ( IEnumerable measurements ) : void
measurements IEnumerable Enumeration of values being discarded.
return void

OnProcessException() protected method

Raises the ProcessException event.
should be a constant string value associated with what type of message is being generated. In general, there should only be a few dozen distinct event names per class. Exceeding this threshold will cause the EventName to be replaced with a general warning that a usage issue has occurred.
protected OnProcessException ( MessageLevel level, Exception exception, string eventName = null, MessageFlags flags = MessageFlags.None ) : void
level MessageLevel The to assign to this message
exception System.Exception Processing .
eventName string A fixed string to classify this event; defaults to null.
flags MessageFlags to use, if any; defaults to .
return void

OnUnpublishedSamples() protected method

Raises the UnpublishedSamples event.
protected OnUnpublishedSamples ( int seconds ) : void
seconds int Total number of unpublished seconds of data.
return void

PublishFrame() protected abstract method

Publish IFrame of time-aligned collection of IMeasurement values that arrived within the concentrator's defined ConcentratorBase.LagTime.
If user implemented publication function consistently exceeds available publishing time (i.e., 1 / ConcentratorBase.FramesPerSecond seconds), concentration will fall behind. A small amount of this time is required by the ConcentratorBase for processing overhead, so actual total time available for user function process will always be slightly less than 1 / ConcentratorBase.FramesPerSecond seconds.
protected abstract PublishFrame ( IFrame frame, int index ) : void
frame IFrame of measurements with the same timestamp that arrived within that are ready for processing.
index int Index of within a second ranging from zero to - 1.
return void

ResetStatistics() public method

Resets the statistics of the concentrator.
public ResetStatistics ( ) : void
return void

SecondsFromRealTime() public method

Returns the deviation, in seconds, that the given number of ticks is from real-time (i.e., ConcentratorBase.RealTime).
public SecondsFromRealTime ( Ticks timestamp ) : double
timestamp Ticks Timestamp to calculate distance from real-time.
return double

SortMeasurement() public method

Sorts the IMeasurement placing the data point in its proper IFrame.
public SortMeasurement ( IMeasurement measurement ) : void
measurement IMeasurement to sort.
return void

SortMeasurements() public method

Sorts each IMeasurement placing each data point in its proper IFrame.
public SortMeasurements ( IEnumerable measurements ) : void
measurements IEnumerable Collection of 's to sort.
return void

Start() public method

Starts the concentrator, if it is not already running.
Concentrator must be started by calling ConcentratorBase.Start method or setting ConcentratorBase.Enabled = true) before concentration will begin.
public Start ( ) : void
return void

Stop() public method

Stops the concentrator.
public Stop ( ) : void
return void