# IBM J9 VM 8
This page describes the Optimization Pack for Eclipse OpenJ9 (formerly known as IBM J9) Virtual Machine version 8.
## Metrics
### All metrics
| Name | Unit | Description |
| ------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| jvm\_heap\_size | bytes | The size of the JVM heap memory |
| jvm\_heap\_used | bytes | The amount of heap memory used |
| jvm\_heap\_util | percent | The utilization % of heap memory |
| jvm\_memory\_used | bytes | The total amount of memory used across all the JVM memory pools |
| jvm\_memory\_used\_details | bytes | The total amount of memory used broken down by pool (e.g., code-cache, compressed-class-space) |
| jvm\_memory\_buffer\_pool\_used | bytes | The total amount of bytes used by buffers within the JVM buffer memory pool |
| jvm\_gc\_time | percent | The % of wall clock time the JVM spent doing stop the world garbage collection activities |
| jvm\_gc\_time\_details | percent | The % of wall clock time the JVM spent doing stop the world garbage collection activities broken down by type of garbage collection algorithm (e.g., ParNew) |
| jvm\_gc\_count | collections/s | The total number of stop the world JVM garbage collections that have occurred per second |
| jvm\_gc\_count\_details | collections/s | The total number of stop the world JVM garbage collections that have occurred per second, broken down by type of garbage collection algorithm (e.g., G1, CMS) |
| jvm\_gc\_duration | seconds | The average duration of a stop the world JVM garbage collection |
| jvm\_gc\_duration\_details | seconds | The average duration of a stop the world JVM garbage collection broken down by type of garbage collection algorithm (e.g., G1, CMS) |
| jvm\_threads\_current | threads | The total number of active threads within the JVM |
| jvm\_threads\_deadlocked | threads | The total number of deadlocked threads within the JVM |
| jvm\_compilation\_time | milliseconds | The total time spent by the JVM JIT compiler compiling bytecode |
## Parameters
### Heap
| Name | Type | Unit | Default | Domain | Restart | Description |
| ----------------- | ------- | --------- | ----------------------------------------- | ---------------------------------- | ------- | -------------------------------------------------------- |
| j9vm\_minHeapSize | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | Minimum heap size (in megabytes) |
| j9vm\_maxHeapSize | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | Maximum heap size (in megabytes) |
| j9vm\_minFreeHeap | real | percent | `0.3` | `0.1` → `0.5` | yes | Specify the minimum % free heap required after global GC |
| j9vm\_maxFreeHeap | real | percent | `0.6` | `0.4` → `0.9` | yes | Specify the maximum % free heap required after global GC |
### Garbage Collection
| Name | Type | Unit | Default | Domain | Restart | Description |
| -------------------------- | ----------- | --------- | ----------------------------------------- | -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| j9vm\_gcPolicy | categorical | | `gencon` | `gencon`, `subpool`, `optavgpause`, `optthruput`, `nogc` | yes | GC policy to use |
| j9vm\_gcThreads | integer | threads | You should select your own default value. | `1` → `64` | yes | Number of threads the garbage collector uses for parallel operations |
| j9vm\_scvTenureAge | integer | | `10` | `1` → `14` | yes | Set the initial tenuring threshold for generational concurrent GC policy |
| j9vm\_scvAdaptiveTenureAge | categorical | | *blank* | *blank*, `-Xgc:scvNoAdaptiveTenure` | yes | Enable the adaptive tenure age for generational concurrent GC policy |
| j9vm\_newSpaceFixed | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | The fixed size of the new area when using the gencon GC policy. Must not be set alongside min or max |
| j9vm\_minNewSpace | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | The initial size of the new area when using the gencon GC policy |
| j9vm\_maxNewSpace | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | The maximum size of the new area when using the gencon GC policy |
| j9vm\_oldSpaceFixed | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | The fixed size of the old area when using the gencon GC policy. Must not be set alongside min or max |
| j9vm\_minOldSpace | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | The initial size of the old area when using the gencon GC policy |
| j9vm\_maxOldSpace | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | The maximum size of the old area when using the gencon GC policy |
| j9vm\_concurrentScavenge | categorical | | `concurrentScavenge` | `concurrentScavenge`, `noConcurrentScavenge` | yes | Support pause-less garbage collection mode with gencon |
| j9vm\_gcPartialCompact | categorical | | `nopartialcompactgc` | `nopartialcompactgc`, `partialcompactgc` | yes | Enable partial compaction |
| j9vm\_concurrentMeter | categorical | | `soa` | `soa`, `loa`, `dynamic` | yes | Determine which area is monitored by the concurrent mark |
| j9vm\_concurrentBackground | integer | | `0` | `0` → `128` | yes | The number of background threads assisting the mutator threads in concurrent mark |
| j9vm\_concurrentSlack | integer | megabytes | `0` | You should select your own domain. | yes | The target size of free heap space for concurrent collectors |
| j9vm\_concurrentLevel | integer | percent | `8` | `0` → `100` | yes | The ratio between the amount of heap allocated and the amount of heap marked |
| j9vm\_gcCompact | categorical | | *blank* | *blank*, `-Xcompactgc`, `-Xnocompactgc` | yes | Enables full compaction on all garbage collections (system and global) |
| j9vm\_minGcTime | real | percent | `0.05` | `0.0` → `1.0` | yes | The minimum percentage of time to be spent in garbage collection, triggering the resize of the heap to meet the specified values |
| j9vm\_maxGcTime | real | percent | `0.13` | `0.0` → `1.0` | yes | The maximum percentage of time to be spent in garbage collection, triggering the resize of the heap to meet the specified values |
| j9vm\_loa | categorical | | `loa` | `loa`, `noloa` | yes | Enable the allocation of the large area object during garbage collection |
| j9vm\_loa\_initial | real | | `0.05` | `0.0` → `0.95` | yes | The initial portion of the tenure area allocated to the large area object |
| j9vm\_loa\_minimum | real | | `0.01` | `0.0` → `0.95` | yes | The minimum portion of the tenure area allocated to the large area object |
| j9vm\_loa\_maximum | real | | `0.5` | `0.0` → `0.95` | yes | The maximum portion of the tenure area allocated to the large area object |
### JIT
| Name | Type | Unit | Default | Domain | Restart | Description |
| ------------------------ | ------- | --------- | ----------------------------------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------------------------ |
| j9vm\_jitOptlevel | ordinal | | `noOpt` | `noOpt`, `cold`, `warm`, `hot`, `veryHot`, `scorching` | yes | Force the JIT compiler to compile all methods at a specific optimization level |
| j9vm\_compilationThreads | integer | integer | You should select your own default value. | `1` → `7` | yes | Number of JIT threads |
| j9vm\_codeCacheTotal | integer | megabytes | You should select your own default value. | You should select your own domain. | yes | Maximum size limit in MB for the JIT code cache |
| j9vm\_jit\_count | integer | | `10000` | `0` → `1000000` | yes | The number of times a method is called before it is compiled |
### Other parameters
| Name | Type | Unit | Default | Domain | Restart | Description |
| -------------------------- | ----------- | ---- | ----------- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| j9vm\_lockReservation | categorical | | categorical | *blank*, `-XlockReservation` | no | Enables an optimization that presumes a monitor is owned by the thread that last acquired it |
| j9vm\_compressedReferences | categorical | | *blank* | *blank*, `-Xcompressedrefs`, `-Xnocompressedrefs` | yes | Enable/disable the use of compressed references |
| j9vm\_aggressiveOpts | categorical | | *blank* | *blank*, `-Xaggressive` | yes | Enable the use of aggressive performance optimization features, which are expected to become default in upcoming releases |
| j9vm\_virtualized | categorical | | *blank* | *blank*, `-Xtune:virtualized` | yes | Optimize the VM for virtualized environment, reducing CPU usage when idle |
| j9vm\_shareclasses | categorical | | *blank* | *blank*, `-Xshareclasses` | yes | Enable class sharing |
| j9vm\_quickstart | categorical | | *blank* | *blank*, `-Xquickstart` | yes | Run JIT with only a subset of optimizations, improving the performance of short-running applications |
| j9vm\_minimizeUserCpu | categorical | | *blank* | *blank*, `-Xthr:minimizeUserCPU` | yes | Minimizes user-mode CPU usage in thread synchronization where possible |
## Domains
The following parameters require their ranges or default values to be updated according to the described rules:
### Memory
| Parameter | Default value | Domain |
| -------------------------- | ----------------------------------------- | ----------------------------------------------------- |
| j9vm\_minNewSpace | 25% of `j9vm_minHeapSize` | must not exceed `j9vm_minHeapSize` |
| j9vm\_maxNewSpace | 25% of j9vm\_maxHeapSize | must not exceed `j9vm_maxHeapSize` |
| j9vm\_minOldSpace | 75% of j9vm\_minHeapSize | must not exceed `j9vm_minHeapSize` |
| j9vm\_maxOldSpace | same as j9vm\_maxHeapSize | must not exceed `j9vm_maxHeapSize` |
| j9vm\_gcthreads | number of CPUs - 1, up to a maximum of 64 | capped to default, no benefit in exceeding that value |
| j9vm\_compressedReferences | enabled for j9vm\_maxHeapSize<= 57 GB | |
Notice that the value `nocompressedreferences` for `j9vm_compressedReferences` can only be specified for JVMs compiled with the proper `--with-noncompressedrefs` flag. If this is not the case you cannot actively disable compressed references, meaning:
* for Xmx <= 57GB is useless to tune this parameter since compressed references are active by default and it is not possible to explicitly disable it
* for Xmx > 57GB, since the by default (blank value) compressed references are disabled, Akamas can try to enable it. This requires removing the `nocompressedreferences` from the domain
## Constraints
The following tables show a list of constraints that may be required in the definition of the study, depending on the tuned parameters:
### Memory
| Formula | Notes |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| jvm.j9vm\_minHeapSize < jvm.j9vm\_maxHeapSize | |
| jvm.j9vm\_minNewSpace < jvm.j9vm\_maxNewSpace &&
jvm.j9vm\_minNewSpace < jvm.j9vm\_minHeapSize &&
jvm.j9vm\_maxNewSpace < jvm.j9vm\_maxHeapSize
| |
| jvm.j9vm\_minOldSpace < jvm.j9vm\_maxOldSpace &&
jvm.j9vm\_minOldSpace < jvm.j9vm\_minHeapSize &&
jvm.j9vm\_maxOldSpace < jvm.j9vm\_maxHeapSize
| |
| jvm.j9vm\_loa\_minimum <= jvm.j9vm\_loa\_initial &&
jvm.j9vm\_loa\_initial <= jvm.j9vm\_loa\_maximum
| |
| jvm.j9vm\_minFreeHeap + 0.05 < jvm.j9vm\_maxFreeHeap | |
| jvm.j9vm\_minGcTimeMin < jvm.j9vm\_maxGcTime | |
Notice that
* `j9vm_newSpaceFixed` is mutually exclusive with `j9vm_minNewSpace` and `j9vm_maxNewSpace`
* `j9vm_oldSpaceFixed` is mutually exclusive with `j9vm_minOldSpace` and `j9vm_maxOldSpace`
* the sum of `j9vm_minNewSpace` and `j9vm_minOldSpace` must be equal to `j9vm_minHeapSize`, so it's useless to tune all of them together. Max values seem to be more complex.