subetha 0.1.0

SubEtha (CXC, Cross-Context Channel): MMF-backed cross-process IPC plus adaptive in-process primitives - one byte layout for cross-thread, cross-process, disk, and network. Umbrella crate re-exporting the subetha-core / -pointers / -sidecar / -cxc stack.
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

# subetha

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE-MIT)
[![Wiki](https://img.shields.io/badge/wiki-variably--constant.github.io-blue)](https://variably-constant.github.io/subetha/)

**Cross-Context Channel (CXC) for Rust.** Kernel-bypass IPC - lock-free,
thread- and process-safe - that spans threads, processes, disk, and
network through memory-mapped files, with no syscalls on the data path
and no locks in your code.

Local IPC normally means picking the least-bad option from a menu that
all goes through the kernel. SubEtha skips the menu: after construction,
every send and recv is a user-space atomic op on a memory-mapped file
the kernel page-aliases between participants. The same typed
`Channel<T>` API works cross-thread, cross-process, and persisted to
disk; the default ring picks and changes its own shape (SPSC to MPMC and
back) under live producers and consumers without losing an item.

Measured 80-528x faster than the fastest kernel IPC mechanism on every
platform tested (Windows, WSL2, Linux, FreeBSD, macOS) and 4.8-8.8x
faster than iceoryx2's zero-copy shared memory. The full benchmark set,
dot plots, and methodology live in the
[GitHub README](https://github.com/Variably-Constant/subetha#readme).

## This crate

`subetha` is the umbrella. It pulls in the whole stack and re-exports
each member as a module:

| Module | Crate | Role |
|---|---|---|
| `subetha::core` | `subetha-core` | shared substrate: handshake header, observation ring, `AxisMask` |
| `subetha::pointers` | `subetha-pointers` | adaptive in-process exotic pointers |
| `subetha::sidecar` | `subetha-sidecar` | adaptive control plane |
| `subetha::cxc` | `subetha-cxc` | MMF-backed cross-process primitives + bridges |

```toml
[dependencies]
subetha = "0.1"
```

```rust
use subetha::cxc::AutoIpc;

let chan = AutoIpc::new("/tmp/events.bin")
    .capacity(64)
    .build_channel::<u64>()?;

chan.send(&42)?;                  // non-blocking
let v = chan.recv()?;
# Ok::<(), Box<dyn std::error::Error>>(())
```

## Feature flags

The default build is dependency-light and cross-platform. The capability
features forward to `subetha-cxc`; the platform- or C-library-specific
dependencies behind each one stay gated, so the default build pulls none
of them.

| Feature | Adds |
|---|---|
| `quic-bridge` | `QuicBridgeClient` / `QuicBridgeServer` over QUIC (quinn + rustls) |
| `tcp-bridge` | `TcpBridgeClient` / `TcpBridgeServer` over TCP |
| `tcp-tls-bridge` | the TCP bridge inside a rustls 1.3 record layer |
| `tls` | the optional TLS record layer for the reliable-UDP transport |
| `wire-locale` | the NIC-bypass datapath (AF_XDP / netmap / BPF / XDP) |
| `linux-futex-raw` | the raw Linux futex surface on `CrossProcessWaker` |

## Requirements

SubEtha builds on **stable Rust** (edition 2024, MSRV 1.96).

## Documentation

Full reference at the wiki:
<https://variably-constant.github.io/subetha/>.

## License

MIT. See [LICENSE-MIT](LICENSE-MIT).