Class TickTracker

Tracks publish timing to estimate output rate and derive a BlockStatus.

Inheritance
TickTracker
Implements
Namespace: MOSAIC.Components.Basics
Assembly: MOSAIC.dll
Syntax
public class TickTracker : ITickTracker
Remarks

TickTracker collects a rolling window of recent tick timestamps (in seconds) and uses them to estimate the current output rate. It is used by processing blocks (e.g., BaseBlock) to provide real-time monitoring information such as "Idle", "Lagging", or "Normal".

Rate estimation: The current rate is computed from the oldest and newest timestamps in the window as: (n - 1) / (last - first), where n is the number of recorded ticks currently represented in the buffer.

Idle detection: A block is considered idle when the current time exceeds lastTick + 10 / desiredRate. This means the idle timeout scales with the desired rate.

Threading: All state access is synchronized via an internal lock, making this type safe to use from multiple threads (e.g., background processing thread + UI timer thread).

Timestamps: Ticks are recorded using a monotonic Stopwatch and expressed as UNIX-like seconds (seconds since 1970-01-01 UTC), which avoids issues with wall-clock adjustments while still producing globally interpretable values.

Fields

_sync

Lock that synchronizes all access to _timestamps and LastTick.

Declaration
private readonly object _sync
Field Value
Type Description
object

_timestamps

Rolling window of recent tick timestamps used for rate estimation.

Declaration
private readonly CircularBuffer<double> _timestamps
Field Value
Type Description
CircularBuffer<double>

sw

Monotonic stopwatch shared across all TickTracker instances, started once at process initialization.

Declaration
private static readonly Stopwatch sw
Field Value
Type Description
Stopwatch

t0

Wall-clock anchor captured at startup, expressed as UNIX seconds. Combined with sw to produce monotonic, UNIX-like timestamps.

Declaration
private static readonly double t0
Field Value
Type Description
double

Properties

CurrentRate

Gets the estimated output rate in Hertz (ticks per second) based on recently recorded ticks.

Declaration
public double CurrentRate { get; }
Property Value
Type Description
double
Remarks

The rate is computed as (n - 1) / (last - first) using the oldest and newest timestamps currently represented by the rolling window.

Returns 0 if fewer than two ticks have been recorded, or if the computed time span is not positive.

LastTick

Gets the timestamp (seconds) of the most recently recorded tick.

Declaration
public double LastTick { get; private set; }
Property Value
Type Description
double
Remarks

The value is expressed in UNIX-like seconds as returned by Now(). The initial value is -1 until the first call to RecordTick().

Methods

GetStatus(double, bool)

Computes the current BlockStatus based on tick history, desired rate, and stumble state.

Declaration
public BlockStatus GetStatus(double desiredRate, bool isStumbling = false)
Parameters
Type Name Description
double desiredRate

Desired rate in Hertz used to determine idle/lagging thresholds. Should be greater than 0.

bool isStumbling

Indicates whether the caller detected a stumble condition (e.g., contention when attempting to publish).

Returns
Type Description
BlockStatus

One of:

  • Idle if fewer than two ticks exist or the stream is idle.
  • Stumbling if isStumbling is true.
  • Lagging if the current rate is below threshold.
  • Normal otherwise.
Remarks

The method first checks whether any meaningful history exists (at least two ticks). If not, it returns Idle. Otherwise, it prioritizes isStumbling over rate-based classifications.

IsIdle(double)

Determines whether the tracked stream is considered idle relative to a desired rate.

Declaration
public bool IsIdle(double desiredRate)
Parameters
Type Name Description
double desiredRate

Desired rate in Hertz used to compute the inactivity threshold. Must be greater than 0.

Returns
Type Description
bool

true if the current time exceeds last + 10 / desiredRate; otherwise, false.

Remarks

The idle threshold scales with desiredRate. For example, at 200 Hz the threshold is 0.05 s; at 20 Hz it is 0.5 s.

This method assumes desiredRate is positive. Passing 0 (or negative values) can result in invalid thresholds (division by zero or inverted timeouts).

IsLagging(double)

Determines whether the current estimated rate is lagging relative to a desired rate.

Declaration
public bool IsLagging(double desiredRate)
Parameters
Type Name Description
double desiredRate

Desired rate in Hertz used as the reference.

Returns
Type Description
bool

true if CurrentRate is positive and less than 95% of desiredRate; otherwise, false.

Remarks

A small tolerance (5%) is applied to avoid oscillating between statuses due to minor jitter.

Now()

Returns a monotonic, UNIX-like timestamp in seconds.

Declaration
public static double Now()
Returns
Type Description
double

The current time in seconds, represented as an offset from 1970-01-01 UTC, with monotonic progression.

Remarks

This method combines a wall-clock anchor (t0) with a monotonic stopwatch delta to produce timestamps that are stable against wall-clock corrections (e.g., NTP adjustments) while remaining interpretable as UNIX-like seconds.

The returned value is suitable for interval timing and rate estimation.

RecordTick()

Records a new tick at the current time.

Declaration
public void RecordTick()
Remarks

The recorded time is obtained from Now() and stored in a rolling window of recent timestamps. This method updates LastTick and contributes to CurrentRate estimation.

Implements

ITickTracker

Search documentation

Start typing to search the documentation.