TimerWheel 0.1.0

dotnet add package TimerWheel --version 0.1.0
                    
NuGet\Install-Package TimerWheel -Version 0.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="TimerWheel" Version="0.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="TimerWheel" Version="0.1.0" />
                    
Directory.Packages.props
<PackageReference Include="TimerWheel" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add TimerWheel --version 0.1.0
                    
#r "nuget: TimerWheel, 0.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package TimerWheel@0.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=TimerWheel&version=0.1.0
                    
Install as a Cake Addin
#tool nuget:?package=TimerWheel&version=0.1.0
                    
Install as a Cake Tool

TimerWheel

A caller-driven hashed timing wheel for .NET, allocation-free once warm. No background threads, no internal scheduling and no clock ownership.

Designed for single-threaded event loops, simulations and deterministic testing where the host controls time and execution. Not thread-safe: schedule, cancel and poll from one thread (the loop's).

  • O(1) scheduling and cancellation. Timers occupy a reusable slab of parallel arrays, linked into wheel spokes. Scheduling is amortized O(1): the slab doubles when full, so allocations stop once it is warm (initialCapacity sizes it up front).
  • Generation-safe handles. Timer IDs carry a generation, preventing stale handles from canceling timers assigned to reused slots.
  • Efficient time advancement. An occupancy bitmap skips empty spokes, making large time jumps cost O(spokes / 64 + timers in the spokes visited), rather than O(ticks).
  • Optimizing for responsiveness. Bound callbacks per poll to prevent timer bursts monopolizing the event loop. Deferred timers retain deadline order, to the spoke; newer timers never overtake older due timers.
  • Bounded, lossless delivery. Per-poll delivery limits defer excess timers without losing them. When timers fall due faster than polls deliver them, the backlog drains oldest first, and later-due timers wait until it clears.
  • Safe callbacks. Timers scheduled during delivery, including zero-period recurring timers, are deferred to the next poll. Cancellation takes effect immediately, even for timers already collected for delivery. A callback must not poll the wheel delivering to it.
  • Exception-safe delivery. If a delivery sink throws, the wheel remains consistent. Undelivered timers retain their priority on the next poll.

Design philosophy

TimerWheel deliberately separates time management from execution.

The host owns the clock, decides when the wheel advances, and determines where callbacks execute. TimerWheel manages deadlines and expiration without imposing a threading model, event loop or scheduling discipline.

This makes it suitable for embedding into existing runtimes rather than competing with them.

Time is a long (e.g. UTC ticks) supplied by you. A timer fires on the first poll at or past its exact deadline; 2^shift time units set the width of a spoke, trading scan cost against how far one revolution of the wheel reaches.

using TimerWheel;

var wheel = new TimerWheel<string>(start: now, resolutionShift: 10, spokes: 512);
long id = wheel.Schedule(now + TimeSpan.FromSeconds(1).Ticks, "flush batch");
// wheel.Cancel(id);

var sink = new Dispatch();
wheel.Poll(now + TimeSpan.FromSeconds(2).Ticks, ref sink);   // delivers "flush batch"

struct Dispatch : ITimerSink<string>
{
    public void OnExpired(long timerId, in string payload) => Console.WriteLine(payload);
}

Build

dotnet test TimerWheel.slnx

License

MIT. See LICENSE.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0 95 11/2/2026