spargio 0.5.13

Work-stealing async runtime for Rust built on io_uring and msg_ring
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

# Time and Cancellation

Spargio ships common runtime primitives for deadline-driven services.

## Time Primitives

- `sleep`, `sleep_until`
- `timeout`, `timeout_at`
- `interval`, `interval_at`
- `Sleep` (resettable timer)

Use `timeout` for request budgets and `interval` for periodic workers.

## Cancellation Primitives

- `CancellationToken`
- `TaskGroup`

Recommended pattern:

1. create one token per subsystem
2. pass clones to workers
3. signal cancel during shutdown
4. await task group completion

## Example Pattern

```rust
use std::time::Duration;

async fn bounded_work() {
    let op = async {
        spargio::sleep(Duration::from_millis(25)).await;
        1usize
    };
    let out = spargio::timeout(Duration::from_millis(50), op).await;
    assert!(out.is_ok());
}
```

This snippet wraps work with a deadline budget: the operation sleeps for
25ms and is bounded by a 50ms timeout.

## Cancellation Token and Task Group Example

```rust
use spargio::{CancellationToken, TaskGroup, TaskPlacement};
use std::time::Duration;

#[spargio::main]
async fn main(handle: spargio::RuntimeHandle) {
    let token = CancellationToken::new();
    let token_waiter = handle
        .spawn_stealable({
            let token = token.clone();
            async move {
                token.cancelled().await;
                "token canceled"
            }
        })
        .expect("spawn token waiter");

    let group = TaskGroup::new(handle.clone());
    let grouped = group
        .spawn_with_placement(TaskPlacement::Stealable, async {
            loop {
                spargio::sleep(Duration::from_millis(10)).await;
            }
        })
        .expect("spawn grouped worker");

    token.cancel();
    assert_eq!(token_waiter.await.expect("join"), "token canceled");

    group.cancel();
    assert!(grouped.await.expect("join").is_none());
}
```

What this does:

- uses `CancellationToken` for direct one-to-many cancellation signaling.
- uses `TaskGroup` to attach cancellation behavior to spawned work.
- shows grouped tasks returning `None` when canceled before completion.

## Common Mistakes

- hard-coded long timeouts with no service-level budget.
- per-call ad-hoc cancellation instead of shared subsystem token.
- no bounded waits during teardown.