indicator-stream

StreamHub indicator development

Provider selection

Performance requirements

Target: StreamHub ≤ 1.5x slower than Series.

Forbid O(n²) recalculation — rebuild entire history on each tick:

// WRONG
for (int k = 0; k <= i; k++) { subset.Add(cache[k]); }
var result = subset.ToIndicator();

O(1) incremental update:

// CORRECT
_avgGain = ((_avgGain * (period - 1)) + gain) / period;

Use RollingWindowMax/Min utilities instead of O(n) linear scans.

RollbackState pattern

Override when maintaining stateful fields. The base class computes restoreIndex via IndexBefore before calling this method. restoreIndex is the last ProviderCache index to preserve, or -1 to reset everything.

protected override void RollbackState(int restoreIndex)
{
    _window.Clear();
    if (restoreIndex < 0) return;
    int startIdx = Math.Max(0, restoreIndex + 1 - LookbackPeriods);
    for (int p = startIdx; p <= restoreIndex; p++)
        _window.Add(ProviderCache[p].Value);
}

Replay up to restoreIndex (inclusive). The item at the rollback timestamp is recalculated via normal processing.

Testing requirements

• Inherit StreamHubTestBase
• Abstract method (compile error if missing): ToStringOverride_ReturnsExpectedName()
• Implement ONE observer interface:
  • ITestChainObserver (most indicators — chain input): inherits ITestQuoteObserver, adds ChainObserver_ChainedProvider_MatchesSeriesExactly()
  • ITestQuoteObserver (direct quote input only): QuoteObserver_WithWarmupLateArrivalAndRemoval_MatchesSeriesExactly(), WithCachePruning_MatchesSeriesExactly()
• If hub acts as chain provider, also implement ITestChainProvider: ChainProvider_MatchesSeriesExactly()

Required implementation

• Source code: src/**/{IndicatorName}.StreamHub.cs file exists
  • Uses appropriate provider base (ChainHub or QuoteProvider)
  • Validates parameters in constructor; calls Reinitialize() as needed
  • Implements O(1) state updates; avoids O(n²) recalculation
  • Overrides RollbackState() when maintaining stateful fields
  • Overrides ToString() with concise hub name
• Unit testing: tests/indicators/**/{IndicatorName}.StreamHub.Tests.cs exists
  • Inherits StreamHubTestBase with correct test interfaces
  • Comprehensive rollback validation present
  • Verifies Series parity
• Catalog registration: Registered in Catalog.Listings.cs
• Performance benchmark: Add to tools/performance/Perf.Stream.cs
• Public documentation: Update docs/indicators/{IndicatorName}.md
• Regression tests: Add to tests/indicators/**/{IndicatorName}.Regression.Tests.cs
• Migration guide: Update docs/migration.md for notable and breaking changes from v2

Examples

• Chain: src/e-k/Ema/Ema.StreamHub.cs

• Complex state: src/a-d/Adx/Adx.StreamHub.cs

• Rolling window: src/a-d/Chandelier/Chandelier.StreamHub.cs

• Compound hub: src/s-z/StochRsi/StochRsi.StreamHub.cs

• Provider selection

• Rollback patterns

• Performance patterns

• Compound hubs

Constraints

• O(n²) recalculation is forbidden; all updates must be O(1)
• RollbackState(int restoreIndex) receives the last index to preserve (-1 = reset all); replay is inclusive of restoreIndex, exclusive of the rollback timestamp
• Series parity required: results must be numerically identical to StaticSeries