From 7af36fb445335a7119b9fbefd005917191170ca8 Mon Sep 17 00:00:00 2001 From: Peter Lawrey Date: Sat, 18 Apr 2026 12:24:05 +0100 Subject: [PATCH 1/2] docs: replace above-U+00FF characters with ASCII equivalents Documentation is expected to stay within 8-bit (1-255) so characters outside that range are folded to the closest Latin-1/ASCII forms: - U+2013 en-dash, U+2010/U+2011/U+2012 hyphens -> `-` - U+2014 em-dash, U+2015 horizontal bar -> `--` - U+2026 ellipsis -> `...` - U+200B-U+200F zero-width / direction marks -> removed - U+2018/U+2019 smart single quotes -> `'` - U+201C/U+201D smart double quotes -> `"` - U+2264/U+2265 math less/greater-equal -> `<=`, `>=` Latin-1 characters (micro sign, NBSP, etc.) are left alone. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.adoc | 20 ++++++++++---------- src/main/adoc/decision-log.adoc | 12 ++++++------ 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/README.adoc b/README.adoc index f1d606c..10fcc77 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. @@ -74,7 +74,7 @@ posix.munmap(addr, 4096); | 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 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. From 75017b440e290e34bd8378fa64a76b32873cb812 Mon Sep 17 00:00:00 2001 From: Peter Lawrey Date: Sat, 18 Apr 2026 13:44:53 +0100 Subject: [PATCH 2/2] Complete above-255 normalisation --- README.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.adoc b/README.adoc index 10fcc77..4668382 100644 --- a/README.adoc +++ b/README.adoc @@ -71,7 +71,7 @@ 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` ... @@ -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] -