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 an IsolateThread that is specific to the current thread. This pointer can be obtained via CurrentIsolate#getCurrentThread(). When there is more than one parameter of IsolateThread, exactly one of the parameters must be annotated with IsolateThreadContext.

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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	CEntryPoint.AlwaysIncluded A `BooleanSupplier` that always returns `true`.
public static enum	CEntryPoint.Builtin The built-in methods which can be aliased.
public static interface	CEntryPoint.ExceptionHandler Marker interface for all `exception handler` classes.
public static class	CEntryPoint.FatalExceptionHandler Special placeholder value for `exceptionHandler()` to print the caught exception and treat it as a `fatal error`.
public static @interface	CEntryPoint.IsolateContext Designates an `Isolate` parameter to use as the execution context.
public static @interface	CEntryPoint.IsolateThreadContext Designates an `IsolateThread` parameter to use as the execution context.
public static class	CEntryPoint.NotIncludedAutomatically A `BooleanSupplier` that always returns `false`.
public static enum	CEntryPoint.Publish

Method Summary

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

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

Method Detail

builtin back to summary

builtin	back to summary
public 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

public 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

documentation	back to summary
public String[] documentation() Method documentation to be included in the header file, as an array of lines. Since 19.0

documentation

back to summary

public String[] documentation()

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

Since: 19.0

exceptionHandler back to summary

exceptionHandler	back to summary
public 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

public 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

include back to summary

include	back to summary
public 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

public 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

name	back to summary
public String name() The symbol name to use for this entry point. Since 19.0

name

back to summary

public String name()

The symbol name to use for this entry point.

Since: 19.0

publishAs	back to summary
public CEntryPoint.Publish publishAs() Whether the entry point is part of the symbols and header files produced by Native Image. Since 22.0

publishAs

back to summary

public CEntryPoint.Publish publishAs()

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

Since: 22.0

org.graalvm.nativeimage.c.function back to summary

public final Class CEntryPoint.AlwaysIncluded

Class Inheritance

extends Object
implements BooleanSupplier

java.lang.Object
org.graalvm.nativeimage.c.function.CEntryPoint.AlwaysIncluded

All Implemented Interfaces

java.util.function.BooleanSupplier

A BooleanSupplier that always returns true.

Since: 22.0

Constructor Summary

Access	Constructor and Description
private	AlwaysIncluded()

Method Summary

Modifier and Type	Method and Description
public boolean	getAsBoolean() Implements java.util.function.BooleanSupplier.getAsBoolean. Returns `true`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

AlwaysIncluded	back to summary
private AlwaysIncluded()

Method Detail

getAsBoolean back to summary

getAsBoolean	back to summary
public boolean getAsBoolean() Implements java.util.function.BooleanSupplier.getAsBoolean. Returns `true`. Returns:boolean Doc from java.util.function.BooleanSupplier.getAsBoolean. a result Annotations @Override Since 22.0

public boolean getAsBoolean()

Implements java.util.function.BooleanSupplier.getAsBoolean.

Returns true.

Returns:boolean

Doc from java.util.function.BooleanSupplier.getAsBoolean.

a result

Annotations

@Override

Since

22.0

org.graalvm.nativeimage.c.function back to summary

public final Enum CEntryPoint.Builtin

Class Inheritance

extends Enum<CEntryPoint.Builtin>

java.lang.Object
java.lang.Enum
org.graalvm.nativeimage.c.function.CEntryPoint.Builtin

The built-in methods which can be aliased.

Since: 19.0

Field Summary

Modifier and Type	Field and Description
public static final CEntryPoint.Builtin	ATTACH_THREAD The annotated method attaches the current thread to an isolate.
public static final CEntryPoint.Builtin	CREATE_ISOLATE The annotated method creates an isolate.
public static final CEntryPoint.Builtin	DETACH_THREAD The annotated method detaches the current thread, given as an `IsolateThread`, from an isolate.
public static final CEntryPoint.Builtin	GET_CURRENT_THREAD The annotated method returns the `IsolateThread` of the current thread in a specified `Isolate`.
public static final CEntryPoint.Builtin	GET_ISOLATE The annotated method returns the `Isolate` for an `IsolateThread`.
public static final CEntryPoint.Builtin	NO_BUILTIN The annotated method is not an alias for a built-in method.
public static final CEntryPoint.Builtin	TEAR_DOWN_ISOLATE The annotated method tears down the specified isolate.

Constructor Summary

Access	Constructor and Description
private	Builtin()

Method Summary

Modifier and Type	Method and Description
public static CEntryPoint.Builtin	valueOf(String name)
public static CEntryPoint.Builtin[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

ATTACH_THREAD back to summary

ATTACH_THREAD	back to summary
public static final CEntryPoint.Builtin ATTACH_THREAD The annotated method attaches the current thread to an isolate. It requires a parameter of type `Isolate` with the isolate to attach to, and a return type of `IsolateThread`. In case of an error, `NULL` is returned. Since 19.0

public static final CEntryPoint.Builtin ATTACH_THREAD

The annotated method attaches the current thread to an isolate. It requires a parameter of type Isolate with the isolate to attach to, and a return type of IsolateThread. In case of an error, NULL is returned.

Since: 19.0

CREATE_ISOLATE back to summary

CREATE_ISOLATE	back to summary
public static final CEntryPoint.Builtin CREATE_ISOLATE The annotated method creates an isolate. An alias for this built-in requires no arguments, and must have a return type of `IsolateThread`. In case of an error, `NULL` is returned. Since 19.0

public static final CEntryPoint.Builtin CREATE_ISOLATE

The annotated method creates an isolate. An alias for this built-in requires no arguments, and must have a return type of IsolateThread. In case of an error, NULL is returned.

Since: 19.0

DETACH_THREAD back to summary

DETACH_THREAD	back to summary
public static final CEntryPoint.Builtin DETACH_THREAD The annotated method detaches the current thread, given as an `IsolateThread`, from an isolate. It requires a parameter of type `IsolateThread`, and a return type of `int` or `void`. With an `int` return type, zero is returned when successful, or non-zero in case of an error. Since 19.0

public static final CEntryPoint.Builtin DETACH_THREAD

The annotated method detaches the current thread, given as an IsolateThread, from an isolate. It requires a parameter of type IsolateThread, and a return type of int or void. With an int return type, zero is returned when successful, or non-zero in case of an error.

Since: 19.0

GET_CURRENT_THREAD back to summary

GET_CURRENT_THREAD	back to summary
public static final CEntryPoint.Builtin GET_CURRENT_THREAD The annotated method returns the `IsolateThread` of the current thread in a specified `Isolate`. It requires a parameter of type `Isolate` for the isolate in question, and a return type of `IsolateThread`. In case of an error or if the current thread is not attached to the specified isolate, `NULL` is returned. Since 19.0

public static final CEntryPoint.Builtin GET_CURRENT_THREAD

The annotated method returns the IsolateThread of the current thread in a specified Isolate. It requires a parameter of type Isolate for the isolate in question, and a return type of IsolateThread. In case of an error or if the current thread is not attached to the specified isolate, NULL is returned.

Since: 19.0

GET_ISOLATE back to summary

GET_ISOLATE	back to summary
public static final CEntryPoint.Builtin GET_ISOLATE The annotated method returns the `Isolate` for an `IsolateThread`. It requires a parameter of type `IsolateThread`, and a return type of `Isolate`. In case of an error, `NULL` is returned. Since 19.0

public static final CEntryPoint.Builtin GET_ISOLATE

The annotated method returns the Isolate for an IsolateThread. It requires a parameter of type IsolateThread, and a return type of Isolate. In case of an error, NULL is returned.

Since: 19.0

NO_BUILTIN	back to summary
public static final CEntryPoint.Builtin NO_BUILTIN The annotated method is not an alias for a built-in method. Since 19.0

NO_BUILTIN

back to summary

public static final CEntryPoint.Builtin NO_BUILTIN

The annotated method is not an alias for a built-in method.

Since: 19.0

TEAR_DOWN_ISOLATE back to summary

TEAR_DOWN_ISOLATE	back to summary
public static final CEntryPoint.Builtin TEAR_DOWN_ISOLATE The annotated method tears down the specified isolate. It requires a parameter of type `IsolateThread`, and a return type of `int` or `void`. With an `int` return type, zero is returned when successful, or non-zero in case of an error. Since 19.0

public static final CEntryPoint.Builtin TEAR_DOWN_ISOLATE

The annotated method tears down the specified isolate. It requires a parameter of type IsolateThread, and a return type of int or void. With an int return type, zero is returned when successful, or non-zero in case of an error.

Since: 19.0

Constructor Detail

Builtin	back to summary
private Builtin()

Method Detail

valueOf	back to summary
public static CEntryPoint.Builtin valueOf(String name)

values	back to summary
public static CEntryPoint.Builtin[] values()

org.graalvm.nativeimage.c.function back to summary

public Interface CEntryPoint.ExceptionHandler

Known Direct Implementers: org.graalvm.nativeimage.c.function.CEntryPoint.FatalExceptionHandler

Marker interface for all exception handler classes.

Since: 22.0

org.graalvm.nativeimage.c.function back to summary

public final Class CEntryPoint.FatalExceptionHandler

Class Inheritance

extends Object
implements ExceptionHandler

java.lang.Object
org.graalvm.nativeimage.c.function.CEntryPoint.FatalExceptionHandler

All Implemented Interfaces

org.graalvm.nativeimage.c.function.CEntryPoint.ExceptionHandler

Special placeholder value for exceptionHandler() to print the caught exception and treat it as a fatal error.

Since: 19.0

Constructor Summary

Access	Constructor and Description
private	FatalExceptionHandler()

Method Summary

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

FatalExceptionHandler	back to summary
private FatalExceptionHandler()

org.graalvm.nativeimage.c.function back to summary

public @Interface CEntryPoint.IsolateContext

Annotations

extends Annotation

@Retention:RUNTIME
@Target:PARAMETER

Designates an Isolate parameter to use as the execution context. At most one parameter can be annotated with this annotation or IsolateThreadContext.

Since: 19.0

Method Summary

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

org.graalvm.nativeimage.c.function back to summary

public @Interface CEntryPoint.IsolateThreadContext

Annotations

extends Annotation

@Retention:RUNTIME
@Target:PARAMETER

Designates an IsolateThread parameter to use as the execution context. At most one parameter can be annotated with this annotation or IsolateContext.

Since: 19.0

Method Summary

Inherited from java.lang.annotation.Annotation:: annotationType equals hashCode toString

org.graalvm.nativeimage.c.function back to summary

public final Class CEntryPoint.NotIncludedAutomatically

Class Inheritance

extends Object
implements BooleanSupplier

java.lang.Object
org.graalvm.nativeimage.c.function.CEntryPoint.NotIncludedAutomatically

All Implemented Interfaces

java.util.function.BooleanSupplier

A BooleanSupplier that always returns false.

Since: 22.0

Constructor Summary

Access	Constructor and Description
private	NotIncludedAutomatically()

Method Summary

Modifier and Type	Method and Description
public boolean	getAsBoolean() Implements java.util.function.BooleanSupplier.getAsBoolean. Returns `false`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

NotIncludedAutomatically	back to summary
private NotIncludedAutomatically()

Method Detail

getAsBoolean back to summary

getAsBoolean	back to summary
public boolean getAsBoolean() Implements java.util.function.BooleanSupplier.getAsBoolean. Returns `false`. Returns:boolean Doc from java.util.function.BooleanSupplier.getAsBoolean. a result Annotations @Override Since 22.0

public boolean getAsBoolean()

Implements java.util.function.BooleanSupplier.getAsBoolean.

Returns false.

Returns:boolean

Doc from java.util.function.BooleanSupplier.getAsBoolean.

a result

Annotations

@Override

Since

22.0

org.graalvm.nativeimage.c.function back to summary

public final Enum CEntryPoint.Publish

Class Inheritance

extends Enum<CEntryPoint.Publish>

java.lang.Object
java.lang.Enum
org.graalvm.nativeimage.c.function.CEntryPoint.Publish

Since: 22.0

Field Summary

Modifier and Type	Field and Description
public static final CEntryPoint.Publish	NotPublished Do not publish the entry point method.
public static final CEntryPoint.Publish	SymbolAndHeader Create a symbol for the entry point method in the native image, and if building a shared library image, also include a C declaration in the generated C header file.
public static final CEntryPoint.Publish	SymbolOnly Create a symbol for the entry point method in the native image.

Constructor Summary

Access	Constructor and Description
private	Publish()

Method Summary

Modifier and Type	Method and Description
public static CEntryPoint.Publish	valueOf(String name)
public static CEntryPoint.Publish[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

NotPublished	back to summary
public static final CEntryPoint.Publish NotPublished Do not publish the entry point method.

SymbolAndHeader	back to summary
public static final CEntryPoint.Publish SymbolAndHeader Create a symbol for the entry point method in the native image, and if building a shared library image, also include a C declaration in the generated C header file.

SymbolOnly	back to summary
public static final CEntryPoint.Publish SymbolOnly Create a symbol for the entry point method in the native image.

Constructor Detail

Publish	back to summary
private Publish()

Method Detail

valueOf	back to summary
public static CEntryPoint.Publish valueOf(String name)

values	back to summary
public static CEntryPoint.Publish[] values()