Package org.graalvm.nativeimage.c.function

Annotation Interface CEntryPoint

@Retention(RUNTIME) @Target(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 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 CEntryPoint.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.

Since:
19.0

  • Element Details

    • name

      String name
      The symbol name to use for this entry point.
      Since:
      19.0
      Default:
      ""

    • documentation

      String[] documentation
      Method documentation to be included in the header file, as an array of lines.
      Since:
      19.0
      Default:
      {""}

    • exceptionHandler

      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

      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

      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

      CEntryPoint.Publish publishAs
      Whether the entry point is part of the symbols and header files produced by Native Image.
      Since:
      22.0
      Default:
      SymbolAndHeader