GhostTick 1.0.4

GhostTick

A high-precision timer toolkit for .NET that delivers events through System.Threading.Channels.

Features

• Sub-millisecond precision — hybrid sleep + busy-spin strategy; Reduce OS timer granularity from ~15 ms to ~1 ms on Windows
• Channel-based API — consumers receive TimerEvent values via ChannelReader<TimerEvent>, keeping the timer thread fully decoupled from consumer latency
• Drift correction — GhostTicker computes every target as start + seq × interval, so accumulated error stays bounded over time
• Multi-targeting — netstandard2.0, net8.0, net10.0

Installation

dotnet add package GhostTick

Quick start

Repeating ticker

using var ticker = new GhostTicker(TimeSpan.FromMilliseconds(16.67)); // ~60 fps
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

await foreach (var evt in ticker.Reader.ReadAllAsync(cts.Token))
{
    // evt.Sequence — monotonic tick counter (gaps indicate dropped ticks)
    // evt.Drift    — how late this tick fired vs its scheduled time
    Render(evt.Sequence);
}

API reference

TimerEvent

GhostTicker

new GhostTicker(TimeSpan interval, GhostTickerOptions? options = null)

Options

GhostTickerOptions

Slow consumers and back-pressure

The timer thread calls TryWrite and never blocks. When the channel is full:

• DropOldest (default) — oldest pending tick is discarded; consumer always gets the freshest event. Gaps in Sequence reveal how many ticks were dropped.
• DropNewest — new tick is discarded; consumer drains at its own pace.
• Wait — has no effect on the timer thread; TryWrite is always used so ticks are still dropped when the channel is full.

Fan-out to multiple consumers

ChannelReader<T> delivers each item to exactly one reader. For broadcast semantics, dispatch manually:

using var ticker = new GhostTicker(TimeSpan.FromMilliseconds(100));

var ch1 = Channel.CreateBounded<TimerEvent>(4);
var ch2 = Channel.CreateBounded<TimerEvent>(4);

// Dispatcher
_ = Task.Run(async () =>
{
    await foreach (var evt in ticker.Reader.ReadAllAsync())
    {
        ch1.Writer.TryWrite(evt);
        ch2.Writer.TryWrite(evt);
    }
    ch1.Writer.Complete();
    ch2.Writer.Complete();
});

// Consumer A
_ = Task.Run(async () =>
{
    await foreach (var evt in ch1.Reader.ReadAllAsync())
        Console.WriteLine($"A #{evt.Sequence}");
});

Benchmarks

Environment: Windows 11, 13th Gen Intel Core i9-13980HX, .NET 10.0.6, BenchmarkDotNet v0.15.8

Fire accuracy — error vs scheduled time (µs, lower is better)

100 samples per cell.

At 1 ms delay, GhostTicker mean error is 0.3 µs vs ~14,600 µs for all others — a ~49,000× improvement.

Tick cadence — 100 consecutive ticks, total wall time (ms, lower is better)

GhostTicker uses a dedicated AboveNormal-priority thread; others depend on the thread pool.

Run benchmarks locally:

dotnet run --project benchmarks/GhostTick.Benchmarks -c Release

Examples

See examples/GhostTick.Examples for runnable examples covering all features.

dotnet run --project examples/GhostTick.Examples

License

MIT

GhostTick（中文）

适用于 .NET 的高精度计时工具库，通过 System.Threading.Channels 传递事件。

功能特性

• 亚毫秒级精度 — 采用休眠 + 忙等待混合策略；将 Windows 的 OS 定时器粒度从约 15 ms 降至约 1 ms
• 基于 Channel 的 API — 消费者通过 ChannelReader<TimerEvent> 接收 TimerEvent，计时线程与消费者延迟完全解耦
• 漂移修正 — GhostTicker 将每个目标时刻计算为 start + seq × interval，无论运行多久，累积误差始终有界
• 多目标框架 — netstandard2.0、net8.0、net10.0

安装

dotnet add package GhostTick

快速上手

周期性 Ticker

using var ticker = new GhostTicker(TimeSpan.FromMilliseconds(16.67)); // ~60 fps
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

await foreach (var evt in ticker.Reader.ReadAllAsync(cts.Token))
{
    // evt.Sequence — 单调递增的 tick 计数器（序号出现间隙表示有 tick 被丢弃）
    // evt.Drift    — 该 tick 相对于计划触发时刻的延迟
    Render(evt.Sequence);
}

API 参考

TimerEvent

GhostTicker

new GhostTicker(TimeSpan interval, GhostTickerOptions? options = null)

选项

GhostTickerOptions

慢消费者与背压

计时线程调用 TryWrite 且永不阻塞。channel 满时：

• DropOldest（默认）— 丢弃最旧的待处理 tick，消费者始终获得最新事件。Sequence 出现间隙即可得知丢弃了多少 tick。
• DropNewest — 丢弃新到达的 tick，消费者按自身速度消费。
• Wait — 对计时线程无效；始终使用 TryWrite，channel 满时 tick 仍会被丢弃。

广播给多个消费者

ChannelReader<T> 每个事件只投递给一个读取者。如需广播语义，可手动分发：

using var ticker = new GhostTicker(TimeSpan.FromMilliseconds(100));

var ch1 = Channel.CreateBounded<TimerEvent>(4);
var ch2 = Channel.CreateBounded<TimerEvent>(4);

// 分发器
_ = Task.Run(async () =>
{
    await foreach (var evt in ticker.Reader.ReadAllAsync())
    {
        ch1.Writer.TryWrite(evt);
        ch2.Writer.TryWrite(evt);
    }
    ch1.Writer.Complete();
    ch2.Writer.Complete();
});

// 消费者 A
_ = Task.Run(async () =>
{
    await foreach (var evt in ch1.Reader.ReadAllAsync())
        Console.WriteLine($"A #{evt.Sequence}");
});

基准测试

环境：Windows 11，13th Gen Intel Core i9-13980HX，.NET 10.0.6，BenchmarkDotNet v0.15.8

触发精度 — 相对计划时刻的误差（µs，越低越好）

每格 100 个样本。

在 1 ms 延迟下，GhostTicker 均值误差为 0.3 µs，其他方案约为 14,600 µs — 提升约 49,000×。

Tick 节奏 — 100 次连续 tick 的总耗时（ms，越低越好）

GhostTicker 使用独立的 AboveNormal 优先级线程；其他方案依赖线程池。

本地运行基准测试：

dotnet run --project benchmarks/GhostTick.Benchmarks -c Release

示例

可运行示例请参见 examples/GhostTick.Examples，涵盖所有功能。

dotnet run --project examples/GhostTick.Examples

许可证

MIT