prototypes for malloc impl

include/ni_alloc/alloc.h

@@ -0,0 +1,122 @@
+#ifndef __NICKEL_ALLOC_H
+#define __NICKEL_ALLOC_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Nickel Allocator API (explicit; does NOT replace libc malloc unless you opt-in).
+   Design goal: easy to use in tools, easy to test, portable across Linux/macOS.
+*/
+
+typedef struct ni_alloc_stats {
+    /* current usage */
+    size_t bytes_in_use;       /* user-visible allocated bytes (approx if desired) */
+    size_t bytes_reserved;     /* backing store reserved from VM */
+    size_t bytes_peak;         /* peak in-use */
+    size_t bytes_reserved_peak;
+
+    /* counters */
+    uint64_t alloc_calls;
+    uint64_t free_calls;
+    uint64_t realloc_calls;
+    uint64_t calloc_calls;
+    uint64_t memalign_calls;
+
+    /* failures */
+    uint64_t oom_count;
+} ni_alloc_stats;
+
+/* Allocator configuration knobs (keep minimal at first; extend later). */
+typedef struct ni_alloc_config {
+    /* If true, ni_free(NULL) is allowed and a no-op (recommended true). */
+    bool free_null_is_noop;
+
+    /* If true, ni_realloc(p,0) behaves like free(p) and returns NULL. */
+    bool realloc_zero_frees;
+
+    /* If true, scribble freed blocks with a pattern (debug build feature). */
+    bool scribble_free;
+
+    /* If true, scribble newly allocated blocks with a pattern (debug). */
+    bool scribble_alloc;
+
+    /* Optional alignment for default allocations (usually alignof(max_align_t)). */
+    size_t default_alignment;
+
+    /* Optional: maximum small-bin size, arena chunk size, etc. */
+    size_t arena_chunk_bytes;
+} ni_alloc_config;
+
+/* Opaque allocator instance.
+   You can use the global allocator, or create a private allocator instance
+   (handy for tests / subsystems).
+*/
+typedef struct ni_allocator ni_allocator;
+
+/* -------- 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);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __NICKEL_ALLOC_H */