From 30273486f1c51973f1a72668ccd9bb7633d58814 Mon Sep 17 00:00:00 2001 From: Elaina Claus Date: Thu, 15 Jan 2026 12:51:44 -0500 Subject: [PATCH] clean up readme --- README.md | 92 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 49 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 1f008e4..77bd8f3 100644 --- a/README.md +++ b/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. + * `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). + * `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. + * 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. + * `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. + * 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. + * `--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. + * 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. + * 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. + * `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. + * 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. + * `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 ---