# rt

The real-time packages provide the allocation-free, lock-free primitives that a `#[realtime]` function can call without breaking its contract. Every method below carries `#[no_alloc]` and `#[no_block]`, so it is usable from a hot path. See the [Real-time](/docs/realtime) page for the contracts themselves.

The capacities are currently fixed at **1024** because C+ does not yet have const-generic struct parameters, and the elements are `u64` (store an index or a tagged handle when you need to carry more).

## `SpscRingU64`: lock-free single-producer / single-consumer ring

Full and empty are reported as values, never as a block:

```cplus
import "rt/rt" as rt;

let mut ring: rt::SpscRingU64 = rt::SpscRingU64::new();

// Producer side:
let ok: bool = ring.push(42 as u64);     // false if the ring is full

// Consumer side:
guard let option::Option::Some(v) = ring.pop() else { return 0; };   // None if empty
```

Other methods: `capacity()`, `len()`, `is_empty()`, `is_full()`.

## `FixedPoolU64`: fixed-capacity free-list object pool

`acquire` hands back a slot index or `None` when the pool is full; `release` returns it:

```cplus
let mut pool: rt::FixedPoolU64 = rt::FixedPoolU64::new();

guard let option::Option::Some(idx) = pool.acquire() else { return 1; };   // None if full
pool.set(idx, 7 as u64);
let v: u64 = pool.get(idx);
pool.release(idx);
```

Other methods: `capacity()`, `in_use_count()`, `available()`, `is_full()`.

## `rt_darwin`: macOS platform controls

The platform package configures the host thread and memory before the hot path. Every fallible call returns a `Result` rather than throwing:

```cplus
import "rt_darwin/clock" as clock;
import "rt_darwin/thread" as rt_thread;
import "rt_darwin/mem" as rt_mem;

// Raise the current thread to audio QoS before the loop.
let _ = rt_thread::set_current_priority(rt_thread::Priority::RealtimeAudio);

// Lock pages so they are not paged out under load.
let _ = rt_mem::lock_pages(buf_ptr, buf_len);

// Monotonic, high-resolution timing for per-frame latency.
let start: u64 = clock::now_monotonic_ns();
// ... run the callback ...
let took: u64 = clock::elapsed_ns(start, clock::now_monotonic_ns());
```

`rt_darwin` ships today; `rt_linux` and `rt_posix` will mirror the same surface with their own syscalls.