memkit-async 0.2.0-beta.1

Async-aware memory allocators for memkit
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
110
111
112
113
114
115

<div align="center">

# ◈ MEMKIT ASYNC ◈


### `[ TASK-LOCAL ASYNC-NATIVE ALLOCATION ]`


[![Crates.io](https://img.shields.io/badge/crates.io-v0.2.0--beta.1-00ff9f?style=for-the-badge&labelColor=0d1117)](https://crates.io/crates/memkit-async)
[![Documentation](https://img.shields.io/badge/docs.rs-memkit--async-ff00ff?style=for-the-badge&labelColor=0d1117)](https://docs.rs/memkit-async)
[![License](https://img.shields.io/badge/license-MPL--2.0-ff6b35?style=for-the-badge&labelColor=0d1117)](../LICENSE.md)

---

```
 █████╗ ███████╗██╗   ██╗███╗   ██╗ ██████╗ 
██╔══██╗██╔════╝╚██╗ ██╔╝████╗  ██║██╔════╝ 
███████║███████╗ ╚████╔╝ ██╔██╗ ██║██║      
██╔══██║╚════██║  ╚██╔╝  ██║╚██╗██║██║      
██║  ██║███████║   ██║   ██║ ╚████║╚██████╗ 
╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═══╝ ╚═════╝ 
```

> *"Memory that moves with your tasks, not your threads."*

**Task-local, async-native memory management for Rust. Avoid the pitfalls of crossing `.await` points with high-speed arenas and managed pools.**

[`◈ QUICK START`](#◈-quick-start) • [`◈ ADVANTAGE`](#◈-the-async-advantage) • [`◈ POLICIES`](#◈-backpressure-policies)

</div>

---

## ◈ THE ASYNC ADVANTAGE


| Feature | Standard `Box` | Memkit Async | Impact |
|:--------|:--------------:|:------------:|:-------|
| **Safety** | Runtime-only | **Task-local** | Thread-safe `.await` |
| **Locality** | Random | **Contiguous** | Cache efficient |
| **Pressure** | None | **Wait/Fail** | System stability |
| **Throughput** | Lock-heavy | **Lock-Free** | Optimized scaling |

---

## ◈ FEATURES


```
┌─────────────────────────────────────────────────────────────────────────┐
│  ◆ TASK-LOCAL  │  Isolated arenas tied to specific async tasks. Correcly │
│                │  preserves locality even during task migration.         │
├─────────────────────────────────────────────────────────────────────────┤
│  ◆ BACKPRESSURE│  Integrated semantics for memory limits: `Wait`, `Fail`, │
│                │  `Timeout`, or `Evict`.                                 │
├─────────────────────────────────────────────────────────────────────────┤
│  ◆ ZERO-COPY   │  Move entire arenas between tasks without memory moves. │
│                │  Ideal for producer-consumer pipelines.                 │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## ◈ QUICK START


```rust
use memkit_async::{MkAsyncFrameAlloc, MkAsyncFrameConfig};

#[tokio::main]

async fn main() {
    let alloc = MkAsyncFrameAlloc::new(MkAsyncFrameConfig::default());
    
    // Begin a task-managed frame
    let frame = alloc.begin_frame().await;
    
    // Allocate high-speed data safe across .await points
    let data = alloc.alloc::<BigData>().await;
    
    do_some_io().await; // Task might move between threads here...
    
    process(data);      // ...but memory remains safe and contiguous!
}
```

---

## ◈ BACKPRESSURE POLICIES


| Policy | Behavior |
|:-------|:---------|
| **`Wait`** | Suspends task until space is available. |
| **`Fail`** | Immediately returns `CapacityReached` error. |
| **`Timeout`** | Waits for duration before returning error. |
| **`Evict`** | Discards oldest entries (ideal for caches). |

---

## ◈ INTEGRATION


Enable the `tokio` feature for native runtime support.

```toml
[dependencies]
memkit-async = { version = "0.2.0-beta.1", features = ["tokio"] }
```

---

## ◈ LICENSE


Licensed under the **Mozilla Public License 2.0**.

---

<div align="center">

**[ Part of the ◈ MEMKIT ◈ Ecosystem ]**

</div>