Skip to main content

Crate rusty_esp_alloc

Crate rusty_esp_alloc 

Source
Expand description

The allocator seam: rusty_alloc as the family’s global allocator.

Every deliverable in Janus declares its global allocator through this crate and never names rusty_alloc itself. That is the house rule, and it buys one thing: the exact pin, the profile and the startup shape are decided here once instead of in every firmware and every CLI.

A library must never declare a global allocator. A program may define exactly one, so a library that declares it forces the choice on every consumer and makes two such libraries impossible to link together. This crate does not declare one either — it hands out the type and the region, and the deliverable’s own main.rs does the declaring.

§A hosted deliverable

ⓘ
#[global_allocator]
static ALLOC: rusty_esp_alloc::Alloc = rusty_esp_alloc::Alloc;

§A firmware

A chip has no operating system to ask for memory: it has a region the linker gave it. [Region] is that region, handed over once at startup.

ⓘ
#[global_allocator]
static ALLOC: rusty_esp_alloc::Alloc = rusty_esp_alloc::Alloc;
static HEAP: rusty_esp_alloc::Region<{ 96 * 1024 }> = rusty_esp_alloc::Region::new();

HEAP.give().expect("the heap is given once");

§Which allocator a firmware should actually use

Not this one, necessarily, and the honest answer is in rusty_alloc’s own README: on a XIAO ESP32-S3 it is 2.0x to 3.7x faster than esp-alloc per allocate/free pair, and it needs 68 KiB where esp-alloc needs 8, because a size-class page allocator’s floor is classes touched x page size rather than bytes live. That is structural, not a missing optimisation.

So: reach for this when a firmware churns — allocates and frees repeatedly at varied sizes, which is what fragments a free list — and has the RAM. Reach for esp-alloc when the budget is tight. A firmware that allocates a handful of buffers at startup and never allocates again gains nothing here and pays the whole floor, and several of ours are exactly that shape.

The reason to adopt it anyway, where the RAM allows, is the safety posture rather than the speed: a double free aborts instead of putting one block on a free list twice and handing identical memory to two owners. Treat that abort as a bug to fix, never a check to disable.

§The single-thread invariant a firmware must assert

rusty_alloc’’‘s no_std profile assumes one thread: its cell’’‘s Sync, the fixed backend’’’s constant thread id and spin lock, and the split 64-bit atomics in its options all depend on it. The crate will not build without the caller saying so, which is the right way round – it refuses rather than assuming.

A firmware opts in through its own .cargo/config.toml:

[build]
rustflags = ["--cfg", "ra_single_threaded"]

Only assert that if it is true. On an ESP32-S3 it holds for a Track B firmware that runs esp_hal::main on one core and never starts the app core. It stops holding the moment a second core is started or an interrupt handler allocates – an interrupt is another context even on one core. A firmware that needs either wants esp-alloc, or rusty_alloc with the std profile if a target ever offers one.

Structs§

Alloc
The global allocator type. A deliverable writes #[global_allocator] static A: Alloc = Alloc; and nothing else. The global allocator handle (zero-sized).

Enums§

Error
What can go wrong handing over a region.

Constants§

VERSION
The pinned allocator version, so a firmware can print what it is running rather than what its manifest said. Our own semantic version, from the crate manifest.