Module maitake::time

Utilities for tracking time and constructing system timers.

Futures

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.

Timers

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.

Modules

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

Structs

• AlreadyInitialized
  Errors returned by set_global_timer.
• Clock
  A hardware clock definition.
• Duration
  A Duration type to represent a span of time, typically used for system timeouts.
• Instant
  A measurement of a monotonically nondecreasing Clock. Opaque and useful only with Duration.
• Sleep
  A Future that completes after a specified Duration.
• Timeout
  A Future that requires an inner Future to complete within a specified Duration.
• Timer
  A Timer tracks the current time, and notifies Sleep and Timeout futures when they complete.
• Turn
  Represents a single turn of the timer wheel.

Enums

• TimerError
  Errors returned by Timer::try_sleep, Timer::try_timeout, and the global try_sleep and try_timeout functions.

Functions

• set_global_timer
  Sets a Timer as the global default timer.
• sleep
  Returns a Future that completes after the specified Duration.
• timeout
  Requires the provided Future to complete before the specified Duration has elapsed.
• try_sleep
  Returns a Future that completes after the specified Duration.
• try_timeout
  Requires the provided Future to complete before the specified Duration has elapsed.