Posix

Table of Contents

• Quick start
• Design goals
• Provider selection & fall-back
• Supported system calls
• Build & test
• Troubleshooting
• Further reading

The OpenHFT Posix module is a zero-GC, low-latency Java façade over a portable subset of POSIX/Linux system calls, with provider fall-back to JNR, JNA or raw/reflective variants. Chronicle components rely on it for deterministic file-IO, memory-mapping and CPU-affinity operations that the JDK does not expose.

Audience: Internal, Stability: Stable

Quick start

Gradle / Maven

<dependency>
  <groupId>net.openhft</groupId>
  <artifactId>posix</artifactId>
  <version>{project-version}</version>
</dependency>

Simple usage:

PosixAPI posix = PosixAPI.posix();
long addr      = posix.mmap(0, 4096,
                           MMapProt.PROT_READ_WRITE.value(),
                           MMapFlag.PRIVATE.value(),
                           fd, 0);
...
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.

Provider selection & fall-back

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

-Dchronicle.posix.provider= provider-name overrides the auto-choice.

Supported system calls

Area	Functions	Return model	Notes
File-IO	open, close, ftruncate, lseek, read, write, lockf	0 / FD / bytes	errno surfaced via PosixRuntimeException
Memory	mmap, munmap, madvise, msync, mlock*, fallocate	addr / 0	MAP_FAILED → -1 sentinel
CPU-affinity	sched_*affinity*, helpers sched_setaffinity_as …	0	portable bit-mask helpers
Timing	clock_gettime, gettimeofday	ns / µs	falls back to System.nanoTime on JDK < 17

Build & test

# run unit tests + Checkstyle + spot-bugs
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.

Troubleshooting

Why do I get PosixRuntimeException: EPERM on mlockall?

The process exceeded its RLIMIT_MEMLOCK. On Linux:

ulimit -l unlimited     # or edit /etc/security/limits.conf

Native provider fails to load on JDK 17+

Add JVM arg:

--add-opens java.base/jdk.internal.misc=ALL-UNNAMED

Further reading

• Functional requirements

• Architecture decision log

• Linux man-pages