Package express.mvp.roray.utils.functions

package express.mvp.roray.utils.functions
Utilities for the Foreign Function & Memory (FFM) API.

This package provides helper classes that reduce boilerplate when working with Java's FFM API for native interop, while maintaining zero runtime overhead.

Design Philosophy

All abstractions in this package are designed for setup-time cost only. The helpers produce standard FFM objects (MethodHandle, FunctionDescriptor, MemoryLayout) that should be stored in static final fields for optimal JIT performance.

Core Utilities (Phase 1)

Extended Utilities (Phase 2)

  • ErrnoCapture - Helper for capturing and interpreting errno
  • StructAccessor - VarHandle-based struct field accessors
  • CriticalSafe - Annotation marking functions safe for critical mode
  • NeverCritical - Annotation marking functions that should NOT use critical mode

Platform Support

The layouts and utilities are designed for the LP64 data model:

  • Linux x86_64 (AMD64) ✓
  • Linux ARM64 (aarch64) ✓
  • Linux RISC-V 64 ✓
  • Windows x64 ✗ (uses LLP64)
  • 32-bit systems ✗

Example Usage

// Create a factory for libc functions
private static final DowncallFactory LIBC = DowncallFactory.forNativeLinker();

// Define downcall handles
private static final MethodHandle getpid = LIBC.downcall(
    "getpid",
    FunctionDescriptorBuilder.returnsInt().build()
);

private static final MethodHandle socket = LIBC.downcall(
    "socket",
    FunctionDescriptorBuilder.returnsInt()
        .args(LinuxLayouts.C_INT, LinuxLayouts.C_INT, LinuxLayouts.C_INT)
        .build()
);

// Use the handles
public static int getPid() throws Throwable {
    return (int) getpid.invokeExact();
}
See Also:
  • Class
    Description
    CriticalSafe
    Marker annotation to document that a native function is safe to call with Linker.Option.critical(false).
    DowncallFactory
    Factory for creating downcall handles with common patterns.
    ErrnoCapture
    Helper for capturing and interpreting errno from native calls.
    FunctionDescriptorBuilder
    Fluent builder for FunctionDescriptor - all costs are paid at setup time.
    LinuxLayouts
    Pre-defined MemoryLayout constants for common Linux/C types and structures.
    NeverCritical
    Marker annotation to document that a native function should NOT be called with Linker.Option.critical(false).
    StructAccessor
    Provides convenient accessors for reading and writing struct fields in a MemorySegment.
    UpcallFactory
    Factory for creating upcall stubs (Java callbacks callable from native code).