[GR-33811] Follow Github issues.

olyagpl · olyagpl · commit 84fc4d85f68e · 2021-09-23T11:06:19.000Z
PullRequest: graal/9792
diff --git a/docs/reference-manual/native-image/DynamicProxy.md b/docs/reference-manual/native-image/DynamicProxy.md
@@ -90,9 +90,9 @@ For the exceptional cases where the analysis cannot discover the interface array
 
 ## Manual Configuration
 
-Dynamic proxy classes can be generated at native image build time by specifying the list of interfaces that they implement. Native Image provides two options for this purpose: `-H:DynamicProxyConfigurationFiles=<comma-separated-config-files>` and `-H:DynamicProxyConfigurationResources=<comma-separated-config-resources>`.
+Dynamic proxy classes can be generated at native image build time by specifying the list of interfaces that they implement.
+Native Image provides two options for that: `-H:DynamicProxyConfigurationFiles=<comma-separated-config-files>` and `-H:DynamicProxyConfigurationResources=<comma-separated-config-resources>`. These options accept JSON files whose structure is an array of arrays of fully qualified interface names. For example:
 
-These options accept JSON files whose structure is an array of arrays of fully qualified interface names. For example:
 ```json
 [
     ["java.lang.AutoCloseable", "java.util.Comparator"],
@@ -101,6 +101,8 @@ These options accept JSON files whose structure is an array of arrays of fully q
 ]
 ```
 
+Note that the order of the specified proxy interfaces is significant: two requests for a `Proxy` class with the same combination of interfaces but in a different order will result in two distinct behaviours (for more detailed information, refer to [`Proxy Class `javadoc](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/reflect/Proxy.html).
+
 The `java.lang.reflect.Proxy` API also allows creation of a dynamic proxy that does not implement any user provided interfaces. Therefore the following is a valid configuration:
 ```json
 [
diff --git a/docs/reference-manual/native-image/MemoryManagement.md b/docs/reference-manual/native-image/MemoryManagement.md
@@ -48,7 +48,7 @@ Note: The maximum heap size is only the upper limit for the Java heap and not ne
 
 The *Serial GC* is optimized for low footprint and small Java heap sizes.
 If no other GC is specified, the Serial GC will be used implicitly as the default on both GraalVM Community and Enterprise Edition.
-Since GraalVM 20.3, it is also possible to explicitly enable the Serial GC by passing the option `--gc=serial` to the native image builder.
+It is also possible to explicitly enable the Serial GC by passing the option `--gc=serial` to the native image builder.
 
 ```shell
 # Build a native image that uses the serial GC with default settings
@@ -75,6 +75,9 @@ Note that this is just the maximum value.
 Depending on the application, the amount of actually used Java heap memory can be much lower.
 To override this default behavior, either specify a value for `-XX:MaximumHeapSizePercent` or explicitly set the maximum [Java heap size](#java-heap-size).
 
+Be mindful that the GC needs some extra memory when performing a garbage collection (2x of the maximum heap size is the worst case, usually, it is significantly less).
+Therefore, the resident set size, RSS, can increase temporarily during a garbage collection which can be an issue in any environment with memory constraints (such as a container).
+
 ### Performance Tuning
 
 For tuning the GC performance and the memory footprint, the following options can be used:

Original file line number	Diff line number	Diff line change
`@@ -90,9 +90,9 @@ For the exceptional cases where the analysis cannot discover the interface array`
`90`	`90`
`91`	`91`	`## Manual Configuration`
`92`	`92`
`93`		-Dynamic proxy classes can be generated at native image build time by specifying the list of interfaces that they implement. Native Image provides two options for this purpose: `-H:DynamicProxyConfigurationFiles=<comma-separated-config-files>` and `-H:DynamicProxyConfigurationResources=<comma-separated-config-resources>`.
	`93`	`+Dynamic proxy classes can be generated at native image build time by specifying the list of interfaces that they implement.`
	`94`	+Native Image provides two options for that: `-H:DynamicProxyConfigurationFiles=<comma-separated-config-files>` and `-H:DynamicProxyConfigurationResources=<comma-separated-config-resources>`. These options accept JSON files whose structure is an array of arrays of fully qualified interface names. For example:
`94`	`95`
`95`		`-These options accept JSON files whose structure is an array of arrays of fully qualified interface names. For example:`
`96`	`96`	```json
`97`	`97`	`[`
`98`	`98`	`["java.lang.AutoCloseable", "java.util.Comparator"],`
`@@ -101,6 +101,8 @@ These options accept JSON files whose structure is an array of arrays of fully q`
`101`	`101`	`]`
`102`	`102`	```
`103`	`103`
	`104`	+Note that the order of the specified proxy interfaces is significant: two requests for a `Proxy` class with the same combination of interfaces but in a different order will result in two distinct behaviours (for more detailed information, refer to [`Proxy Class `javadoc](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/reflect/Proxy.html).
	`105`	`+`
`104`	`106`	The `java.lang.reflect.Proxy` API also allows creation of a dynamic proxy that does not implement any user provided interfaces. Therefore the following is a valid configuration:
`105`	`107`	```json
`106`	`108`	`[`