Module tw_timer 

Timer wheels

Design Considerations

This module implements a hierarchical timer wheel data structure optimised for efficient expiration of large numbers of timers in O(1) amortised time. Key design decisions:

• Hierarchical levels: Multiple levels with decreasing resolution enable handling both near-term (high precision) and far-future (lower precision) timers efficiently without requiring a massive single-level array.

• Doubly-linked lists per slot: Each slot in each level contains a doubly-linked list of timers, enabling O(1) stop (and removal) of arbitrary timers.

• Head entries: Every slot is pre-initialised with a head entry, eliminating the need for special-case list manipulation.

• Cascading: When a timer expires in a coarser level, it is re-added to finer levels (if available), until it is determined to the caller as having expired. This still allows efficient processing of many timers far in the future whilst still allowing them to have the fine expiration resolution.

• Generic context: The context type T is associated with each timer, allowing arbitrary application data to be attached without additional allocation.

Structs

TimerHandle

Timer handle

TimerWheel

Hierarchical timer wheel

Enums

StartTimerError

Add timer error