https://github.com/davidzeng0/aurora
I/O at the speed of light. Safe abstractions for io_uring on stackful coroutines.
https://github.com/davidzeng0/aurora
async coroutines io-uring rust stackful
Last synced: 8 months ago
JSON representation
I/O at the speed of light. Safe abstractions for io_uring on stackful coroutines.
- Host: GitHub
- URL: https://github.com/davidzeng0/aurora
- Owner: davidzeng0
- License: mit
- Created: 2023-10-08T01:20:51.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-14T00:54:56.000Z (over 1 year ago)
- Last Synced: 2025-02-14T01:38:49.460Z (over 1 year ago)
- Topics: async, coroutines, io-uring, rust, stackful
- Language: Rust
- Homepage: https://davidzeng0.github.io/aurora
- Size: 227 KB
- Stars: 9
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# xx-pulse
`msrv: 1.80.0 stable`
[Documentation](https://davidyz0.github.io/aurora)
I/O at the speed of light. See [benchmarks](./benchmarks/README.md).
- [Getting started](#getting-started)
- [Thread local safety](#thread-local-safety)
- [Motivation and use cases](./Motivation.md)
### Note:
This library is not ready for production use. Many semantics and APIs are still under development.
This library is currently only available for Linux (kernel 5.6+, other OS's contributions are welcome).
For Windows and Mac users, running in Docker or WSL also work.
The [rust](https://hub.docker.com/_/rust) docker container is sufficient.
### Getting started
The following is a simple echo server example
#### Add dependency
```sh
# support lib and async impls
cargo add --git https://github.com/davidyz0/xx-core.git xx-core
# i/o engine and driver
cargo add --git https://github.com/davidyz0/xx-pulse.git xx-pulse
```
In file `main.rs`
```rust
use xx_pulse::{Tcp, TcpListener};
use xx_pulse::impls::TaskExt;
use xx_core::error::{Error, Result};
use xx_core::macros::duration;
#[xx_pulse::main]
async fn main() -> Result<()> {
let listener = Tcp::bind("127.0.0.1:8080").await?;
// Can also timeout operations after 5s
let listener2: Option> = Tcp::bind("...")
.timeout(duration!(5 s))
.await;
loop {
let (mut client, _) = listener.accept().await?;
xx_pulse::spawn(async move {
let mut buf = [0; 1024];
loop {
let n = client.recv(&mut buf, Default::default()).await?;
if n == 0 {
break;
}
let n = client.send(&buf, Default::default()).await?;
if n == 0 {
break;
}
}
Ok::<_, Error>(())
}).await;
}
}
```
### Thread local safety
Thread local access is safe because of async/await syntax.
A compiler error prevents usage of `.await` in synchronous functions and closures.
xx-pulse uses cooperative scheduling, so it is impossble to suspend in a closure without using `unsafe`.
To suspend anyway, see [using sync code as if it were async](./Motivation.md#use-sync-code-as-if-it-were-async)
```rust
#[asynchronous]
async fn try_use_thread_local() {
THREAD_LOCAL.with(|value| {
// Ok, cannot cause UB
use_value_synchronously(value);
});
THREAD_LOCAL.with(|value| {
// Compiler error: cannot use .await in a synchronous function/closure!
do_async_stuff().await;
});
}
```