From 7afc3b063789d3df79ca0a1386eec368b4f113b3 Mon Sep 17 00:00:00 2001
From: Elaina Claus <elaina.claus@chtm.me>
Date: Thu, 15 Jan 2026 17:26:18 -0500
Subject: [PATCH] allocator prototypes

---
 src/ni_alloc/alloc.c    | 58 +++++++++++++++++++++++++++++++++++++++++
 src/ni_alloc/vm_posix.c | 29 +++++++++++++++++++++
 2 files changed, 87 insertions(+)

diff --git a/src/ni_alloc/alloc.c b/src/ni_alloc/alloc.c
index e69de29..a600bd5 100644
--- a/src/ni_alloc/alloc.c
+++ b/src/ni_alloc/alloc.c
@@ -0,0 +1,58 @@
+#include "ni_alloc/alloc.h"
+
+/* -------- Global allocator API -------- */
+
+/* Initialize/shutdown global allocator (optional; can be lazy).
+   Returns false if initialization fails.
+*/
+bool ni_alloc_global_init(const ni_alloc_config* cfg);
+void ni_alloc_global_shutdown(void);
+
+/* Allocation functions using the global allocator. */
+void* ni_malloc(size_t size);
+void  ni_free(void* ptr);
+void* ni_realloc(void* ptr, size_t new_size);
+void* ni_calloc(size_t count, size_t elem_size);
+
+/* Alignment:
+   - alignment must be power of two and >= sizeof(void*)
+   - returns NULL on failure
+*/
+void* ni_memalign(size_t alignment, size_t size);
+
+/* Equivalent of C11 aligned_alloc semantics:
+   - alignment must be power of two
+   - size must be a multiple of alignment
+*/
+void* ni_aligned_alloc(size_t alignment, size_t size);
+
+/* Query/reset stats for global allocator. */
+void ni_alloc_get_stats(ni_alloc_stats* out_stats);
+void ni_alloc_reset_stats(void);
+
+/* -------- Instance allocator API -------- */
+
+ni_allocator* ni_allocator_create(const ni_alloc_config* cfg);
+void          ni_allocator_destroy(ni_allocator* a);
+
+void* ni_allocator_malloc(ni_allocator* a, size_t size);
+void  ni_allocator_free(ni_allocator* a, void* ptr);
+void* ni_allocator_realloc(ni_allocator* a, void* ptr, size_t new_size);
+void* ni_allocator_calloc(ni_allocator* a, size_t count, size_t elem_size);
+void* ni_allocator_memalign(ni_allocator* a, size_t alignment, size_t size);
+
+void  ni_allocator_get_stats(ni_allocator* a, ni_alloc_stats* out_stats);
+void  ni_allocator_reset_stats(ni_allocator* a);
+
+/* -------- Utilities / validation -------- */
+
+/* Returns true if n is a power of two (and nonzero). */
+bool ni_is_pow2_size(size_t n);
+
+/* Round up x to next multiple of align (align must be power of two). */
+size_t ni_align_up(size_t x, size_t align);
+
+/* Optional: verify internal invariants in debug builds.
+   - returns false if corruption detected
+*/
+bool ni_alloc_validate(void);
\ No newline at end of file
diff --git a/src/ni_alloc/vm_posix.c b/src/ni_alloc/vm_posix.c
index e69de29..6bb133c 100644
--- a/src/ni_alloc/vm_posix.c
+++ b/src/ni_alloc/vm_posix.c
@@ -0,0 +1,29 @@
+#include "ni_alloc/vm.h"
+
+/* Returns OS page size (usually sysconf(_SC_PAGESIZE)). Never returns 0. */
+size_t ni_vm_page_size(void);
+
+/* Reserve anonymous virtual memory.
+   - bytes will be rounded up to a page multiple.
+   - returns NULL on failure.
+*/
+void* ni_vm_reserve(size_t bytes);
+
+/* Release a region previously returned by ni_vm_reserve (page-multiple size). */
+bool ni_vm_release(void* addr, size_t bytes);
+
+/* Optional: “commit/decommit” for platforms where it’s meaningful.
+   On many Unix systems, reserve implies commit; implementations may no-op.
+*/
+bool ni_vm_commit(void* addr, size_t bytes);
+bool ni_vm_decommit(void* addr, size_t bytes);
+
+/* Optional: set guard pages (mprotect) for debug.
+   Returns false if unsupported or fails.
+*/
+bool ni_vm_protect_none(void* addr, size_t bytes);
+bool ni_vm_protect_rw(void* addr, size_t bytes);
+
+/* Stats are optional but very useful for tests/tools. */
+void ni_vm_get_stats(ni_vm_stats* out_stats);
+void ni_vm_reset_stats(void);
\ No newline at end of file