Crate sand_clock

Crate sand_clock 

Source
Expand description

§SandClock ⏳

§Purpose

SandClock is a time-aware HashMap designed to track whether a given entity is still active. You may find it useful for usecases such as presence detection, ephemeral sessions, or activity timeouts.

§Quick start

 use sand_clock::prelude::*;
 use std::time::Duration;

 //Configure the clock, set the time-checking frequency :
 let config = SandClockConfig::new().frequency(Duration::from_millis(200)); // ou SandClockConfig::default();
 //Default is set to 2 seconds.

//Instantiate the SandClock, with the key type as generic argument.
let user_connection_base = SandClock::<String>::new(config)
   .set_time_out_event(move |clock_event| match clock_event {
       ClockEvent::TimeOut(key) => {
           println!("No more known activity: [{:?}] has disconnected", key);
       }
        ClockEvent::SandClockDrop => {}
   })
   .set_time_out_duration(Duration::from_millis(15_000))
   .build()
   .unwrap();

// *Signals* :
// New activity !
user_connection_base.insert_or_update_timer("alf".to_string());

// Activity continue !
user_connection_base.insert_or_update_timer("alf".to_string());

⚙️ Runtime-free design: SandClock uses a single background thread for polling and rayon::ThreadPool to run the timeouts callbacks.

  • SandClock — main entry point, used to insert or update tracked entities
  • SandClockConfig — configures the loop frequency
  • ClockEvent — type of events triggered on timeout
  • [TimeOutUpdate] — passed to your callback when a timeout occurs

§How it works

Each tracked entity can periodically signal the SandClock using its associated key.

If signaling stops within a defined timeout, SandClock automatically triggers a callback, notifying the caller that the entity is no longer active. The entity is then removed from the map.

Internally, SandClock uses a lightweight polling loop to monitor timeouts + rayon::ThreadPool to manage timout-callbacks.

§Runtime & Safety

  • 🧩 Thread-safe: Yes – SandClock can be safely shared across threads.
  • 🔀 Send + Sync: Yes – core types are Send and Sync, usable in multithreaded contexts.
  • 🚫 no_std: Not supported – standard library is required (std::thread, std::time, etc.).
  • 🧵Background thread: ✅
  • ⚙️ Runtime dependency: ❌

Re-exports§

pub use config::SandClockConfig;
pub use errors::SandClockError;
pub use user_table::ClockEvent;
pub use user_table::SandClock;
pub use user_table::SandClockInsertion;

Modules§

config
SandClock Configuration
errors
prelude
timer_loop
user_table