Crate align_constr 

Alignment-constrained newtype

Newtype whose alignment is constrained not only by the inherent alignment requirements of the underlying type but also by the alignment requirements of the “alignment constraint archetype”. Within this context, “alignment constraint archetype” AlignConstrArchetype is a type whose alignment constraint is imposed on the underlying type T to produce AlignConstr<T, AlignConstrArchetype>.

Notes

• “alignment constraint archetype” is a stipulative functional definition.
• AlignConstr<T, AlignConstrArchetype> for some underlying type T and “alignment constraint archetype” AlignConstrArchetype can also be seen as a refinement type reified in the form of a parameterized newtype.

Resources on alignment

• “Data Alignment”, personal website of Song Ho Ahn - a professor in the Computer Science department at Sheridan College (Oakville)

Not so visually appealing yet incredibly well written article that explains not only what alignment is but also why it exists and where one might need to overalign data.

Dmitrii Demenev

• “What is overalignment of execution regions and input sections?”, Stack Overflow
• “Data Structure alignment”, GeeksforGeeks
• “Type Layout”, The Rust Referece
• “The Lost Art of Structure Packing”, article by Eric. S. Raymond (also known as ESR) - an American software developer, open-source software advocate, and author of the 1997 essay and 1999 book The Cathedral and the Bazaar

Rather deep exploration of the topic from the point of view of a C programming expert. The article covers not only the information about alignment but also related related topics as applied to C, as well as sever other programming languages, including Rust.

Dmitrii Demenev

Example

use align_constr::{AlignConstr, n_zst::ZST128};

let overaligned_u8 = AlignConstr::<u8, ZST128>::new(3);
assert!(overaligned_u8.value == 3);
// requires non-const context
assert!(&overaligned_u8 as *const _ as usize % 128 == 0);

align_constr vs aligned

aligned is a popular library that served as a prototype for align_constr. At the time of writing, align_constr is featurewise and idiomatically superior and provides not only more extensive documentation but also a selection of resources on the subject. To pay respect to the contributors of aligned crate, the quality of their creation’s CI is still unmatched by align_constr. However, the limited scope of both libraries nonetheless makes align_constr arguably better for any use case.

Note: Unlike in aligned, the dependency on as_slice is optional.

About align_constr

• #[no_std] friendly

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

Modules

n_zst

N-ZSTs, i.e. zero-sized datatypes whose alignment is N.

Structs

AlignConstr

Alignment-constrained datatype, i.e. a type whose alignment is constrained not only by the inherent alignment requirements of the underlying type T, whose value is stored internally, but also by the alignment requirements of the “alignment constraint archetype” AlignConstrArchetype. Within this context, “alignment constraint archetype” AlignConstrArchetype is a type whose alignment constraint is imposed on the underlying type T to produce AlignConstr<T, AlignConstrArchetype>.