nivirx/nickel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

clean up readme

Browse Source
This commit is contained in:
Elaina Claus
2026-01-15 12:51:44 -05:00
parent eab45f3f58
commit 30273486f1
1 changed files with 49 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
README.md
View File

@@ -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
---