Module maitake::time

source ·
Expand description

Utilities for tracking time and constructing system timers.


This module contains the following Futures:

  • Sleep, a future which completes after a specified duration,
  • Timeout, which wraps another Future to limit the duration it can run for.


The Sleep and Timeout futures do not complete on their own. Instead, they must be driven by a Timer, which tracks the current time and notifies time-based futures when their deadlines are reached.

The Timer struct implements a hierarchical timer wheel, a data structure for tracking large numbers of timers efficiently. It is used to create Sleeps and Timeouts, and notify them when their deadlines complete. In order to be used, a Timer must be driven by a hardware time source. See the Timer documentation for more information on using this type to implement a system timer.

Global Timers

In most cases, it is desirable to have a single global timer instance that drives all time-based futures in the system. In particular, creating new Sleep and Timeout futures typically requires a reference to a Timer instance, which can be inconvenient to pass around to the points in a system where Sleep and Timeout futures are created.

Therefore, the maitake timer also includes support for setting a global timer, using the set_global_timer function. Once a global timer has been initialized, the sleep() and timeout() free functions in this module can be used to create time-based futures without a reference to a Timer instance. These functions will always create futures bound to the global default timer.

Note that a global default timer can only be set once. Subsequent calls to set_global_timer after a global timer has been initialized will return an error.


  • Clocks provide a mechanism for tracking the current time.
  • Timeouts limit the amount of time a Future is allowed to run before it completes.