application-toys 0.0.1

Lightweight application primitives for async Rust — typed event bus, async trait support, and more to come
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# application-toys

[![crates.io](https://img.shields.io/crates/v/application-toys.svg)](https://crates.io/crates/application-toys)
[![docs.rs](https://docs.rs/application-toys/badge.svg)](https://docs.rs/application-toys)
[![license](https://img.shields.io/crates/l/application-toys.svg)](LICENSE)

Lightweight application primitives for async Rust, built on [Tokio](https://tokio.rs).

Each primitive lives behind a feature flag so you only compile what you need. More tools will be added in future releases.

## Feature flags

| Flag | Default | Enables |
|------|:-------:|---------|
| `event` | | Typed global broadcast event bus and the `#[asynchronous]` attribute macro |

```toml
[dependencies]
application-toys = { version = "0.0.1", features = ["event"] }
```

---

## Event system (`event`)

A process-wide, type-keyed publish/subscribe bus built on `tokio::sync::broadcast`. One channel exists per event type; all senders and handlers share it automatically.

```text
                event::<E>().dispatch(e)
                         │
                         ▼
              ┌──────────────────────┐
              │    EventChannel<E>   │  ← one per type, process-global
              └──────────┬───────────┘
                         │ broadcast
             ┌───────────┼───────────┐
             ▼           ▼           ▼
        Handler A    Handler B    Handler C
```

### Quick start

```rust
use toys::event::{event, EventHandler, EventLoop};
use toys::asynchronous;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};

pub enum AppEvent { Increment(u64) }

struct Counter {
    value: AtomicU64,
}

#[asynchronous]
impl EventHandler<AppEvent> for Counter {
    async fn handle(self: Arc<Self>, event: AppEvent) {
        if let AppEvent::Increment(n) = event {
            self.value.fetch_add(n, Ordering::Relaxed);
        }
    }
}

#[tokio::main]
async fn main() {
    let counter = Arc::new(Counter { value: AtomicU64::new(0) });

    let handles = EventLoop::<AppEvent>::new()
        .dispatch(&[counter.clone()])
        .await;

    event::<AppEvent>().dispatch(AppEvent::Increment(1)).await.unwrap();
    event::<AppEvent>().dispatch(AppEvent::Increment(30)).await.unwrap();

    // graceful shutdown
    handles[0].1.send(()).unwrap();
    handles[0].0.await.unwrap().unwrap();

    println!("counter = {}", counter.value.load(Ordering::Relaxed));
    // counter = 31
}
```

### How it works

1. **Define** an event type — any `Clone + Send + Sync + 'static` type works, typically an `enum`.
2. **Implement** `EventHandler<E>` on your consumer struct, annotated with `#[asynchronous]`.
3. **Register** handlers at startup via `EventLoop::dispatch`, which spawns one background Tokio task per handler.
4. **Publish** from anywhere with `event::<E>().dispatch(value).await`.

### `#[asynchronous]`

The `#[asynchronous]` attribute (re-exported from `application-toys-macros`) makes `async fn` methods in `trait` and `impl` blocks dyn-compatible by rewriting them to return `Pin<Box<dyn Future<Output = T> + Send + Sync + 'lt>>`.

It accepts optional flags:

| Flag | Effect |
|------|--------|
| `no_sync` | Remove the `Sync` bound; keep only `Send` |
| `local` | Remove both `Send` and `Sync` (single-threaded runtimes) |
| `static_lifetime` | Force `'static` even when a borrowed receiver is present |

See [`application-toys-macros`](https://docs.rs/application-toys-macros) for full documentation.

---

## License

MIT — see [LICENSE](LICENSE).