# ps-alloc - a reasonably safe allocator
This crate provides three functions: `alloc`, `free`, and `realloc`. They are thin
wrappers over the system allocator with best-effort runtime misuse detection.
Every allocation is prefixed with a hidden 16-byte header storing a marker and the
allocation's size, and every returned pointer is aligned to 16 bytes.
While this crate does implement several safety precautions, you still shouldn't call
`free` on stuff willy-nilly, because that _is_ undefined behaviour.
`free` is **NOT** guaranteed to fail when provided anything other than a valid pointer
produced by `alloc` or `realloc`.
**Do not** call `free` on any pointer not produced by `alloc` or `realloc`.
Unlike C's `free(NULL)`, freeing a null pointer returns an error instead of being a
no-op.
`realloc` mirrors C's `realloc`: `realloc(null, size)` allocates, `realloc(ptr, 0)`
frees and returns null, and resizing preserves the contents up to the lesser of the old
and new sizes, in place when possible. After a successful `realloc`, only the returned
pointer may be used.
All three functions return `Result`s. `alloc` returning an `Err` does not signify a
problem. `free` or `realloc` returning any error besides `NullPtr`, or `realloc`'s
recoverable `NewAllocationFailed`, means your program is already in an undefined state
and you should consider aborting it.