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.