Module runtime 

Infrastructure for integrating time primitives into async runtimes.

This module provides the necessary components to bridge time-based operations with async runtime execution. The primary workflow involves:

1. Start with an InactiveClock that can be safely moved across threads
2. Activate it using InactiveClock::activate to get a Clock and ClockDriver
3. Use the ClockDriver to periodically advance timers in your runtime loop
4. Use the Clock for time operations like creating timers and measuring time

Integration with Runtimes

Different runtime architectures can integrate this module as follows:

Thread-per-core Runtimes

In thread-per-core architectures, each thread should own an isolated clock with its own timer storage. This eliminates cross-thread lock contention and scales linearly.

The pattern is to clone the InactiveClock, relocate each clone to its target thread using ThreadAware::relocate, and then activate:

let root = InactiveClock::default();

// Clone and relocate to each thread's affinity
let mut inactive_1 = root.clone();
inactive_1.relocate(Some(affinities[0]), affinities[0]);
let mut inactive_2 = root;
inactive_2.relocate(Some(affinities[1]), affinities[1]);

// On thread 1: activate and drive timers independently
let (clock_1, driver_1) = inactive_1.activate();

// On thread 2: activate and drive timers independently
let (clock_2, driver_2) = inactive_2.activate();

After relocation, each thread’s clock and driver operate on an independent set of timers. Timers registered on clock_1 are only visible to driver_1, and the other way around. Each driver must be advanced independently by its owning thread.

Multi-threaded Runtimes

In multi-threaded runtimes where tasks may run on any thread, activate once and share the clock across threads. The driver should be kept on a dedicated thread or task for timer advancement:

let (clock, driver) = InactiveClock::default().activate();

// Share `clock` across threads (it is Clone + Send + Sync)
// Keep `driver` on a single thread to advance timers

Structs

ClockDriver

Drives timer advancement for the clock.

ClockGone

Error returned when all owners of a clock have been dropped.

InactiveClock

An inactive clock that must be activated before time operations can be performed.

Isolated

Marker for an InactiveClock backed by per-core isolated timer storage.

Shared

Marker for an InactiveClock backed by a single shared timer set.