ps_alloc/lib.rs
1//! A reasonably safe allocator: a thin, checked wrapper over [`std::alloc`] exposing
2//! C-style [`alloc`], [`free`], and [`realloc`].
3//!
4//! Every allocation is prefixed with a hidden header storing a marker and the
5//! allocation's size, which lets the crate detect some misuse (double frees, corrupted
6//! or foreign pointers) at runtime, on a best-effort basis. All allocations are aligned
7//! to [`HEADER_SIZE`] (16) bytes.
8//!
9//! Any error other than `NullPtr` returned by [`free`] or [`realloc`] (or `realloc`'s
10//! recoverable `NewAllocationFailed`) indicates that the program is already in an
11//! undefined state.
12//!
13//! # Example
14//!
15//! ```
16//! # fn main() -> Result<(), ps_alloc::AllocationError> {
17//! let ptr = ps_alloc::alloc(64)?;
18//!
19//! unsafe {
20//! ptr.write(42);
21//! assert_eq!(ptr.read(), 42);
22//!
23//! ps_alloc::free(ptr).expect("the pointer came from alloc");
24//! }
25//! # Ok(())
26//! # }
27//! ```
28
29#![warn(missing_docs)]
30#![warn(unsafe_op_in_unsafe_fn)]
31
32mod alloc;
33mod error;
34mod free;
35mod header;
36mod marker;
37mod realloc;
38
39pub use alloc::alloc;
40pub use error::{AllocationError, DeallocationError, ReallocationError};
41pub use free::free;
42pub use header::HEADER_SIZE;
43pub use realloc::realloc;