In this lesson, you will learn how to design Rust APIs that guarantee deterministic performance by eliminating implicit heap allocations.
In real-time embedded systems, a single unexpected call to malloc—or its Rust equivalent, Box or Vec—can trigger non-deterministic latency spikes due to allocator fragmentation or complex free-list searches. To design truly embedded-friendly APIs, you must shift memory management from the callee to the caller.
The "Borrow or Buffer" Pattern
Instead of designing a function that returns a Vec<u8> or an owned String, force the caller to provide the storage. This is typically achieved by accepting a mutable slice (&mut [u8]) or a pre-allocated structure.
Consider an API that fetches sensor data:
// BAD: Implicit allocation
fn get_sensor_data() -> Vec<u8> {
let mut data = vec![0; 1024];
// ... fill data
data
}
// GOOD: Caller-managed storage
fn get_sensor_data(buffer: &mut [u8]) -> Result<usize, Error> {
if buffer.len() < 1024 {
return Err(Error::BufferTooSmall);
}
// ... fill buffer directly
Ok(1024)
}
Static vs. Dynamic Sizing
When your API requires an internal data structure, such as a queue or a map, avoid std::collections types that resize dynamically. Instead, leverage generic arrays or "heapless" patterns. By using const generics, you allow the user to decide the buffer size at compile time, ensuring the memory footprint is baked into the binary’s data segment rather than the heap:
pub struct SensorBuffer<const N: usize> {
storage: [u8; N],
pos: usize,
}
impl<const N: usize> SensorBuffer<N> {
pub fn push(&mut self, byte: u8) -> Result<(), Error> {
if self.pos >= N { return Err(Error::Full); }
self.storage[self.pos] = byte;
self.pos += 1;
Ok(())
}
}
By forcing the caller to define the capacity, you make the memory cost explicit in the type signature. This ensures that your API remains predictable, requires no runtime allocator, and behaves identically whether it is running on a bare-metal microcontroller or a constrained real-time task.
Key Takeaway: Design your APIs to require caller-provided memory buffers to ensure deterministic execution and zero heap fragmentation.