# I/O Timer [](https://docs.rs/io-timer/latest/io_timer) [](https://matrix.to/#/#pimalaya:matrix.org)
Set of **I/O-free** Rust coroutines to manage timers, based on [io-stream](https://github.com/pimalaya/io-stream).
This library allows you to manage timers using an I/O-agnostic approach, based on 3 concepts:
### Coroutine
A coroutine is an *I/O-free*, *resumable* and *composable* state machine that **emits I/O requests**. A coroutine is considered *terminated* when it does not emit I/O requests anymore.
*See available coroutines at [./src](https://github.com/pimalaya/io-timer/tree/master/src).*
### Runtime
A runtime contains all the I/O logic, and is responsible for **processing I/O requests** emitted by coroutines.
*See available runtimes at [pimalaya/io-stream](https://github.com/pimalaya/io-stream/tree/master/src/runtimes).*
### Loop
The loop is the glue between coroutines and runtimes. It makes the coroutine progress while allowing runtime to process I/O.
## Examples
### Standard blocking client using TCP
```rust,ignore
use std::net::TcpStream;
use io_stream::runtimes::std::handle;
use io_timer::client::coroutines::{GetTimer, StartTimer};
let mut stream = TcpStream::connect("localhost:1234").unwrap();
// start the timer
let mut arg = None;
let mut start = StartTimer::new();
while let Err(io) = start.resume(arg.take()) {
arg = Some(handle(&mut stream, io).unwrap());
}
// wait few seconds, then get the timer
let mut arg = None;
let mut get = GetTimer::new();
let timer = loop {
match get.resume(arg.take()) {
Ok(timer) => break timer,
Err(io) => arg = Some(handle(&mut stream, io).unwrap()),
}
};
```
*See complete example at [./examples/std-tcp.rs](https://github.com/pimalaya/io-timer/blob/master/examples/std-tcp.rs).*
### Tokio async server using Unix sockets
```rust,ignore
use std::{sync::Arc, time::Duration};
use io_stream::runtimes::tokio::handle;
use io_timer::{
server::coroutines::HandleRequest,
timer::{TimerConfig, TimerCycles, TimerLoop},
Timer,
};
let config = TimerConfig {
cycles: TimerCycles::from([("Work", 2).into(), ("Rest", 3).into()]),
cycles_count: TimerLoop::Infinite,
};
let timer = Arc::new(tokio::sync::Mutex::new(Timer::new(config)));
// use an unbounded channel for receiving timer events
let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
// start the timer event notifier
tokio::spawn(async move {
loop {
let _event = rx.recv().await.unwrap();
// do whatever with the event
}
});
// define and spawn the timer tick
// this is needed to update the internal state of the timer
tokio::spawn({
let timer = timer.clone();
let tx = tx.clone();
async move {
loop {
let mut timer = timer.lock().await;
let events = timer.update();
drop(timer);
for event in events {
tx.send(event).unwrap();
}
// the timer can be refreshed every seconds
tokio::time::sleep(Duration::from_secs(1)).await;
}
}
});
// listen to the unix socket for client <-> server communication
let listener = tokio::net::UnixListener::bind("/tmp/timer.sock").unwrap();
let (mut stream, _) = listener.accept().await.unwrap();
loop {
let mut arg = None;
let mut handler = HandleRequest::new();
let events = loop {
let mut timer = timer.lock().await;
let output = handler.resume(&mut timer, arg.take());
drop(timer);
match output {
Ok(events) => break events,
Err(io) => arg = Some(handle(&mut stream, io).await.unwrap()),
}
};
for event in events {
tx.send(event).unwrap();
}
}
```
*See complete example at [./examples/tokio-unix.rs](https://github.com/pimalaya/io-timer/blob/master/examples/tokio-unix.rs).*
### More examples
See projects built at the top of this library:
- [comodoro](https://github.com/pimalaya/comodoro): CLI to manage timers
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that helped the project to receive financial support from various programs:
- [NGI Assure](https://nlnet.nl/project/Himalaya/) in 2022
- [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/) in 2023
- [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/) in 2024 *(still ongoing)*
If you appreciate the project, feel free to donate using one of the following providers:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/soywod)
[](https://www.buymeacoffee.com/soywod)
[](https://liberapay.com/soywod)
[](https://thanks.dev/soywod)
[](https://www.paypal.com/paypalme/soywod)