A timer wheel is a vector-of-collections-of timers to fire. Timers may be one-shot or recurring, and may be scheduled arbitrarily far in the future.

A timer wheel is configured with a spoke count and resolution:

• The spoke count determines the size of the timer vector.

  A larger spoke count will require more memory, but will result in less insert contention.

• The resolution determines the duration of time that each spoke corresponds to, and thus how often timers are checked for expiry.

  For example, in a timer wheel with a resolution of 1 second, a timer that is scheduled to fire at 8.4 o'clock will end up firing around 9.0 o'clock instead (that is, on the 1 second-boundary).

  A larger resolution will result in more insert contention and less accurate timers, but will require fewer wakeups by the timeout thread.

The timeout thread has some important properties:

• There is only one, and it fires expired timers synchronously. If your timer actions execute quicky, you can register them directly. Otherwise, consider registering an action that enqueues the real action to be performed on a job queue.
• A synchronous exception thrown by a registered timer will bring the timeout thread down, and the exception will be propagated to the thread that created the timer wheel. If you want to log and ignore exceptions, for example, you will have to bake this into the registered actions yourself.

API summary

A timer wheel config.

• spokes must be ∈ [1, maxBound], and is set to 1024 if invalid.
• resolution must be ∈ (0, ∞], and is set to 1 if invalid.

API summary

A number of seconds, with nanosecond precision.

You can use numeric literals to construct a value of this type, e.g. 0.5.

Otherwise, to convert from a type like Int or Double, you can use the generic numeric conversion function realToFrac.

A registered timer, parameterized by the result of attempting to cancel it:

• A one-shot timer may only be canceled if it has not already fired.
• A recurring timer can always be canceled.

API summary

Create a timer wheel in a scope.

Perform an action with a timer wheel.

Get the number of timers in a timer wheel.

O(1).

register wheel delay action registers action in wheel to fire after delay seconds.

When canceled, the timer returns whether or not the cancelation was successful; False means the timer had either already fired, or had already been canceled.

Like register, but for when you don't intend to cancel the timer.

recurring wheel action delay registers action in wheel to fire in delay seconds, and every delay seconds thereafter.

Like recurring, but for when you don't intend to cancel the timer.

Cancel a timer.