# SandClock ⏳
## Purpose
**SandClock** is a time-aware `HashMap` designed to track whether a given entity is still active.
You may find it useful for cases such as presence detection, ephemeral sessions, or activity timeouts.
### Quick Start
```rust
use sand_clock::prelude::*;
//Configure the clock, set the time-checking frequency :
let config = SandClockConfig::new().frequency(Duration::from_millis(200)); // or SandClockConfig::default();
//Default is set to 2000 milliseconds.
//Instantiate the SandClock, with the key type as generic argument.
let user_connection_base = SandClock::<String>::new(config)
.set_time_out_duration(Duration::from_secs(5))
.set_time_out_event(move |conn_update| match conn_update.event() {
ClockEvent::TimeOut => {
println!("No more known activity: [{:?}] has disconnected", conn_update.key());
}
})
.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 and requires no async runtime.
## 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 polling loop to monitor timeouts.
## Disclaimers
- SandClock uses a polling mechanism, so timeouts are not accurate to the millisecond.
**Do not use this crate if your application requires precise timeout accuracy.**
- This crate is currently in beta and has only been tested in my personal projects.
Use it at your own risk.
## License
This project is licensed under the MIT OR Apache-2.0 License.