Annotation Interface CriticalSafe

@Documented @Retention(SOURCE) @Target({FIELD,METHOD,LOCAL_VARIABLE}) public @interface CriticalSafe
Marker annotation to document that a native function is safe to call with Linker.Option.critical(false).

A function is safe for critical mode when it:

  • Does NOT make system calls
  • Does NOT block or wait
  • Does NOT call back into Java (no upcalls)
  • Does NOT take locks that could contend with GC
  • Executes in bounded, short time

Critical mode skips the thread state transition overhead (~10-20ns savings) but prevents the JVM from reaching a safepoint during the call. Misusing critical mode with blocking calls can cause GC pauses and deadlocks.

Good Candidates for Critical Mode

  • Pure memory reads/writes (no syscalls)
  • Pointer arithmetic operations
  • CPU-only operations (memory fences, atomics)
  • Fast inline functions that don't call other functions

Usage

@CriticalSafe("Pure memory read, no syscall")
private static final MethodHandle io_uring_cq_ready = FACTORY.downcall(
    "io_uring_cq_ready", descriptor,
    Linker.Option.critical(false)
);
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    value
    Explanation of why this function is safe for critical mode.

  • Element Details

    • value

      String value
      Explanation of why this function is safe for critical mode.
      Default:
      ""