Annotation Interface NeverCritical

@Documented
@Retention(SOURCE)
@Target({FIELD,METHOD,LOCAL_VARIABLE})
public @interface NeverCritical

Marker annotation to document that a native function should NOT be called with Linker.Option.critical(false).

This annotation is for documentation purposes only and does not provide compile-time enforcement. It serves as a warning to developers that the annotated function may:

• Make system calls that can block
• Trigger callbacks into Java (upcalls)
• Take locks that could contend with GC
• Perform I/O operations

Why No Compile-Time Enforcement?

The Java compiler cannot verify that a MethodHandle was created with or without the critical option, as this is a runtime decision. Additionally, the safety of using critical mode depends on the native function's implementation, which cannot be introspected at compile time.

Usage

// Document that this handle should NOT use critical mode
@NeverCritical("Blocks waiting for I/O completion")
private static final MethodHandle io_uring_wait_cqe = FACTORY.downcall(
    "io_uring_wait_cqe", descriptor
    // NO critical option here - this blocks!
);

// This handle CAN safely use critical mode (not annotated)
private static final MethodHandle io_uring_cq_ready = FACTORY.downcall(
    "io_uring_cq_ready", descriptor,
    Linker.Option.critical(false)  // Safe: just reads memory
);

Static Analysis

For actual enforcement, consider using static analysis tools like:

• Error Prone (custom BugChecker)
• SpotBugs (custom detector)
• Checker Framework (custom type system)

See Also:

• CriticalSafe

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	value	Explanation of why this function should not use critical mode.

Element Details

value

String value

Explanation of why this function should not use critical mode.

Default:

""