# ztimer
[](https://crates.io/crates/ztimer)
[](https://docs.rs/ztimer)
`ztimer` (Zero-Overhead Timer) provides a highly efficient, near O(1) timer system for Rust applications. It assumes that, in most use cases, the number of timer expirations is limited, eliminating the need to support a huge number of expirations, and reducing overhead.
## Features
- **Efficient Timer**: Implements a near O(1) timer suitable for systems that require minimal overhead.
- **Auto-Drop Timer**: Automatically cancels the underlying timer if the `AutoDropTimer` instance is dropped before expiration.
- **Clock Management**: A `Clock` can manage multiple timers within the same process, handling multiple timer groups based on your application needs.
- **Cancelable Timers**: `Timer` instances can be canceled before they expire, avoiding callback invocations.
- **Thread-Safe Execution**: Manages timers across threads using safe abstractions and provides support for non-blocking tick processing.
## Concepts
- **`Timer`**: A direct reference to a real timer instance stored in a `Clock`. It holds a callback that gets invoked upon expiration and can be canceled.
- **`AutoDropTimer`**: A wrapper around `Timer` that cancels the timer automatically when dropped, preventing further callback invocations.
- **`Clock`**: Groups and manages timers. A `Clock` can hold several timers, and you can have multiple `Clock` instances in a process.
## Usage
### Example: Using `AutoDropTimer`
Here’s an example of how to use `AutoDropTimer` to manage timers in your application:
```rust
use std::thread::sleep;
use std::time::Duration;
use ztimer::{AutoDropTimer, Clock};
// Create a clock instance
let clock = Clock::new(None).unwrap();
// Create some timers
let t1 = AutoDropTimer::new(clock, Duration::from_secs(1), || {
println!("T1 expired");
}, "t1".to_string()).unwrap();
let t2 = AutoDropTimer::new(clock, Duration::from_secs(10), || {
println!("T2 expired");
}, "t2".to_string()).unwrap();
// Use sleep to simulate the passage of time
sleep(Duration::from_secs(2)); // T1 expires
assert_eq!(clock.len(), 2);
```
### Example: Waiting for the Underlying Timer Thread Before Termination
If your application needs to wait for the underlying timer thread before exiting, here's what you should do:
```rust
use ztimer::Clock;
// Create a clock instance
let _ = Clock::new(None);
// Before terminating:
let tjh = Clock::take_thread_handle();
Clock::terminate_for_process_exit();
let _ = tjh.unwrap().join();
```
## License
This crate is licensed under the Apache License, Version 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0) for details.