[GR-71128] Expose argc and argv in graal_create_isolate_params_t.

PullRequest: graal/22596

Author: peter-hofer

docs/reference-manual/native-image/C-API.md

@@ -17,7 +17,7 @@ The C API is available when Native Image is built as a shared library and its de
  * passed to an entry point as the execution context.
  */
 struct __graal_isolate_t;
-typedef struct _graal_isolate_t graal_isolate_t;
+typedef struct __graal_isolate_t graal_isolate_t;
 
 /*
  * Structure representing a thread that is attached to an isolate. A pointer to
@@ -28,17 +28,38 @@ struct __graal_isolatethread_t;
 typedef struct __graal_isolatethread_t graal_isolatethread_t;
 
 /* Parameters for the creation of a new isolate. */
+enum { __graal_create_isolate_params_version = 5 };
 struct __graal_create_isolate_params_t {
-    /* for future use */
+    /* Version of this struct. Set to __graal_create_isolate_params_version after zeroing this struct. */
+    int version;
+
+    /* Fields introduced in version 1 */
+    __graal_uword  reserved_address_space_size; /* Size of virtual address space to reserve for the heap. */
+
+    /* Fields introduced in version 2. Internal usage, do not use. */
+    const char    *auxiliary_image_path;                /* Path to an auxiliary image to load. */
+    __graal_uword  auxiliary_image_reserved_space_size; /* Reserved bytes for loading an auxiliary image. */
+
+    /* Fields introduced in version 3 */
+    int            argc;                        /* Number of char* argument strings in argv. */
+    char         **argv;                        /* Array of argument strings, parsed like command line arguments. */
+    int            pkey;                        /* Isolate protection key or domain. Internal usage, do not use. */
+
+    /* Fields introduced in version 4 */
+    char           ignore_unrecognized_args;    /* Ignore unrecognized arguments in argv when 1. */
+    char           _reserved_4;                 /* Internal usage, do not use. */
+
+    /* Fields introduced in version 5 */
+    char           _reserved_5;                 /* Internal usage, do not use. */
 };
 typedef struct __graal_create_isolate_params_t graal_create_isolate_params_t;
 
 /*
  * Create a new isolate, considering the passed parameters (which may be NULL).
  * Returns 0 on success, or a non-zero value on failure.
  * On success, the current thread is attached to the created isolate, and the
- * address of the isolate and the isolate thread structures is written to the
- * passed pointers if they are not NULL.
+ * address of the isolate and the isolate thread are written to the passed pointers
+ * if they are not NULL.
  */
 int graal_create_isolate(graal_create_isolate_params_t* params, graal_isolate_t** isolate, graal_isolatethread_t** thread);
 
@@ -59,9 +80,8 @@ int graal_attach_thread(graal_isolate_t* isolate, graal_isolatethread_t** thread
 graal_isolatethread_t* graal_get_current_thread(graal_isolate_t* isolate);
 
 /*
- * Given an isolate thread structure, determines to which isolate it belongs and
- * returns the address of its isolate structure. If an error occurs, returns NULL
- * instead.
+ * Given an isolate thread structure, determines to which isolate it belongs and returns
+ * the address of its isolate structure. If an error occurs, returns NULL instead.
  */
 graal_isolate_t* graal_get_isolate(graal_isolatethread_t* thread);
 
@@ -74,10 +94,18 @@ graal_isolate_t* graal_get_isolate(graal_isolatethread_t* thread);
 int graal_detach_thread(graal_isolatethread_t* thread);
 
 /*
- * Tears down the isolate of the passed (and still attached) isolate thread
+ * Tears down the isolate of the passed (and still attached) isolate thread,
  * waiting for any attached threads to detach from it, then discards its objects,
  * threads, and any other state or context that is associated with it.
  * Returns 0 on success, or a non-zero value on failure.
+ *
+ * If this call blocks indefinitely, this means there are still Java threads running
+ * which do not terminate after receiving the Thread.interrupt() event.
+ * To prevent indefinite blocking, these threads should be cooperatively shut down
+ * within Java before invoking this call.
+ * To diagnose such issues, use the option '-R:TearDownWarningSeconds=<secs>' to detect
+ * the threads that are still running.
+ * This will print the stack traces of all threads that block tear-down.
  */
 int graal_tear_down_isolate(graal_isolatethread_t* thread);
 ```

docs/reference-manual/native-image/guides/troubleshoot-run-time-errors.md

@@ -39,7 +39,7 @@ This can be avoided by eagerly checking for missing metadata.
 
 For diagnosing shared libraries built with Native Image, you can either:
 * specify `-R:MissingRegistrationReportingMode=Exit` when building a native shared library;
-* or specify `-XX:MissingRegistrationReportingMode=Exit` when the isolate is created. `graal_create_isolate_params_t` has `argc (_reserved_1)` and `argv (_reserved_2)` fields that can be used to pass C-style command-line options at run time. However, note that both fields are currently not public APIs.
+* or specify `-XX:MissingRegistrationReportingMode=Exit` when the isolate is created. `graal_create_isolate_params_t` has `argc` and `argv` fields that can be used to pass C-style command-line options at run time.
 
 ### 2. Set java.home Explicitly
 

espresso/src/com.oracle.truffle.espresso.mokapot/include/graal_isolate_dynamic.h

@@ -54,24 +54,25 @@ typedef unsigned long __graal_uword;
 #define NEW_PROTECTION_DOMAIN -1
 
 /* Parameters for the creation of a new isolate. */
-enum { __graal_create_isolate_params_version = 4 };
+enum { __graal_create_isolate_params_version = 5 };
 struct __graal_create_isolate_params_t {
-    int version;                                /* Version of this struct */
+    /* Version of this struct. Set to __graal_create_isolate_params_version after zeroing this struct. */
+    int version;
 
     /* Fields introduced in version 1 */
-    __graal_uword  reserved_address_space_size; /* Size of address space to reserve */
+    __graal_uword  reserved_address_space_size; /* Size of virtual address space to reserve for the heap. */
 
-    /* Fields introduced in version 2 */
+    /* Fields introduced in version 2. Internal usage, do not use. */
     const char    *auxiliary_image_path;                /* Path to an auxiliary image to load. */
     __graal_uword  auxiliary_image_reserved_space_size; /* Reserved bytes for loading an auxiliary image. */
 
     /* Fields introduced in version 3 */
-    int            _reserved_1;                 /* Internal usage, do not use. */
-    char         **_reserved_2;                 /* Internal usage, do not use. */
-    int            pkey;                        /* Isolate protection key or domain. */
+    int            argc;                        /* Number of char* argument strings in argv. */
+    char         **argv;                        /* Array of argument strings, parsed like command line arguments. */
+    int            pkey;                        /* Isolate protection key or domain. Internal usage, do not use. */
 
     /* Fields introduced in version 4 */
-    char           _reserved_3;                 /* Internal usage, do not use. */
+    char           ignore_unrecognized_args;    /* Ignore unrecognized arguments in argv when 1. */
     char           _reserved_4;                 /* Internal usage, do not use. */
 
     /* Fields introduced in version 5 */
@@ -136,7 +137,7 @@ typedef int (*graal_detach_thread_fn_t)(graal_isolatethread_t* thread);
  * the threads that are still running.
  * This will print the stack traces of all threads that block tear-down.
  */
-typedef int (*graal_tear_down_isolate_fn_t)(graal_isolatethread_t* isolateThread);
+typedef int (*graal_tear_down_isolate_fn_t)(graal_isolatethread_t* thread);
 
 /*
  * In the isolate of the passed isolate thread, detach all those threads that were
@@ -158,7 +159,7 @@ typedef int (*graal_tear_down_isolate_fn_t)(graal_isolatethread_t* isolateThread
  * the threads that are still running.
  * This will print the stack traces of all threads that block tear-down.
  */
-typedef int (*graal_detach_all_threads_and_tear_down_isolate_fn_t)(graal_isolatethread_t* isolateThread);
+typedef int (*graal_detach_all_threads_and_tear_down_isolate_fn_t)(graal_isolatethread_t* thread);
 
 #if defined(__cplusplus)
 }

espresso/src/com.oracle.truffle.espresso.mokapot/src/mokapot.c

@@ -2228,12 +2228,10 @@ _JNI_IMPORT_OR_EXPORT_ jint JNICALL JNI_CreateJavaVM(JavaVM **vm_ptr, void **pen
     }
 
     params.version = 4;
-    char ignore_unrecognized_arguments = initArgs->ignoreUnrecognized == JNI_TRUE ? 1 : 0;
-    char exit_on_arg_parse_fail = 0;
-    params._reserved_1 = isolate_argc;
-    params._reserved_2 = isolate_argv;
-    params._reserved_3 = ignore_unrecognized_arguments;
-    params._reserved_4 = exit_on_arg_parse_fail;
+    char ignore_unrecognized_args = initArgs->ignoreUnrecognized == JNI_TRUE ? 1 : 0;
+    params.argc = isolate_argc;
+    params.argv = isolate_argv;
+    params.ignore_unrecognized_args = ignore_unrecognized_args;
 
     if (libjavavm->create_isolate(&params, &isolate, &thread) != 0) {
         if (isolate_argv != NULL) free(isolate_argv);

substratevm/src/com.oracle.svm.core/headers/graal_isolate.preamble

@@ -29,24 +29,25 @@ typedef unsigned long __graal_uword;
 #define NEW_PROTECTION_DOMAIN -1
 
 /* Parameters for the creation of a new isolate. */
-enum { __graal_create_isolate_params_version = 4 };
+enum { __graal_create_isolate_params_version = 5 };
 struct __graal_create_isolate_params_t {
-    int version;                                /* Version of this struct */
+    /* Version of this struct. Set to __graal_create_isolate_params_version after zeroing this struct. */
+    int version;
 
     /* Fields introduced in version 1 */
-    __graal_uword  reserved_address_space_size; /* Size of address space to reserve */
+    __graal_uword  reserved_address_space_size; /* Size of virtual address space to reserve for the heap. */
 
-    /* Fields introduced in version 2 */
+    /* Fields introduced in version 2. Internal usage, do not use. */
     const char    *auxiliary_image_path;                /* Path to an auxiliary image to load. */
     __graal_uword  auxiliary_image_reserved_space_size; /* Reserved bytes for loading an auxiliary image. */
 
     /* Fields introduced in version 3 */
-    int            _reserved_1;                 /* Internal usage, do not use. */
-    char         **_reserved_2;                 /* Internal usage, do not use. */
-    int            pkey;                        /* Isolate protection key or domain. */
+    int            argc;                        /* Number of char* argument strings in argv. */
+    char         **argv;                        /* Array of argument strings, parsed like command line arguments. */
+    int            pkey;                        /* Isolate protection key or domain. Internal usage, do not use. */
 
     /* Fields introduced in version 4 */
-    char           _reserved_3;                 /* Internal usage, do not use. */
+    char           ignore_unrecognized_args;    /* Ignore unrecognized arguments in argv when 1. */
     char           _reserved_4;                 /* Internal usage, do not use. */
 
     /* Fields introduced in version 5 */

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/JavaMainWrapper.java

@@ -77,15 +77,15 @@
 import com.oracle.svm.core.thread.RecurringCallbackSupport;
 import com.oracle.svm.core.thread.VMThreads;
 import com.oracle.svm.core.thread.VMThreads.OSThreadHandle;
-import com.oracle.svm.shared.singletons.traits.BuiltinTraits.AllAccess;
-import com.oracle.svm.shared.singletons.traits.BuiltinTraits.NoLayeredCallbacks;
-import com.oracle.svm.shared.singletons.traits.SingletonLayeredInstallationKind.ApplicationLayerOnly;
-import com.oracle.svm.shared.singletons.traits.SingletonTraits;
 import com.oracle.svm.core.util.UserError;
 import com.oracle.svm.guest.staging.Uninterruptible;
 import com.oracle.svm.guest.staging.jdk.InternalVMMethod;
 import com.oracle.svm.sdk.staging.layeredimage.LayeredCompilationBehavior;
 import com.oracle.svm.sdk.staging.layeredimage.LayeredCompilationBehavior.Behavior;
+import com.oracle.svm.shared.singletons.traits.BuiltinTraits.AllAccess;
+import com.oracle.svm.shared.singletons.traits.BuiltinTraits.NoLayeredCallbacks;
+import com.oracle.svm.shared.singletons.traits.SingletonLayeredInstallationKind.ApplicationLayerOnly;
+import com.oracle.svm.shared.singletons.traits.SingletonTraits;
 import com.oracle.svm.shared.util.VMError;
 import com.oracle.svm.util.ClassUtil;
 import com.oracle.svm.util.ModuleSupport;
@@ -496,8 +496,8 @@ public static void enter(int paramArgc, CCharPointerPointer paramArgv) {
             args.setVersion(4);
             args.setArgc(paramArgc);
             args.setArgv(paramArgv);
-            args.setIgnoreUnrecognizedArguments(false);
-            args.setExitWhenArgumentParsingFails(true);
+            args.setIgnoreUnrecognizedArgs(false);
+            args.setForJavaMainCall(true);
 
             int code = CEntryPointActions.enterCreateIsolate(args);
             if (code != CEntryPointErrors.NO_ERROR) {

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/c/function/CEntryPointCreateIsolateParameters.java

@@ -24,7 +24,6 @@
  */
 package com.oracle.svm.core.c.function;
 
-import org.graalvm.nativeimage.Isolates.CreateIsolateParameters;
 import org.graalvm.nativeimage.c.struct.CField;
 import org.graalvm.nativeimage.c.struct.CStruct;
 import org.graalvm.nativeimage.c.type.CCharPointer;
@@ -73,36 +72,30 @@ public interface CEntryPointCreateIsolateParameters extends PointerBase {
     @CField("pkey")
     int protectionKey();
 
-    /**
-     * C arguments passed from the C main function into the isolate creation. These fields are not
-     * public API, therefore they are named "reserved" in the C header files, and they are not
-     * listed in the {@link CreateIsolateParameters} Java API to create isolates.
-     */
-
-    @CField("_reserved_1")
+    @CField("argc")
     int getArgc();
 
-    @CField("_reserved_1")
+    @CField("argc")
     void setArgc(int value);
 
-    @CField("_reserved_2")
+    @CField("argv")
     CCharPointerPointer getArgv();
 
-    @CField("_reserved_2")
+    @CField("argv")
     void setArgv(CCharPointerPointer value);
 
     /* fields below: version 4 */
-    @CField("_reserved_3")
-    boolean getIgnoreUnrecognizedArguments();
+    @CField("ignore_unrecognized_args")
+    boolean getIgnoreUnrecognizedArgs();
 
-    @CField("_reserved_3")
-    void setIgnoreUnrecognizedArguments(boolean value);
+    @CField("ignore_unrecognized_args")
+    void setIgnoreUnrecognizedArgs(boolean value);
 
     @CField("_reserved_4")
-    boolean getExitWhenArgumentParsingFails();
+    boolean getForJavaMainCall();
 
     @CField("_reserved_4")
-    void setExitWhenArgumentParsingFails(boolean value);
+    void setForJavaMainCall(boolean value);
 
     /* fields below: version 5 */
     @CField("_reserved_5")

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/c/function/CEntryPointNativeFunctions.java

@@ -33,13 +33,13 @@
 import org.graalvm.nativeimage.c.function.CEntryPoint;
 import org.graalvm.nativeimage.c.struct.CPointerTo;
 import org.graalvm.word.PointerBase;
+import org.graalvm.word.impl.Word;
 
 import com.oracle.svm.core.SubstrateOptions;
-import com.oracle.svm.guest.staging.Uninterruptible;
 import com.oracle.svm.core.c.function.CEntryPointOptions.NoEpilogue;
 import com.oracle.svm.core.c.function.CEntryPointOptions.NoPrologue;
 import com.oracle.svm.core.thread.VMThreads;
-import org.graalvm.word.impl.Word;
+import com.oracle.svm.guest.staging.Uninterruptible;
 
 @CHeader(value = GraalIsolateHeader.class)
 public final class CEntryPointNativeFunctions {
@@ -178,8 +178,8 @@ Tears down the isolate of the passed (and still attached) isolate thread,
                     THREAD_TERMINATION_NOTE,
     })
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
-    public static int tearDownIsolate(IsolateThread isolateThread) {
-        int result = CEntryPointActions.enter(isolateThread);
+    public static int tearDownIsolate(IsolateThread thread) {
+        int result = CEntryPointActions.enter(thread);
         if (result != 0) {
             return result;
         }
@@ -202,8 +202,8 @@ or this will cause entirely undefined (and likely fatal) behavior.
                     THREAD_TERMINATION_NOTE,
     })
     @CEntryPointOptions(prologue = NoPrologue.class, epilogue = NoEpilogue.class, nameTransformation = NameTransformation.class)
-    public static int detachAllThreadsAndTearDownIsolate(IsolateThread isolateThread) {
-        int result = CEntryPointActions.enter(isolateThread);
+    public static int detachAllThreadsAndTearDownIsolate(IsolateThread thread) {
+        int result = CEntryPointActions.enter(thread);
         if (result != 0) {
             return result;
         }

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/c/function/IsolateSupportImpl.java

@@ -35,6 +35,7 @@
 import org.graalvm.nativeimage.c.type.CCharPointerPointer;
 import org.graalvm.nativeimage.c.type.CTypeConversion;
 import org.graalvm.nativeimage.impl.IsolateSupport;
+import org.graalvm.word.impl.Word;
 
 import com.oracle.svm.core.SubstrateOptions;
 import com.oracle.svm.core.c.function.CEntryPointNativeFunctions.IsolateThreadPointer;
@@ -49,7 +50,6 @@
 import com.oracle.svm.shared.singletons.traits.BuiltinTraits.SingleLayer;
 import com.oracle.svm.shared.singletons.traits.SingletonLayeredInstallationKind.InitialLayerOnly;
 import com.oracle.svm.shared.singletons.traits.SingletonTraits;
-import org.graalvm.word.impl.Word;
 
 @AutomaticallyRegisteredImageSingleton(IsolateSupport.class)
 @SingletonTraits(access = RuntimeAccessOnly.class, layeredCallbacks = SingleLayer.class, layeredInstallationKind = InitialLayerOnly.class)
@@ -111,8 +111,8 @@ public static IsolateThread createIsolate(CreateIsolateParameters parameters, bo
             params.setAuxiliaryImagePath(auxImagePath.get());
             params.setAuxiliaryImageReservedSpaceSize(parameters.getAuxiliaryImageReservedSpaceSize());
             params.setVersion(5);
-            params.setIgnoreUnrecognizedArguments(false);
-            params.setExitWhenArgumentParsingFails(false);
+            params.setIgnoreUnrecognizedArgs(false);
+            params.setForJavaMainCall(false);
             params.setArgc(argc);
             params.setArgv(argv);
             params.setIsCompilationIsolate(compilationIsolate);