diff --git a/README.adoc b/README.adoc index f1d606c..4668382 100644 --- a/README.adoc +++ b/README.adoc @@ -39,22 +39,22 @@ posix.munmap(addr, 4096); == Design goals -* _Determinism_ – no heap allocation on the hot path. -* _Portability_ – Linux/macOS/Windows support via provider auto-selection. -* _Fallback safety_ – `NoOpPosixAPI` guarantees compilation in CI sandboxes. -* _Traceability_ – every public constant links to POSIX-FN requirements. +* _Determinism_ - no heap allocation on the hot path. +* _Portability_ - Linux/macOS/Windows support via provider auto-selection. +* _Fallback safety_ - `NoOpPosixAPI` guarantees compilation in CI sandboxes. +* _Traceability_ - every public constant links to POSIX-FN requirements. == Provider selection & fall-back [cols="1,1,3"] |=== -| Provider | Native layer | Typical when… +| Provider | Native layer | Typical when... | `JNRPosixAPI` | JNR-FFI | **Linux** & x86_64/ARM, fastest syscalls | `WinJNRPosixAPI` | JNR-FFI | **Windows** equivalents (subset) | `JNAPosixAPI` | JNA | exotic/legacy platforms -| `RawPosixAPI` | Reflection | JVM ≥ 21 with `--add-opens` -| `NoOpPosixAPI` | — | CI sandboxes / Graal native-image +| `RawPosixAPI` | Reflection | JVM >= 21 with `--add-opens` +| `NoOpPosixAPI` | -- | CI sandboxes / Graal native-image |=== `-Dchronicle.posix.provider=` *provider-name* overrides the auto-choice. @@ -71,10 +71,10 @@ posix.munmap(addr, 4096); | Memory | `mmap`, `munmap`, `madvise`, `msync`, `mlock*`, `fallocate` -| addr / 0 | `MAP_FAILED` → -1 sentinel +| addr / 0 | `MAP_FAILED` -> -1 sentinel | CPU-affinity -| `sched_*affinity*`, helpers `sched_setaffinity_as` … +| `sched_*affinity*`, helpers `sched_setaffinity_as` ... | 0 | portable bit-mask helpers | Timing @@ -92,8 +92,8 @@ mvn -q verify Environment variables: -* `POSIX_TEST_ALLOW_NATIVE` – set to *false* in CI to force `NoOpPosixAPI`. -* `POSIX_SYSLOG_LEVEL` – adjust logging noise during native provider load. +* `POSIX_TEST_ALLOW_NATIVE` - set to *false* in CI to force `NoOpPosixAPI`. +* `POSIX_SYSLOG_LEVEL` - adjust logging noise during native provider load. == Troubleshooting @@ -123,4 +123,3 @@ Add JVM arg: * link:src/main/adoc/project-requirements.adoc[Functional requirements] * link:src/main/adoc/decision-log.adoc[Architecture decision log] * link:https://man7.org/linux/man-pages/[Linux man-pages] - diff --git a/src/main/adoc/decision-log.adoc b/src/main/adoc/decision-log.adoc index 225bec4..395aaa9 100644 --- a/src/main/adoc/decision-log.adoc +++ b/src/main/adoc/decision-log.adoc @@ -1,4 +1,4 @@ -= Decision Log – OpenHFT Posix += Decision Log - OpenHFT Posix :doctype: book :toc: :icons: font @@ -26,8 +26,8 @@ Chronicle teams span multiple regions. Mixed US/UK spelling and occasional UTF-8 * Restrict all source and documentation files to **ASCII-7** code-points (0-127). *Alternatives considered*:: -*Allow UTF-8 universally* – rejected: breaks zero-copy buffers that rely on MSB=0. -*Allow US spellings* – rejected: inconsistent with London HQ style guide. +*Allow UTF-8 universally* - rejected: breaks zero-copy buffers that rely on MSB=0. +*Allow US spellings* - rejected: inconsistent with London HQ style guide. *Consequences*:: * Tooling: CI linter added (`scripts/check-ascii.sh`). @@ -50,8 +50,8 @@ At first successful class-load we try providers in this strict order: Override with `-Dchronicle.posix.provider`. *Alternatives*:: -*ServiceLoader scan* – too slow; non-deterministic. -*OS-hard-coded providers* – would fork the code-base per platform. +*ServiceLoader scan* - too slow; non-deterministic. +*OS-hard-coded providers* - would fork the code-base per platform. *Consequences*:: * Single-point selection in `PosixAPIHolder`. @@ -60,7 +60,7 @@ Override with `-Dchronicle.posix.provider`. == ALL-DOC-002 Real-Time Documentation Loop *Context*:: -Documentation drift led to mis-generated code from AI agents. The team adopted a “doc-first or doc-alongside” workflow but lacked formal guidance. +Documentation drift led to mis-generated code from AI agents. The team adopted a "doc-first or doc-alongside" workflow but lacked formal guidance. *Decision*:: * Update AsciiDoc **in the same commit** as code/tests.