org.graalvm.nativeimage.c.function

Annotation Type CEntryPoint

@Retention(value=RUNTIME)
 @Target(value=METHOD)
public @interface CEntryPoint

Annotates a method that is a VM entry point. Such a method must be declared static, and is made accessible so that it can be called as a C function using the native ABI.

An execution context must be passed as a parameter and can be either an IsolateThread that is specific to the current thread, or an Isolate for an isolate in which the current thread is attached. These pointers can be obtained via the methods of CurrentIsolate. When there is more than one parameter of these types, exactly one of the parameters must be annotated with CEntryPoint.IsolateThreadContext for IsolateThread, or CEntryPoint.IsolateContext for Isolate.

Exceptions cannot be thrown to the caller and must be explicitly caught in the entry point method. Any uncaught exception causes the termination of the process after it is printed.

No object types are permitted for parameters or return types; only primitive Java values, word values, and enum values are allowed. Enum values are automatically converted from integer constants to Java enum object constants. The enum class must have a CEnum annotation. When enum values are passed as parameters, the enum class must have a method with a CEnumLookup annotation. For enum return types, the enum class must have a method that is annotated with CEnumValue.

Since:

19.0

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
CEntryPoint.Builtin	builtin Specifies that the annotated entry point method is an alias for a built-in function as provided by the C API.
String[]	documentation Method documentation to be included in the header file, as an array of lines.
Class<? extends CEntryPoint.ExceptionHandler>	exceptionHandler Provides an exception handler for all exceptions that are not handled explicitly by the entry point method.
Class<? extends BooleanSupplier>	include If the supplier returns true, this entry point is added automatically when building a shared library.
String	name The symbol name to use for this entry point.
CEntryPoint.Publish	publishAs Whether the entry point is part of the symbols and header files produced by Native Image.

Element Detail

name

public abstract String name

The symbol name to use for this entry point.

Since:

19.0

Default:

""

documentation

public abstract String[] documentation

Method documentation to be included in the header file, as an array of lines.

Since:

19.0

Default:

""

exceptionHandler

public abstract Class<? extends CEntryPoint.ExceptionHandler> exceptionHandler

Provides an exception handler for all exceptions that are not handled explicitly by the entry point method. Java exceptions cannot be passed back to C code. If this property is not set, any uncaught exception is treated as a fatal error.

The provided class must have exactly one declared method (the exception handler method). The method must be static, have one parameter of type Throwable or Object, and must have a return type that is assignable to the return type of the annotated entry point method. That exception handler method is invoked when an exception reaches the entry point, and the exception is passed as the argument. The return value of the exception handler method is then the return value of the entry point, i.e., passed back to the C code.

Since:

19.0

Default:

org.graalvm.nativeimage.c.function.CEntryPoint.FatalExceptionHandler.class

builtin

public abstract CEntryPoint.Builtin builtin

Specifies that the annotated entry point method is an alias for a built-in function as provided by the C API. Such aliases may have extra arguments which are ignored and can be used to adhere to specific external conventions. The annotated method must be declared native and as such, cannot have its own code body. Refer to the C API for descriptions of the built-ins, and to the individual built-ins for their requirements to the annotated method's signature.

Since:

19.0

Default:

NO_BUILTIN

include

public abstract Class<? extends BooleanSupplier> include

If the supplier returns true, this entry point is added automatically when building a shared library. This means the method is a root method for compilation, and everything reachable from it is compiled too. The provided class must have a nullary constructor, which is used to instantiate the class. Then the supplier function is called on the newly instantiated instance.

Since:

22.0

Default:

org.graalvm.nativeimage.c.function.CEntryPoint.AlwaysIncluded.class

publishAs

public abstract CEntryPoint.Publish publishAs

Whether the entry point is part of the symbols and header files produced by Native Image.

Since:

22.0

Default:

SymbolAndHeader