Nickel lib overview/roadmap

Core “make C nicer” utilities

1. xmalloc/xcalloc/xrealloc/xstrdup (header: xalloc.h)

   • Teaches: error handling patterns, errno, consistent OOM behavior.

2. Arena allocator (header: arena.h)

   • arena_init, arena_alloc, arena_reset, arena_free
   • Teaches: alignment, bump allocators, lifetime-based allocation.

3. Dynamic buffer / string builder (header: buf.h)

   • buf_reserve, buf_append, buf_appendf
   • Teaches: amortized growth, vsnprintf, safe formatting.

4. Slice + spans (header: span.h)

   • typedef struct { uint8_t* p; size_t n; } span_u8; etc.
   • Teaches: safer APIs than raw pointers, length-carrying.

5. Hash map (header: hashmap.h) (string→void* or string→u64)

   • Teaches: hashing, open addressing, tombstones, resizing.

6. Bitset (header: bitset.h)

   • bitset_set/clear/test, bitset_find_first_zero
   • Teaches: word operations, popcount/ctz if you want.

7. Intrusive double linked list (header: linkedlist.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”.

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.

3. Defer/cleanup pattern (header: defer.h)

   • Macro that runs cleanup at scope end (via goto pattern).
   • Teaches: structured cleanup in C, error paths.

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

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

2. Lock-free SPSC ring buffer (header: ring_spsc.h)

   • Single-producer/single-consumer queue.
   • Teaches: atomics, cache friendliness, correctness reasoning.

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.

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

1. Argument parser (header: argparse.h)

   • --long, -s, combined short flags, --key=value
   • Teaches: string parsing, API design, test cases.

2. INI parser (header: ini.h)

   • Minimal: sections, key=value, comments.
   • Teaches: parsing state machines, callbacks.

3. CSV reader/writer (header: csv.h)

   • Correct quoting/escaping.
   • Teaches: edge cases, streaming parsing.

4. Path utilities (header: path.h)

   • path_join, path_dirname, path_basename, normalize .. and .
   • Teaches: portability pitfalls, careful string ops.

Systems-ish building blocks

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.

2. Timing + profiling helpers (header: timeutil.h)

   • now_ns(), stopwatch, scope_timer macro
   • Teaches: timespec_get, measurement pitfalls, microbenchmark hygiene.

---

suggested order

xalloc/arena/buf -> static assert, generic, cleanup, results -> argparse -> io -> parsers -> atomics/threads -> hashmap/bitset-> timing -> ring + threadpool, as capstone

---

Two capstone tool ideas that use a lot of the above

• logscan: fast log parser + filter + histogram (buf + argparse + csv + hashmap + timeutil)
• dedupe: file deduplicator by hashing chunks (io + hashmap + arena + threadpool)

---