Skip to content

feature: Support wall-clock timers in addition to relative ones - #51

Merged
thedmi merged 1 commit into
masterfrom
feat/wall-clock-timers
Aug 14, 2026
Merged

feature: Support wall-clock timers in addition to relative ones#51
thedmi merged 1 commit into
masterfrom
feat/wall-clock-timers

Conversation

@thedmi

@thedmi thedmi commented Aug 14, 2026

Copy link
Copy Markdown
Owner

Closes #49

Added

  • ITimerService.StartSingleShot(DateTimeOffset deadline, Func<Task> callback, string? discriminator = null):
    wall-clock deadline timers. The wall clock is re-read on every wake-up, so a backward clock step
    (e.g. NTP stepping) cannot make a timer fire before its deadline. Guarantee is never early only —
    a forward step means the timer is already late and fires on wake-up.
  • TimerReference.Deadline (DateTimeOffset?), non-null for deadline timers.
  • FakeTimerService supports deadline timers; firing stays manual via ExecuteAsync/ExecuteAllAsync.
  • TimerService accepts an optional TimeProvider (test seam, defaults to TimeProvider.System).
  • Dependency Microsoft.Bcl.TimeProvider for netstandard2.0 only.

Changed

  • BREAKING TimerReference.Timeout widened from TimeSpan to TimeSpan?; it is null for deadline
    timers. Exactly one of Timeout and Deadline is non-null. Source- and binary-breaking for any
    code reading Timeout.
  • BREAKING ITimerService gained a member. Third-party implementations must implement the deadline
    overload; a default interface implementation is not possible on netstandard2.0.
  • The relative StartSingleShot(TimeSpan, ...) overload is unchanged and keeps its monotonic guarantee.
    Both overloads now document which clock domain their guarantee lives in.
  • Timer debug log messages now describe the timer as either timeout <x> or deadline <t>.

Removed

  • BREAKING FakeTimerService.StartSingleShot(TimeSpan, Func<Task>), the Capsule.Core 3.0.0
    compatibility overload. Source-compatible (calls bind to the optional-parameter overload), but
    binary-breaking for assemblies compiled against Capsule.Testing 3.0.0 — recompile.

@thedmi
thedmi merged commit fdba09f into master Aug 14, 2026
3 checks passed
@thedmi
thedmi deleted the feat/wall-clock-timers branch August 14, 2026 11:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Timers can fire "early" when the system clock is stepped

1 participant