Skip to content

docs: replace above-U+00FF characters with 8-bit equivalents #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
peter-lawrey wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

docs: replace above-U+00FF characters with 8-bit equivalents #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7af36fb
docs: replace above-U+00FF characters with ASCII equivalents
peter-lawrey Apr 18, 2026
75017b4
Complete above-255 normalisation
peter-lawrey Apr 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 11 additions & 12 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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]

12 changes: 6 additions & 6 deletions src/main/adoc/decision-log.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
= Decision Log – OpenHFT Posix
= Decision Log - OpenHFT Posix
:doctype: book
:toc:
:icons: font
Expand Down Expand Up @@ -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`).
Expand All @@ -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`.
Expand All @@ -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.
Expand Down