allocator prototypes

README.md

@@ -1,4 +1,6 @@
-### Core “make C nicer” utilities
+# Nickel lib overview/roadmap
+
+## Core “make C nicer” utilities
 
 1. **`xmalloc/xcalloc/xrealloc/xstrdup` (header: `xalloc.h`)**
 
@@ -28,89 +30,93 @@
    * `bitset_set/clear/test`, `bitset_find_first_zero`
    * Teaches: word operations, popcount/ctz if you want.
 
-### C11 correctness features
+7. **Intrusive double linked list (header: `linkedlist.h`)**
 
-7. **Compile-time assertions & type checks (header: `ctassert.h`)**
+   * An implementation of a double linked list using a sentinel pattern
+
+## C11 correctness features
+
+1. **Compile-time assertions & type checks (header: `ctassert.h`)**
 
    * Wrap `_Static_assert`, plus some `_Generic` helpers.
    * Teaches: compile-time constraints, “making invalid states unrepresentable”.
 
-8. **`_Generic` logging macros (header: `log.h`)**
+2. **`_Generic` logging macros (header: `log.h`)**
 
    * `LOG_INFO("x=%d", x)` with file/line, optional type-based formatting helpers.
    * Teaches: variadic macros, `_Generic`, ergonomics.
 
-9. **Defer/cleanup pattern (header: `defer.h`)**
+3. **Defer/cleanup pattern (header: `defer.h`)**
 
    * Macro that runs cleanup at scope end (via `goto` pattern).
    * Teaches: structured cleanup in C, error paths.
 
-10. **Optional result type (header: `result.h`)**
+4. **Optional result type (header: `result.h`)**
 
    * `typedef struct { int ok; int err; T value; } result_T;` pattern.
    * Teaches: explicit error handling, no hidden global state.
 
-### Concurrency & atomics (C11’s “real” new power)
+## Concurrency & atomics
 
-11. **Atomic reference counting (header: `refcnt.h`)**
+1. **Atomic reference counting (header: `refcnt.h`)**
 
    * `ref_inc/ref_dec` with destructor callback.
    * Teaches: `stdatomic.h`, memory ordering (start with seq_cst, then learn relax/acq_rel).
 
-12. **Lock-free SPSC ring buffer (header: `ring_spsc.h`)**
+2. **Lock-free SPSC ring buffer (header: `ring_spsc.h`)**
 
    * Single-producer/single-consumer queue.
    * Teaches: atomics, cache friendliness, correctness reasoning.
 
-13. **Thread pool (header: `threadpool.h`)** using `threads.h`
+3. **Thread pool (header: `threadpool.h`)** using `threads.h`
 
    * `tp_init`, `tp_submit`, `tp_join`, `tp_destroy`
    * Teaches: `thrd_t`, `mtx_t`, `cnd_t`, work queues.
 
-14. **Once-init & singletons (header: `once.h`)**
+4. **Once-init & singletons (header: `once.h`)**
 
    * Use `once_flag` / `call_once` (or implement if platform lacks).
    * Teaches: init races, safe global setup.
 
-### Parsing / CLI tools (you’ll actually use these)
+## Parsing / CLI tools
 
-15. **Argument parser (header: `argparse.h`)**
+1. **Argument parser (header: `argparse.h`)**
 
    * `--long`, `-s`, combined short flags, `--key=value`
    * Teaches: string parsing, API design, test cases.
 
-16. **INI parser (header: `ini.h`)**
+2. **INI parser (header: `ini.h`)**
 
    * Minimal: sections, key=value, comments.
    * Teaches: parsing state machines, callbacks.
 
-17. **CSV reader/writer (header: `csv.h`)**
+3. **CSV reader/writer (header: `csv.h`)**
 
    * Correct quoting/escaping.
    * Teaches: edge cases, streaming parsing.
 
-18. **Path utilities (header: `path.h`)**
+4. **Path utilities (header: `path.h`)**
 
    * `path_join`, `path_dirname`, `path_basename`, normalize `..` and `.`
    * Teaches: portability pitfalls, careful string ops.
 
-### Systems-ish building blocks
+## Systems-ish building blocks
 
-19. **File mapping / buffered reader (header: `io.h`)**
+1. **File mapping / buffered reader (header: `io.h`)**
 
    * Portable-ish wrapper for “read whole file”, “iter lines”, “atomic write via temp+rename”.
    * Teaches: robust file I/O patterns, error handling.
 
-20. **Timing + profiling helpers (header: `timeutil.h`)**
+2. **Timing + profiling helpers (header: `timeutil.h`)**
 
    * `now_ns()`, `stopwatch`, `scope_timer` macro
    * Teaches: `timespec_get`, measurement pitfalls, microbenchmark hygiene.
 
 ---
 
-## A suggested “crash course” order (so it builds)
+## suggested order
 
-1–3 (xalloc/arena/buf) → 7–10 (static assert, generic, cleanup, results) → 15 (argparse) → 19 (io) → 16–18 (parsers) → 11–14 (atomics/threads) → 5–6 (hashmap/bitset) → 20 (timing) → 12/13 (ring + threadpool, as capstone)
+xalloc/arena/buf -> static assert, generic, cleanup, results -> argparse -> io -> parsers -> atomics/threads -> hashmap/bitset-> timing -> ring + threadpool, as capstone
 
 ---
 

include/ni_alloc/alloc.h

@@ -13,6 +13,8 @@ extern "C" {
    Design goal: easy to use in tools, easy to test, portable across Linux/macOS.
 */
 
+//#define ENABLE_NICKEL_ALLOC_SHIM
+
 typedef struct ni_alloc_stats {
     /* current usage */
     size_t bytes_in_use;       /* user-visible allocated bytes (approx if desired) */
@@ -115,6 +117,17 @@ size_t ni_align_up(size_t x, size_t align);
 */
 bool ni_alloc_validate(void);
 
+
+#ifdef ENABLE_NICKEL_ALLOC_SHIM
+   /* Allocation functions using the global allocator.
+      define symbols pointing at our versions 
+   */
+   void* malloc(size_t size) { ni_malloc(size); }
+   void  free(void* ptr) { ni_free(ptr); }
+   void* realloc(void* ptr, size_t new_size) { ni_realloc(ptr, new_size); }
+   void* calloc(size_t count, size_t elem_size) { ni_calloc(count, elem_size); }
+#endif
+
 #ifdef __cplusplus
 }
 #endif

include/nickel.h

@@ -0,0 +1,29 @@
+#ifndef __NICKEL_H_
+#define __NICKEL_H_
+
+/* common includes across the project */
+#include <sys/types.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+#include <unistd.h>
+#include <errno.h>
+#include <string.h>
+
+/* includes from internal to the project */
+// ...
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// any thing we need in the top level here
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  /* __NICKEL_H_ */

include/nickel/linkedlist.h

@@ -1,10 +1,7 @@
 #ifndef __NICKEL_LINKEDLIST_H_
 #define __NICKEL_LINKEDLIST_H_
 
-#include <stdlib.h>
-#include <stddef.h>
-#include <stdint.h>
-#include <stdbool.h>
+#include "nickel.h"
 
 #ifdef __cplusplus
 extern "C" {

include/nickel/oops.h

@@ -0,0 +1,31 @@
+#ifndef __NICKEL_OOPS_H
+#define __NICKEL_OOPS_H
+
+#include <sys/types.h>
+#include <stdlib.h>
+
+#include <unistd.h>
+#include <errno.h>
+#include <string.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// TODO: C23 adds [[noreturn]] (& [[]] function attribute tags)
+// which are standardized, the below depends on compiler support.
+#if defined(__GNUC__) || defined(__CLANG__)
+#define NORETURN __attribute__ ((__noreturn__))
+#else
+#define NORETURN
+#endif /* __GNUC__ || __CLANG__*/
+
+void nickel_oops_handler(const char *format, ...) NORETURN;
+
+#ifdef __cplusplus
+}
+#endif
+
+// clean up our noreturn define
+#undef NORETURN
+#endif

include/nickel/xalloc.h

@@ -1,11 +1,19 @@
 #ifndef __NICKEL_XALLOC_H_
 #define __NICKEL_XALLOC_H_
 
+#include "nickel.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* header contents */
+void* ni_xmalloc(size_t size);
+
+void* ni_xcalloc(size_t nmemb,size_t size);
+void* ni_xrealloc(void* ptr, size_t size);
+
+char* ni_xstrdup(const char *s);
+char* ni_xstrndup(const char s[], size_t n);
 
 #ifdef __cplusplus
 }

make/rules.mk

@@ -1,9 +1,13 @@
+ALLOC_LIB := $(BUILD_DIR)/lib/libnia.a
 LIB      := $(BUILD_DIR)/lib/libnickel.a
 BIN_DIR  := $(BUILD_DIR)/bin
 OBJ_DIR  := $(BUILD_DIR)/obj
 
+NI_ALLOC_SRCS  := $(wildcard src/nickel/ni_alloc/*.c)
+NI_ALLOC_OBJS  := $(patsubst src/ni_alloc/%.c,$(OBJ_DIR)/ni_alloc/%.o,$(NI_ALLOC_SRCS))
+
 NICKEL_SRCS  := $(wildcard src/nickel/*.c)
-NICKEL_OBJS  := $(patsubst src/%.c,$(OBJ_DIR)/%.o,$(NICKEL_SRCS))
+NICKEL_OBJS  := $(patsubst src/nickel/%.c,$(OBJ_DIR)/nickel/%.o,$(NICKEL_SRCS))
 
 TEST_SRCS := $(wildcard tests/*.c)
 TEST_BIN  := $(BIN_DIR)/tests
@@ -14,7 +18,12 @@ TOOL_BINS := \
 
 .PHONY: all clean test tools examples
 
-all: $(LIB) tools $(TEST_BIN)
+all: $(ALLOC_LIB) $(LIB) tools $(TEST_BIN)
+
+$(ALLOC_LIB): $(NI_ALLOC_OBJS)
+	@mkdir -p $(dir $@)
+	$(AR) rcs $@ $^
+	$(RANLIB) $@
 
 $(LIB): $(NICKEL_OBJS)
 	@mkdir -p $(dir $@)
@@ -26,9 +35,9 @@ $(OBJ_DIR)/%.o: src/%.c
 	$(CC) $(CFLAGS) -c $< -o $@
 
 # Tests link against libnickel.a
-$(TEST_BIN): $(TEST_SRCS) $(LIB)
+$(TEST_BIN): $(TEST_SRCS) $(ALLOC_LIB) $(LIB)
 	@mkdir -p $(BIN_DIR)
-	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(TEST_SRCS) $(LIB) $(LDLIBS)
+	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $(TEST_SRCS) $(ALLOC_LIB) $(LIB) $(LDLIBS)
 
 # Tools (one main.c each; expand as needed)
 #$(BIN_DIR)/logscan: tools/logscan/main.c $(LIB)
@@ -39,10 +48,10 @@ $(TEST_BIN): $(TEST_SRCS) $(LIB)
 #	@mkdir -p $(BIN_DIR)
 #	$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $< $(LIB) $(LDLIBS)
 
+tools: $(TOOL_BINS)
+
 test: $(TEST_BIN)
 	$(TEST_BIN)
 
-tools: $(TOOL_BINS)
-
 clean:
 	rm -rf $(BUILD_DIR)

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);

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);

src/nickel/xalloc.c

@@ -0,0 +1,64 @@
+#include <sys/types.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+#include <unistd.h>
+#include <errno.h>
+#include <string.h>
+
+#include "nickel/xalloc.h"
+
+void* ni_xmalloc(size_t size) {
+    void* retptr = malloc(size);
+
+    if (retptr != NULL) {
+        return retptr;
+    } else {
+        perror("xmalloc failed");
+        exit(EXIT_FAILURE);
+    }    
+}
+
+void* ni_xcalloc(size_t nmemb,size_t size) {
+    void* retptr = calloc(nmemb, size);
+
+    if (retptr != NULL) {
+        return retptr;
+    } else {
+        perror("xcalloc failed");
+        exit(EXIT_FAILURE);
+    }    
+}
+
+void* ni_xrealloc(void* ptr, size_t size) {
+    void* retptr = realloc(ptr, size);
+
+    if (retptr != NULL) {
+        return retptr;
+    } else {
+        perror("xrealloc failed");
+        exit(EXIT_FAILURE);
+    }    
+}
+
+char* ni_xstrdup(const char *s) {
+    void* dupstr = strdup(s);
+
+    if (dupstr != NULL) {
+        return dupstr;
+    } else {
+        perror("xdupstr failed");
+        exit(EXIT_FAILURE);
+    }
+}
+
+char* ni_xstrndup(const char s[], size_t n) {
+    void* dupstr = strndup(s, n);
+
+    if (dupstr != NULL) {
+        return dupstr;
+    } else {
+        perror("xdupstr failed");
+        exit(EXIT_FAILURE);
+    }
+}