NativeFunction.md

NativeFunction

NativeFunction is a fluent builder for configuring dynamic downcalls. It maps Java parameters to their native carriers, executes downcalls via Java's MethodHandle, and converts the results back to high-level Java types.

Key Features

• Fluent Configuration: Chained .returns(...) and .args(...) calls.
• Automatic Garbage Collection of Arguments: When arguments require native allocation (e.g. translating a Java String to a UTF-8 C-string), a confined call-scope arena is created for the execution and automatically cleared right before the method returns.
• Type mapping: Accepts Java classes (resolved via TypeMapperRegistry) or explicit TypeSpec / NativeType constants.

Usage Example

import io.github.undeffineddev.ffmkit.NativeLibrary;
import io.github.undeffineddev.ffmkit.NativeFunction;
import static io.github.undeffineddev.ffmkit.type.NativeType.*;

try (NativeLibrary libc = NativeLibrary.load("c")) {
    
    // Class-based signature (int / String → C int / char*)
    NativeFunction strlen = libc.function("strlen")
        .returns(int.class)
        .args(String.class);

    int length = (int) strlen.invoke("ffmkit");
    System.out.println(length); // 6

    // Explicit C types (same mapping)
    libc.function("strlen")
        .returns(C_INT)
        .args(C_STRING)
        .invoke("ffmkit");
}

Built-in mappings (boolean → 1-byte _Bool, char → 1-byte C char, C_LONG platform width, …) are documented in NativeTypes.md.