xonovex Memory Management Guidelines
General principles for allocating, owning, and freeing memory in manual-memory or buffer-passing code. Language-agnostic; examples are in C. Domain skills (e.g. C99, GPU device memory) keep their own specifics and link here for the underlying principle.
Essentials
- Caller owns memory - APIs take caller-provided storage; never allocate internally, see references/caller-owns-memory.md
- Group by lifetime - Allocate together what dies together; free as a unit, see references/ownership-and-lifetimes.md
- One owner - Exactly one owner frees; everyone else borrows, see references/ownership-and-lifetimes.md
Allocation strategy
- Arena / bump - Pointer-bump from a block; reset frees everything at once, see references/arenas-and-pools.md
- Object pool - Fixed-size slots + free list; O(1) alloc/free, stable, see references/arenas-and-pools.md
- Scratch / temp - Per-frame/per-request arena reset each cycle, see references/arenas-and-pools.md
- Virtual-memory reserve/commit - Reserve a large range, commit pages on demand; stable addresses, no realloc copy, see references/arenas-and-pools.md
- Virtual-memory tricks - Cap-free arrays, page-aligned growth, gapless ring buffers, end-of-page bounds checks, see references/virtual-memory.md
Ownership
- Lifetime by scope - Tie allocation lifetime to a clear scope/phase, see references/ownership-and-lifetimes.md
- Handles over pointers - Reference relocatable storage by index/handle (layout detail in data-oriented-design-guide), see references/ownership-and-lifetimes.md
Gotchas
- Bump allocation has no bounds safety unless you check capacity; always assert/return on overflow.
- Two owners means double-free or leak; decide ownership explicitly, don't infer it.
- Pointers into a growing/reset allocation dangle. Prefer offsets/handles across a boundary (a virtual-memory reserve/commit block is the exception: it never moves).
Progressive Disclosure
- Read references/caller-owns-memory.md - Load when designing an API's allocation boundary or a non-allocating library
- Read references/arenas-and-pools.md - Load when choosing an allocator: arena, pool, scratch, or virtual-memory backed
- Read references/virtual-memory.md - Load when using address-space reservation for cap-free arrays, ring buffers, page-aligned growth, or end-of-page bounds checking
- Read references/ownership-and-lifetimes.md - Load when deciding who owns/frees memory and how long it lives