org.graalvm.nativeimage.c.struct

Annotation Type CStruct

@Retention(value=RUNTIME)
 @Target(value=TYPE)
public @interface CStruct

Denotes Java interface that imports a C struct. The interface must extend PointerBase, i.e., it is a word type. There is never a Java class that implements the interface.

Field accesses are done via interface methods that are annotated with CField, CFieldAddress, or CFieldOffset. All calls of the interface methods are replaced with the appropriate memory or address arithmetic operations. Here is an example to define a complex number structure:

@CStruct
interface ComplexValue extends PointerBase {
    @CField("re")
    double realPart();

    @CField("re")
    void realPart(double re);

    @CField("im")
    double imagineryPart();

    @CField("im")
    void imagineryPart(double im);
}

The annotated interface, or an outer class that contains the interface, must be annotated with CContext. Allocate an instances of the struct either by StackValue.get(java.lang.Class) or by UnmanagedMemory.malloc(org.graalvm.word.UnsignedWord). To access an array of structs one can define a special addressOf method:

@CStruct("int_double")
interface IntOrDouble extends PointerBase {
    // allows access to individual structs in an array
    IntOrDouble addressOf(int index);

    @CField
    int i();

    @CField
    void i(int i);

    @CField
    double d();

    @CField
    void d(double d);

}

Implementation of such method then allows one to do array arithmetics - e.g. obtain pointer to the first element of the array and then access the others:

private static double acceptIntIntDouble(IntOrDouble arr) {
    IntOrDouble firstInt = arr.addressOf(0);
    IntOrDouble secondInt = arr.addressOf(1);
    IntOrDouble thirdDouble = arr.addressOf(2);
    return firstInt.i() + secondInt.i() + thirdDouble.d();
}

Since:

19.0

See Also:

StackValue, UnmanagedMemory

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	addStructKeyword Add the C "struct" keyword to the name specified in CStruct.value().
boolean	isIncomplete If marked as incomplete, we will not try to determine the size of the struct.
String	value Specifies the name of the imported C struct type.

Element Detail

value

public abstract String value

Specifies the name of the imported C struct type. If no name is provided, the type name is used as the struct name.

Since:

19.0

Default:

""

isIncomplete

public abstract boolean isIncomplete

If marked as incomplete, we will not try to determine the size of the struct.

Since:

19.0

Default:

false

addStructKeyword

public abstract boolean addStructKeyword

Add the C "struct" keyword to the name specified in CStruct.value().

Since:

19.0

Default:

false