Skip to content

Commit

Permalink
Follow Paul W. comments
Browse files Browse the repository at this point in the history
olyagpl committed Aug 6, 2020
1 parent 2924613 commit a8d48d7
Showing 16 changed files with 66 additions and 77 deletions.
2 changes: 1 addition & 1 deletion substratevm/C-API.md
Original file line number Diff line number Diff line change
@@ -3,7 +3,7 @@
Native Image provides an API for the C language for initializing isolates and attaching threads for use with the entry point feature that is demonstrated [here](SubstrateVM.md#images-and-entry-points).
The C API is available when Native Image is built as a shared library and its declarations are included in the header file that is generated during the build:

```
```c
/*
* Structure representing an isolate. A pointer to such a structure can be
* passed to an entry point as the execution context.
1 change: 0 additions & 1 deletion substratevm/Configuration.md
Original file line number Diff line number Diff line change
@@ -221,7 +221,6 @@ HELLO
Build a native image as regularly, without a reflection configuration file and run a resulting image:
```
$JAVA_HOME/bin/native-image ReflectionExample
Build on Server(pid: 59625, port: 58819)
[reflectionexample:59625] classlist: 467.66 ms
...
Note: Image 'reflectionexample' is a fallback image that requires a JDK for execution (use --no-fallback to suppress fallback image generation).
2 changes: 1 addition & 1 deletion substratevm/HostedvsRuntimeOptions.md
Original file line number Diff line number Diff line change
@@ -19,7 +19,7 @@ be used both as hosted options (if you want to dump graphs of the boot image
generator) and runtime options (if you want to dump graphs during dynamic
compilation at runtime).

GraalVM options that work as expected include `Dump`, `DumpOnError`, `Log`,
The Graal compiler options that work as expected include `Dump`, `DumpOnError`, `Log`,
`MethodFilter` and the options to specify file names and ports for the dump
handlers.

9 changes: 5 additions & 4 deletions substratevm/JNI.md
Original file line number Diff line number Diff line change
@@ -66,7 +66,7 @@ The analysis is not obstructed by object handles because it can observe the enti

### Java-to-native Method Calls
Methods declared with the `native` keyword have a JNI-compliant implementation in native code, but can be called like any other Java method. For example:
```
```c
// Java declaration
native int[] sort0(int[] array);
// native declaration with JNI name mangling
@@ -91,7 +91,7 @@ The automatic initialization of this struct is prepared during the image build.
### Native-to-Java Method Calls
Native code can invoke Java methods by first obtaining a `jmethodID` for the target method, and then using one of the `Call<Type>Method`, `CallStatic<Type>Method` or `CallNonvirtual<Type>Method` functions for the invocation.
Each of these `Call...` functions is also available in a `Call...MethodA` and a `Call...MethodV` variant, which take arguments as an array or as a `va_list` instead of variadic arguments. For example:
```
```c
jmethodID intcomparator_compare_method = (*env)->GetMethodID(env, intcomparator_class, "compare", "(II)I");
jint result = (*env)->CallIntMethod(env, this, intcomparator_compare_method, a, b);
```
@@ -107,7 +107,7 @@ As another optimization, the call wrappers are able to efficiently restore the c

### Object Creation
JNI provides two ways of creating Java objects, either by calling `AllocObject` to allocate memory and then using `CallVoidMethod` to invoke the constructor, or by using `NewObject` to create and initialize the object in a single step (or variants `NewObjectA` or `NewObjectV`). For example:
```
```c
jclass calendarClass = (*env)->FindClass(env, "java/util/GregorianCalendar");
jmethodID ctor = (*env)->GetMethodID(env, calendarClass, "<init>", "(IIIIII)V");
jobject firstObject = (*env)->AllocObject(env, calendarClass);
@@ -121,10 +121,11 @@ In that case, the call wrapper allocates a new instance before invoking the actu
### Field Accesses
Native code can access a Java field by obtaining its `jfieldID` and then using one of the `Get<Type>Field`, `Set<Type>Field`, `GetStatic<Type>Field` or `SetStatic<Type>Field` functions. For example:
```
```c
jfieldID intsorter_comparator_field = (*env)->GetFieldID(env, intsorter_class, "comparator", "Lorg/example/sorter/IntComparator;");
jobject value = (*env)->GetObjectField(env, self, intsorter_comparator_field);
```

For a field that is accessible via JNI, its offset within an object (or within the static field area) is stored in the reflection metadata and is used as its `jfieldID`.
The image build generates accessor methods for for fields of all primitive types and for object fields.
These accessor methods perform the transition to Java code and back, and use unsafe loads or stores to directly manipulate the field value.
10 changes: 5 additions & 5 deletions substratevm/LIMITATIONS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Native Image Compatibility and Optimization Guide

GraalVM Native Image uses a different way of executing Java programs than users of the Java HotSpot VM are used to.
It distinguishes between *image build time* and *image run time*.
It distinguishes between *image build-time* and *image runtime*.
At image build time, a static analysis finds all methods that are reachable from the entry point of the application.
These (and only these) methods are then ahead-of-time compiled into the native image.
Because of the different optimization model, Java programs can behave somewhat differently when compiled into a native image.
@@ -19,7 +19,7 @@ Configuration ensures that the minimum amount of space necessary is used in the
If one of the following features is used without providing a configuration at image build time, a fallback image is generated.

### Dynamic Class Loading
Any class to be accessed by name at image run time must be enumerated at image build time.
Any class to be accessed by name at image runtime must be enumerated at image build time.
For example, a call to `Class.forName("myClass”)` must have `myClass` in a [configuration file](Configuration.md).
If the configuration file is used, but does not include a class that is requested for dynamic class loading, a `ClassNotFoundException` will be thrown, as if the class was not found on the class path or was inaccessible.

@@ -63,7 +63,7 @@ Some Java features are not yet supported with the closed-world optimization, and
Under the closed-world assumption, all methods that are called and their call sites must be known.
`invokedynamic` and method handles can introduce calls at runtime or change the method that is invoked.

Note that `invokedynamic` use cases generated by `javac` for, e.g., Java lambda expressions and string concatenation are supported because they do not change called methods at image run time.
Note that `invokedynamic` use cases generated by `javac` for, e.g., Java lambda expressions and string concatenation are supported because they do not change called methods at image runtime.

### Serialization
Java serialization requires class metadata information in order to function, and could be supported similarly to reflection using configuration at image build time.
@@ -82,15 +82,15 @@ Using separate processes is now recommended for these cases.
GraalVM Native Image implements some Java features in a different way than the Java HotSpot VM.

### Class Initializers
By default, classes are initialized at image run time.
By default, classes are initialized at image runtime.
This ensures compatibility, but limits some optimizations.
For faster startup and better peak performance, it is desirable to initialize classes at image build time.
Class initialization behavior can be adjusted using the options `--initialize-at-build-time` or `--initialize-at-run-time` for specific classes and packages or for all classes.
See `native-image --help` for details.
Classes of the JDK class libraries are handled for you and do not need special consideration from the user.

Native image users should be aware that class initialization at image build time may break specific assumptions in existing code.
For example, files loaded in a class initializer may not be in the same place at image build time as at image run time.
For example, files loaded in a class initializer may not be in the same place at image build time as at image runtime.
Also, certain objects such as a file descriptors or running threads must not be stored into a native image binary.
If such objects are reachable at image build time, image generation fails with an error.

2 changes: 0 additions & 2 deletions substratevm/NativeImageHeapdump.md
Original file line number Diff line number Diff line change
@@ -79,7 +79,6 @@ heap dump.

```
$JAVA_HOME/bin/native-image SVMHeapDump -H:+AllowVMInspection
Build on Server(pid: 41691, port: 61250)
[svmheapdump:41691] classlist: 412.03 ms, 2.52 GB
[svmheapdump:41691] (cap): 1,655.34 ms, 2.52 GB
[svmheapdump:41691] setup: 2,741.18 ms, 2.52 GB
@@ -188,7 +187,6 @@ $JAVA_HOME/bin/javac SVMHeapDumpAPI.java
Then build a native executable:
```
$JAVA_HOME/bin/ native-image SVMHeapDumpAPI
Build on Server(pid: 41691, port: 61250)
[svmheapdumpapi:41691] classlist: 447.96 ms, 2.53 GB
[svmheapdumpapi:41691] (cap): 2,105.64 ms, 2.53 GB
[svmheapdumpapi:41691] setup: 3,010.19 ms, 2.53 GB
13 changes: 0 additions & 13 deletions substratevm/OPTIONS.md
Original file line number Diff line number Diff line change
@@ -86,17 +86,4 @@ The `--language:python`, `--language:ruby` and `--language:R` polyglot macro opt
| --dry-run | Output the command line that would be used for building. |
| -V<key>=<value> | Provide values for placeholders in _native-image.properties_ files. |

### Server Options

| Option | Description |
|----------------------------------------|---------------------------------------------------------------------------------------|
| --no-server | Do not use server-based image building. |
| --server-list | List current image-build servers. |
| --server-list-details | List current image-build servers with more details. |
| --server-cleanup | Remove stale image-build servers entries. |
| --server-shutdown | Shut down image-build servers under current session ID. |
| --server-shutdown-all | Shut down all image-build servers. |
| --server-session=<custom-session-name> | Use custom session name instead of system provided session ID of the calling process. |
| --verbose-server | Enable verbose output for image-build server handling. |

Options to Native Image are also distinguished as hosted and runtime options. Continue reading to the [ Native Image Hosted and Runtime Options](HostedvsRuntimeOptions.md) guide.
10 changes: 5 additions & 5 deletions substratevm/PROPERTIES.md
Original file line number Diff line number Diff line change
@@ -8,12 +8,12 @@ public class App {
}
}
```
If you compile that with, e.g., `native-image -Dfoo=bar App` the system property `foo` will be available at the *image build time*.
For example, whenever you are in the [code that is part of your application but executed at image buildtime](http://www.graalvm.org/sdk/javadoc/org/graalvm/nativeimage/ImageInfo.html#inImageBuildtimeCode--) (usually static field initializations and static initializers).
If you compile that with, e.g., `native-image -Dfoo=bar App` the system property `foo` will be available at *image build time*.
For example, whenever you are in the [code that is part of your application but executed at image build time](http://www.graalvm.org/sdk/javadoc/org/graalvm/nativeimage/ImageInfo.html#inImageBuildtimeCode--) (usually static field initializations and static initializers).
Thus if you execute the image above it will not contain `foo` in the list of properties.

If, on the other hand, you execute the image with `app -Dfoo=bar`, it will show `foo` in the list of properties because you specified it for the *image runtime*.
If, on the other hand, you execute the image with `app -Dfoo=bar`, it will show `foo` in the list of properties because you specified it for *image runtime*.

In other words:
* Passing `-D<key>=<value>` to `native-image` affects properties seen at the image build time.
* Passing `-D<key>=<value>` to an image execution affects properties seen at the image runtime.
* Passing `-D<key>=<value>` to `native-image` affects properties seen at image build time.
* Passing `-D<key>=<value>` to an image execution affects properties seen at image runtime.
58 changes: 31 additions & 27 deletions substratevm/README.md
Original file line number Diff line number Diff line change
@@ -12,54 +12,46 @@ compared to a Java VM.

The **Native Image builder** or `native-image` is a utility that processes all
the classes of your application and their dependencies, including those from the
JDK. It statically analyses these classes to determine which classes and methods
are reachable during application execution. which ahead-of-time compiles it to a
native executable for a specific operating system and architecture. This entire
process is called an **image build time** to clearly distinguish it from the
compilation of Java source code to bytecode.

GraalVM Native Image supports JVM-based languages, e.g., Java, Scala,
Clojure, Kotlin. The resulting native image can, optionally, execute dynamic
languages like JavaScript, Ruby, R, or Python, but it does not pre-compile their code
itself. Polyglot embeddings can also be compiled ahead-of-time. To inform
`native-image` of guest languages used by an application, specify
`--language:<languageId>` for each guest language used (e.g., `--language:js`).
JDK. It analyses these classes to determine which classes, methods and fields
are reachable during application execution. It then ahead-of-time compiles all
reachable code and data into a native executable for a specific operating system
and architecture. This entire process is called **image build time** to
clearly distinguish it from the compilation of Java source code to bytecode.

GraalVM Native Image supports JVM-based languages, e.g., Java, Scala, Clojure,
Kotlin. The resulting native image can, optionally, execute dynamic languages
like JavaScript, Ruby, R, or Python. Polyglot embeddings can also be compiled
ahead-of-time. To inform `native-image` of guest languages used by an
application, specify `--language:<languageId>` for each guest language used
(e.g., `--language:js`).

### License
GraalVM Native Image is licensed under the GPL 2 with Classpath Exception.

## Install Native Image

Native Image is distributed as a separate installable and can be added to the core installation with the [GraalVM Updater]({{ "/docs/reference-manual/graal-updater/" | relative_url}}) tool.
Native Image is distributed as a separate installable and can be added to the core installation with the [GraalVM Updater](https://www.graalvm.org/docs/reference-manual/gu/) tool.

Run this command to install Native Image from GitHub:
If you use GraalVM, run this command to install Native Image from GitHub:
```
$ gu install native-image
```

After this additional step, the `native-image` executable will become available in
the `bin` directory.

Take a look at the [native image generation]({{ "/docs/examples/native-list-dir/" | relative_url}}) or [compiling a Java and Kotlin app ahead-of-time]({{ "/docs/examples/java-kotlin-aot/" | relative_url}}) samples.
Take a look at the [native image generation](https://www.graalvm.org/docs/examples/native-list-dir/) or [compiling a Java and Kotlin app ahead-of-time](https://www.graalvm.org/docs/examples/java-kotlin-aot/) samples.

## Prerequisites

For compilation `native-image` depends on the local toolchain, so please make
sure: `glibc-devel`, `zlib-devel` (header files for the C library and `zlib`)
and `gcc` are available on your system. For Linux platform, install `libstdc++`
and `gcc` are available on your system. For Linux platform, install install `libstdc++-static`
dependency additionally. For instance, on Oracle Linux run:
```
yum install libstdc++ -static
$ sudo yum install libstdc++-static
```

Another prerequisite to consider is the maximum heap size. Physical memory for
running a JVM-based application may be insufficient to build a native image. For
server-based image building we allow to use 80% of the reported physical RAM for
all servers together, but never more than 14GB per server (for exact details
please consult the native-image source code). If you run with `--no-server`
option, you will get the whole 80% of what is reported as physical RAM as the
baseline. This mode respects `-Xmx` arguments additionally.

#### Prerequisites for Using Native Image on Windows
To make use of Native Image on Windows, follow the further recommendations. The
required Microsoft Visual C++ (MSVC) version depends on the JDK version that
@@ -71,15 +63,14 @@ SDK 7.1:

For GraalVM distribution based on JDK 11, you will need MSVC 2017 15.5.5 or later version.

The last prerequisite, common for both GraalVM distribution based on JDK 11 and JDK 8, is the proper [Developer Command Prompt](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_prompt_shortcuts) for your version of [Visual Studio](https://visualstudio.microsoft.com/vs/). Namely, it is should be the x64 Native Tools Command Prompt. Use Visual Studio 2017 or later.
The last prerequisite, common for both GraalVM distribution based on JDK 11 and JDK 8, is the proper [Developer Command Prompt](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_prompt_shortcuts) for your version of [Visual Studio](https://visualstudio.microsoft.com/vs/). On Windows the `native-image` tool only works when it is executed from the **x64 Native Tools Command Prompt**.

### How to Determine What Version of GraalVM an Image Is Generated With?

Assuming you have a Java class file _EmptyHello.class_ containing an empty main method
and have generated an empty shared object `emptyhello` with GraalVM Native Image Generator utility of it:
```
$ native-image -cp hello EmptyHello
Build on Server(pid: 11228, port: 41223)
[emptyhello:11228] classlist: 149.59 ms
...
```
@@ -107,6 +98,19 @@ The following command will query that information from an image:
```
strings <path to native-image exe or shared object> | grep com.oracle.svm.core.VM
```
Here is an example output:
```
com.oracle.svm.core.VM.Target.LibC=com.oracle.svm.core.posix.linux.libc.GLibC
com.oracle.svm.core.VM.Target.Platform=org.graalvm.nativeimage.Platform$LINUX_AMD64
com.oracle.svm.core.VM.Target.StaticLibraries=liblibchelper.a|libnet.a|libffi.a|libextnet.a|libnio.a|libjava.a|libfdlibm.a|libzip.a|libjvm.a
com.oracle.svm.core.VM=GraalVM 20.2.0 Java 11
com.oracle.svm.core.VM.Target.Libraries=pthread|dl|z|rt
com.oracle.svm.core.VM.Target.CCompiler=gcc|redhat|x86_64|10.2.1
```
If the image was build with Oracle GraalVM Enterprise Edition the output would instead contain:
```
com.oracle.svm.core.VM=GraalVM 20.2.0 Java 11 EE
```

## Ahead-of-time Compilation Limitations

6 changes: 3 additions & 3 deletions substratevm/REFLECTION.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Reflection on Native Image
# Reflection Use in Native Images

Java reflection support (the `java.lang.reflect.*` API) enables Java code to examine its own classes, methods and fields and their properties at runtime.

@@ -135,11 +135,11 @@ class RuntimeReflectionRegistrationFeature implements Feature {
}

```
### Use Reflection during Native Image Generation
### Use of Reflection during Native Image Generation
Reflection can be used without restrictions during native image generation, for example in static initializers.
At this point, code can collect information about methods and fields and store them in own data structures, which are then reflection-free at run time.

### Unsafe accesses
### Unsafe Accesses
The `Unsafe` class, although its use is discouraged, provides direct access to memory of Java objects. The `Unsafe.objectFieldOffset()` method provides the offset of a field within a Java object. This information is not available by default, but can be enabled with the `allowUnsafeAccess` attribute in the reflection configuration, for example:
```json
"fields" : [ { "name" : "hash", "allowUnsafeAccess" : true }, ... ]
Loading

0 comments on commit a8d48d7

Please sign in to comment.