aligned-vec

aligned-vec provides AVec<T> and ABox<T>, drop-in-style replacements for Rust’s Vec<T> and Box<T> that guarantee their backing memory is aligned to a chosen power-of-two boundary. This matters for numerical and SIMD code, where operating on misaligned buffers costs performance or, on some architectures, is outright unsupported. The crate offers two alignment strategies through a sealed Alignment trait: RuntimeAlign for a value chosen dynamically, and ConstAlign<N> for an alignment fixed at compile time via a const generic, so callers can pick zero-cost or flexible alignment without changing the rest of their code.

It also ships a platform-aware CACHELINE_ALIGN constant, optional serde support behind a feature flag, and works in no_std environments when the default std feature is disabled. It’s used as low-level allocation plumbing by numerical/linear-algebra crates that need aligned buffers for vectorized kernels.

What You Get

• AVec<T, A> - an aligned, growable vector type with the same core API surface as std::Vec (push, extend, reserve, into_boxed_slice)
• ABox<T, A> - an aligned box type for a single value or boxed slice, mirroring std::Box
• RuntimeAlign and ConstAlign<N> - two alignment strategies behind a shared sealed trait, chosen at runtime or fixed at compile time
• A platform-aware CACHELINE_ALIGN constant that adapts to the target architecture (x86_64, aarch64, arm, s390x, and more)
• Optional serde support - Serialize/Deserialize implementations for AVec and ABox behind a feature flag
• no_std compatibility when the default std feature is disabled

Common Use Cases

• SIMD kernels - allocating buffers aligned to 16/32/64-byte boundaries so vectorized loads and stores avoid unaligned-access penalties
• Cache-line-sensitive data structures - aligning hot data to CACHELINE_ALIGN to reduce false sharing in concurrent code
• FFI buffers - passing memory to C/C++ code or hardware APIs that require specific alignment guarantees
• Numerical and scientific computing - backing matrix or vector types with the alignment guarantees vectorized math libraries need

Under The Hood

Architecture The crate is organized into three files: src/lib.rs (the public API - AVec, ABox, the Alignment trait, RuntimeAlign/ConstAlign, and the CACHELINE_ALIGN constant), src/raw.rs (ARawVec, the low-level unsafe allocation and reallocation logic wrapping alloc::alloc), and src/io.rs (a std::io::Write impl for AVec<u8>, gated behind the std feature). The design mirrors std::Vec/Box internals: AVec wraps ARawVec (buffer pointer, capacity, alignment) plus a length field and delegates growth entirely to ARawVec, while ABox is built on top of AVec’s raw parts for the single-value and boxed-slice cases. The Alignment trait is sealed (private::Seal) with two implementors, RuntimeAlign and ConstAlign<N>, letting the same generic AVec<T, A>/ABox<T, A> code monomorphize into either a dynamically configurable or a compile-time-fixed alignment. There’s no plugin or extensibility point beyond generics - changing the core allocation strategy in ARawVec would ripple through both AVec and ABox, since both are thin wrappers over it.

Tech Stack This is a Rust 2021-edition crate with a minimal dependency footprint: equator (used for its assert! macro, which produces richer panic messages on alignment checks) as a required runtime dependency, and an optional serde 1.0 dependency behind a feature flag. Dev-dependencies (bincode, diol) are used only for examples and benchmarks, not the published crate. There’s no build.rs and no proc-macro crate involved. The crate is #![no_std]-capable via extern crate alloc, with std pulled in only through the default std feature for the io.rs Write implementation. It’s distributed as a single crates.io package, with docs.rs configured to build with all-features enabled.

Code Quality The crate has 20 inline #[test] functions across two test modules (src/lib.rs and src/io.rs), colocated with the implementation rather than in a separate integration-test directory - a common pattern for small crates. Fallible allocation paths use a dedicated TryReserveError type rather than panicking outright, and the panicking API surface leans on equator’s assert! for readable failure messages (e.g. alignment-power-of-two checks). The crate is necessarily unsafe-heavy in raw.rs, since it implements low-level allocator plumbing directly, but the unsafe functions carry explicit ”# Safety” doc comments stating their preconditions (visible on ARawVec::new_unchecked and with_capacity_unchecked). No CI configuration or clippy lint config was found in the shallow clone beyond a rustfmt.toml, and there’s no separate integration-test suite.

What Makes It Unique Unlike crates that only offer a single fixed alignment strategy, aligned-vec exposes both a RuntimeAlign wrapper for dynamically chosen alignment and a ConstAlign<N> wrapper for a compile-time-checked, zero-cost alignment - unified behind one sealed trait so generic downstream code can stay alignment-strategy-agnostic. It also computes a platform-aware CACHELINE_ALIGN constant that varies by target architecture, something most general-purpose allocation crates don’t bother with. The scope is intentionally narrow - it isn’t trying to be a general SIMD or numerics library - but the dual runtime/const alignment abstraction over one generic AVec/ABox API is a distinctive, well-executed solution to a specific low-level problem.