From 19a7068990343d418cc7dc7aec4a8f50dd86cbd3 Mon Sep 17 00:00:00 2001
From: genie-openj9 <openj9-bot@eclipse.org>
Date: Wed, 25 Oct 2023 16:25:38 +0000
Subject: [PATCH] Generated from commit:
 e5c44a6dfc1967cda12fc0a42b18e9da9b9e0678

Signed-off-by: genie-openj9 <openj9-bot@eclipse.org>
---
 jitserver_tuning/index.html       |   4 +-
 search/search_index.json          |   2 +-
 shrc/index.html                   |   2 +-
 sitemap.xml                       | 620 +++++++++++++++---------------
 sitemap.xml.gz                    | Bin 2501 -> 2501 bytes
 version0.41/index.html            |   2 +-
 xshareclasses/index.html          |  10 +-
 xxjitserveruseaotcache/index.html |   2 +-
 xxportablesharedcache/index.html  |   2 +-
 9 files changed, 322 insertions(+), 322 deletions(-)

diff --git a/jitserver_tuning/index.html b/jitserver_tuning/index.html
index 49d1c52f77..1b7ee9696d 100644
--- a/jitserver_tuning/index.html
+++ b/jitserver_tuning/index.html
@@ -8301,7 +8301,7 @@ <h3 id="client-session-caches">Client-session caches</h3>
 </code></pre>
 <h3 id="jitserver-aot-cache">JITServer AOT cache</h3>
 <p>The JITServer technology can cache AOT compiled methods at the server.
- The JITServer can, therefore, avoid carrying out an AOT compilation when a compatible AOT method body already exists in the cache, thereby saving CPU resource and improving remote compilation latency. This mechanism works in conjunction with the <a href="https://www.eclipse.org/openj9/docs/aot/">dynamic AOT technology</a> at the client and therefore the client needs to have the <a href="https://www.eclipse.org/openj9/docs/shrc/">shared class cache</a> (SCC) enabled (the SCC is the repository for the AOT code).</p>
+ The JITServer can, therefore, avoid carrying out an AOT compilation when a compatible AOT method body already exists in the cache, thereby saving CPU resource and improving remote compilation latency. This mechanism works in conjunction with the <a href="https://www.eclipse.org/openj9/docs/aot/">dynamic AOT technology</a> at the client and therefore the client needs to have the <a href="https://www.eclipse.org/openj9/docs/shrc/">shared classes cache</a> (SCC) enabled (the SCC is the repository for the AOT code).</p>
 <p>When the JITServer receives an AOT compilation request, it checks its AOT cache for a compatible compiled method body. If one is not found, the server performs the AOT compilation, sends the response to the client JVM, then serializes the compiled method and stores it in its local AOT cache, for future use. If a compatible compiled method is found, the server sends the client the serialized compiled method from its cache, thus avoiding a compilation. The client deserializes the response, stores the result in its local SCC, and loads the compiled method as a regular dynamic AOT code.</p>
 <p>To enable this feature, specify the <a href="../xxjitserveruseaotcache/"><code>-XX:+JITServerUseAOTCache</code></a> command line option, both at the server and at the client JVM.</p>
 <p>A JITServer instance can have several AOT caches, each with its own name. This addresses the situation when client JVMs with significantly different profiles of execution use the same JITServer instance. A client JVM can indicate a specific AOT cache it wants to use by providing its name with the following command-line option <a href="../xxjitserveraotcachename/"><code>-XX:JITServerAOTCacheName=&lt;cache_name&gt;</code></a>. If the client doesn't specify a name for the AOT cache, the server uses a cache named <code>default</code>.</p>
@@ -8311,7 +8311,7 @@ <h3 id="jitserver-aot-cache">JITServer AOT cache</h3>
 <li>The number of extra AOT methods added to the in-memory cache since the last save operation is equal to or more than the value specified by the <code>-Xjit:aotCachePersistenceMinDeltaMethods=&lt;number_of_methods&gt;</code> option (default value - 200 methods), and</li>
 <li>The time passed since the last AOT cache save is equal to or later than the time specified by the <code>-Xjit:aotCachePersistenceMinPeriodMs=&lt;milliseconds&gt;</code> option (default time gap - 10000 milliseconds).</li>
 </ul>
-<p>If the JITServer AOT cache feature and the <a href="../xshareclasses/#readonly"><code>-Xshareclasses:readonly</code></a> option are both enabled at the same time at a JITServer client, the shared class cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p>
+<p>If the JITServer AOT cache feature and the <a href="../xshareclasses/#readonly"><code>-Xshareclasses:readonly</code></a> option are both enabled at the same time at a JITServer client, the shared classes cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p>
 <p>Current limitation:</p>
 <ul>
 <li>Caching works only for AOT compilation requests. For this reason, when JITServer AOT caching is enabled, the client JVM will attempt to generate as many AOT requests as possible.</li>
diff --git a/search/search_index.json b/search/search_index.json
index 9f6c52d853..884ed5e486 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"About the docs","text":""},{"location":"#eclipse-openj9","title":"Eclipse OpenJ9","text":"<p>Welcome to the user documentation for the Eclipse OpenJ9\u2122 virtual machine (VM).</p> <p>This user documentation supports the configuration, tuning, and diagnosis of the OpenJ9 VM in an OpenJDK runtime. However, due to differences between the Java SE class libraries, specific options might apply only to one Java SE version. Icons are used to indicate where differences apply. For example:</p> <p> This sentence applies only to Java 11 binaries that include the OpenJ9 VM. Icons for LTS releases are this colour. </p> <p> This sentence applies only to Java 16 or later binaries that include the OpenJ9 VM. Icons for feature releases are this colour. </p> <p>To see which Java releases are LTS releases and which are feature releases, and for information about release cadence, supported platforms, and build environments, see Supported environments.</p> <p> Note: Documentation to support OpenJ9 is still under construction. The current content covers some high level information about OpenJ9 components together with the command-line options and environment variables that you can use to configure the VM when you start your application. Because OpenJ9 was contributed to the Eclipse Foundation by IBM, this content contains some links to additional information that forms part of the IBM\u00ae SDK, Java\u2122 Technology Edition product documentation in IBM Documentation. That content supplements the documentation here until a more complete set of user documentation is available.</p> <p>We welcome contributions to the user documentation. If you would like to get involved, please read our Contribution guidelines. If you spot any errors in the documentation, please raise an issue at our GitHub repository.</p>"},{"location":"#supported-environments","title":"Supported environments","text":"<p>OpenJDK binaries that contain the OpenJ9 VM are supported on a range of hardware and operating systems. This range is expanding as work progresses at the Eclipse foundation. See the current list of supported environments for details.</p> <p> Note: This user guide also contains information about configuring, tuning, and debugging OpenJ9 on the z/OS\u00ae platform.</p>"},{"location":"#documentation-for-specific-releases","title":"Documentation for specific releases","text":"<p>Several versions of the documentation are available, covering all releases of OpenJ9:</p> <ul> <li>Online documentation for the last release</li> <li>Online, in-progress documentation for the forthcoming release</li> <li>Downloads of earlier releases: to download a zip file, click the filename, then click Download. After downloading a <code>.zip</code> file, extract it, then open the <code>index.html</code> file in your browser.</li> </ul>"},{"location":"#useful-links","title":"Useful links","text":"<ul> <li>Eclipse OpenJ9 website home page</li> <li>Eclipse OpenJ9 GitHub repository</li> <li>Eclipse Foundation OpenJ9 project page</li> </ul>"},{"location":"allocation/","title":"Heap allocation","text":""},{"location":"allocation/#heap-allocation","title":"Heap allocation","text":"<p>The process of managing memory in the VM is handled by the allocator and the garbage collector. These components operate on an area of memory that is reserved for VM processing called the Java\u2122 heap.</p> <p>The allocator assigns areas of the heap for Java objects. Objects are considered as live when they have a chain of references to them that start from root references, such as those found in thread stacks. When that reference or pointer no longer exists, the objects are considered as garbage.</p> <p>The garbage collector reclaims memory by removing objects when they are no longer required. To find out more about the garbage collector, see Garbage collection.</p> <p>Depending on your application workload or service level agreement, you can choose from a number of Eclipse OpenJ9\u2122 garbage collection (GC) policies. Each GC policy uses a different strategy to manage memory on the heap. The structure of the heap also depends on the strategy in force. For more information about choosing a GC policy, see Garbage collection policies.</p>"},{"location":"allocation/#the-allocator","title":"The allocator","text":"<p>The allocator manages pools of free memory and how the free memory is consumed. It is also responsible for allocating areas of storage in the Java heap for objects at the request of applications, class libraries, or the VM.</p> <p>In general, allocation requires a heap lock to synchronize concurrent threads that try to access the same area of memory at the same time. When an object is allocated, the heap lock is released. If there is insufficient space to allocate the object, allocation fails, the heap lock is released, and the garbage collector is called. If GC manages to recover some space on the heap, the allocator can resume operations. If GC does not recover enough space, it returns an <code>OutOfMemoryError</code> exception.</p> <p>Acquiring a heap lock for every allocation would be an intensive operation with an impact to performance. To get around this problem, small objects are allocated to allocation caches.</p>"},{"location":"allocation/#allocation-caches","title":"Allocation caches","text":"<p>To improve performance, allocation caches are reserved in the heap for different threads. These allocation caches are known as thread local heaps (TLH) and allow each thread to allocate memory from its cache without acquiring the heap lock. Objects are allocated from the TLH unless there is insufficient space remaining in the TLH to satisfy the request. In this situation, the allocation might proceed directly from the heap for larger objects by using a heap lock or the TLH might be refreshed for smaller objects.</p> <p>If a thread allocates a lot of objects, the allocator gives that thread a larger TLH to reduce contention on the heap lock.</p> <p>A TLH is predefined with an initial default size of 2 KB. On every TLH refresh, the requested size for that thread is increased by an increment (default 4 KB). The requested size can grow up to a predefined maximum (default 128 KB). If a TLH refresh fails to complete, a GC cycle is triggered.</p> <p>After every GC cycle, the requested size of the TLH for each thread is reduced, sometimes by as much as 50%, to take account of threads that reduce their allocation rate and no longer need large TLHs.</p> <p>For very inactive threads, the requested size can even drop below the initial value, down to the predefined minimum (512/768 bytes). For very active threads, the maximum TLH requested size might be reached before the next GC occurs.</p> <p>Larger TLHs can help reduce heap lock contention, but might also reduce heap utilization and increase heap fragmentation.</p> <p>The following options control the requested TLH size:</p> <ul> <li><code>-Xgc:tlhMaximumSize=&lt;bytes&gt;</code></li> <li><code>-Xgc:tlhInitialSize=&lt;bytes&gt;</code></li> <li><code>-Xgc:tlhIncrementSize=&lt;bytes&gt;</code></li> </ul> <p>Typically, when the maximum TLH size is increased, you should also increase the increment proportionally, so that active threads can reach the maximum requested TLH size more quickly.</p>"},{"location":"allocation/#heap-configuration","title":"Heap configuration","text":"<p>Depending on the memory management strategy in force, the Java heap can be configured in a number of ways. The simplest configuration consists of a single area of memory, often referred to as a flat heap. Other configurations divide the heap into different areas or regions, which might contain objects of different ages (generations) or sizes.</p>"},{"location":"allocation/#area-based-heaps","title":"Area-based heaps","text":"<p>The default GC policy for OpenJ9 uses a heap configuration that is divided into two main areas: the nursery area for new object allocation, and the tenure area for objects that continue to be reachable for a longer period of time. Most objects have short lifecycles and can be reclaimed by the garbage collector more quickly by focusing only on the nursery area. Global GC cycles that cause application pauses in order to clear and defragment the tenure area are less frequent.</p>"},{"location":"allocation/#soa-and-loa","title":"SOA and LOA","text":"<p>All area-based heaps subdivide part of the heap into the Small Object Area (SOA) and the Large Object Area (LOA).</p> <p>The allocator initially attempts to allocate objects in the SOA, regardless of size. If the allocation cannot be satisfied the following actions are possible, depending on object size:</p> <ul> <li>If the object is smaller than 64 KB, an allocation failure occurs, which triggers a GC action.</li> <li>If the object is larger than 64 KB, the allocator attempts to allocate the object in the LOA. If the allocation cannot be satisfied, an allocation failure occurs, which triggers a GC action.</li> </ul> <p>The GC action that is triggered by the allocation failure depends on the GC policy in force.</p> <p>The overall size of the LOA is calculated when the heap is initialized, and recalculated at the end of each global GC cycle. The garbage collector can expand or contract the LOA, depending on usage, to avoid allocation failures.</p> <p>You can control the size of the LOA by using the <code>-Xloainitial</code>, <code>-Xloaminimum</code>, and <code>-Xloamaximum</code> command line options. If the LOA is not used, the garbage collector contracts the LOA after a few cycles, down to the value of <code>-Xloaminimum</code>. You can also specify <code>-Xnoloa</code> to prevent an LOA being created.</p> <p>An SOA and LOA are used by the OpenJ9 GC policies: <code>gencon</code>, <code>optavgpause</code>, and <code>optthruput</code>. For the <code>gencon</code> policy, the LOA and SOA are contained within the tenure area, which is designated for ageing objects. For more information about policies, see Garbage collection policies.</p>"},{"location":"allocation/#region-based-heaps","title":"Region-based heaps","text":"<p>The Java heap can also be subdivided into multiple regions. The <code>balanced</code> GC policy uses a heap that is divided into thousands of equal size regions in order to manage multiple generations of objects. The <code>metronome</code> GC policy also uses multiple regions, which are grouped by size-class to manage a singe generation of objects. To learn more about how the regions are configured for each policy, see Garbage collection policies.</p> <p>In addition to regions, the <code>balanced</code> and <code>metronome</code> policies use structures called arraylets to store large arrays in the heap.</p>"},{"location":"allocation/#arraylets","title":"Arraylets","text":"<p>A Java heap that is subdivided into regions might not be able to contain a large enough region for data arrays. This problem is solved by using arraylets. An arraylet has a spine, which contains the class pointer and size, and leaves, which contain the data associated with the array. The spine also contains arrayoids, which are pointers to the respective arraylet leaves, as shown in the following diagram.</p> <p></p> <p>There are a number of advantages to using arraylets.</p> <ul> <li> <p>Because the heap tends to fragment over time, some GC policies might be forced to run a global garbage collection and defragmentation (compaction) to recover sufficient contiguous memory to allocate a large array. By removing the requirement for large arrays to be allocated in contiguous memory, the garbage collector is more likely to be able to satisfy such an allocation without requiring unscheduled garbage collection, particularly a global defragmentation operation.</p> </li> <li> <p>Additionally, the garbage collector never needs to move an arraylet leaf once it has been allocated. The cost of relocating an array is therefore limited to the cost of relocating the spine, so large arrays do not contribute to higher defragmentation times.</p> </li> </ul> <p> Note: Despite the general advantage of using arraylets, they can slow down processing when the Java Native Interface (JNI) is being used. The JNI provides flexibility by enabling Java programs to call native code; for example, C or C++, and if direct addressability to the inside of an object is needed, a JNI critical section can be used. However, that requires the object to be in a contiguous region of memory, or at least appear to be so. The JNI, therefore, creates a temporary contiguous array that is the same size as the original array and copies everything, element by element, to the temporary array. After the JNI critical section is finished, everything is copied from the temporary array back to the arraylet, element by element.</p>"},{"location":"allocation/#heap-sizing","title":"Heap sizing","text":"<p>The overall size of the Java heap is determined by two command-line options, <code>-Xms</code>, which sets the initial size of the heap, and <code>-Xmx</code>, which sets the maximum size of the heap. Finer tuning of the heap depends on the heap configuration that is being used by a GC policy. For example, an LOA within the heap can be sized by using the <code>-Xloainitial</code>, <code>-Xloaminimum</code>, and <code>-Xloamaximum</code> command-line options. A nursery area within the heap can be sized by using the <code>-Xmn</code>, <code>-Xmns</code>, and <code>-Xmnx</code> command-line options. For more information about policies and the heap configurations that are used, see GC policies. To determine the values that are in use for the Java heap, use the <code>-verbose:sizes</code> option when you run your Java application.</p> <p>When the Java heap runs out of space, <code>OutOfMemoryError</code> exceptions are generated. If you are confident that your heap settings are appropriate for your application but are still receiving an <code>OutOfMemoryError</code> exception, check the Java dump file that gets automatically generated when the error occurs. A Java dump file can tell you more about what your application was attempting to do at the time of the error. For example, see the Java OutOfMemoryError scenario.</p>"},{"location":"allocation/#expansion-and-contraction","title":"Expansion and contraction","text":"<p>At startup, the VM allocates a single contiguous area of virtual storage to match the value of <code>-Xmx</code>. By default, this is 25% of the available memory up to a maximum of 25 GB. The actual Java heap size starts at the value set by <code>-Xms</code> and expands automatically, as required, up to the maximum heap size. The VM can also contract the size of the Java heap. Expansion and contraction occur as part of a GC cycle when the VM has exclusive access to the heap. The only GC policy that does not support heap expansion and contraction is the <code>metronome</code> GC policy, where the heap is always fully expanded.</p> <p> Note: On operating systems that support paging, the VM allocates a single contiguous area that matches the value of <code>-Xms</code>. Additional memory is committed as the heap expands by using the paging process.</p> <p>Expansion occurs to maintain free space on the Java heap for object allocation. By default, the heap is expanded to maintain 30% free space, but this proportion can be adjusted by setting one of the following command-line options:</p> <ul> <li><code>-Xminf</code> determines the minimum proportion of the heap that must be free after garbage is removed.</li> <li><code>-Xmaxf</code> determines the maximum proportion of the heap that must be free after garbage is removed.</li> </ul> <p>If expansion is required, the amount of memory that the heap can expand by is controlled by the following command-line options:</p> <ul> <li><code>-Xmine</code> sets the minimum amount that the heap can expand by.</li> <li><code>-Xmaxe</code> sets the maximum amount that the heap can expand by. The default is unlimited expansion up to the maximum heap size (<code>-Xmx</code>).</li> </ul> <p>Expansion can also be triggered if more time is being spent on GC processing than is specified by the <code>-Xmaxt</code> option. In this case, the heap expands by an amount that provides 17% more free space, within the limits imposed by the <code>-Xmine</code> and <code>-Xmaxe</code> values.</p> <p>Heap contraction occurs under certain conditions and might be preceded by heap compaction. If the last three GC cycles caused a heap expansion, contraction does not occur. Otherwise, contraction is triggered when the proportion of free heap space that is specified by the <code>-Xmaxf</code> option is reached. The amount of memory to reduce the heap by is calculated to the nearest 1024-byte boundary, down to the minimum size specified for the initial Java heap (<code>-Xms</code>). To prevent heap contraction, set the <code>-Xmaxf</code> value to <code>1</code>, which sets the maximum free space allowed on the heap to 100%.</p> <p>When the heap contracts, physical memory is not released unless paging is supported by the underlying operating system.</p>"},{"location":"allocation/#balanced-gc-policy","title":"<code>balanced</code> GC policy","text":"<p>For the <code>balanced</code> GC policy, if the <code>-Xminf</code>/<code>-Xmaxf</code> and/or <code>-Xmint</code>/<code>-Xmaxt</code> criteria are not being met and this results in a heap resize, then the heap resize that occurs, happens only on non-eden heap (similar to how these options apply to tenure part for gencon).</p> <p>The non-eden heap resizing occurs at the end of a GMP cycle, or global collection. At this point, heap resizing decision is made by observing both <code>-Xmint</code>/<code>-Xmaxt</code> and <code>-Xminf</code>/<code>-Xmaxf</code> and comparing them to the appropriate proportion of time spent in GC, and free heap respectively.</p> <p>If either <code>-Xmint</code>/<code>-Xmaxt</code> and/or <code>-Xminf</code>/<code>-Xmaxf</code> criteria are not being met, there is no guarantee that a heap resize will occur. The heap sizing logic is looking at the following two things:</p> <ul> <li>if % of time in GC pauses is between <code>-Xmint</code>/<code>-Xmaxt</code>. If it's greater than <code>-Xmaxt</code>, the VM will try to expand the heap, if it's less than <code>-Xmint</code>, then contract it.</li> <li>if % of free heap is between <code>-Xminf</code>/<code>-Xmaxf</code>. If it's too high, i.e. greater than <code>-Xmaxf</code>(too much free), heap size will contract, if too low, i.e. lesser than <code>-Xminf</code>, it will expand.</li> </ul> <p>Since these two criteria may be providing opposite recommendations (for example, lots of free memory, but high % of time in GC) causing oscillations in heap size, the <code>balanced</code> GC heap sizing logic finds a balance between these two criteria.</p>"},{"location":"allocation/#compressed-references","title":"Compressed references","text":"<p>On 64-bit systems, the VM can use compressed references to decrease the size of Java objects and make better use of the available space in the Java heap. By storing objects in a 32-bit representation, the object size is identical to that in a 32-bit VM, which creates a smaller memory footprint. These 4 byte (32-bit) compressed references are converted to 64-bit values at runtime with minimal overhead. Smaller objects enable larger heap sizes that result in less frequent garbage collection and improve memory cache utilization. Overall, the performance of 64-bit applications that store compressed rather than uncompressed 64-bit object references is significantly improved.</p> <p>Compressed references are used by default when the maximum Java heap size is in the range 0 - 57 GB on AIX\u00ae, Linux\u00ae, and Windows\u00ae systems. The upper limit is also 57 GB on z/OS\u00ae systems that have APAR OA49416 installed (25 GB without APAR OA49416). All GC policies observe these limits except for the <code>metronome</code> policy, which can support a heap size of up to 25 GB only with compressed references.</p> <p>When the VM uses compressed references, classes, threads, and monitors are stored in the lowest 4 GB of address space. However, this area of memory is also used by native libraries, the operating system, and for small Java heaps. If you receive native memory <code>OutOfMemoryError</code> exceptions in the lowest 4 GB when running with compressed references enabled, these errors might result from the lowest 4 GB of address space becoming full. Try specifying a large heap with the <code>-Xmx</code> option, which puts the Java heap into a higher area of address space or using the <code>-Xmcrs</code> option to reserve space in the lowest 4 GB of address space for compressed references.</p> <p>To turn off compressed references, use the <code>-Xnocompressedrefs</code> command-line option.</p>"},{"location":"aot/","title":"AOT Compiler","text":""},{"location":"aot/#ahead-of-time-aot-compiler","title":"Ahead-Of-Time (AOT) compiler","text":"<p>The AOT compiler dynamically compiles Java methods into native AOT code at runtime and stores them in the shared classes cache. This activity enables the VM to start an application faster the next time it runs because it doesn't need to spend time interpreting Java methods. The VM automatically chooses which methods should be AOT-compiled based on heuristics that identify the start-up phase of large applications. AOT code is always used in combination with class data sharing and is enabled automatically when <code>-Xshareclasses</code> is set on the command line. When a cached AOT method is run it might also be optimized further by the Just-In-Time (JIT) compiler.</p> <p>If you want to turn off AOT compilation and disable the use of AOT-compiled code, set the <code>-Xnoaot</code> suboption. When the AOT compiler is disabled, the JIT compiles frequently used methods into native code. However, because the JIT compiler operates while the application is running, the startup time for an application will increase.</p>"},{"location":"aot/#see-also","title":"See also","text":"<ul> <li>Diagnosing a JIT or AOT problem</li> <li>JIT compiler</li> <li>Introduction to class data sharing</li> </ul>"},{"location":"api-conditionhandling/","title":"Condition exception handling","text":""},{"location":"api-conditionhandling/#condition-handling-api-documentation","title":"Condition Handling API documentation","text":""},{"location":"api-cuda/","title":"CUDA4J","text":""},{"location":"api-cuda/#cuda4j-api-documentation","title":"CUDA4J API documentation","text":""},{"location":"api-daa/","title":"Data access acceleration","text":""},{"location":"api-daa/#data-access-acceleration-api-documentation","title":"Data access acceleration API documentation","text":""},{"location":"api-dtfj/","title":"DTFJ","text":""},{"location":"api-dtfj/#dtfj-api-documentation","title":"DTFJ API documentation","text":""},{"location":"api-gpu/","title":"GPU","text":""},{"location":"api-gpu/#gpu-api-documentation","title":"GPU API documentation","text":""},{"location":"api-jdk11/","title":"Java 11 API","text":""},{"location":"api-jdk11/#openj9-jdk-11-api-documentation","title":"OpenJ9 JDK 11 API documentation","text":""},{"location":"api-jdk17/","title":"Java 17 API","text":""},{"location":"api-jdk17/#openj9-jdk-17-api-documentation","title":"OpenJ9 JDK 17 API documentation","text":""},{"location":"api-jdk21/","title":"Java 21 API","text":""},{"location":"api-jdk21/#openj9-jdk-21-api-documentation","title":"OpenJ9 JDK 21 API documentation","text":""},{"location":"api-jvm/","title":"JVM diagnostic utilities","text":""},{"location":"api-jvm/#jvm-diagnostic-utilities-api-documentation","title":"JVM diagnostic utilities API documentation","text":""},{"location":"api-langmgmt/","title":"Monitoring and management","text":""},{"location":"api-langmgmt/#monitoring-and-management-api-documentation","title":"Monitoring and management API documentation","text":""},{"location":"api-overview/","title":"Overview","text":""},{"location":"api-overview/#api-documentation","title":"API documentation","text":"<p>The Eclipse OpenJ9\u2122 VM provides supplementary application programming interfaces and extensions, which can be used to improve performance, assist with problem determination, or help monitor and manage the OpenJ9 VM. The documentation also includes links to the API documentation for the Java\u2122 SE and JDK reference implementation.</p>"},{"location":"api-overview/#native-data-operations","title":"Native data operations","text":"<p>If your Java application manipulates native data, the Data Access Accelerator API package (<code>com.ibm.dataaccess</code>) can help improve application performance. Classes are available for the following types of operation:</p> <ul> <li>performing arithmetic, comparison, and validation of packed decimal data</li> <li>converting between decimal data types as well as to and from <code>BigDecimal</code> and <code>BigInteger</code> types</li> <li>marshalling Java binary types to and from byte arrays</li> </ul>"},{"location":"api-overview/#gpu-acceleration","title":"GPU acceleration","text":"<p>You can improve the performance of your applications by offloading certain processing functions from your processor (CPU) to a graphics processing unit (GPU). If your application contains code that would benefit from parallel processing, you can use the CUDA4J API package (<code>com.ibm.cuda</code>) to specify in your code when to offload processing to the GPU. You can also use the GPU API package (<code>com.ibm.gpu</code>)  to accelerate certain Java functions, such as <code>sort</code> operations.</p>"},{"location":"api-overview/#problem-determination","title":"Problem determination","text":"<p>The JVM diagnostic utilities API package (<code>com.ibm.jvm</code>) provides classes for controlling dump, log, and trace operations.</p> <p>The Diagnostic Tool Framework for Java (DTFJ) API packages (<code>com.ibm.dtfj.*</code>) allow custom applications to be written that can access a wide range of information in a system dump or a Java dump.</p>"},{"location":"api-overview/#monitoring-and-management","title":"Monitoring and management","text":"<p>The shared classes API package (<code>com.ibm.oti.shared</code>) provides a large number of classes for managing permissions, finding and storing classes and byte data, and obtaining statistics about a shared classes cache. Classes are also available to enable class sharing for a custom class loader implementation.</p> <p>OpenJ9 includes MXBean extensions to the <code>java.lang.management</code> API (<code>com.ibm.lang.management</code> and <code>openj9.lang.management</code>), which can be used to monitor and manage the VM. These extensions provide access to information about the state of the OpenJ9 VM and the environment in which it is running.</p>"},{"location":"api-shrc/","title":"Shared classes","text":""},{"location":"api-shrc/#shared-classes-api-documentation","title":"Shared classes API documentation","text":""},{"location":"attachapi/","title":"Java Attach API","text":""},{"location":"attachapi/#java-attach-api","title":"Java Attach API","text":"<p>With the Attach API, your application can connect to a running VM and load an agent into that VM to run tasks. The typical use case for this feature is to load an agent that can be used to monitor the application that's running in the target VM.</p> <p>For example, if you wanted to start monitoring an application that is already running with the Attach API enabled, you could use a tool such as the IBM Health Center. In this case, a Health Center agent can start in its own VM and attach to the target VM where the application is running to start recording and sending data to the Health Center client.</p> <p>The Eclipse OpenJ9\u2122 implementation of the Attach API is equivalent to the reference implementation (API documentation is available on the Oracle website). However, you can use the Attach API only to connect to another OpenJ9 VM.</p> <p>When you run a Java\u2122 application, VM support for the Attach API is enabled by default on all platforms except z/OS\u00ae. For security reasons on z/OS, processes that use the default z/OS OMVS segment cannot enable the Attach API.</p> <p>To enable or disable the Attach API, use the <code>-Dcom.ibm.tools.attach.enable=[yes|no]</code> command line option.</p>"},{"location":"attachapi/#securing-the-attach-api","title":"Securing the Attach API","text":"<p>Because the Attach API can be used to connect to a running application, you must control access to it to ensure that only authorized users or processes can use it. Disable the Attach API if you do not intend to use it.</p> <p>If you do not want to disable the Attach API but want to control the unauthorized dynamic loading of agents into the VM by using the Attach API, use the <code>-XX:-EnableDynamicAgentLoading</code> option.</p> <p>On Windows systems, the Attach API uses the system temporary directory, which is typically <code>C:\\Users\\&lt;USERNAME&gt;\\AppData\\Local\\Temp</code>. The Attach API creates a common subdirectory, which is <code>.com_ibm_tools_attach</code> by default. Because files and directories in the system temporary directory are handled by Windows security, only the process owner can connect to their processes.</p> <p>On UNIX systems, the Attach API uses <code>/tmp</code> and creates a common subdirectory, which is <code>.com_ibm_tools_attach</code> by default. The common subdirectory must be on a local drive, not a network drive. Security is handled by POSIX file permissions. The Attach API directory must be owned by <code>root</code> user and must have read, write, and execute file permissions for <code>user</code>, <code>group</code>, and <code>other</code> (<code>drwxrwxrwx</code>). The sticky bit is set so that only the owner and <code>root</code> can delete or rename files or directories within it. A process that uses the Java Attach API must be owned by the same UNIX user ID as the target process.</p> <pre><code>~/tmp $ ls -al\ntotal 0\ndrwxr-xr-x   3 user_a staff    96  6 Aug 17:11 .\ndrwxr-xr-x+ 89 user_a staff  2848  6 Aug 17:11 ..\ndrwxrwxrwx+  7 root   staff   224  6 Aug 17:22 .com_ibm_tools_attach\n</code></pre> <p>In the default Attach API directory you can find certain files that start with an underscore <code>_*</code>, which are involved in synchronization. These files can be owned by any user but must have read and write permissions set. The files are empty and are automatically re-created if deleted. When your application attaches to a VM, a process directory is created.</p> <pre><code>~/tmp/.com_ibm_tools_attach $ ls -l\ntotal 3\n-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _attach_lock\n-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _controller\n-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _notifier\ndrwx--x--x  6 user_b  staff  192  6 Aug 17:21 process_a\n</code></pre> <p>The files in the subdirectory for a process, with the exception of a lock file, are accessible only by the owner of a process. The permissions for these files are <code>rwxr-xr-x</code> with the exception of the <code>attachNotificationSync</code> file, as shown in the following example.</p> <pre><code>~/tmp/.com_ibm_tools_attach/process_a $ ls -l\ntotal 4\n-rwxrw-rw-  1 user_b  staff  0  6 Aug 17:18 attachNotificationSync\n-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_a\n-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_b\n-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_c\n</code></pre> <p>Notes for z/OS:</p> <ul> <li>z/OS systems must also set POSIX permissions on files and cannot rely on RACF\u00ae or system level security to protect applications.</li> <li>To avoid z/OS console messages reporting security violations in <code>/tmp</code>, add a security exception or specify a different common subdirectory by setting the <code>com.ibm.tools.attach.directory</code> system property.</li> </ul>"},{"location":"attachapi/#configuring","title":"Configuring","text":"<p>A number of system properties are available to configure the Attach API when you start a Java application, as shown in the following table:</p> System property Description <code>-Dcom.ibm.tools.attach.directory=&lt;directory_name&gt;</code> Specify a different common directory for Attach API working files. <code>-Dcom.ibm.tools.attach.displayName=&lt;my_display_name&gt;</code> Change the display name recorded by an agent <code>-Dcom.ibm.tools.attach.id=&lt;my_vm_ID&gt;</code> Change the VM identifier recorded by an agent <code>-Dcom.ibm.tools.attach.timeout=&lt;value_in_milliseconds&gt;</code> Change the connection timeout <code>-Dcom.ibm.tools.attach.shutdown_timeout=&lt;value_in_milliseconds&gt;</code> Specify the timeout for ending the Attach API wait loop thread <code>-Dcom.ibm.tools.attach.command_timeout=&lt;value_in_milliseconds&gt;</code> Specify the timeout for sending a command to the target VM after initial attachment <p>To learn more about each property, click the link in the table.</p>"},{"location":"attachapi/#troubleshooting","title":"Troubleshooting","text":"<p>Problems with the Attach API generate one of the following exceptions:</p> <ul> <li><code>com.sun.tools.attach.AgentLoadException</code></li> <li><code>com.sun.tools.attach.AgentInitializationException</code></li> <li><code>com.sun.tools.attach.AgentNotSupportedException</code></li> <li><code>com.sun.tools.attach.AttachOperationFailedException</code></li> <li><code>java.io.IOException</code></li> </ul> <p>Exceptions from agents on the target VM go to <code>stderr</code> or <code>stdout</code> for the target VM. These exceptions are not reported in the output of the attaching VM.</p> <p>Here are some problems that you might encounter:</p> <ul> <li>On Unix systems, the file permissions are incorrectly set, causing access issues. Resolve these issues by reading and complying with Securing the Attach API. Also check that the Attach API is not disabled.</li> <li>The common directory is deleted, the contents of the common directory are deleted, or permissions of the common directory or subdirectories are changed. As a result, the source VM might not be able list target VMs or attach to them. Deletion of the common directory can also cause semaphore leaks.</li> <li>The system temporary directory is full or inaccessible and the Attach API cannot initialize. Try specifying a different directory in which to create the common subdirectory by using the <code>-Dcom.ibm.tools.attach.directory</code> system property.</li> <li>A short delay between the start of the target VM and the initialization of the Attach API process can cause an <code>AttachNotSupportedException: No provider for virtual machine id</code> issue when the <code>VirtualMachine.attach(String id)</code> method is called.</li> <li>The target process is overloaded, suspended, or no longer running, or the port that is used to connect to the target is subject to a wait time (use the <code>netstat -a</code> command to check for ports in the <code>TIME_WAIT</code> state). These situations can cause an <code>AttachNotSupportedException</code> when the <code>attach</code> method is called.</li> <li>A JVMTI agent is corrupt or attempts to run an operation that is not available after the VM starts. These situations can cause an <code>AgentLoadException</code> or <code>AgentInitializationException</code> when one of the following methods is called: <code>loadAgent()</code>, <code>loadAgentLibrary()</code>, or <code>loadAgentPath()</code>. Depending on the method invoked, try loading the agent at VM startup by using one of the following command-line options <code>-javaagent</code>, <code>-agentlib</code>, or <code>-agentpath</code>. For more information about these options, see Java Virtual Machine Tool Interface.</li> </ul> <p>If you have checked for these potential issues but you are still experiencing problems, a number of command line system properties are available to help narrow down the cause. These options are shown in the following table:</p> System property Description <code>-Dcom.ibm.tools.attach.logging=&lt;yes|no&gt;</code> Turn on tracing of attach API events <code>-Dcom.ibm.tools.attach.log.name=&lt;my_log_name&gt;</code> Specify the path and prefix for the log files <p>To learn more about each property, click the link in the table.</p>"},{"location":"builds/","title":"OpenJ9 builds","text":""},{"location":"builds/#eclipse-openj9-builds","title":"Eclipse OpenJ9 builds","text":"<p>Eclipse Foundation projects are not permitted to distribute, market or promote JDK binaries unless they have passed a Java SE Technology Compatibility Kit licensed from Oracle, to which the Eclipse OpenJ9\u2122 project does not currently have access. See the Eclipse Adoptium Project Charter.</p>"},{"location":"builds/#supported-platforms","title":"Supported platforms","text":"<p>The community develops and maintains a test infrastructure for the OpenJ9 source across a broad range of platforms. For information about the platforms and minimum operating system levels supported, see the Platform support matrix.</p>"},{"location":"builds/#building-your-own-binaries","title":"Building your own binaries","text":"<p>If you want to build your own binaries of OpenJDK with OpenJ9, a complete set of build instructions for several platforms can be found in the OpenJ9 GitHub repository.  </p>"},{"location":"builds/#installation-pre-requisites","title":"Installation pre-requisites","text":"<p>Note the following:</p> <ul> <li>For the best performance, OpenSSL support should be enabled in the build. In builds that aren't configured with <code>--enable-openssl-bundling</code>, the OpenSSL library is expected to be found on the system path. If you want to use OpenSSL cryptographic acceleration, you must install OpenSSL 1.0.2, 1.1.x, or 3.x on your system. If the library is not found on the system path, the in-built Java crytographic implementation is used instead, which performs less well.</li> <li> On Linux systems, the <code>fontconfig.x86_64</code> package should be installed to avoid a <code>NullPointerException</code> error when the AWT font subsystem is initialized.</li> <li>From Eclipse OpenJ9 release 0.16.0 (OpenJDK 13) and release 0.17.0 (OpenJDK 8 and 11), CUDA is now enabled on Windows (x86-64) and Linux (x86-64 and IBM POWER LE) platforms, which allows you to offload certain Java application processing tasks to a general purpose graphics processing unit (GPU). To take advantage of this feature, your system must support NVIDIA Compute Unified Device Architecture (CUDA). The JIT requires the CUDA Toolkit 7.5 and your GPU device must have a minimum compute capability of 3.0.</li> </ul>"},{"location":"cmdline_general/","title":"Standard options","text":""},{"location":"cmdline_general/#standard-command-line-options","title":"Standard command-line options","text":"<p>The Eclipse OpenJ9\u2122 virtual machine supports the standard Java\u2122 options that are common to all Java virtual machine implementations, including Oracle's HotSpot VM. Some of the common options supported are summarised in the following table:</p> Standard option name Purpose <code>-classpath:&lt;resource_name&gt;[:&lt;resource_name&gt;]</code> Sets the search path for application classes and resources (directories and compressed or .jar files). <code>cp</code> can be used instead of <code>classpath</code>. <code>-help</code>, <code>-?</code> Prints a usage message. <code>-fullversion</code> Prints the build and version information for a VM <code>-showversion</code> Prints product version and continues. <code>-verbose:&lt;option&gt;[,&lt;option&gt;]</code> Enables verbose output. Options include <code>class</code>, <code>dynload</code>, <code>gc</code>, <code>init</code>, <code>jni</code>, <code>sizes</code>, <code>stack</code>, and <code>module</code>. (See Notes) <code>-version</code> Prints the full build and version information a VM <p> Notes:</p> <ul> <li><code>-verbose:class</code>: Writes an entry to <code>stderr</code> for each class that is loaded.</li> <li><code>-verbose:dynload</code>: Writes detailed class information to <code>stderr</code> as each bootstrap class is loaded by the VM:</li> <li><code>-verbose:gc</code>: Provides verbose garbage collection information.</li> <li><code>-verbose:init</code>: Writes information to <code>stderr</code> describing VM initialization and termination.</li> <li><code>-verbose:jni</code>: Writes information to <code>stderr</code> describing the JNI services called by the application and VM.</li> <li><code>-verbose:sizes</code>: Writes information to <code>stderr</code> describing the active memory usage settings.</li> <li><code>-verbose:stack</code>: Writes information to <code>stderr</code> describing the Java and C stack usage for each thread.</li> <li><code>-verbose:module</code>:  Writes information to <code>stderr</code> for each module that is loaded and unloaded.</li> </ul> <p>For more information about standard options, see Oracle Java SE Standard Options</p>"},{"location":"cmdline_general/#openj9-extensions","title":"OpenJ9 extensions","text":"<p>OpenJ9 supports the following extension to the <code>-verbose</code> option:</p> <ul> <li><code>-verbose:stacktrace</code> : Writes either the module name or the <code>Classloader</code> name (with the code source location when available) to the end of each line of a Java stack trace.</li> </ul>"},{"location":"cmdline_migration/","title":"Switching to OpenJ9","text":""},{"location":"cmdline_migration/#switching-to-eclipse-openj9","title":"Switching to Eclipse OpenJ9","text":"<p>If you are already familiar with HotSpot command-line options but want the advantages of Eclipse OpenJ9\u2122, the following information will prove helpful. In all cases, check individual topics for minor discrepancies in the way these options might work.</p> <p> Note: For information about HotSpot equivalences and differences for items other than command-line options, see New to Eclipse OpenJ9?</p>"},{"location":"cmdline_migration/#compatible-options","title":"Compatible options","text":"<p>You can use the following command-line options in OpenJ9, just as you did in HotSpot; you can continue to use the HotSpot option in OpenJ9 without having to change your code:</p> Option Usage <code>-X</code> Displays help on nonstandard options. <code>-Xbootclasspath</code> Specifies the search path for bootstrap classes and resources. <code>-Xcheck:jni</code> Runs additional checks for JNI functions during VM startup. <code>-Xfuture</code> Turns on strict class-file format checks. <code>-Xint</code> Runs an application in interpreted-only mode. <code>-Xlog</code> Some forms of <code>-Xlog</code> that enable garbage collection logging are recognized. (Equivalent to <code>-Xverbosegclog</code>). <code>-Xmn</code> Sets the initial and maximum size of the new area when using -Xgcpolicy:gencon. <code>-Xms</code> Sets the initial size of the heap. (Equivalent to <code>-XX:InitialHeapSize</code>) <code>-Xmx</code> Specifies the maximum size of the object memory allocation pool. (Equivalent to <code>-XX:MaxHeapSize</code>) <code>-Xnoclassgc</code> Disables class garbage collection (GC). <code>-Xrs</code> Prevents the OpenJ9 run time environment from handling signals. <code>-Xss</code> Sets the Java\u2122 thread stack size. (Equivalent to <code>-XX:ThreadStackSize</code>).  Note: Unlike HotSpot, this option applies only to the Java stack. OpenJ9 has a separate native stack for operating system threads (see <code>-Xmso</code>) <code>-Xverify:mode</code> Enables or disables the verifier. <code>-XX:ConcGCThreads</code> Configures the number of GC mutator background threads. <code>-XX:[+|-]AlwaysPreTouch</code> Enables/disables committing of memory during initial heap inflation or heap expansion. <code>-XX:[+|-]CompactStrings</code> Enables/disables <code>String</code> compression. Note: This option is enabled by default in OpenJ9 on Java 11 and later. In the earlier versions, this option is disabled by default. <code>-XX:DiagnoseSyncOnValueBasedClasses=&lt;number&gt;</code> Configure warnings for value-based classes. <code>-XX:[+|-]DisableExplicitGC</code> Enables/disables explicit <code>System.gc()</code> calls. (Alias for <code>-Xdisableexplicitgc</code> / <code>-Xenableexplicitgc</code>) <code>-XX:[+|-]ExitOnOutOfMemoryError</code> Triggers VM shutdown on out-of-memory conditions. <code>-XX:[+|-]HeapDumpOnOutOfMemory</code> Enables/disables dumps on out-of-memory conditions. <code>-XX:HeapDumpPath</code> Specifies a directory for all VM dumps including heap dumps, javacores, and system dumps. (Alias for <code>-Xdump:directory</code>) <code>-XX:[+|-]IgnoreUnrecognizedVMOptions</code> Specifies whether to ignore unrecognized top-level VM options. <code>-XX:InitialHeapSize</code> Sets the initial size of the heap. (Alias for <code>-Xms</code>) <code>-XX:InitialRAMPercentage</code> Sets the initial size of the Java heap as a percentage of total memory. <code>-XX:MaxDirectMemorySize</code> Sets a limit on the amount of memory that can be reserved for all direct byte buffers. <code>-XX:MaxHeapSize</code> Specifies the maximum size of the object memory allocation pool. (Alias for <code>-Xmx</code>) <code>-XX:MaxRAMPercentage</code> Sets the maximum size of the Java heap as a percentage of total memory. <code>-XX:OnOutOfMemoryError</code> Runs specified commands when a <code>java.lang.OutOfMemoryError</code> is thrown. (Equivalent to <code>-Xdump:tool:events=systhrow,filter=java/lang/OutOfMemoryError,exec=</code>) <code>-XX:ParallelCMSThreads</code> Configures the number of GC mutator background threads. <code>-XX:ParallelGCThreads</code> Configures the number of GC threads. <code>-XX:[+|-]PrintCodeCache</code> Prints code cache usage when the application exits. <code>-XX:[+|-]ShowHiddenFrames</code> Specifies whether generated hidden <code>MethodHandle</code> frames are displayed in a stack trace.  Note: Unlike HotSpot, this option doesn't require the <code>+UnlockDiagnosticVMOptions</code> option. <code>-XX:[+|-]UseCompressedOops</code> Disables compressed references in 64-bit JVMs. (See also <code>-Xcompressedrefs</code>) <code>-XX:[+|-]UseContainerSupport</code> Sets a larger fraction of memory to the Java heap when the VM detects that it is running in a container."},{"location":"cmdline_migration/#equivalent-options","title":"Equivalent options","text":"<p>These HotSpot command-line options have equivalents in OpenJ9 that are not specified in the same way, but perform a related function:</p> HotSpot Option OpenJ9 Option Usage <code>-Xcomp</code> <code>-Xjit:count=0</code><sup>1</sup> <code>-Xcomp</code> disables interpreted method invocations. <code>-Xgc</code> <code>-Xgcpolicy</code><sup>2</sup> Configuring your garbage collection policy. <code>-XX:+UseNUMA</code> <code>-Xnuma:none</code><sup>3</sup> Controls non-uniform memory architecture (NUMA) awareness. <p> Notes:</p> <ol> <li> <p>HotSpot uses <code>-Xcomp</code> to force compilation of methods on first invocation. However, this option is deprecated. Whilst it can be used for compatibility, using <code>-Xjit:count=0</code> is preferred.</p> </li> <li> <p>HotSpot uses <code>-Xgc</code> to both select policies and configure them; OpenJ9 uses <code>-Xgcpolicy</code> to select policies, reserving <code>-Xgc</code> for configuration.</p> </li> <li> <p>In HotSpot, NUMA awareness is turned off by default and is turned on by using the <code>-XX:+UseNUMA</code> option. Conversely, the OpenJ9 VM automatically enables NUMA awareness and uses <code>-Xnuma:none</code> to turn it off.</p> <ul> <li>If you were previously using HotSpot in its default mode, you must now explicitly turn off NUMA awareness in OpenJ9.</li> <li>If you are used to using <code>-XX:+UseNUMA</code> in HotSpot, you no longer need to explicitly turn on NUMA awareness; it's on by default.</li> </ul> </li> </ol>"},{"location":"cmdline_migration/#creating-compatible-behavior","title":"Creating compatible behavior","text":"<p>You can set the following options to make OpenJ9 behave in the same way as HotSpot.</p> Option Usage <code>-Djava.lang.string.substring.nocopy=true</code> Avoid String sharing by <code>String.substring()</code>. <code>-Xnuma:none</code> Disable non-uniform memory architecture (NUMA) awareness. <code>-XX:+CompactStrings</code> Enables <code>String</code> compression. <code>-XX:[+|-]HandleSIGABRT</code> Force handling of SIGABRT signals to be compatible with HotSpot."},{"location":"cmdline_migration/#compatible-environment-variables","title":"Compatible environment variables","text":"<p>The <code>JAVA_TOOL_OPTIONS</code> environment variable can be used to set command line options as described in OpenJ9 command-line options and Environment variables.</p>"},{"location":"cmdline_specifying/","title":"Specifying options","text":""},{"location":"cmdline_specifying/#eclipse-openj9-command-line-options","title":"Eclipse OpenJ9 command-line options","text":"<p>When you start a Java\u2122 application you can specify various options on the command line to configure the runtime environment. These options include:</p> <ul> <li>System properties</li> <li>Standard options</li> <li>Nonstandard (or -X) options</li> <li>-XX options</li> </ul> <p>Although the command line is the traditional way to specify command-line options, you can also pass options to the Eclipse OpenJ9\u2122 virtual machine (VM) by using a manifest file, options files, and environment variables.</p> <p>Options specified on the command line override the equivalent environment variables. For example, specifying <code>java -cp &lt;dir1&gt;</code> completely overrides setting the environment variable <code>CLASSPATH=&lt;dir2&gt;</code>.</p>"},{"location":"cmdline_specifying/#quotation-marks","title":"Quotation marks","text":"<p>Use single or double quotation marks for command-line options only when explicitly directed to do so. Single and double quotation marks have different meanings on different platforms, operating systems, and shells. Do not use <code>'-X&lt;option&gt;'</code> or <code>\"-X&lt;option&gt;\"</code>. Instead, you must use <code>-X&lt;option&gt;</code>. For example, do not use <code>'-Xmx500m'</code> and <code>\"-Xmx500m\"</code>. Write this option as <code>-Xmx500m</code>.</p>"},{"location":"cmdline_specifying/#precedence","title":"Precedence","text":"<p>The sequence of the Java options on the command line defines which options take precedence during startup. Rightmost options have precedence over leftmost options. In the following example, the <code>-Xjit</code> option takes precedence:</p> <pre><code>java -Xint -Xjit myClass\n</code></pre> <p>At startup, the list of VM arguments is constructed in the following order, with the lowest precedence first:</p> <ol> <li> <p>Certain options are created automatically by the VM, which specify arguments such as search paths and version information. The VM automatically adds <code>-Xoptionsfile=&lt;path&gt;/options.default</code> at the beginning of the command line, where <code>&lt;path&gt;</code> is the path to the VM directory.</p> <p>You can modify the <code>options.default</code> file to include any options that you want to specify for your application instead of entering these options on the command line. For more information about the path and construction of the file, see -Xoptionsfile.</p> </li> <li> <p>Options can be specified in an executable JAR file by using the META-INF/MANIFEST.MF file. Options are placed in the main section in a header named <code>IBM-Java-Options</code>. Only one <code>IBM-Java-Options</code> header is permitted, but the header can contain multiple options, separated by spaces. A long sequence of options can be split using a header continuation but are treated as a single line.</p> <p>Example manifest file:</p> <pre><code>Manifest-Version: 1.0\nClass-Path: .\nMain-Class: HelloWorld\nIBM-Java-Options: -Xshareclasses:name=mycache,nonfa\n tal,cacheDirPerm=1000 -Dproperty=example -Da.long.system.pro\n perty=\"this is a long system property value to\n  demonstrate long VM arguments\n in the manifest file\"\n</code></pre> <p>This example manifest file is parsed as the following string:</p> <pre><code>-Xshareclasses:name=mycache,nonfatal,cacheDirPerm=1000\n-Dproperty=example\n-Da.long.system.property=this is a long system property value to\ndemonstrate long VM arguments in the manifest file\n</code></pre> <p>Options specified in the manifest file are subject to the same restrictions as options files. For more information, see the -Xoptionsfile topic in the user guide.</p> </li> <li> <p>Environment variables that are described in OpenJ9 environment variables are translated into command-line options. For example, the following environment variable adds the parameter <code>-Xrs</code> to the list of arguments:</p> <ul> <li> <p>On Windows\u2122 systems:</p> <pre><code>set IBM_NOSIGHANDLER=&lt;non_null_string&gt;\n</code></pre> </li> <li> <p>On AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae systems:</p> <pre><code>export IBM_NOSIGHANDLER=&lt;non_null_string&gt;\n</code></pre> </li> </ul> </li> <li> <p>The <code>OPENJ9_JAVA_OPTIONS</code> environment variable. You can set command-line options using this environment variable. The options that you specify with this environment variable are added to the command line when a VM starts in that environment. The environment variable can contain multiple blank-delimited argument strings, but must not contain comments. For example:</p> <ul> <li> <p>On Windows systems:</p> <pre><code>set OPENJ9_JAVA_OPTIONS=-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\n</code></pre> </li> <li> <p>On AIX, Linux, macOS, and z/OS systems:</p> <pre><code>export OPENJ9_JAVA_OPTIONS=\"-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\"\n</code></pre> </li> </ul> <p> Note: The environment variable <code>JAVA_TOOL_OPTIONS</code> is equivalent to <code>OPENJ9_JAVA_OPTIONS</code> and is available for compatibility with JVMTI. The equivalent <code>IBM_JAVA_OPTIONS</code> environment variable is deprecated and will be removed in a future release.</p> </li> <li> <p>Options that are specified on the command line. For example:</p> <pre><code>java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass\n</code></pre> <p>The Java launcher adds some automatically generated arguments to this list, such as the names of the main class.</p> </li> <li> <p>The <code>_JAVA_OPTIONS</code> environment variable. You can override previous options using this environment variable. The options that you specify with this environment variable are added to the end of the command line when a VM starts in that environment. The environment variable can contain multiple blank-delimited argument strings, but must not contain comments. For example:</p> <ul> <li> <p>On Windows systems:</p> <pre><code>set _JAVA_OPTIONS=-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\n</code></pre> </li> <li> <p>On AIX, Linux, macOS, and z/OS systems:</p> <pre><code>export _JAVA_OPTIONS=\"-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\"\n</code></pre> </li> </ul> </li> </ol> <p>You can also use the <code>-Xoptionsfile</code> parameter to specify VM options. This parameter can be used on the command line, or as part of the <code>OPENJ9_JAVA_OPTIONS</code> environment variable. The contents of an option file are expanded in place during startup. For more information about the structure and contents of this type of file, see -Xoptionsfile.</p> <p>To troubleshoot startup problems, you can check which options are used by the OpenJ9 VM. Append the following command-line option, and inspect the Java core file that is generated:</p> <pre><code>-Xdump:java:events=vmstart\n</code></pre> <p>Here is an extract from a Java core file that shows the options that are used:</p> <pre><code>    2CIUSERARG               -Xdump:java:file=/home/test_javacore.txt,events=vmstop\n    2CIUSERARG               -Dtest.cmdlineOption=1\n    2CIUSERARG               -XXallowvmshutdown:true\n    2CIUSERARG               -Xoptionsfile=test1.test_options_file\n</code></pre>"},{"location":"configuring/","title":"Configuring your system","text":""},{"location":"configuring/#configuring-your-system","title":"Configuring your system","text":"<p>Configuring your local system can help you optimize the runtime environment for your Java application. Options include setting operating system environment variables and configuring system resources so that Eclipse OpenJ9\u2122 can exploit the underlying operating system and hardware capabilities.</p> <p>When you install a Java\u2122 runtime environment on your system you can set the PATH environment variable so that the operating system can find the Java programs and utilities to run your application. To tell your application where to find user classes, you can use the -cp option or set the CLASSPATH environment variable. However, if you set CLASSPATH globally, all invocations of Java are affected. How to set these environment variables is covered in many publications about Java, such as The Java Tutorials: PATH and CLASSPATH.</p> <p>On some systems, a further environment variable might be required if your application requires shared libraries but does not specify their exact location. You can set the following environment variables to specify the directory location of the shared libraries, although setting a global value affects all invocations of Java:</p> <ul> <li>LIBPATH (AIX\u00ae and z/OS\u00ae)</li> <li>LD_LIBRARY_PATH (Linux\u00ae)</li> <li>DYLD_LIBRARY_PATH (macOS\u00ae)</li> <li>PATH (Windows\u00ae)</li> </ul> <p> Although most Java applications should run without changing anything on the underlying system, a unique pre-requisite exists for AIX systems on OpenJDK version 11 and later; you must have the 16.1 XL C++ Runtime installed. </p>"},{"location":"configuring/#setting-resource-limits-aix-linux-and-macos","title":"Setting resource limits (AIX, Linux, and macOS)","text":"<p>The operating system sets resource limits for a shell, and to processes started by the shell, to ensure that a single process cannot consume all available resources. However, these limits can affect certain operations that might need to run for a Java application, such as producing a dump file.</p>"},{"location":"configuring/#setting-ulimit-values","title":"Setting ulimit values","text":"<p>Some resource limits are controlled by the ulimit command. A soft limit is the value set by the kernel for a resource and a hard limit imposes a maximum value on the soft limit. A privileged process can change either limit, but an unprivileged process can change only its soft limit (between 0 and the hard limit) or irreversibly lower its hard limit. To see the current limits set for a system, run <code>ulimit -a</code>. The output is similar to the following example:</p> <pre><code>core file size          (blocks, -c) 0\ndata seg size           (kbytes, -d) unlimited\nfile size               (blocks, -f) unlimited\nmax locked memory       (kbytes, -l) unlimited\nmax memory size         (kbytes, -m) unlimited\nopen files                      (-n) 256\npipe size            (512 bytes, -p) 1\nstack size              (kbytes, -s) 8192\ncpu time               (seconds, -t) unlimited\nmax user processes              (-u) 2784\nvirtual memory          (kbytes, -v) unlimited\n</code></pre> <p>To show hard limits, use <code>ulimit -Ha</code>.</p> <p>You can change limits for specific resources on a temporary basis by running the ulimit command. Alternatively, you can store limit settings in a configuration file, which is <code>/etc/security/limits</code> for AIX or <code>etc/security/limits.conf</code> for Linux. For more information about configuring resource limits, refer to the documentation for your operating system.   </p> <p>The main use case for changing <code>ulimit</code> resources is when enabling a system dump to ensure that all the required data can be collected for analysis. For more information, see Enabling a full system dump.</p>"},{"location":"configuring/#setting-shared-memory-values","title":"Setting shared memory values","text":"<p>Another use case for changing resource limits is to ensure that there is sufficient shared memory allocated for class data sharing. By default, the shared classes cache consists of memory-mapped files that are created on disk and persist when the system is restarted. If you choose to use non-persistent caches by setting the <code>-Xshareclasses:nonpersistent</code> option, caches are not retained on startup and are allocated by using the System V IPC shared memory mechanism.</p> <ul> <li>On AIX systems, the kernel dynamically adjusts the shared memory settings as required. No special configuration is required.</li> <li>On Linux systems, the SHMMAX setting limits the amount of shared memory that can be allocated, which affects the shared classes cache size. You can find the value of SHMMAX for your system in the <code>/proc/sys/kernel/shmmax</code> file. For non-persistent caches, set this value to an appropriate size for your applications. To make these changes permanent, edit <code>/etc/sysctl.conf</code> and reboot your system.</li> <li>On macOS systems, you must set kern.sysv.shmmax and kern.sysv.shmall when using a nonpersistent cache. Modify the settings in your <code>/etc/sysctl.conf</code> file and reboot your system. To check the value, run <code>sysctl kern.sysv.shmmax</code>.</li> </ul> <p> Note: The virtual address space of a process is shared between the shared classes cache and the Java heap. Increasing the maximum size for the shared classes cache might reduce the size of the Java heap that you can create.</p> <p>Shared memory limits are also important when configuring large page memory allocation on Linux systems. For more information, see Configuring large page memory allocation: Linux systems.</p>"},{"location":"configuring/#setting-resource-limits-zos","title":"Setting resource limits (z/OS)","text":"<p>Resource limits imposed by z/OS might affect Java operations. To learn how these resource limits are set, see Customizing the BPXPRMxx member of SYS1.PARMLIB.</p> <p>The OpenJ9 class data sharing feature is implemented by using shared memory segments on z/OS. Special consideration should be given to the following parameters that relate to the shared memory and IPC semaphore settings:</p> <ul> <li>IPCSHMSPAGES</li> <li>IPCSHMMPAGES</li> <li>IPCSHMNSEGS</li> </ul> <p>Incorrect or suboptimal settings might prevent shared classes from working or impact performance. By default, the VM attempts to create a 16 MB cache on Java 8 and a 300 MB cache on Java 11 and later. If you set a cache size for your application by specifying the <code>-Xscmx</code> option on the command line, the VM rounds the value up to the nearest megabyte. Ensure that the value set for IPCSHMMPAGES takes this adjustment into consideration.</p> <p>To see the current settings, enter the following z/OS operator command:</p> <pre><code>D OMVS,O\n</code></pre> <p>The suggested minimum values for Java applications are shown in the following table:</p> Parameter Value MAXPROCSYS 900 MAXPROCUSER 512 MAXUIDS 500 MAXTHREADS 10000 MAXTHREADTASKS 5000 MAXASSIZE 2147483647 MAXCPUTIME 2147483647 MAXMMAPAREA 40960 IPCSHMSPAGES 262144 IPCSHMMPAGES 25600 IPCSHMNSEGS 10 IPCSEMNIDS 500 IPCSEMNSEMS 1000 SHRLIBRGNSIZE 67 108 864 <p> Note: The number of threads that can be created by a Java process is limited by the lower of the two values for MAXTHREADS and MAXTHREADSTASKS.</p> <p>You can change these settings dynamically without re-IPLing the system. For example, to set MACPROCUSER to 256, run <code>SETOMVS MAXPROCUSER=256</code></p> <p>z/OS uses region sizes to determine the amount of storage available to running programs. For a Java runtime environment, the  region size must be sufficiently large to avoid storage related error messages or abends. Rather than restricting region size, allow the VM to use what it needs. Region size can be affected by one of the following parameters: JCL REGION, BPXPRMxx MAXASSIZE, the RACF OMVS segment ASSIZEMAX, or IEFUSI (Step initiation exit).</p> <p>SHRLIBRGNSIZE controls how much storage is reserved in each address space for mapping shared DLLs that have the +l extended attribute set. If this storage space is exceeded, DLLs are loaded into the address space instead of using a single copy of z/OS UNIX System Services storage that is shared between the address spaces. The z/OS command D OMVS,L shows the SHRLIBRGNSIZE size and peak usage. If this size is set to a much higher value than is needed, the Java application might have problems acquiring native storage. These problems can cause a z/OS abend, such as <code>878-10</code>, or a Java <code>OutOfMemoryError</code>.</p>"},{"location":"configuring/#configuring-language-environment-runtime-options","title":"Configuring Language Environment runtime options","text":"<p>Language Environment\u00ae runtime options affect performance and storage usage. These options can be optimized for your application.</p> <p>Runtime options are typically embedded in programs by using #pragma runopts settings. In many cases, these options provide suitable default values that are known to produce good performance results. However, these options can be overridden to tune the runtime environment of your application.</p> <p>On 64-bit z/OS systems, the following runtime options affect Java applications:</p> <ul> <li>HEAP64: Controls allocation of the user heap. A suggested starting point for an override is HEAP64(512M,4M,KEEP,16M,4M,KEEP,0K,0K,FREE).</li> <li>HEAPPOOLS64: Used to manage Java heap storage above the 2 G bar. The Java USS launcher sets HEAPPOOLS64(ALIGN) for more optimal management of multi-threaded applications. Other Java launchers might have different settings. Before you set an override for HEAPPOOLS64, use RPTOPTS(ON) to confirm the active settings for your environment and RPTSTG(ON) to review storage usage and tuning recommendations. Note that the host product might have already set cell sizes and numbers that are known to produce good performance.</li> <li>STACK64: Controls the allocation and management of stack storage. A suggested default is STACK64(1M,1M,128M).</li> <li>THREADSTACK64: Controls the allocation of thread-level stack storage for both the upward and downward-growing stack. A suggested default is THREADSTACK64(OFF,1M,1M,128M).</li> </ul> <p>A suitable MEMLIMIT value is also required. The OpenJ9 VM requirement is the sum of the following amounts:</p> <ul> <li>User heap storage required by the VM and native libraries, as controlled by HEAP64 (minimum 512 M) settings.</li> <li>User stack storage (3 MB multiplied by the expected number of concurrent threads), as controlled by STACK64 settings.</li> <li><code>-Xmx</code> largest expected VM heap size.</li> <li>The JIT data cache maximum size.</li> <li>The JIT code cache maximum size, if RMODE64 is supported.</li> </ul> <p> Note: If you intend to use the Concurrent Scavenge mode of the default Generational Concurrent (<code>gencon</code>) garbage collection policy by using hardware-based support, the virtual storage used might exceed the Java maximum heap size. Set the z/OS memory limit to a larger value than the maximum heap size. For more information, see <code>-Xgc:concurrentScavenge</code>.</p> <p>The following guides are available to help you configure Language Environment runtime options and callable services:</p> <ul> <li>See z/OS Language Environment Programming Guide for guidance on how to override the default options. Use RPTOPTS (ON) to write the options that are in effect to stderr on termination.</li> <li>See z/OS Language Environment Programming Reference for a full list of the available runtime options.</li> <li>See z/OS Language Environment Debugging Guide for tuning guidance by using RPTSTG (ON).</li> </ul> <p> Warning: Changing the runtime options can often degrade performance.</p>"},{"location":"configuring/#configuring-large-page-memory-allocation","title":"Configuring large page memory allocation","text":"<p>If your application allocates a large amount of memory and frequently accesses that memory, you might be able to improve performance by enabling large page support on your system.</p> <p>Some Linux kernels implement Transparent HugePage Support (THP), which automates the provision of large pages to back virtual memory, as described in Linux systems. Alternatively, you can enable large page support by setting the <code>-Xlp:objectheap</code> and <code>-Xlp:codecache</code> options on the command line when you start your application. These options have the following effects:</p> <ul> <li>The <code>-Xlp:objectheap</code> option requests that the Java object heap is allocated by using large pages.</li> <li>The <code>-Xlp:codecache</code> option requests that the JIT code cache is allocated by using large pages.</li> </ul> <p>You must also enable large pages on your local system. This process differs according to the operating system.</p>"},{"location":"configuring/#aix-systems","title":"AIX systems","text":"<p>AIX supports large page sizes of 64 KB and 16 MB, and a huge page size of 16 GB depending on the underlying system P hardware. To determine which page sizes are supported on a particular system, run <code>pagesize -a</code>.</p> <p>To use large pages to back an application's data and heap segments, specify the LDR_CNTRL environment variable. You can set different page sizes for different purposes. The following variables can be used:</p> <ul> <li>TEXTPSIZE: Page size to use for text</li> <li>STACKPSIZE: Page size to use for stacks</li> <li>DATAPSIZE: Page size to use for native data or HEAP64</li> </ul> <p>The following example sets 4 KB for text and 64 KB for stack, native data, and heap areas:</p> <pre><code>LDR_CNTRL=TEXTPSIZE=4K@STACKPSIZE=64K@DATAPSIZE=64K\n</code></pre> <p>For more information, including support considerations, see Large pages and Multiple page size support in the AIX documentation.</p> <p>The 16 MB and 16 GB page sizes, which are intended for very high performance environments, require special user permissions. You must also configure the number of pages that you require, which cannot be adjusted on demand. For 16 MB large pages, you set the number of large pages by using the <code>vmo</code> command. For 16 GB huge pages you must define the number of pages by using the hardware management console. For more information, see Page sizes for very high-performance environments in the AIX documentation.</p>"},{"location":"configuring/#linux-systems","title":"Linux systems","text":"<p>Large pages are typically referred to as huge pages on Linux systems. To configure huge page memory allocation, the kernel must support huge pages. If huge pages are supported, the following lines are present in the /proc/meminfo file:</p> <pre><code>HugePages_Total:    \nHugePages_Free:     \nHugepagesize:     \n</code></pre> <p>If these lines do not exist, update your Linux kernel. If <code>HugePages_Total</code> has a value of <code>0</code>, huge pages are available, but not enabled. To enable huge pages, add the following line to your /etc/sysctl.conf file and reload the configuration by running <code>sysctl -p</code>:</p> <pre><code>vm.nr_hugepages=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of huge pages required.</p> <p>Configure the number of huge pages that you require at boot time to ensure that the VM has access to sufficient contiguous pages. The following kernel parameters must be set appropriately for your system:</p> <ul> <li>SHMMAX: The maximum size of the shared memory segment (bytes).</li> <li>SHMALL: The total amount of shared memory in the system (bytes or pages).</li> </ul> <p>The user running the Java process must either be ROOT or have permissions to use huge pages. For the appropriate permissions, the user must be a member of a group that has its group identifier (gid) stored in /proc/sys/vm/hugetlb_shm_group. The locked memory limit must also be increased to at least the size of the Java heap by using the ulimit -l command.</p> <p>Where huge page support is available, the following default sizes apply for the object heap:</p> <ul> <li>Linux on x86: 2 MB</li> <li>Linux on IBM Power Systems: Varies depending on kernel version, check <code>/proc/meminfo</code></li> <li>Linux on IBM Z: 1 MB</li> </ul> <p>Transparent HugePage Support (THP) is an automated mechanism of using huge pages to back virtual memory. On Linux kernels that support THP, it is typically enabled by default with the madvise option and can be relied on to provide huge pages as required without any user configuration. To disable THP for your application, use the OpenJ9 <code>-XX:-TransparentHugePage</code> option on the command line. To disable THP system-wide, change the sysfs boot time defaults with the command <code>transparent_hugepage=never</code>. For more information about THP see Transparent HugePage Support.</p>"},{"location":"configuring/#windows-systems","title":"Windows systems","text":"<p>On Windows systems, large pages are typically 2 MB in size. To use large pages, the VM user must have the Windows Lock pages in memory setting enabled in the Local Security Policy. Applications must also be run with Admin privileges in order to use large page memory allocations.</p> <p>For more information, see the following resources from Microsoft:</p> <ul> <li>Large page support</li> <li><code>GetLargePageMinimum</code> function (<code>memoryapi.h</code>)</li> </ul>"},{"location":"configuring/#zos-systems","title":"z/OS systems","text":"<p>When available, 1 MB pageable pages are the default size for the object heap and the code cache. Other page sizes are available for the object heap, depending on the system architecture as shown in the following table:</p> Large page size System architecture required <code>-Xlp:codecache</code> <code>-Xlp:objectheap</code> 2 GB nonpageable IBM zEnterprise EC12 processor or later Not supported Supported (64-bit VM only) 1 MB nonpageable System z10 processor or later Not supported Supported (64-bit VM only) 1 MB pageable IBM zEnterprise EC12 processor or later (see Note) Supported Supported <p> Note: The Flash Express feature (#0402) helps avoid demoting 1 MB pageable pages to 4 KB pages when there is system paging activity.</p> <p>If a particular page size cannot be allocated, a smaller page size is attempted, in descending order. For example, if 2 GB nonpageable pages are requested but not available, the VM tries to allocate 1MB nonpageable pages. If 1 MB nonpageable pages are not available, the VM tries to allocate 1MB pageable pages. If large pages are not available, 4 KB pages are allocated.</p> <p>If you want to use nonpageable large pages for the object heap, a system programmer must configure z/OS for nonpageable large pages in the IEASYSxx parmlib member. Users who require large pages must also be authorized to the IARRSM.LRGPAGES resource in the RACF FACILITY class with read authority.</p> <p>Use the following z/OS system command to show large page usage for an LPAR:</p> <pre><code>MODIFY AXR,IAXDMEM\n</code></pre> <p>For more information, see Displaying real storage memory statistics in the z/OS product documentation.</p> <p>For usage information, including examples, see <code>-Xlp:objectheap</code>.</p>"},{"location":"configuring/#configuring-dynamic-lpar-support-aix-only","title":"Configuring Dynamic LPAR support (AIX only)","text":"<p>Dynamic logical partitioning (DLPAR) provides a mechanism to add or remove system resources, such as memory or CPU, to or from the operating system in a logical partition without rebooting. Changing these resources dynamically can have an impact on Java applications that are running on the LPAR.</p> <p>To enable an application to respond to DLPAR events, you can use OpenJ9 MXBean extensions to the <code>java.lang.management</code> API. The following classes are available in the <code>com.ibm.lang.management</code> package:</p> <ul> <li><code>AvailableProcessorsNotificationInfo</code>: Use to listen for changes to the number of available processors.</li> <li><code>ProcessingCapacityNotificationInfo</code>: Use to listen for changes to processing capacity.</li> <li><code>TotalPhysicalMemoryNotificationInfo</code>: Use to listen for changes to the total amount of physical memory that is available.</li> </ul> <p>These extensions can listen for events and trigger any necessary adjustments to the runtime environment. For example, if a Java VM is running in an LPAR with 2GB of memory, but the available memory might be adjusted between 1GB and 8GB, you might set the following options for the Java heap at run time:</p> <pre><code>\u2013Xms1g \u2013Xsoftmx2g \u2013Xmx8g\n</code></pre> <p>This command-line string sets an initial heap size of 1 GB, a soft (adjustable) maximum heap size of 2 GB, and a maximum heap size of 8 GB. You can then use the <code>MemoryMXBean</code> API to dynamically respond to changes in memory resources. The following classes can be used:</p> <ul> <li><code>getMaxHeapSize()</code>: Query the maximum heap size.</li> <li><code>isSetMaxHeapSizeSupported()</code>: Query whether the VM can support dynamic updates.</li> <li><code>setMaxHeapSize()</code>: Adjust the maximum heap size.</li> </ul> <p>For more information about the <code>com.ibm.lang.managment</code> package, which extends the <code>jdk.management</code> module, see the API documentation.</p>"},{"location":"criusupport/","title":"CRIU support","text":""},{"location":"criusupport/#criu-support","title":"CRIU support","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p> Notes:</p> <ul> <li>Support for the Checkpoint/Restore In Userspace (CRIU) tool is currently provided as a technical preview in container environments. CRIU support is available for the customized CRIU version that is packaged with the Semeru container image. This preview is supported for use in production environments, however, all APIs and command-line options are subject to change.</li> <li>CRIU support is not available on OpenJDK 20 in version 0.39.0 release.</li> </ul> <p>In OpenJ9, the CRIU support includes an API that you can use to stop the VM at a checkpoint, save its state, and then run the VM from the point where it was stopped. The period of time between when the VM starts and when the application takes a checkpoint is referred to as the checkpoint phase. The application writes the VM state that was saved at the checkpoint to one or more image files. The saved state includes memory pages, methods, file systems, processes, and network connections. You can restore the VM from these files multiple times from the same point and in multiple environments.</p> <p>Because the checkpoint image files have the live state of the VM that is used to restore the VM in different systems, they should not contain cryptographically-sensitive security data. If the image files contain sensitive security data, the security components are vulnerable to exploitation even if you don't move the image files between systems. The CRIU technical preview introduces the <code>CRIUSECProvider</code> security provider, which provides the following limited set of security services: <code>MessageDigest</code> and <code>SecureRandom</code>. When you enable CRIU support, all existing security providers are removed from the security provider list during the checkpoint phase and <code>CRIUSECProvider</code> is added. When you restore the VM in the nonportable restore mode (<code>-XX:+CRIURestoreNonPortableMode</code>), <code>CRIUSECProvider</code> is removed from the security provider list and the previous security providers are added back again.</p> <p>When the VM starts from the saved point instead of the beginning, the VM startup time improves.</p>"},{"location":"criusupport/#enabling-criu-support","title":"Enabling CRIU support","text":"<p>CRIU support is not enabled by default. You must enable it by specifying the <code>-XX:+EnableCRIUSupport</code> command-line option when you start your application.</p>"},{"location":"criusupport/#configuring-criu-support","title":"Configuring CRIU support","text":"<p>You can access the OpenJ9 CRIU support capabilities by specifying different options. The VM enables the addition of VM options on restore through the <code>CRIUSupport.registerRestoreOptionsFile</code> API and environment variables through the <code>CRIUSupport.registerRestoreEnvVariables</code> API. <code>OPENJ9_RESTORE_JAVA_OPTIONS</code> is a special environment variable for adding the VM options on restore.</p> <p>There are new options that work at checkpoint as well as at restore and some new options that work at restore only. There are also some existing options that work on restore but some of them behave differently.</p>"},{"location":"criusupport/#new-options","title":"New options","text":"<p>You can use the following options only during the checkpoint phase:</p> <ul> <li><code>-XX:[+|-]CRIURestoreNonPortableMode</code>: Specifies whether the JIT and AOT compiler generates nonportable compiled code on restore.</li> <li><code>-XX:CheckpointGCThreads</code>: Reduces the number of garbage collection (GC) threads that exist when you create a checkpoint image, to speed up the later restoration of the checkpoint image.</li> <li><code>-Dorg.eclipse.openj9.criu.ImmutableEnvVars</code>: Adds the environment variables in the <code>immutableEnvvars</code> list. The VM can detect these variables during the checkpoint and restore phases.</li> </ul> <p>You can use the following options only when you restore a VM. If you specify these options when you start the VM (during the checkpoint phase), the VM does not start:</p> <ul> <li><code>-XX:[+|-]IgnoreUnrecognizedRestoreOptions</code>: Specifies whether a restored VM ignores unrecognized command-line options and starts anyway or throws a <code>JVMRestoreException</code> error and does not start.</li> <li><code>-Xshareclasses:disableOnRestore</code>: Disables further use of the shared classes cache (SCC) on restore.</li> <li><code>-Xrs:onRestore</code> and <code>-Xrs:syncOnRestore</code>: Disables signal handling on restore. These options behave in a similar way to the existing <code>-Xrs</code> and <code>-Xrs:sync</code> options. However, there are differences because some signal handlers might exist when a checkpoint is taken, and remain after restoration.</li> </ul>"},{"location":"criusupport/#existing-options","title":"Existing options","text":"<p>Of the existing command-line options, only the following are supported when you run a restored VM and some of these options have changed behavior:</p> Options Changed behavior <code>-Xverbosegclog</code> <code>-XcompilationThreads</code> <code>-XsamplingExpirationTime</code> <code>-XX:[+|-]PrintCodeCache</code> <code>-Xtrace</code> If you specify an <code>output</code> file before a checkpoint and another <code>output</code> file for restore, both the files are written according to the <code>-Xtrace</code> options associated with the <code>output</code> file. <code>-Xdump</code> Dump events that are triggered on exception throws or catches cannot be enabled on restore. <code>-Xgcthreads</code> This option is ignored if the number of GC threads is less than the checkpoint GC thread count. <code>-Xjit</code> If <code>-Xint</code> or <code>-Xnoaot</code> and <code>-Xnojit</code> are specified pre-checkpoint, the compiler remains disabled post-restore. <code>-Xaot</code> If <code>-Xnoaot</code> is specified pre-checkpoint, then specifying <code>-Xaot</code> post-restore does not enable AOT compilation or load. <code>-Xjit</code> / <code>-Xaot</code> You can specify the following parameters with the <code>-Xjit</code> and <code>-Xaot</code> options when you run a restored VM:<code>count</code>: Applies only to new methods; existing interpreted methods will not have their counts that are updated. <code>limit</code>, <code>limitFile</code>, <code>exclude</code>: Invalidates the existing compiled methods that do not match the filters. The filters are then enforced for all future JIT and AOT compilations. <code>loadLimit</code>, <code>loadLimitFile</code>, <code>loadExclude</code>: Applies only to future AOT loads; does not impact existing compiled methods. <code>verbose</code>: Effective post-restore; does not override verbose options specified pre-checkpoint. <code>vlog</code>: A vlog file is opened post-restore. If this option was specified pre-checkpoint, the old file is closed first. <code>-Xnoaot</code> Prevents AOT compilations and loads; does not affect the existing compiled methods and does not prevent JIT compilation. <code>-Xnojit</code> Invalidates all existing compiled methods and prevents JIT compilations; does not prevent AOT compilations and loads. <p>If you specify an unsupported option, the VM throws a <code>JVMRestoreException</code> error by default. If you specify the <code>-XX:+IgnoreUnrecognizedRestoreOptions</code> option, the VM does not throw any exception and just ignores the unsupported option.</p> <p>For more more information on CRIU support, see the <code>openj9.criu</code> module in your OpenJ9 JDK version (OpenJDK 11 and later) API documentation.</p> <p> Restrictions:</p> <ul> <li>If an <code>-Xtrace</code> or JIT log output file is specified on startup and doesn\u2019t exist on restore, or is modified in any way between checkpoint and restore, the restore operation fails.</li> <li>Method tracing might not work consistently if a method is compiled pre-checkpoint.</li> <li>The Java\u2122 heap is configured at startup. The VM detects the available memory on the system and sizes the heap based on it. With the CRIU support, this means that the size of the Java heap (<code>-Xms</code>, <code>-Xmx</code>) and the respective heap regions, such as nursery and tenure at checkpoint will be same on restore. If a checkpoint is taken in a container with no memory limits and then restored in a container with memory limits, the restored VM instance does not detect the memory limits.</li> <li>There is currently no support for changing locales. A checkpoint must be taken with the intended target locale on restore for it to function properly.</li> </ul>"},{"location":"criusupport/#see-also","title":"See Also","text":"<ul> <li>CRIU</li> <li>Fast JVM startup with OpenJ9 CRIU Support</li> <li>Getting started with OpenJ9 CRIU Support</li> <li>OpenJ9 CRIU Support: A look under the hood</li> <li>OpenJ9 CRIU Support: A look under the hood\u202f(part II)</li> </ul>"},{"location":"d_jvm_commands/","title":"Using System properties","text":""},{"location":"d_jvm_commands/#using-system-property-command-line-options","title":"Using system property command-line options","text":"<p>Java\u2122 system properties determine the environment in which a Java program runs by starting a Java virtual machine with a set of values. You can choose to use the default values for Java system properties or you can specify values for them by adding parameters to the command line when you start your application.</p> <p>To set a system property from the command line, use:</p> <pre><code>java -D&lt;property_name&gt;=&lt;value&gt; &lt;program_name&gt;\n</code></pre> <p>For example, to specify the UTF-8 file encoding for your application <code>MyProgram</code>, use:</p> <pre><code>java -Dfile.encoding=UTF-8 MyProgram\n</code></pre>"},{"location":"dcomibmenableclasscaching/","title":"-Dcom.ibm.enableClassCaching","text":""},{"location":"dcomibmenableclasscaching/#-dcomibmenableclasscaching","title":"-Dcom.ibm.enableClassCaching","text":"<p>Setting this property to <code>true</code> enables caching of the Latest User Defined Class Loader (LUDCL).</p>"},{"location":"dcomibmenableclasscaching/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableClassCaching=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenableclasscaching/#explanation","title":"Explanation","text":"<p>By reducing repeated lookups, Java\u2122 applications that use deserialization extensively can see a performance improvement.</p>"},{"location":"dcomibmenableclasscaching/#see-also","title":"See also","text":"<ul> <li> Java Object Serialization Specification</li> </ul>"},{"location":"dcomibmenablelegacydumpsecurity/","title":"-Dcom.ibm.enableLegacyDumpSecurity","text":""},{"location":"dcomibmenablelegacydumpsecurity/#-dcomibmenablelegacydumpsecurity","title":"-Dcom.ibm.enableLegacyDumpSecurity","text":"<p>To improve security, the security checks in the certain <code>com.ibm.jvm.Dump</code> APIs are now enabled by default, when the <code>SecurityManger</code> is enabled. Use this system property to turn off security checking for these APIs.</p>"},{"location":"dcomibmenablelegacydumpsecurity/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableLegacyDumpSecurity=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenablelegacydumpsecurity/#explanation","title":"Explanation","text":"<p>Security checking is enabled in the following APIs:</p> <ul> <li><code>com.ibm.jvm.Dump.JavaDump()</code></li> <li><code>com.ibm.jvm.Dump.HeapDump()</code></li> <li><code>com.ibm.jvm.Dump.SnapDump()</code></li> </ul>"},{"location":"dcomibmenablelegacydumpsecurity/#see-also","title":"See also","text":"<ul> <li>-Dcom.ibm.enableLegacyLogSecurity</li> <li>-Dcom.ibm.enableLegacyTraceSecurity</li> </ul>"},{"location":"dcomibmenablelegacylogsecurity/","title":"-Dcom.ibm.enableLegacyLogSecurity","text":""},{"location":"dcomibmenablelegacylogsecurity/#-dcomibmenablelegacylogsecurity","title":"-Dcom.ibm.enableLegacyLogSecurity","text":"<p>To improve security, the security checks in the certain <code>com.ibm.jvm.Log</code> APIs are now enabled by default, when the <code>SecurityManger</code> is enabled. Use this system property to turn off security checking for these APIs.</p>"},{"location":"dcomibmenablelegacylogsecurity/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableLegacyLogSecurity=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenablelegacylogsecurity/#explanation","title":"Explanation","text":"<p>Security checking is enabled in the following APIs:</p> <ul> <li><code>com.ibm.jvm.Log.QueryOptions()</code></li> <li><code>com.ibm.jvm.Log.SetOptions(String)</code></li> </ul>"},{"location":"dcomibmenablelegacylogsecurity/#see-also","title":"See also","text":"<ul> <li>-Dcom.ibm.enableLegacyDumpSecurity</li> <li>-Dcom.ibm.enableLegacyTraceSecurity</li> </ul>"},{"location":"dcomibmenablelegacytracesecurity/","title":"-Dcom.ibm.enableLegacyTraceSecurity","text":""},{"location":"dcomibmenablelegacytracesecurity/#-dcomibmenablelegacytracesecurity","title":"-Dcom.ibm.enableLegacyTraceSecurity","text":"<p>To improve security, the security checks in certain <code>com.ibm.jvm.Trace</code> APIs are now enabled by default, when the <code>SecurityManger</code> is enabled. Use this system property to turn off security checking for these APIs.</p>"},{"location":"dcomibmenablelegacytracesecurity/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableLegacyTraceSecurity=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenablelegacytracesecurity/#explanation","title":"Explanation","text":"<p>Security checking is enabled in the following APIs:</p> <ul> <li><code>com.ibm.jvm.Trace.set(String)</code></li> <li><code>com.ibm.jvm.Trace.snap()</code></li> <li><code>com.ibm.jvm.Trace.suspend()</code></li> <li><code>com.ibm.jvm.Trace.suspendThis()</code></li> <li><code>com.ibm.jvm.Trace.resume()</code></li> <li><code>com.ibm.jvm.Trace.resumeThis()</code></li> <li><code>com.ibm.jvm.Trace.registerApplication(String, String[])</code></li> </ul>"},{"location":"dcomibmenablelegacytracesecurity/#see-also","title":"See also","text":"<ul> <li>-Dcom.ibm.enableLegacyDumpSecurity</li> <li>-Dcom.ibm.enableLegacyLogSecurity</li> </ul>"},{"location":"dcomibmgpudisable/","title":"-Dcom.ibm.gpu.disable","text":""},{"location":"dcomibmgpudisable/#-dcomibmgpudisable","title":"-Dcom.ibm.gpu.disable","text":"<p> Restriction: This system property is supported only on Java\u2122 11 and later.</p> <p>If you have enabled GPU processing with <code>-Dcom.ibm.gpu.enable</code>, use this system property to turn off processing that can be offloaded to a graphics processing unit (GPU).</p>"},{"location":"dcomibmgpudisable/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.gpu.disable\n</code></pre>"},{"location":"dcomibmgpudisable/#explanation","title":"Explanation","text":"<p>Because establishing and completing communication with a GPU incurs an additional overhead, not all processing requirements benefit from being offloaded to the GPU. GPU processing is therefore disabled by default. However, if you have enabled GPU processing with <code>-Dcom.ibm.gpu.enable</code>, this property turns GPU processing off.</p>"},{"location":"dcomibmgpudisable/#see-also","title":"See also","text":"<ul> <li>Exploiting GPUs</li> <li>-Dcom.ibm.gpu.enable</li> <li>-Dcom.ibm.gpu.verbose</li> </ul>"},{"location":"dcomibmgpuenable/","title":"-Dcom.ibm.gpu.enable","text":""},{"location":"dcomibmgpuenable/#-dcomibmgpuenable","title":"-Dcom.ibm.gpu.enable","text":"<p> Restriction: This system property is supported only on Java\u2122 11 and later.</p> <p>Use this system property to control the type of processing that can be offloaded to a graphics processing unit (GPU) when processing requirements meet a specific threshold. This feature can improve the performance of certain Java functions.</p>"},{"location":"dcomibmgpuenable/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.gpu.enable=[all|sort]\n</code></pre> Setting Effect all Turns on GPU processing for all possible Java functions. sort Turns on GPU processing only for the Java <code>sort()</code> function. <p>By default, this property is not set.</p>"},{"location":"dcomibmgpuenable/#explanation","title":"Explanation","text":"<p>Because establishing and completing communication with a GPU incurs an additional overhead, not all processing requirements benefit from being offloaded to the GPU. When set, this property enables GPU processing for any array that meets a minimum size.</p>"},{"location":"dcomibmgpuenable/#see-also","title":"See also","text":"<ul> <li>Exploiting GPUs</li> <li>-Dcom.ibm.gpu.disable</li> <li>-Dcom.ibm.gpu.verbose</li> </ul>"},{"location":"dcomibmgpuverbose/","title":"-Dcom.ibm.gpu.verbose","text":""},{"location":"dcomibmgpuverbose/#-dcomibmgpuverbose","title":"-Dcom.ibm.gpu.verbose","text":"<p> Restriction: This system property is supported only on Java\u2122 11 and later.</p> <p>This system property can be used to help identify problems with graphics processing unit (GPU) processing.</p>"},{"location":"dcomibmgpuverbose/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.gpu.verbose\n</code></pre> <p>This property is not set by default.</p>"},{"location":"dcomibmgpuverbose/#explanation","title":"Explanation","text":"<p>When specified, this option generates verbose output to STDOUT, which can be piped to a file.</p>"},{"location":"dcomibmgpuverbose/#see-also","title":"See also","text":"<ul> <li>Exploiting GPUs</li> <li>-Dcom.ibm.gpu.disable</li> <li>-Dcom.ibm.gpu.enable</li> </ul>"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/","title":"-Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns","text":""},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#-dcomibmlangmanagementoperatingsystemmxbeaniscputime100ns","title":"-Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns","text":"<p>Changes the unit of the return value of the <code>OperatingSystemMXBean.getProcessCpuTime()</code> method.</p>"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns=[true|false]\n</code></pre> Setting Effect Default true Enable false Disable yes"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#explanation","title":"Explanation","text":"<p>The Oracle <code>java.lang.management</code> package includes MBean categories such as <code>Memory</code>, <code>OperatingSystem</code>, and <code>GarbageCollector</code>. The Eclipse OpenJ9\u2122 VM  provides additional MXBeans to extend the monitoring and management capabilities. For example, the <code>OperatingSystemMXBean</code>, which monitors operating system settings such as physical and virtual memory size, processor capacity, and processor utilization.</p> <p>The <code>OperatingSystemMXBean.getProcessCpuTime()</code> method returns a value in nanoseconds (10<sup>-9</sup> s), for compatibility with the <code>com.sun.management.OperatingSystemMXBean</code> and <code>UnixOperatingSystemMXBean</code> interfaces.</p> <p>In earlier VM releases, the return value was in hundreds of nanoseconds. If you want to revert to this behavior, set the <code>-Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns</code> property to <code>true</code>.</p> <p>The default value for this property is <code>false</code>.</p>"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#see-also","title":"See also","text":"<ul> <li>Monitoring and management API documentation </li> </ul>"},{"location":"dcomibmlangmanagementverbose/","title":"-Dcom.ibm.lang.management.verbose","text":""},{"location":"dcomibmlangmanagementverbose/#-dcomibmlangmanagementverbose","title":"-Dcom.ibm.lang.management.verbose","text":"<p>Enables verbose information from <code>java.lang.management</code> operations to be written to the output channel during VM operations.</p>"},{"location":"dcomibmlangmanagementverbose/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.lang.management.verbose\n</code></pre> <p>There are no options for this system property.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/","title":"-Dcom.ibm.oti.shared.SharedClassGlobalFilterClass","text":""},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#-dcomibmotisharedsharedclassglobalfilterclass","title":"-Dcom.ibm.oti.shared.SharedClassGlobalFilterClass","text":"<p>This system property applies a global filter to all non-bootstrap class loaders that share classes.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.oti.shared.SharedClassGlobalFilterClass=&lt;filter_class_name&gt;\n</code></pre> <p>This property is not set by default.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#explanation","title":"Explanation","text":"<p>A filter can be used to decide which classes are found and stored by a custom class loader in a shared classes cache. The filter is applied to a particular package by implementing the <code>SharedClassFilter</code> interface.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#see-also","title":"See also","text":"<ul> <li>The Java shared classes Helper API</li> <li>Shared classes Helper API package: <code>com.ibm.oti.shared</code></li> </ul>"},{"location":"dcomibmtoolsattachcommand_timeout/","title":"-Dcom.ibm.tools.attach.command_timeout","text":""},{"location":"dcomibmtoolsattachcommand_timeout/#-dcomibmtoolsattachcommand_timeout","title":"-Dcom.ibm.tools.attach.command_timeout","text":"<p>Specify the timeout for sending a command to the target VM after the initial attachment.</p>"},{"location":"dcomibmtoolsattachcommand_timeout/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.command_timeout=&lt;ms&gt;\n</code></pre> Setting Value Default <code>&lt;ms&gt;</code> [1 millisecond or greater] 0 milliseconds (no timeout)"},{"location":"dcomibmtoolsattachcommand_timeout/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachdirectory/","title":"-Dcom.ibm.tools.attach.directory","text":""},{"location":"dcomibmtoolsattachdirectory/#-dcomibmtoolsattachdirectory","title":"-Dcom.ibm.tools.attach.directory","text":"<p>Specify a different common directory for Attach API working files.</p>"},{"location":"dcomibmtoolsattachdirectory/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.directory=&lt;directory_name&gt;\n</code></pre> Setting Value Default <code>&lt;directory_name&gt;</code> [string] <code>.com_ibm_tools_attach</code> <p>To change the value for <code>directory_name</code>, specify a different directory name. If the directory does not exist, it is created. However, if a parent directory is specified, it must exist. The common directory must be on a local drive, not a network drive.</p>"},{"location":"dcomibmtoolsattachdirectory/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachdisplayname/","title":"-Dcom.ibm.tools.attach.displayName","text":""},{"location":"dcomibmtoolsattachdisplayname/#-dcomibmtoolsattachdisplayname","title":"-Dcom.ibm.tools.attach.displayName","text":"<p>Change the default display name for the target virtual machine.</p>"},{"location":"dcomibmtoolsattachdisplayname/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.displayName=&lt;my_display_name&gt;\n</code></pre> Setting Value Default <code>&lt;my_display_name&gt;</code> [string] The command line invocation used to start the application <p>To change the value for <code>&lt;my_display_name&gt;</code> that is recorded by an agent, enter a character string of your choice.</p>"},{"location":"dcomibmtoolsattachdisplayname/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachenable/","title":"-Dcom.ibm.tools.attach.enable","text":""},{"location":"dcomibmtoolsattachenable/#-dcomibmtoolsattachenable","title":"-Dcom.ibm.tools.attach.enable","text":"<p>Enable the Attach API for this application.</p>"},{"location":"dcomibmtoolsattachenable/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.enable=[yes|no]\n</code></pre> <p>On AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122 systems, the following default applies:</p> Value Effect Default yes Enable yes no Disable <p>On z/OS\u00ae systems, the following default applies:</p> Value Effect Default yes Enable no Disable yes"},{"location":"dcomibmtoolsattachenable/#explanation","title":"Explanation","text":"<p>A useful reference for information about the Java\u2122 Attach API can be found at http://docs.oracle.com/javase/8/docs/technotes/guides/attach/index.html. The following extract is taken from the Oracle documentation:</p> <p>The Attach API is an extension that provides a mechanism to attach to a Java virtual machine. A tool written in the Java Language, uses this API to attach to a target  virtual machine and load its tool agent into that virtual machine.</p> <p>A usage example is to late attach the IBM\u00ae Health Center agent to a virtual machine (VM) that is already running.</p> <p>The Eclipse OpenJ9\u2122 implementation of the Attach API is equivalent to the Oracle implementation. However, the OpenJ9 implementation cannot be used to attach to, or accept attach requests from, other VM implementations.</p>"},{"location":"dcomibmtoolsattachenable/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachid/","title":"-Dcom.ibm.tools.attach.id","text":""},{"location":"dcomibmtoolsattachid/#-dcomibmtoolsattachid","title":"-Dcom.ibm.tools.attach.id","text":"<p>Specify a different virtual machine (VM) identifier.</p>"},{"location":"dcomibmtoolsattachid/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.id=&lt;my_vm_ID&gt;\n</code></pre> Setting Value Default <code>&lt;my_vm_ID&gt;</code> [string] Target VM process ID <p>To change the VM identifier recorded by an agent, change the value for <code>&lt;my_vm_ID&gt;</code>. The string must start with an alphabetic character. The remaining characters must be alphanumeric or underscore. Case-sensitivity is system dependent. If the VM identifier is already in use, the attach API modifies it to create a unique value.</p>"},{"location":"dcomibmtoolsattachid/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachlogging/","title":"-Dcom.ibm.tools.attach.logging","text":""},{"location":"dcomibmtoolsattachlogging/#-dcomibmtoolsattachlogging","title":"-Dcom.ibm.tools.attach.logging","text":"<p>Enable logging for Attach API events.</p>"},{"location":"dcomibmtoolsattachlogging/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.logging=[yes|no]\n</code></pre> Value Effect Default yes Enable no Disable yes"},{"location":"dcomibmtoolsattachlogging/#explanation","title":"Explanation","text":"<p>Turn on tracing and logging of Attach API events to help diagnose problems. One timestamped log file is created for each Java\u2122 process in the current directory for the running JVM .</p>"},{"location":"dcomibmtoolsattachlogging/#see-also","title":"See also","text":"<ul> <li>Java Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachlogname/","title":"-Dcom.ibm.tools.attach.log.name","text":""},{"location":"dcomibmtoolsattachlogname/#-dcomibmtoolsattachlogname","title":"-Dcom.ibm.tools.attach.log.name","text":"<p>Specify the path and prefix for the log files.</p>"},{"location":"dcomibmtoolsattachlogname/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.log.name=&lt;path/prefix&gt;\n</code></pre> Setting Value Default <code>&lt;path/prefix&gt;</code> [string] VM process directory <p>By default, when <code>-Dcom.ibm.tools.attach.logging=true</code> is set, timestamped log files are written to the current directory for the running VM. Use the  <code>-Dcom.ibm.tools.attach.log.name</code> option to change the path and prefix for the logfiles.</p>"},{"location":"dcomibmtoolsattachlogname/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachshutdown_timeout/","title":"-Dcom.ibm.tools.attach.shutdown_timeout","text":""},{"location":"dcomibmtoolsattachshutdown_timeout/#-dcomibmtoolsattachshutdown_timeout","title":"-Dcom.ibm.tools.attach.shutdown_timeout","text":"<p>Specify a timeout before ending the Attach API wait loop thread.</p>"},{"location":"dcomibmtoolsattachshutdown_timeout/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.shutdown_timeout=&lt;ms&gt;\n</code></pre> Setting Value Default <code>&lt;ms&gt;</code> [1 millisecond or greater] 10000 milliseconds (10 seconds)"},{"location":"dcomibmtoolsattachshutdown_timeout/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachtimeout/","title":"-Dcom.ibm.tools.attach.timeout","text":""},{"location":"dcomibmtoolsattachtimeout/#-dcomibmtoolsattachtimeout","title":"-Dcom.ibm.tools.attach.timeout","text":"<p>Specify a time that an application should wait when attempting to connect to a target virtual machine (VM) before ending.</p>"},{"location":"dcomibmtoolsattachtimeout/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.timeout=&lt;ms&gt;\n</code></pre> Setting Value Default <code>&lt;ms&gt;</code> [501 milliseconds or greater] 120000 milliseconds (120 seconds) <p>If you specify a value of 500 milliseconds or lower, no connection attempt is made.</p>"},{"location":"dcomibmtoolsattachtimeout/#example","title":"Example","text":"<p>To timeout after 60 seconds, specify:</p> <p><code>-Dcom.ibm.tools.attach.timeout=60000</code></p>"},{"location":"dcomibmtoolsattachtimeout/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> </ul>"},{"location":"dfileencoding/","title":"-Dfile.encoding","text":""},{"location":"dfileencoding/#-dfileencoding","title":"-Dfile.encoding","text":"<p>Use this OpenJDK property to define the file encoding that is required.</p>"},{"location":"dfileencoding/#syntax","title":"Syntax","text":"<pre><code>    -Dfile.encoding=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [string] Unicode 3.0 standards where <code>&lt;value&gt;</code> defines the file encoding that is required."},{"location":"dfileencoding/#explanation","title":"Explanation","text":"<p>By default the GBK converter follows Unicode 3.0 standards. To force the GBK converter to follow Unicode 2.0 standards, use a value of <code>bestfit936</code>.</p>"},{"location":"diag_overview/","title":"Overview","text":""},{"location":"diag_overview/#diagnostic-data-and-tooling","title":"Diagnostic data and tooling","text":"<p>Eclipse OpenJ9\u2122 contains a broad range of diagnostic capabilities to help identify, isolate, and solve run time problems. These capabilities include dump files, verbose logs, and trace files, which are supported by a variety of diagnostic tools and interfaces.</p>"},{"location":"diag_overview/#dumps","title":"Dumps","text":"<p>Various types of dumps are produced by default in response to certain events, such as a GPF fault or an <code>OutOfMemoryError</code> exception. You can also trigger the production of dumps by using the <code>com.ibm.jvm.Dump</code> API or by specifying <code>-Xdump</code> options on the command line.</p> <p>All dumps are produced by dump agents, which are initialized when the OpenJ9 VM starts. Different dumps target different areas of the runtime environment. If you want to generate a dump to diagnose a particular type of problem, you need to understand what data the dump will provide. The following dumps are typically used for problem diagnosis:   </p> <ul> <li>Java dumps (<code>-Xdump:java</code>) contain information that relates to the OpenJ9 VM and the Java\u2122 application, such as the operating environment, locks, threads, hooks, shared classes, and class loaders.</li> <li>Heap dumps (<code>-Xdump:heap</code>) show the content of the Java heap.</li> <li>System dumps (<code>-Xdump:system</code>) contain a raw process image or address space of an application.  </li> </ul> <p>Other types of dump include binary JIT dumps, stack dumps, and snap dumps. For a complete list of dump agents and the diagnostic data they produce, see Dump agents.</p>"},{"location":"diag_overview/#verbose-log-files","title":"Verbose log files","text":"<p>Some components of OpenJ9 can also produce verbose output or log files to assist with problem determination.</p> <ul> <li> <p>Class data sharing provides a number of <code>-Xshareclasses</code> suboptions to provide detailed data about the content of a shared classes cache, cache I/O activity, and information about the Java Helper API (where used). For example, the <code>-Xshareclasses:printAllStats</code> suboption lists every class in chronological order with a reference to the location from which it was loaded. For more information, see -Xshareclasses.   </p> </li> <li> <p>Garbage collection operations can be analyzed by producing verbose output from the <code>-verbose:gc</code> standard option. This output can be redirected to a file by specifying the <code>-Xverbosegclog</code> option. Information can be obtained about GC initialization, stop-the-world processing, finalization, reference processing, and allocation failures. Even more granular information can be obtained with the -Xtgc option. For more information, see verbose GC logs.</p> </li> <li> <p>The JIT compiler provides verbose logging, which records all compiler operations. To find out how to enable logging, read the JIT troubleshooting content.</p> </li> <li> <p>Class loader operations can be analyzed by producing verbose output from the <code>-verbose:dynload</code> standard option, which shows detailed information as each class is loaded by the VM.</p> </li> </ul>"},{"location":"diag_overview/#trace-files","title":"Trace files","text":"<p>The OpenJ9 trace facility can be used to trace applications, Java methods, or internal JVM operations with minimal impact on performance. Trace is configured by using the -Xtrace command line option, which allows you to control what is traced and when.</p> <p>Trace data is produced in binary format and must be processed by the OpenJ9 trace formatter to convert it to a readable form. For more information, see Trace formatter.</p>"},{"location":"diag_overview/#diagnostic-tools","title":"Diagnostic tools","text":"<p>A number of diagnostic tools are available with OpenJ9 to assist with the analysis of dump and trace files.</p>"},{"location":"diag_overview/#dump-extractor","title":"Dump extractor","text":"<p>The dump extractor (<code>jpackcore</code>) supports a full analysis of core files on specific platforms by collecting key files from a system and packaging them into an archive along with a core dump. This archive file is extremely useful when reporting issues to the OpenJ9 community, helping to ensure a faster analysis and turnaround. For more information, see Dump extractor.</p>"},{"location":"diag_overview/#dump-viewer","title":"Dump viewer","text":"<p>Because system dumps are binary files, OpenJ9 provides a dump viewer tool (<code>jdmpview</code>) to analyze the contents. This tool can work with dumps from any platforms independently of a system debugger. For more information, see Dump viewer.</p>"},{"location":"diag_overview/#trace-formatter","title":"Trace formatter","text":"<p>The trace formatter tool converts binary trace point data in a trace file into a readable format for analysis. For more information, see Trace formatter.</p>"},{"location":"diag_overview/#option-builder","title":"Option builder","text":"<p>OpenJ9 contains an extensive set of command-line options to assist with problem diagnosis. Certain options are complex, containing many sub-options with numerous parameters. Whilst these offer a great degree of flexibility, the syntax can be difficult to construct. Option builder tools are available that provide a simple graphical user interface to help you construct your command-line argument. For more information, see Option builder.</p>"},{"location":"diag_overview/#hotspot-compatible-tools","title":"HotSpot-compatible tools","text":"<p>A number of tools are available for compatibility with the reference implementation. These tools are independently implemented by OpenJ9 but have similar functions, allowing users to migrate more easily. The available tools are listed in the Tools section.  </p> <p> Note: If you are already familiar with tools that are provided with HotSpot, see Switching to OpenJ9, which explains some of the differences you might encounter when using OpenJ9.</p>"},{"location":"diag_overview/#eclipse-marketplace-tools","title":"Eclipse marketplace tools","text":"<p>OpenJ9 provides support for a number of monitoring and diagnostic tools that can be found in the Eclipse marketplace. Each tool provides a graphical user interface to help you visualize data and, in some cases, can provide tuning or debugging recommendations.</p> <ul> <li>Health Center: Provides real-time monitoring of running applications with minimal overhead over the network. You can monitor a whole range of operations including, class loading, CPU usage, GC heap and pause times, I/O activity, lock contention, method trace, native memory usage, profiling, and live threads. For more information, read the Health Center documentation.</li> <li>Garbage Collection Memory Vizualizer (GCMV): Plots GC and native memory data over time. You can view and save data as a report, raw log, tabulated data, or in graphical format. The tool helps to diagnose problems such as memory leaks with data presented in various visual formats for analysis. Tuning recommendations are also provided. For more information, read the GCMV documentation.</li> <li>Eclipse Memory Analyzer\u2122: Examines the Java object heap to help find memory leaks or reduce memory consumption. Support is available for OpenJ9 via the DTFJ interface (Install from the Eclipse Help menu; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java). More information about Eclipse MAT can be found on the project website page.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, the Java VisualVM utility is functionally similar to Health Center.</p>"},{"location":"diag_overview/#interfaces","title":"Interfaces","text":""},{"location":"diag_overview/#jvm-tool-interface-jvmti","title":"JVM tool interface (JVMTI)","text":"<p>OpenJ9 supports the Java Virtual Machine Tool Interface (JVMTI) and provides extensions that allow JVMTI tools to obtain diagnostic information or trigger diagnostic operations in the VM. For more information, see Java Virtual Machine Tool Interface.</p>"},{"location":"diag_overview/#dtfj-interface","title":"DTFJ Interface","text":"<p>OpenJ9 includes the Diagnostic Tool Framework for Java (DTFJ) API. Custom applications can be written that use this API to access a wide range of information in a system dump or a Java dump. DTFJ can be used with the Eclipse Memory Analyzer tool (MAT) to examine the Java object heap for memory leaks and to reduce memory consumption. For more information, see Diagnostic Tool Framework for Java.</p>"},{"location":"diag_overview/#language-management-interface","title":"Language Management interface","text":"<p>OpenJ9 provides MXBean additions and extensions to the standard <code>java.lang.management</code> API, which enables you to use tools such as JConsole to monitor and manage your Java applications. For more information, see Language management interface.</p>"},{"location":"diag_overview/#jpda-tools","title":"JPDA tools","text":"<p>OpenJ9 is compliant with the Java Platform Debugging Architecture (JPDA), which means you can use any JPDA tool for diagnosis, including Eclipse JDT Debug.</p>"},{"location":"djavacompiler/","title":"-Djava.compiler","text":""},{"location":"djavacompiler/#-djavacompiler","title":"-Djava.compiler","text":"<p>This Oracle HotSpot property is used for loading a JIT compiler from a named, native library. This option can be used on the command line to specify the JIT compiler for the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"djavacompiler/#syntax","title":"Syntax","text":"<pre><code>    -Djava.compiler=j9jit29\n</code></pre>"},{"location":"djavalangstringbuffergrowaggressively/","title":"-Djava.lang.stringBuffer.growAggressively","text":""},{"location":"djavalangstringbuffergrowaggressively/#-djavalangstringbuffergrowaggressively","title":"-Djava.lang.stringBuffer.growAggressively","text":"<p> Restriction: This system property is supported only on Java\u2122 8.</p> <p> Setting this property to <code>false</code> reverts to the behavior (Eclipse OpenJ9\u2122 0.18 and earlier) of growing a 1 G <code>char[]</code> or larger <code>StringBuffer</code> or <code>StringBuilder</code> only as much as necessary to accommodate the <code>String</code> being added. The default behavior is to immediately grow to the maximum possible size, similarly to Java 11 and later. The default behavior is compatible with the Oracle HotSpot VM.</p>"},{"location":"djavalangstringbuffergrowaggressively/#syntax","title":"Syntax","text":"<pre><code>    -Djava.lang.stringBufferAndBuilder.growAggressively=[true|false]\n</code></pre> Setting Effect Default true Above 1 G, grow to the maximum size yes false Above 1 G, grow only as required"},{"location":"djavalangstringsubstringnocopy/","title":"-Djava.lang.string.substring.nocopy","text":""},{"location":"djavalangstringsubstringnocopy/#-djavalangstringsubstringnocopy","title":"-Djava.lang.string.substring.nocopy","text":"<p> Restriction: This system property is supported only on Java\u2122 8. String sharing cannot be enabled on Java 11 and later.</p> <p> Setting this property to <code>true</code> avoids sharing a String object when substring() is used to subset a String beginning from offset zero. Avoiding sharing is compatible with the Oracle HotSpot VM.</p>"},{"location":"djavalangstringsubstringnocopy/#syntax","title":"Syntax","text":"<pre><code>    -Djava.lang.string.substring.nocopy=[true|false]\n</code></pre> Setting Effect Default true No sharing false Sharing yes"},{"location":"djdknativecbc/","title":"-Djdk.nativeCBC","text":""},{"location":"djdknativecbc/#-djdknativecbc","title":"-Djdk.nativeCBC","text":"<p>This option enables or disables OpenSSL native cryptographic support for the CBC algorithm.</p>"},{"location":"djdknativecbc/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeCBC=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeCBC</code> true yes <code>-Djdk.nativeCBC</code> false"},{"location":"djdknativecbc/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the CBC algorithm. If you want to turn off this algorithm only, set this option to <code>false</code>. To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativechacha20/","title":"-Djdk.nativeChaCha20","text":""},{"location":"djdknativechacha20/#-djdknativechacha20","title":"-Djdk.nativeChaCha20","text":"<p>This option enables or disables OpenSSL native cryptographic support for the ChaCha20 and ChaCha20-Poly1305 algorithms.</p> <p> Restrictions:</p> <ul> <li> These algorithms are not supported on Java\u2122 8. </li> <li>These algorithms are not supported on OpenSSL 1.0.x.</li> </ul>"},{"location":"djdknativechacha20/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeChaCha20=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeChaCha20</code> true yes <code>-Djdk.nativeChaCha20</code> false"},{"location":"djdknativechacha20/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the ChaCha20 and ChaCha20-Poly1305 algorithms. If you want to turn off support for these algorithms only, set this option to <code>false</code>. To turn off support for these and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativecrypto/","title":"-Djdk.nativeCrypto","text":""},{"location":"djdknativecrypto/#-djdknativecrypto","title":"-Djdk.nativeCrypto","text":"<p>This option controls the use of OpenSSL native cryptographic support.</p>"},{"location":"djdknativecrypto/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeCrypto=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeCrypto</code> true yes <code>-Djdk.nativeCrypto</code> false"},{"location":"djdknativecrypto/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the Digest, CBC, GCM, RSA, ChaCha20 and ChaCha20-Poly1305, ECDH key agreement, EC key generation, XDH key agreement, and XDH key generation algorithms. If you want to turn off the OpenSSL implementation, set this option to <code>false</code>.</p> <p> Restriction:  The ChaCha20 and ChaCha20-Poly1305 algorithms are not supported on Java\u2122 8. The XDH key agreement and XDH key generation algorithms also are not supported on Java 8. </p> <p>If you want to turn off the algorithms individually, use the following system properties:</p> <ul> <li><code>-Djdk.nativeCBC</code></li> <li><code>-Djdk.nativeChaCha20</code> ( Not supported on Java 8. )</li> <li><code>-Djdk.nativeGCM</code></li> <li><code>-Djdk.nativeRSA</code></li> <li><code>-Djdk.nativeDigest</code></li> <li><code>-Djdk.nativeEC</code></li> <li><code>-Djdk.nativeECKeyGen</code></li> <li> <code>-Djdk.nativeXDHKeyAgreement</code></li> <li><code>-Djdk.nativeXDHKeyGen</code> </li> </ul>"},{"location":"djdknativedigest/","title":"-Djdk.nativeDigest","text":""},{"location":"djdknativedigest/#-djdknativedigest","title":"-Djdk.nativeDigest","text":"<p>This option enables or disables OpenSSL native cryptographic support for the Digest algorithm.</p>"},{"location":"djdknativedigest/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeDigest=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeDigest</code> true yes <code>-Djdk.nativeDigest</code> false"},{"location":"djdknativedigest/#explanation","title":"Explanation","text":"<p>To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativeec/","title":"-Djdk.nativeEC","text":""},{"location":"djdknativeec/#-djdknativeec","title":"-Djdk.nativeEC","text":"<p>This option enables or disables OpenSSL native cryptographic support for the ECDH key agreement algorithm.</p>"},{"location":"djdknativeec/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeEC=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeEC</code> true yes <code>-Djdk.nativeEC</code> false"},{"location":"djdknativeec/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the ECDH key agreement algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativeeckeygen/","title":"-Djdk.nativeECKeyGen","text":""},{"location":"djdknativeeckeygen/#-djdknativeeckeygen","title":"-Djdk.nativeECKeyGen","text":"<p>This option enables or disables OpenSSL native cryptographic support for the EC key generation algorithm.</p>"},{"location":"djdknativeeckeygen/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeECKeyGen=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeECKeyGen</code> true yes <code>-Djdk.nativeECKeyGen</code> false"},{"location":"djdknativeeckeygen/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the EC key generation algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativegcm/","title":"-Djdk.nativeGCM","text":""},{"location":"djdknativegcm/#-djdknativegcm","title":"-Djdk.nativeGCM","text":"<p>This option enables or disables OpenSSL native cryptographic support for the GCM algorithm.</p>"},{"location":"djdknativegcm/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeGCM=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeGCM</code> true yes <code>-Djdk.nativeGCM</code> false"},{"location":"djdknativegcm/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the GCM algorithm. If you want to turn off this algorithm only, set this option to <code>false</code>. To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativersa/","title":"-Djdk.nativeRSA","text":""},{"location":"djdknativersa/#-djdknativersa","title":"-Djdk.nativeRSA","text":"<p>This option enables or disables OpenSSL native cryptographic support for the RSA algorithm.</p>"},{"location":"djdknativersa/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeRSA=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeRSA</code> true yes <code>-Djdk.nativeRSA</code> false"},{"location":"djdknativersa/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the RSA algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativexdhkeyagreement/","title":"-Djdk.nativeXDHKeyAgreement","text":""},{"location":"djdknativexdhkeyagreement/#-djdknativexdhkeyagreement","title":"-Djdk.nativeXDHKeyAgreement","text":"<p> This option enables or disables OpenSSL native cryptographic support for the XDH key agreement algorithm.</p> <p> Restrictions:</p> <ul> <li>This algorithm is supported on Java\u2122 11 and later.</li> <li>This algorithm is supported on OpenSSL 1.1.1 onwards.</li> </ul>"},{"location":"djdknativexdhkeyagreement/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeXDHKeyAgreement=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeXDHKeyAgreement</code> true yes <code>-Djdk.nativeXDHKeyAgreement</code> false"},{"location":"djdknativexdhkeyagreement/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the XDH key agreement algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativexdhkeygen/","title":"-Djdk.nativeXDHKeyGen","text":""},{"location":"djdknativexdhkeygen/#-djdknativexdhkeygen","title":"-Djdk.nativeXDHKeyGen","text":"<p> This option enables or disables OpenSSL native cryptographic support for the XDH key generation algorithm.</p> <p> Restrictions:</p> <ul> <li>This algorithm is supported on Java\u2122 11 and later.</li> <li>This algorithm is supported on OpenSSL 1.1.1 onwards.</li> </ul>"},{"location":"djdknativexdhkeygen/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeXDHKeyGen=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeXDHKeyGen</code> true yes <code>-Djdk.nativeXDHKeyGen</code> false"},{"location":"djdknativexdhkeygen/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the XDH key generation algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/","title":"-Dorg.eclipse.openj9.criu.ImmutableEnvVars","text":""},{"location":"dorgeclipseopenj9criuimmutableenvvars/#-dorgeclipseopenj9criuimmutableenvvars","title":"-Dorg.eclipse.openj9.criu.ImmutableEnvVars","text":"<p>This system property specifies the environment variables that you want to add to the <code>ImmutableEnvVars</code> list.</p> <p> Restrictions: This option takes effect only when the <code>-XX:+EnableCRIUSupport</code> option is enabled. This option can be used only during the checkpoint phase.</p>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/#syntax","title":"Syntax","text":"<pre><code>    -Dorg.eclipse.openj9.criu.ImmutableEnvVars=&lt;environment_variables&gt;\n</code></pre> <p>Where <code>&lt;environment_variables&gt;</code> is a comma-separated list of environment variables. For example:</p> <pre><code>-Dorg.eclipse.openj9.criu.ImmutableEnvVars=INVOKED,WLP_USER_DIR,WLP_OUTPUT_DIR,LOG_DIR,X_LOG_DIR,LOG_FILE,X_LOG_FILE,VARIABLE_SOURCE_DIRS,X_CMD\n</code></pre> <p>The following environment variables are included in the list by default and cannot be removed:</p> <ul> <li><code>LANG</code></li> <li><code>LC_ALL</code></li> <li><code>LC_CTYPE</code></li> </ul>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/#explanation","title":"Explanation","text":"<p>The environment variables are a property of the operating system environment and not the VM. The VM considers these properties as immutable and does not allow the environment variables to change values between checkpoint and restore.</p> <p>During the checkpoint and restore phases, the VM can detect the environment variables that are in the <code>immutableEnvvars</code> list. You can add any other immutable variables that you want the VM to detect in the <code>ImmutableEnvVars</code> list with the <code>-Dorg.eclipse.openj9.criu.ImmutableEnvVars</code> option. If an environment variable is not in the list, the VM does not detect that variable even if the underlying system has defined it. These environment variables exist for the entire lifetime of the VM (checkpoint and restore).</p> <p>At restore, the VM can also detect the environment variables that are added through the <code>CRIUSupport.registerRestoreEnvVariables</code> API.</p> <p>For more information about how environment variables are handled during the checkpoint and restore process, see the Environment Variables section in the OpenJ9 CRIU Support: A look under the hood\u202f(part II) blog post.</p>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"dump_heapdump/","title":"Heap dump","text":""},{"location":"dump_heapdump/#heap-dump","title":"Heap dump","text":"<p>Heap dumps contain a snapshot of all the live objects that are being used by a running Java\u2122 application on the Java heap. You can obtain detailed information for each object instance, such as the address, type, class name, or size, and whether the instance has references to other objects.</p> <p>There are two formats for heap dumps; the classic format and the Portable Heap Dump (PHD) format, which is the default. Whilst the classic format is generated in ascii text and can be read, the PHD format is binary and and must be processed for analysis.</p>"},{"location":"dump_heapdump/#obtaining-dumps","title":"Obtaining dumps","text":"<p>Heap dumps are generated by default in PHD format when the Java heap runs out of space. If you want to trigger the production of a heap dump in response to other situations, or in classic format, you can use one of the following options:</p> <ul> <li>Configure the heap dump agent. For more information, see the -Xdump option.</li> <li>Use the <code>com.ibm.jvm.Dump</code> API programmatically in your application code. For more information, see the  JVM diagnostic utilities API documentation. </li> </ul>"},{"location":"dump_heapdump/#analyzing-dumps","title":"Analyzing dumps","text":"<p>The best method to analyze a PHD heap dump is to use the Eclipse Memory Analyzer\u2122 tool (MAT) or the IBM Memory Analyzer tool. These tools process the dump file and provide a visual representation of the objects in the Java Heap. Both tools require the Diagnostic Tool Framework for Java (DTFJ) plugin. To install the DTFJ plugin in the Eclipse IDE, select the following menu items:</p> <pre><code>Help &gt; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java   \n</code></pre> <p>The following sections contain detailed information about the content of each type of heap dump file.</p>"},{"location":"dump_heapdump/#portable-heap-dump-phd-format","title":"Portable Heap Dump (PHD) format","text":"<p>A PHD format dump file contains a header section and a body section. The body section can contain information about object, array, or class records. Primitive numbers are used to describe the file format, as detailed in the following table:</p> Primitive number Length in bytes <code>byte</code> 1 <code>short</code> 2 <code>int</code> 4 <code>long</code> 8 <code>word</code> 4 (32-bit platforms) or 8 (64-bit platforms)"},{"location":"dump_heapdump/#general-structure","title":"General structure","text":"<p>The following structure comprises the header section of a PHD file:</p> <ul> <li>A UTF string indicating that the file is a <code>portable heap dump</code></li> <li>An <code>int</code> containing the PHD version number</li> <li>An <code>int</code> containing flags:<ul> <li><code>1</code> indicates that the <code>word</code> length is 64-bit.</li> <li><code>2</code> indicates that all the objects in the dump are hashed. This flag is set for heap dumps that use 16-bit hash codes. Eclipse OpenJ9\u2122 heap dumps use 32-bit hash codes that are created only when used. For example, these hash codes are created when the APIs <code>Object.hashCode()</code> or <code>Object.toString()</code> are called in a Java application. If this flag is not set, the presence of a hash code is indicated by the hash code flag on the individual PHD records.</li> <li><code>4</code> indicates that the dump is from an OpenJ9 VM.</li> </ul> </li> <li>A <code>byte</code> containing a tag with a value of <code>1</code> that indicates the start of the header.</li> <li>A number of optional header records, each preceded by a one-byte header tag. Header record tags have a different range of values from the body, or object record tags. The end of the header is indicated by the end of header tag. The following tags are included:<ul> <li><code>header tag 1</code> - not used</li> <li><code>header tag 2</code> - indicates the end of the header</li> <li><code>header tag 3</code> - not used</li> <li><code>header tag 4</code> - indicates the VM version (Variable length UTF string)</li> </ul> </li> </ul> <p>The body of a PHD file is indicated by a <code>byte</code> that contains a tag with a value of 2, after which there are a number of dump records. Dump records are preceded by a 1 byte tag with the following record types:</p> <ul> <li>Short object: <code>0x80</code> bit of the tag is set</li> <li>Medium object: <code>0x40</code> bit of the tag is set (top bit value is 0)</li> <li>Primitive Array: <code>0x20</code> bit if the tag is set (all other tag values have the top 3 bits with a value of 0)</li> <li>Long record: tag value is <code>4</code></li> <li>Class record: tag value is <code>6</code></li> <li>Long primitive array: tag value is <code>7</code></li> <li>Object array: tag value is <code>8</code></li> </ul> <p>These records are described in more detail in the sections that follow.</p> <p>The end of the PHD body is indicated by a <code>byte</code> that contains a tag with a value of 3.</p>"},{"location":"dump_heapdump/#object-records","title":"Object records","text":"<p>Object records can be short, medium, or long, depending on the number of object references in the heap dump.</p> <p>1. Short object record</p> <p>The following information is contained within the tag byte:</p> <ul> <li> <p>The 1 byte tag, which consists of the following bits:</p> Bit number Value or description 1 Bit is set (0x80) 2 and 3 Indicates the class cache index. The value represents an index into a cache of the last 4 classes used. 4 and 5 Contain the number of references. Most objects contain 0 - 3 references. If there are 4 - 7 references, the Medium object record is used. If there are more than 7 references, the Long object record is used. 6 Indicates whether the gap is a 1 <code>byte</code> value or a <code>short</code>. The gap is the difference between the address of this object and the previous object. If set, the gap is a <code>short</code>. If the gap does not fit into a <code>short</code>, the Long object record format is used. 7 and 8 Indicates the size of each reference (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) </li> <li> <p>A <code>byte</code> or a <code>short</code> containing the gap between the address of this object and the address of the preceding object. The value is signed and represents the number of 32-bit words between the two addresses. Most gaps fit into 1 byte.</p> </li> <li>If all objects are hashed, a <code>short</code> containing the hash code.</li> <li>The array of references, if references exist. The tag shows the number of elements, and the size of each element. The value in each element is the gap between the address of the references and the address of the current object. The value is a signed number of 32-bit words. Null references are not included.</li> </ul> <p>2. Medium object record</p> <p>These records provide the actual address of the class rather than a cache index. The following format is used:</p> <ul> <li> <p>The 1 byte tag, consisting of the following bits:</p> Bit number Value or description 1 0 2 Set (0x40) 3, 4, and 5 Contain the number of references 6 Indicates whether the gap is a 1 <code>byte</code> value or a <code>short</code> (see Short object record description) 7 and 8 Indicates the size of each reference (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) </li> <li> <p>A <code>byte</code> or a <code>short</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record description)</p> </li> <li>A <code>word</code> containing the address of the class of this object.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code.</li> <li>The array of references (See the Short object record description).</li> </ul> <p>3. Long object record</p> <p>This record format is used when there are more than 7 references, or if there are extra flags or a hash code. The following format is used:</p> <ul> <li> <p>The 1 byte tag, containing the value 4.</p> </li> <li> <p>A <code>byte</code> containing flags, consisting of the following bits:</p> Bit number Value or description 1 and 2 Indicates whether the gap is a <code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> format 3 and 4 Indicates the size of each reference  (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) 5 and 6 Unused 7 Indicates if the object was hashed and moved. If this bit is set, the record includes the hash code 8 Indicates if the object was hashed </li> <li> <p>A <code>byte</code>, <code>short</code>, <code>int</code>, or <code>long</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record description).</p> </li> <li>A <code>word</code> containing the address of the class of this object.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. Otherwise, an optional <code>int</code> containing the hash code if the hashed and moved bit is set in the record flag byte.</li> <li>An <code>int</code> containing the length of the array of references.</li> <li>The array of references (See the Short object record description).</li> </ul>"},{"location":"dump_heapdump/#array-records","title":"Array records","text":"<p>PHD arrays can be primitive arrays or object arrays, as described in the sections that follow.</p> <p>1. Primitive array record</p> <p>The following information is contained in an array record:</p> <ul> <li> <p>The 1 byte tag, consisting of the following bits:</p> Bit number Value or description 1 and 2 0 3 Set (0x20) 4, 5, and 6 Contains the array type ( 0=bool, 1=char, 2=float, 3=double, 4=<code>byte</code>, 5=<code>short</code>, 6=<code>int</code>, and 7=<code>long</code>) 7 and 8 Indicates the length of the array size and the length of the gap (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) </li> <li> <p><code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record description).</p> </li> <li><code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> containing the array length.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code.</li> <li>An unsigned <code>int</code> containing the size of the instance of the array on the heap, including header and padding. The size is measured in 32-bit words, which you can multiply by four to obtain the size in bytes. This format allows encoding of lengths up to 16GB in an unsigned <code>int</code>.</li> </ul> <p>2. Long primitive array record</p> <p>This type of record is used when a primitive array has been hashed.</p> <ul> <li> <p>The 1 byte tag with a  value of 7.</p> </li> <li> <p>A byte containing the following flags:</p> Bit number Value or description 1, 2, and 3 Contains the array type ( 0=bool, 1=char, 2=float, 3=double, 4=<code>byte</code>, 5=<code>short</code>, 6=<code>int</code>, and 7=<code>long</code>) 4 Indicates the length of the array size and the length of the gap (0=<code>byte</code>, 1=<code>word</code>). 5 and 6 Unused 7 Indicates if the object was hashed and moved. If this bit is set, the record includes the hash code. 8 Indicates if the object was hashed </li> <li> <p>a <code>byte</code> or <code>word</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record  description).</p> </li> <li>a <code>byte</code> or <code>word</code> containing the array length.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. Otherwise, an optional <code>int</code> containing the hash code if the hashed and moved bit is set in the record flag byte.</li> <li>An unsigned <code>int</code> containing the size of the instance of the array on the heap, including header and padding. The size is measured in 32-bit words, which you can multiply by four to obtain the size in bytes. This format allows encoding of lengths up to 16GB in an unsigned <code>int</code>.</li> </ul> <p>3. Object array record</p> <p>The following format applies:</p> <ul> <li> <p>The 1 byte tag with a  value of 8.</p> </li> <li> <p>A byte containing the following flags:</p> Bit number Value or description 1 and 2 Indicates whether the gap is <code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code>. 3 and 4 Indicates the size of each reference  (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) 5 and 6 Unused 7 Indicates if the object was hashed and moved. If this bit is set, the record includes the hash code. 8 Indicates if the object was hashed </li> <li> <p>A <code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record format description).</p> </li> <li>A <code>word</code> containing the address of the class of the objects in the array. Object array records do not update the class cache.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. If the hashed and moved bit is set in the records flag, this field contains an <code>int</code>.</li> <li>An <code>int</code> containing the length of the array of references.</li> <li>The array of references (See the Short object record description).</li> <li>An unsigned <code>int</code> containing the size of the instance of the array on the heap, including header and padding. The size is measured in 32-bit words, which you can multiply by four to obtain the size in bytes. This format allows encoding of lengths up to 16GB in an unsigned <code>int</code>.</li> <li>An final <code>int</code> value is shown at the end. This <code>int</code> contains the true array length, shown as a number of array elements. The true array length might differ from the length of the array of references because null references are excluded.</li> </ul>"},{"location":"dump_heapdump/#class-records","title":"Class records","text":"<p>The PHD class record encodes a class object and contains the following format:</p> <ul> <li> <p>The 1 byte tag, containing the value 6.</p> </li> <li> <p>A byte containing the following flags:</p> Bit number Value or description 1 and 2 Indicates whether the gap is byte, <code>short</code>, <code>int</code> or <code>long</code> 3 and 4 Indicates the size of each static reference  (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) 5 Indicates if the object was hashed </li> <li> <p>A byte, <code>short</code>, <code>int</code> or <code>long</code> containing the gap between the address of this class and the address of the preceding object (See the Short object record description).</p> </li> <li>An <code>int</code> containing the instance size.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. Otherwise, an optional <code>int</code> containing the hash code if the hashed and moved bit is set in the record flag byte.</li> <li>A <code>word</code> containing the address of the superclass.</li> <li>A UTF string containing the name of this class.</li> <li>An <code>int</code> containing the number of static references.</li> <li>The array of static references (See the Short object record description).</li> </ul>"},{"location":"dump_heapdump/#classic-heap-dump-format","title":"Classic Heap Dump format","text":"<p>Classic heap dumps are produced in ascii text on all platforms except z/OS, which are encoded in EBCDIC. The dump is divided into the following sections:</p>"},{"location":"dump_heapdump/#header-record","title":"Header record","text":"<p>A single string containing information about the runtime environment, platform, and build levels, similar to the following example:</p> <pre><code>// Version: JRE 1.8.0 Linux amd64-64 (build 1.8.0_232-b09)\n</code></pre>"},{"location":"dump_heapdump/#object-records_1","title":"Object records","text":"<p>A record of each object instance in the heap with the following format:</p> <pre><code>&lt;object address, in hexadecimal&gt; [&lt;length in bytes of object instance, in decimal&gt;] OBJ &lt;object type&gt;\n&lt;heap reference, in hexadecimal&gt; &lt;heap reference, in hexadecimal&gt; ...\n</code></pre> <p>The following object types (<code>object type</code>) might be shown:</p> <ul> <li>class name (including package name)</li> <li>class array type</li> <li>primitive array type</li> </ul> <p>These types are abbreviated in the record. To determine the type, see the Java VM Type Signature table.</p> <p>Any references found are also listed, excluding references to an object's class or NULL references.</p> <p>The following example shows an object instance (16 bytes in length) of type <code>java/lang/String</code>, with a reference to a char array:</p> <pre><code>0x00000000E0000AF0 [16] OBJ java/lang/String\n    0x00000000E0000B00\n</code></pre> <p>The object instance (length 32 bytes) of type char array, as referenced from the <code>java/lang/String</code>, is shown in the following example:</p> <pre><code>0x00000000E0000B00 [32] OBJ [C\n</code></pre> <p>The following example shows an object instance (24 bytes in length) of type array of <code>java/lang/String</code>:</p> <pre><code>0x00000000FFF07498 [24] OBJ [Ljava/lang/String;\n    0x00000000E0005D78 0x00000000E0005D50 0x00000000E0005D28 0x00000000E0005D00\n</code></pre>"},{"location":"dump_heapdump/#class-records_1","title":"Class records","text":"<p>A record of each class in the following format:</p> <pre><code>&lt;class object address, in hexadecimal&gt; [&lt;length in bytes of class object, in decimal&gt;] CLS &lt;class type&gt;\n&lt;heap reference, in hexadecimal&gt; &lt;heap reference, in hexadecimal&gt;...\n</code></pre> <p>The following class types (<code>&lt;class type&gt;</code>) might be shown:</p> <ul> <li>class name (including package name)</li> <li>class array type</li> <li>primitive array types</li> </ul> <p>These types are abbreviated in the record. To determine the type, see the Java VM Type Signature table.</p> <p>Any references found in the class block are also listed, excluding NULL references.</p> <p>The following example shows a class object (80 bytes in length) for <code>java/util/Date</code>, with heap references:</p> <pre><code>0x00000000E00174F0 [80] CLS java/util/Date\n    0x00000000FFF1BB60 0x00000000FFF29630\n</code></pre>"},{"location":"dump_heapdump/#trailer-record-1","title":"Trailer record 1","text":"<p>A single record containing record counts, in decimal.</p> <p>For example:</p> <pre><code>// Breakdown - Classes: 630, Objects: 3692, ObjectArrays: 576, PrimitiveArrays: 2249\n</code></pre>"},{"location":"dump_heapdump/#trailer-record-2","title":"Trailer record 2","text":"<p>A single record containing totals, in decimal.</p> <p>For example:</p> <pre><code>// EOF:  Total 'Objects',Refs(null) : 7147,22040(12379)\n</code></pre> <p>The values in the example reflect the following counts:</p> <ul> <li><code>7147</code> total objects</li> <li><code>22040</code> total references</li> <li><code>(12379)</code> total NULL references as a proportion of the total references count</li> </ul>"},{"location":"dump_heapdump/#java-vm-type-signatures","title":"Java VM Type Signatures","text":"<p>The following table shows the abbreviations used for different Java types in the heap dump records:</p> Java VM Type Signature Java Type <code>Z</code> <code>boolean</code> <code>B</code> <code>byte</code> <code>C</code> <code>char</code> <code>S</code> <code>short</code> <code>I</code> <code>int</code> <code>J</code> <code>long</code> <code>F</code> <code>float</code> <code>D</code> <code>double</code> <code>L&lt;fully-qualified class&gt;;</code> <code>&lt;fully-qualified class&gt;</code> <code>[&lt;type&gt;</code> <code>&lt;type&gt;[](array of &lt;type&gt;)</code> <code>(&lt;arg-types&gt;)&lt;ret-type&gt;</code> <code>method</code>"},{"location":"dump_heapdump/#see-also","title":"See also","text":"<ul> <li>DTFJ interface</li> </ul>"},{"location":"dump_javadump/","title":"Java dump","text":""},{"location":"dump_javadump/#java-dump","title":"Java dump","text":"<p>Java\u2122 dumps, sometimes referred to as Java cores, are produced when the VM ends unexpectedly because of an operating system signal, <code>OutOfMemoryError</code>, or a user-initiated keystroke combination. You can also generate a Java dump by calling the Dump API programmatically from your application or specifying the <code>-Xdump:java</code> option on the command line.</p> <p>If your Java application crashes or hangs, Java dumps can provide useful information to help you diagnose the root cause.</p> <ul> <li>If your application crashes, Java dumps are generated automatically for the following types of failure:<ul> <li>the VM receives an unexpected signal or an assertion failure</li> <li>the VM runs out of memory</li> </ul> </li> <li> <p>If your application hangs, you can trigger the generation of a Java dump by sending a SIGQUIT signal (<code>kill -3</code>) to the VM.</p> <p> Note: On Windows\u00ae, if you started the VM in a console window you can force the VM to produce a Java dump in response to a SIGBREAK signal (Ctrl-Break keyboard combination). If you didn't start in a console window, there is no equivalent to a Linux <code>kill</code> command on Windows for sending signals. The only option here is to trigger a full system dump by finding the VM process in the Processes tab of the Windows Task Manager and clicking Create dump file.</p> </li> </ul> <p>To help you understand how a Java dump can help you with problem diagnosis, this topic includes a few scenarios to help you interpret the data:</p> <ul> <li>A crash caused by a general protection fault (gpf)</li> <li>A Java heap OutOfMemoryError (OOM)</li> <li>A native OutOfMemoryError (OOM)</li> <li>A deadlock situation</li> <li>A hang</li> </ul>"},{"location":"dump_javadump/#java-dump-contents","title":"Java dump contents","text":"<p>Java dumps summarize the state of the VM when the event occurs, with most of the information relating to components of the VM. The file is made up of a number of sections that provide different types of information.</p>"},{"location":"dump_javadump/#title","title":"TITLE","text":"<p>The first section of the Java dump file provides information about the event that triggered the production of the dump. In the following example, you can see that a <code>vmstop</code> event triggered the dump at a specified date and time.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"vmstop\" (00000002) Detail \"#0000000000000000\" received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/doc-javacore/javacore.20210423.140244.1175.0001.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x106 (vm_access+exclusive_vm_access+trace_disabled)\n</code></pre>"},{"location":"dump_javadump/#gpinfo","title":"GPINFO","text":"<p>The GPINFO section provides general information about the system that the VM is running on. The following example is taken from a Java dump that was generated on a Linux system.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       GPINFO subcomponent dump routine\nNULL           ================================\n2XHOSLEVEL     OS Level         : Linux 3.10.0-862.11.6.el7.x86_64\n2XHCPUS        Processors -\n3XHCPUARCH       Architecture   : amd64\n3XHNUMCPUS       How Many       : 4\n3XHNUMASUP       NUMA is either not supported or has been disabled by user\nNULL\n1XHERROR2      Register dump section only produced for SIGSEGV, SIGILL or SIGFPE.\nNULL\n</code></pre> <p>The content of this section can vary, depending on the cause of the dump. For example, if the dump was caused by a general protection fault (gpf), the library in which the crash occurred is also recorded, together with a value shown as <code>VM flags</code>. This value can provide some clues about which component of the VM might have been involved. Look for the following line in the output:</p> <pre><code>1XHFLAGS       VM flags:0000000000000000\n</code></pre> <p>The hexadecimal number that is recorded for <code>VM flags</code> ends in MSSSS, where M is the VM component and SSSS is component-specific code as shown in the following table:</p> Component Code value INTERPRETER 0x10000 GC 0x20000 GROW_STACK 0x30000 JNI 0x40000 JIT_CODEGEN 0x50000 BCVERIFY 0x60000 RTVERIFY 0x70000 SHAREDCLASSES 0x80000 <p>A value of <code>0000000000000000</code> (0x00000) indicates that a crash occurred outside of the VM.</p>"},{"location":"dump_javadump/#envinfo","title":"ENVINFO","text":"<p>This section contains useful information about the environment in which the crash took place, including the following data:</p> <ul> <li>Java version (<code>1CIJAVAVERSION</code>)</li> <li>Eclipse OpenJ9\u2122 VM and subcomponent version information (<code>1CIVMVERSION</code>, <code>1CIJ9VMVERSION</code>, <code>1CIJITVERSION</code>, <code>1CIOMRVERSION</code>, <code>1CIJCLVERSION</code>)</li> <li>VM start time (<code>1CISTARTTIME</code>) and process information (<code>1CIPROCESSID</code>)</li> <li>Java home (<code>1CIJAVAHOMEDIR</code>) and DLL (<code>1CIJAVADLLDIR</code>) directories</li> <li>User arguments passed on the command line (<code>1CIUSERARGS</code>), identifying those that are ignored (<code>1CIIGNOREDARGS</code>)</li> <li>User limits imposed by the system (<code>1CIUSERLIMITS</code>)</li> <li>Environment variables in place (<code>1CIENVVARS</code>)</li> <li>System information (<code>1CISYSINFO</code>)</li> <li>CPU information (<code>1CICPUINFO</code>)</li> <li>Control group (Cgroup) information (<code>1CICGRPINFO</code>)</li> </ul> <p>For clarity, the following example shows a shortened version of this section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       ENVINFO subcomponent dump routine\nNULL           =================================\n1CIJAVAVERSION JRE 9 Linux amd64-64 (build 9.0.4-internal+0-adhoc..openj9-openjdk-jdk9)\n1CIVMVERSION   20180830_000000\n1CIJ9VMVERSION 8e7c6ec\n1CIJITVERSION  8e7c6ec\n1CIOMRVERSION  553811b_CMPRSS\n1CIJCLVERSION  ec1d223 based on jdk-9.0.4+12\n1CIJITMODES    JIT enabled, AOT enabled, FSD disabled, HCR enabled\n1CIRUNNINGAS   Running as a standalone JVM\n1CIVMIDLESTATE VM Idle State: ACTIVE\n1CICONTINFO    Running in container : FALSE\n1CICGRPINFO    JVM support for cgroups enabled : TRUE\n1CISTARTTIME   JVM start time: 2018/08/30 at 21:55:47:387\n1CISTARTNANO   JVM start nanotime: 22012135233549\n1CIPROCESSID   Process ID: 30285 (0x764D)\n1CICMDLINE     [not available]\n1CIJAVAHOMEDIR Java Home Dir:   /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk\n1CIJAVADLLDIR  Java DLL Dir:    /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/bin\n1CISYSCP       Sys Classpath:\n1CIUSERARGS    UserArgs:\n2CIUSERARG               -Xoptionsfile=/home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/options.default\n...\n1CIIGNOREDARGS Ignored Args:\n2CIIGNOREDARG            -XX:+UseCompressedOop\n2CIIGNOREDARG            -XX:CompressedClassSpaceSize=528482304\nNULL\n1CIUSERLIMITS  User Limits (in bytes except for NOFILE and NPROC)\nNULL           ------------------------------------------------------------------------\nNULL           type                            soft limit           hard limit\n2CIUSERLIMIT   RLIMIT_AS                        unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_CORE                              0            unlimited\n2CIUSERLIMIT   RLIMIT_CPU                       unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_DATA                      unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_FSIZE                     unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_LOCKS                     unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_MEMLOCK                       65536                65536\n2CIUSERLIMIT   RLIMIT_NOFILE                         4096                 4096\n2CIUSERLIMIT   RLIMIT_NPROC                          4096                30592\n2CIUSERLIMIT   RLIMIT_RSS                       unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_STACK                       8388608            unlimited\n2CIUSERLIMIT   RLIMIT_MSGQUEUE                     819200               819200\n2CIUSERLIMIT   RLIMIT_NICE                              0                    0\n2CIUSERLIMIT   RLIMIT_RTPRIO                            0                    0\n2CIUSERLIMIT   RLIMIT_SIGPENDING                    30592                30592\nNULL\n1CIENVVARS     Environment Variables\nNULL           ------------------------------------------------------------------------\n2CIENVVAR      XDG_VTNR=1\n2CIENVVAR      SSH_AGENT_PID=2653\n...\nNULL\n1CISYSINFO     System Information\nNULL           ------------------------------------------------------------------------\n2CISYSINFO     /proc/sys/kernel/core_pattern = core\n2CISYSINFO     /proc/sys/kernel/core_uses_pid = 1\nNULL\n1CICPUINFO     CPU Information\nNULL           ------------------------------------------------------------------------\n2CIPHYSCPU     Physical CPUs: 8\n2CIONLNCPU     Online CPUs: 8\n2CIBOUNDCPU    Bound CPUs: 8\n2CIACTIVECPU   Active CPUs: 0\n2CITARGETCPU   Target CPUs: 8\n2CIJITFEATURE  CPU features (JIT): fpu cx8 cmov mmx sse sse2 ssse3 fma sse4_1 popcnt aesni osxsave avx avx2 rdt_m\n2CIAOTFEATURE  CPU features (AOT): fpu cx8 cmov mmx sse sse2 ssse3 fma sse4_1 popcnt aesni osxsave avx avx2 rdt_m\nNULL\n1CICGRPINFO    Cgroup Information\nNULL           ------------------------------------------------------------------------\n2CICGRPINFO    subsystem : cpu\n2CICGRPINFO    cgroup name : /\n3CICGRPINFO    CPU Period : 100000 microseconds\n3CICGRPINFO    CPU Quota : Not Set\n3CICGRPINFO    CPU Shares : 1024\n3CICGRPINFO    Period intervals elapsed count : 0\n3CICGRPINFO    Throttled count : 0\n3CICGRPINFO    Total throttle time : 0 nanoseconds\n2CICGRPINFO    subsystem : cpuset\n2CICGRPINFO    cgroup name : /\n3CICGRPINFO    CPU exclusive : 1\n3CICGRPINFO    Mem exclusive : 1\n3CICGRPINFO    CPUs : 0-7\n3CICGRPINFO    Mems : 0\n2CICGRPINFO    subsystem : memory\n2CICGRPINFO    cgroup name : /\n3CICGRPINFO    Memory Limit : Not Set\n3CICGRPINFO    Memory + Swap Limit : Not Set\n3CICGRPINFO    Memory Usage : 5363396608 bytes\n3CICGRPINFO    Memory + Swap Usage : 5363396608 bytes\n3CICGRPINFO    Memory Max Usage : 0 bytes\n3CICGRPINFO    Memory + Swap Max Usage : 0 bytes\n3CICGRPINFO    Memory limit exceeded count : 0\n3CICGRPINFO    Memory + Swap limit exceeded count : 0\n3CICGRPINFO    OOM Killer Disabled : 0\n3CICGRPINFO    Under OOM : 0\nNULL\n</code></pre>"},{"location":"dump_javadump/#nativememinfo","title":"NATIVEMEMINFO","text":"<p>This section records information about native memory that is requested by using library functions such as <code>malloc()</code> and <code>mmap()</code>. Values are provided as a breakdown, per component, indicating the total number of bytes allocated and the number of native memory allocations. In the following example, 4,682,840 bytes of native memory are allocated (but not yet freed) to VM Classes, which correspond to 141 allocations.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       NATIVEMEMINFO subcomponent dump routine\nNULL           =================================\n0MEMUSER\n1MEMUSER       JRE: 2,569,088,312 bytes / 4653 allocations\n1MEMUSER       |\n2MEMUSER       +--VM: 2,280,088,336 bytes / 2423 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Classes: 4,682,840 bytes / 141 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Memory Manager (GC): 2,054,966,784 bytes / 433 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Heap: 2,014,113,792 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 40,852,992 bytes / 432 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Threads: 10,970,016 bytes / 156 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Stack: 197,760 bytes / 16 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Native Stack: 10,616,832 bytes / 17 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 155,424 bytes / 123 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Trace: 180,056 bytes / 263 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JVMTI: 17,776 bytes / 13 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JNI: 36,184 bytes / 52 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Port Library: 208,179,632 bytes / 72 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Unused &lt;32bit allocation regions: 208,168,752 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 10,880 bytes / 71 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 1,055,048 bytes / 1293 allocations\n1MEMUSER       |\n2MEMUSER       +--JIT: 288,472,816 bytes / 140 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Code Cache: 268,435,456 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Data Cache: 2,097,216 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 17,940,144 bytes / 138 allocations\n1MEMUSER       |\n2MEMUSER       +--Class Libraries: 13,432 bytes / 25 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--VM Class Libraries: 13,432 bytes / 25 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--sun.misc.Unsafe: 3,184 bytes / 13 allocations\n4MEMUSER       |  |  |  |\n5MEMUSER       |  |  |  +--Direct Byte Buffers: 1,056 bytes / 12 allocations\n4MEMUSER       |  |  |  |\n5MEMUSER       |  |  |  +--Other: 2,128 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 10,248 bytes / 12 allocations\n1MEMUSER       |\n2MEMUSER       +--Unknown: 513,728 bytes / 2065 allocations\nNULL\n</code></pre> <p>This section does not record memory that is allocated by application or JNI code and is typically a little less than the value recorded by operating system tools.</p>"},{"location":"dump_javadump/#meminfo","title":"MEMINFO","text":"<p>This section relates to memory management, providing a breakdown of memory usage in the VM for the object heap, internal memory, memory used for classes, the JIT code cache, and JIT data cache in decimal and hexadecimal format. You can also find out which garbage collection policy is in use when the dump is produced.</p> <p>The object memory area (<code>1STHEAPTYPE</code>) records each memory region in use, its start and end address, and region size. Further information is recorded about the memory segments that are used for internal memory, class memory, the JIT code cache, and JIT data cache (<code>1STSEGMENT</code>). This information includes the address of the segment control data structure, the start and end address of the native memory segment, as well as the segment size.</p> <p>For clarity, the following example shows a shortened version of this section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       MEMINFO subcomponent dump routine\nNULL           =================================\nNULL\n1STHEAPTYPE    Object Memory\nNULL           id                 start              end                size               space/region\n1STHEAPSPACE   0x00007FF4F00744A0         --                 --                 --         Generational\n1STHEAPREGION  0x00007FF4F0074CE0 0x0000000087F40000 0x0000000088540000 0x0000000000600000 Generational/Tenured Region\n1STHEAPREGION  0x00007FF4F0074930 0x00000000FFE00000 0x00000000FFF00000 0x0000000000100000 Generational/Nursery Region\n1STHEAPREGION  0x00007FF4F0074580 0x00000000FFF00000 0x0000000100000000 0x0000000000100000 Generational/Nursery Region\nNULL\n1STHEAPTOTAL   Total memory:                     8388608 (0x0000000000800000)\n1STHEAPINUSE   Total memory in use:              2030408 (0x00000000001EFB48)\n1STHEAPFREE    Total memory free:                6358200 (0x00000000006104B8)\nNULL\n1STSEGTYPE     Internal Memory\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F004CBC8 0x00007FF4CD33C000 0x00007FF4CD33C000 0x00007FF4CE33C000 0x01000440 0x0000000001000000\n1STSEGMENT     0x00007FF4F004CB08 0x00007FF4DE43D030 0x00007FF4DE517770 0x00007FF4DE53D030 0x00800040 0x0000000000100000\nNULL\n1STSEGTOTAL    Total memory:                    17825792 (0x0000000001100000)\n1STSEGINUSE    Total memory in use:               894784 (0x00000000000DA740)\n1STSEGFREE     Total memory free:               16931008 (0x00000000010258C0)\nNULL\n1STSEGTYPE     Class Memory\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F03B5638 0x0000000001053D98 0x000000000105BD98 0x000000000105BD98 0x00010040 0x0000000000008000\n1STSEGMENT     0x00007FF4F03B5578 0x0000000001048188 0x0000000001050188 0x0000000001050188 0x00010040 0x0000000000008000\n...\nNULL\n1STSEGTOTAL    Total memory:                     3512520 (0x00000000003598C8)\n1STSEGINUSE    Total memory in use:              3433944 (0x00000000003465D8)\n1STSEGFREE     Total memory free:                  78576 (0x00000000000132F0)\nNULL\n1STSEGTYPE     JIT Code Cache\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F00961F8 0x00007FF4CE43D000 0x00007FF4CE445790 0x00007FF4DE43D000 0x00000068 0x0000000010000000\nNULL\n1STSEGTOTAL    Total memory:                   268435456 (0x0000000010000000)\n1STSEGINUSE    Total memory in use:                34704 (0x0000000000008790)\n1STSEGFREE     Total memory free:              268400752 (0x000000000FFF7870)\n1STSEGLIMIT    Allocation limit:               268435456 (0x0000000010000000)\nNULL\n1STSEGTYPE     JIT Data Cache\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F0096668 0x00007FF4CC553030 0x00007FF4CC753030 0x00007FF4CC753030 0x00000048 0x0000000000200000\nNULL\n1STSEGTOTAL    Total memory:                     2097152 (0x0000000000200000)\n1STSEGINUSE    Total memory in use:              2097152 (0x0000000000200000)\n1STSEGFREE     Total memory free:                      0 (0x0000000000000000)\n1STSEGLIMIT    Allocation limit:               402653184 (0x0000000018000000)\nNULL\n1STGCHTYPE     GC History\nNULL\n</code></pre> <p>In the example, the GC History (<code>1STGCHTYPE</code>) section is blank. This section is populated if a garbage collection cycle occurred in a VM that is being diagnosed with the trace facility.</p>"},{"location":"dump_javadump/#locks","title":"LOCKS","text":"<p>This section of the Java dump provides information about locks, which protect shared resources from being accessed by more than one entity at a time. The information is essential in a deadlock situation, where two threads attempt to synchronize on an object and lock an instance of a class. Precise information is recorded about the threads that are causing the problem, which enables you to identify the root cause.</p> <p>The following example shows a typical LOCKS section, where no deadlocks existed at the time the dump was triggered. For clarity, the following example shows a shortened version of this section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       LOCKS subcomponent dump routine\nNULL           ===============================\nNULL\n1LKPOOLINFO    Monitor pool info:\n2LKPOOLTOTAL     Current total number of monitors: 3\nNULL\n1LKMONPOOLDUMP Monitor Pool Dump (flat &amp; inflated object-monitors):\n2LKMONINUSE      sys_mon_t:0x00007FF4B0001D78 infl_mon_t: 0x00007FF4B0001DF8:\n3LKMONOBJECT       java/lang/ref/ReferenceQueue@0x00000000FFE26A10: &lt;unowned&gt;\n3LKNOTIFYQ            Waiting to be notified:\n3LKWAITNOTIFY            \"Common-Cleaner\" (J9VMThread:0x0000000000FD0100)\nNULL\n1LKREGMONDUMP  JVM System Monitor Dump (registered monitors):\n2LKREGMON          Thread global lock (0x00007FF4F0004FE8): &lt;unowned&gt;\n2LKREGMON          &amp;(PPG_mem_mem32_subAllocHeapMem32.monitor) lock (0x00007FF4F0005098): &lt;unowned&gt;\n2LKREGMON          NLS hash table lock (0x00007FF4F0005148): &lt;unowned&gt;\n...\nNULL\n</code></pre>"},{"location":"dump_javadump/#threads","title":"THREADS","text":"<p>The THREADS section of a Java dump file provides summary information about the VM thread pool and detailed information about Java threads, native threads, and stack traces. Understanding the content of this section can help you diagnose problems that are caused by blocked or waiting threads.</p> <p>A Java thread runs on a native thread. Several lines are recorded for each Java thread in the <code>Thread Details</code> subsection, which include the following key pieces of information:</p> <ul> <li><code>3XMTHREADINFO</code>: The thread name, address information for the VM thread structures and Java thread object, the thread state, and thread priority.</li> <li><code>3XMJAVALTHREAD</code>: The Java thread ID and daemon status from the thread object.</li> <li><code>3XMTHREADINFO1</code>: The native operating system thread ID, priority, scheduling policy, internal VM thread state, and VM thread flags.</li> <li><code>3XMTHREADINFO2</code>: The native stack address range.</li> <li><code>3XMTHREADINFO3</code>: Java call stack information (<code>4XESTACKTRACE</code>) or Native call stack information (<code>4XENATIVESTACK</code>).</li> <li><code>5XESTACKTRACE</code>: This line indicates whether locks were taken by a specific method.</li> </ul> <p>Java thread priorities are mapped to operating system priority values. Thread states are shown in the following table:</p> Thread state value Status Description R Runnable The thread is able to run CW Condition Wait The thread is waiting S Suspended The thread is suspended by another thread Z Zombie The thread is destroyed P Parked The thread is parked by <code>java.util.concurrent</code> B Blocked The thread is waiting to obtain a lock <p>For threads that are parked (P), blocked (B), or waiting (CW), an additional line (<code>3XMTHREADBLOCK</code>) is included in the output that shows what the thread is parked on, blocked on, or waiting for. For threads that are waiting for a class initialization lock (<code>java/lang/J9VMInternals$ClassInitializationLock</code>), this line includes the name of the thread that is currently working to progress the initialization of the class. You can use this information to diagnose deadlocks that are caused by class initialization, which might not be detected and reported in the LOCKS section.</p> <p>For clarity, the following example shows a shortened version of a typical THREADS section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 19\n2XMPOOLLIVE        Current total number of live threads: 18\n2XMPOOLDAEMON      Current total number of live daemon threads: 15\nNULL\n1XMTHDINFO     Thread Details\nNULL\n...\n3XMTHREADINFO      \"JIT Diagnostic Compilation Thread-007 Suspended\" J9VMThread:0x0000000000035200, omrthread_t:0x00007F3F8C0D02C8, java/lang/Thread:0x00000000FFF42120, state:R, prio=10\n3XMJAVALTHREAD            (java/lang/Thread getId:0x9, isDaemon:true)\n3XMJAVALTHRCCL            sun/misc/Launcher$AppClassLoader(0x00000000FFF3BF98)\n3XMTHREADINFO1            (native thread ID:0x618F, native priority:0xB, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000081)\n3XMTHREADINFO2            (native stack address range from:0x00007F3F879C5000, to:0x00007F3F87AC5000, size:0x100000)\n3XMCPUTIME               CPU usage total: 0.052410771 secs, current category=\"JIT\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           No Java callstack associated with this thread\n...\nNULL\n...\n3XMTHREADINFO      \"Class Initialization Thread 2\" J9VMThread:0x0000000000124D00, omrthread_t:0x00007F3F8C1494C8, java/lang/Thread:0x00000000FFF53EE8, state:CW, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x13, isDaemon:false)\n3XMJAVALTHRCCL            sun/misc/Launcher$AppClassLoader(0x00000000FFF3BF98)\n3XMTHREADINFO1            (native thread ID:0x6199, native priority:0x5, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000181)\n3XMTHREADINFO2            (native stack address range from:0x00007F3F74AB4000, to:0x00007F3F74AF4000, size:0x40000)\n3XMCPUTIME               CPU usage total: 0.008712260 secs, current category=\"Application\"\n3XMTHREADBLOCK     Waiting on: java/lang/J9VMInternals$ClassInitializationLock@0x00000000FFF61C90 Owned by: &lt;unowned&gt; Initializing thread: \"Class Initialization Thread 1\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=4096 (0x1000)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/Class.forNameImpl(Native Method)\n4XESTACKTRACE                at java/lang/Class.forName(Class.java:339)\n4XESTACKTRACE                at ClassInitLockBug$ClassInitThread.run(ClassInitLockBug.java:16)\n...\nNULL\n...\nNULL\n3XMTHREADINFO      \"Class Initialization Thread 1\" J9VMThread:0x0000000000124100, omrthread_t:0x00007F3F8C148F50, java/lang/Thread:0x00000000FFF53D80, state:CW, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x12, isDaemon:false)\n3XMJAVALTHRCCL            sun/misc/Launcher$AppClassLoader(0x00000000FFF3BF98)\n3XMTHREADINFO1            (native thread ID:0x6198, native priority:0x5, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000481)\n3XMTHREADINFO2            (native stack address range from:0x00007F3F74AF5000, to:0x00007F3F74B35000, size:0x40000)\n3XMCPUTIME               CPU usage total: 0.010221701 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=12736 (0x31C0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/Thread.sleepImpl(Native Method)\n4XESTACKTRACE                at java/lang/Thread.sleep(Thread.java:983)\n4XESTACKTRACE                at java/lang/Thread.sleep(Thread.java:966)\n4XESTACKTRACE                at TestClass.&lt;clinit&gt;(ClassInitLockBug.java:29)\n4XESTACKTRACE                at java/lang/Class.forNameImpl(Native Method)\n4XESTACKTRACE                at java/lang/Class.forName(Class.java:339)\n4XESTACKTRACE                at ClassInitLockBug$ClassInitThread.run(ClassInitLockBug.java:16)\n...\nNULL\n...\nNULL\n1XMTHDSUMMARY  Threads CPU Usage Summary\nNULL           =========================\nNULL\n1XMTHDCATINFO  Warning: to get more accurate CPU times for the GC, the option -XX:-ReduceCPUMonitorOverhead can be used. See the user guide for more information.\nNULL\n1XMTHDCATEGORY All JVM attached threads: 0.698865000 secs\n1XMTHDCATEGORY |\n2XMTHDCATEGORY +--System-JVM: 0.653723000 secs\n2XMTHDCATEGORY |  |\n3XMTHDCATEGORY |  +--GC: 0.047248000 secs\n2XMTHDCATEGORY |  |\n3XMTHDCATEGORY |  +--JIT: 0.512971000 secs\n1XMTHDCATEGORY |\n2XMTHDCATEGORY +--Application: 0.045142000 secs\n</code></pre>"},{"location":"dump_javadump/#hooks","title":"HOOKS","text":"<p>This section shows internal VM event callbacks, which are used for diagnosing performance problems in the VM. Multiple hook interfaces are listed, which include their individual hook events.</p> <p>The following example shows data for the <code>J9VMHookInterface</code>, including the total time for all previous events, the call site location (&lt;source file&gt;:&lt;line number&gt;), start time, and duration of the last callback and the longest callback (all times measured in microseconds). The hook data is reset after each Java dump.</p> <pre><code>NULL           ------------------------------------------------------------------------\nSECTION HOOK   subcomponent dump routine\nNULL           =========================\n1NOTE          These data are reset every time a javacore is taken\n1HKINTERFACE   MM_OMRHookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   MM_PrivateHookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   MM_HookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   J9VMHookInterface\nNULL           ------------------------------------------------------------------------\n2HKEVENTID     1\n3HKCALLCOUNT       1239\n3HKTOTALTIME       219564us\n3HKLAST            Last Callback\n4HKCALLSITE            trcengine.c:395\n4HKSTARTTIME           Start Time: 2019-10-18T00:15:14.664\n4HKDURATION            Duration : 16us\n3HKLONGST          Longest Callback\n4HKCALLSITE            trcengine.c:395\n4HKSTARTTIME           Start Time: 2019-10-18T21:28:34.895\n4HKDURATION            Duration : 5012us\nNULL\n...\n1HKINTERFACE   J9VMZipCachePoolHookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   J9JITHookInterface\nNULL           ------------------------------------------------------------------------\n2HKEVENTID     3\n3HKCALLCOUNT       3113\n3HKTOTALTIME       4904us\n3HKLAST            Last Callback\n4HKCALLSITE            common/mgmtinit.c:193\n4HKSTARTTIME           Start Time: 2019-10-18T16:04:15.320\n4HKDURATION            Duration : 3us\n3HKLONGST          Longest Callback\n4HKCALLSITE            common/mgmtinit.c:193\n4HKSTARTTIME           Start Time: 2019-10-18T16:37:17.633\n4HKDURATION            Duration : 27us\nNULL\n...\n</code></pre>"},{"location":"dump_javadump/#shared-classes","title":"SHARED CLASSES","text":"<p>If the shared classes cache is enabled at run time, the information that is provided in a Java dump file describes settings that were used when creating the cache, together with summary information about the size and content of the cache.</p> <p>In the following example, the shared classes cache was created with a Class Debug Area (<code>-Xnolinenumbers=false</code>). Byte code instrumentation (BCI) is enabled, which is the default, and VMs sharing the cache are allowed to store classpaths, which is also the default.</p> <p>The <code>Cache Summary</code> shows a cache size (<code>2SCLTEXTCSZ</code>) of 16776608 bytes, with a soft maximum size (<code>2SCLTEXTSMB</code>) also of 16776608 bytes, which leaves 12691668 bytes of free space (<code>2SCLTEXTFRB</code>). The size of the Class Debug Area (<code>2SCLTEXTDAS</code>) is 1331200 bytes and only 11% of this space is used.</p> <p>In the <code>Cache Memory Status</code> subsection, the line <code>2SCLTEXTCMDT</code> indicates the name and location of the shared cache and <code>cr</code> indicates that the cache is a 64-bit compressed references cache.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       SHARED CLASSES subcomponent dump routine\nNULL           ========================================\nNULL\n1SCLTEXTCRTW   Cache Created With\nNULL           ------------------\nNULL\n2SCLTEXTXNL        -Xnolinenumbers       = false\n2SCLTEXTBCI        BCI Enabled           = true\n2SCLTEXTBCI        Restrict Classpaths   = false\nNULL\n1SCLTEXTCSUM   Cache Summary\nNULL           ------------------\nNULL\n2SCLTEXTNLC        No line number content                    = false\n2SCLTEXTLNC        Line number content                       = true\nNULL\n2SCLTEXTRCS        ROMClass start address                    = 0x00007F423061C000\n2SCLTEXTRCE        ROMClass end address                      = 0x00007F42307B9A28\n2SCLTEXTMSA        Metadata start address                    = 0x00007F42313D42FC\n2SCLTEXTCEA        Cache end address                         = 0x00007F4231600000\n2SCLTEXTRTF        Runtime flags                             = 0x00102001ECA6028B\n2SCLTEXTCGN        Cache generation                          = 35\nNULL\n2SCLTEXTCSZ        Cache size                                = 16776608\n2SCLTEXTSMB        Softmx bytes                              = 16776608\n2SCLTEXTFRB        Free bytes                                = 12691668\n2SCLTEXTRCB        ROMClass bytes                            = 1694248\n2SCLTEXTAOB        AOT code bytes                            = 0\n2SCLTEXTADB        AOT data bytes                            = 0\n2SCLTEXTAHB        AOT class hierarchy bytes                 = 32\n2SCLTEXTATB        AOT thunk bytes                           = 0\n2SCLTEXTARB        Reserved space for AOT bytes              = -1\n2SCLTEXTAMB        Maximum space for AOT bytes               = -1\n2SCLTEXTJHB        JIT hint bytes                            = 308\n2SCLTEXTJPB        JIT profile bytes                         = 2296\n2SCLTEXTJRB        Reserved space for JIT data bytes         = -1\n2SCLTEXTJMB        Maximum space for JIT data bytes          = -1\n2SCLTEXTNOB        Java Object bytes                         = 0\n2SCLTEXTZCB        Zip cache bytes                           = 919328\n2SCLTEXTSHB        Startup hint bytes                        = 0\n2SCLTEXTRWB        ReadWrite bytes                           = 114080\n2SCLTEXTJCB        JCL data bytes                            = 0\n2SCLTEXTBDA        Byte data bytes                           = 0\n2SCLTEXTMDA        Metadata bytes                            = 23448\n2SCLTEXTDAS        Class debug area size                     = 1331200\n2SCLTEXTDAU        Class debug area % used                   = 11%\n2SCLTEXTDAN        Class LineNumberTable bytes               = 156240\n2SCLTEXTDAV        Class LocalVariableTable bytes            = 0\nNULL\n2SCLTEXTNRC        Number ROMClasses                         = 595\n2SCLTEXTNAM        Number AOT Methods                        = 0\n2SCLTEXTNAD        Number AOT Data Entries                   = 0\n2SCLTEXTNAH        Number AOT Class Hierarchy                = 1\n2SCLTEXTNAT        Number AOT Thunks                         = 0\n2SCLTEXTNJH        Number JIT Hints                          = 14\n2SCLTEXTNJP        Number JIT Profiles                       = 20\n2SCLTEXTNCP        Number Classpaths                         = 1\n2SCLTEXTNUR        Number URLs                               = 0\n2SCLTEXTNTK        Number Tokens                             = 0\n2SCLTEXTNOJ        Number Java Objects                       = 0\n2SCLTEXTNZC        Number Zip Caches                         = 5\n2SCLTEXTNSH        Number Startup Hint Entries               = 0\n2SCLTEXTNJC        Number JCL Entries                        = 0\n2SCLTEXTNST        Number Stale classes                      = 0\n2SCLTEXTPST        Percent Stale classes                     = 0%\nNULL\n2SCLTEXTCPF        Cache is 24% full\nNULL\n1SCLTEXTCMST   Cache Memory Status\nNULL           ------------------\n1SCLTEXTCNTD       Cache Name                    Feature                  Memory type              Cache path\nNULL\n2SCLTEXTCMDT       sharedcc_doc-javacore         CR                       Memory mapped file       /tmp/javasharedresources/C290M4F1A64P_sharedcc_doc-javacore_G35\nNULL\n1SCLTEXTCMST   Cache Lock Status\nNULL           ------------------\n1SCLTEXTCNTD       Lock Name                     Lock type                TID owning lock\nNULL\n2SCLTEXTCWRL       Cache write lock              File lock                Unowned\n2SCLTEXTCRWL       Cache read/write lock         File lock                Unowned\nNULL\n</code></pre> <p>The following example shows information for a layered cache:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       SHARED CLASSES subcomponent dump routine\nNULL           ========================================\nNULL\n1SCLTEXTCSTL   Cache Statistics for Top Layer\nNULL\n1SCLTEXTCRTW       Cache Created With\nNULL               ------------------\nNULL\n2SCLTEXTXNL            -Xnolinenumbers       = false\n2SCLTEXTBCI            BCI Enabled           = true\n2SCLTEXTBCI            Restrict Classpaths   = false\nNULL\n1SCLTEXTCSUM       Cache Summary\nNULL               ------------------\nNULL\n2SCLTEXTNLC            No line number content                    = false\n2SCLTEXTLNC            Line number content                       = false\nNULL\n2SCLTEXTRCS            ROMClass start address                    = 0x00007F0EDB567000\n2SCLTEXTRCE            ROMClass end address                      = 0x00007F0EDB567000\n2SCLTEXTMSA            Metadata start address                    = 0x00007F0EDC40241C\n2SCLTEXTCEA            Cache end address                         = 0x00007F0EDC54B000\n2SCLTEXTRTF            Runtime flags                             = 0x80102001ECA602BB\n2SCLTEXTCGN            Cache generation                          = 41\n2SCLTEXTCLY            Cache layer                               = 1\nNULL\n2SCLTEXTCSZ            Cache size                                = 16776608\n2SCLTEXTSMB            Softmx bytes                              = 16776608\n2SCLTEXTFRB            Free bytes                                = 15315996\n2SCLTEXTARB            Reserved space for AOT bytes              = -1\n2SCLTEXTAMB            Maximum space for AOT bytes               = -1\n2SCLTEXTJRB            Reserved space for JIT data bytes         = -1\n2SCLTEXTJMB            Maximum space for JIT data bytes          = -1\n2SCLTEXTRWB            ReadWrite bytes                           = 114080\n2SCLTEXTDAS            Class debug area size                     = 1331200\n2SCLTEXTDAU            Class debug area % used                   = 0%\n2SCLTEXTDAN            Class LineNumberTable bytes               = 0\n2SCLTEXTDAV            Class LocalVariableTable bytes            = 0\nNULL\n2SCLTEXTCPF            Cache is 8% full\nNULL\n1SCLTEXTCMST       Cache Memory Status\nNULL               ------------------\n1SCLTEXTCNTD           Cache Name                    Feature                  Memory type              Cache path\nNULL\n2SCLTEXTCMDT           Cache1                        CR                       Memory mapped file       /tmp/javasharedresources/C290M4F1A64P_Cache1_G41L01\nNULL\n1SCLTEXTCMST       Cache Lock Status\nNULL               ------------------\n1SCLTEXTCNTD           Lock Name                     Lock type                TID owning lock\nNULL\n2SCLTEXTCWRL           Cache write lock              File lock                Unowned\n2SCLTEXTCRWL           Cache read/write lock         File lock                Unowned\nNULL\n1SCLTEXTCSAL   Cache Statistics for All Layers\nNULL\n2SCLTEXTRCB            ROMClass bytes                            = 1459040\n2SCLTEXTAOB            AOT code bytes                            = 57624\n2SCLTEXTADB            AOT data bytes                            = 272\n2SCLTEXTAHB            AOT class hierarchy bytes                 = 1840\n2SCLTEXTATB            AOT thunk bytes                           = 632\n2SCLTEXTJHB            JIT hint bytes                            = 484\n2SCLTEXTJPB            JIT profile bytes                         = 0\n2SCLTEXTNOB            Java Object bytes                         = 0\n2SCLTEXTZCB            Zip cache bytes                           = 1134016\n2SCLTEXTSHB            Startup hint bytes                        = 0\n2SCLTEXTJCB            JCL data bytes                            = 0\n2SCLTEXTBDA            Byte data bytes                           = 0\nNULL\n2SCLTEXTNRC            Number ROMClasses                         = 503\n2SCLTEXTNAM            Number AOT Methods                        = 16\n2SCLTEXTNAD            Number AOT Data Entries                   = 1\n2SCLTEXTNAH            Number AOT Class Hierarchy                = 28\n2SCLTEXTNAT            Number AOT Thunks                         = 11\n2SCLTEXTNJH            Number JIT Hints                          = 15\n2SCLTEXTNJP            Number JIT Profiles                       = 0\n2SCLTEXTNCP            Number Classpaths                         = 1\n2SCLTEXTNUR            Number URLs                               = 0\n2SCLTEXTNTK            Number Tokens                             = 0\n2SCLTEXTNOJ            Number Java Objects                       = 0\n2SCLTEXTNZC            Number Zip Caches                         = 21\n2SCLTEXTNSH            Number Startup Hint Entries               = 0\n2SCLTEXTNJC            Number JCL Entries                        = 0\n2SCLTEXTNST            Number Stale classes                      = 0\n2SCLTEXTPST            Percent Stale classes                     = 0%\n</code></pre>"},{"location":"dump_javadump/#classes","title":"CLASSES","text":"<p>The classes section shows information about class loaders. The first part is a summary that records each available class loader (<code>2CLTEXTCLLOADER</code>) followed by the number of libraries and classes that it loaded. This information is followed by a more detailed list of libraries (<code>1CLTEXTCLLIB</code>) and classes (<code>1CLTEXTCLLO</code>) that are loaded.</p> <p>In the example you can see that the <code>java/lang/InternalAnonymousClassLoader</code> loaded two classes, <code>jdk/internal/loader/BuiltinClassLoader$$Lambda$2/00000000F03876A0(0x0000000001030F00)</code> and <code>jdk/internal/loader/BuiltinClassLoader$$Lambda$1/00000000F00D2460(0x0000000001018A00)</code>.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       CLASSES subcomponent dump routine\nNULL           =================================\n1CLTEXTCLLOS    Classloader summaries\n1CLTEXTCLLSS        12345678: 1=primordial,2=extension,3=shareable,4=middleware,5=system,6=trusted,7=application,8=delegating\n2CLTEXTCLLOADER     p---st-- Loader *System*(0x00000000FFE1D258)\n3CLNMBRLOADEDLIB        Number of loaded libraries 5\n3CLNMBRLOADEDCL         Number of loaded classes 638\n2CLTEXTCLLOADER     -x--st-- Loader jdk/internal/loader/ClassLoaders$PlatformClassLoader(0x00000000FFE1D4F0), Parent *none*(0x0000000000000000)\n3CLNMBRLOADEDLIB        Number of loaded libraries 0\n3CLNMBRLOADEDCL         Number of loaded classes 0\n2CLTEXTCLLOADER     ----st-- Loader java/lang/InternalAnonymousClassLoader(0x00000000FFE1DFD0), Parent *none*(0x0000000000000000)\n3CLNMBRLOADEDLIB        Number of loaded libraries 0\n3CLNMBRLOADEDCL         Number of loaded classes 2\n2CLTEXTCLLOADER     -----ta- Loader jdk/internal/loader/ClassLoaders$AppClassLoader(0x00000000FFE1DAD0), Parent jdk/internal/loader/ClassLoaders$PlatformClassLoader(0x00000000FFE1D4F0)\n3CLNMBRLOADEDLIB        Number of loaded libraries 0\n3CLNMBRLOADEDCL         Number of loaded classes 0\n1CLTEXTCLLIB    ClassLoader loaded libraries\n2CLTEXTCLLIB        Loader *System*(0x00000000FFE1D258)\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/compressedrefs/jclse9_29\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/java\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/compressedrefs/j9jit29\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/zip\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/nio\n1CLTEXTCLLOD    ClassLoader loaded classes\n2CLTEXTCLLOAD       Loader *System*(0x00000000FFE1D258)\n3CLTEXTCLASS            [Ljava/lang/Thread$State;(0x0000000001056400)\n...\n2CLTEXTCLLOAD       Loader jdk/internal/loader/ClassLoaders$PlatformClassLoader(0x00000000FFE1D4F0)\n2CLTEXTCLLOAD       Loader java/lang/InternalAnonymousClassLoader(0x00000000FFE1DFD0)\n3CLTEXTCLASS            jdk/internal/loader/BuiltinClassLoader$$Lambda$2/00000000F03876A0(0x0000000001030F00)\n3CLTEXTCLASS            jdk/internal/loader/BuiltinClassLoader$$Lambda$1/00000000F00D2460(0x0000000001018A00)\n2CLTEXTCLLOAD       Loader jdk/internal/loader/ClassLoaders$AppClassLoader(0x00000000FFE1DAD0)\n</code></pre>"},{"location":"dump_javadump/#scenarios","title":"Scenarios","text":""},{"location":"dump_javadump/#general-protection-fault","title":"General Protection Fault","text":"<p>In this scenario, a Java application has crashed due to a General Protection Fault (GPF), automatically generating a Java dump file.</p> <p>The first section of the file (TITLE) tells you that the GPF triggered the Java dump.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"gpf\" (00002000) received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/test/JNICrasher/javacore.20210423.140244.29399.0002.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x100 (trace_disabled)\n1TIPREPINFO    Exclusive VM access not taken: data may not be consistent across javacore sections\n</code></pre> <p>To troubleshoot this problem, you need to know which thread caused the GPF to occur. The thread that was running at the time of the crash is reported as the current thread in the THREADS section of the Java dump. Here is an extract from the THREADS section:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 16\n2XMPOOLLIVE        Current total number of live threads: 15\n2XMPOOLDAEMON      Current total number of live daemon threads: 14\nNULL\n1XMCURTHDINFO  Current thread\n3XMTHREADINFO      \"main\" J9VMThread:0xB6B60E00, omrthread_t:0xB6B049D8, java/lang/Thread:0xB55444D0, state:R, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x1, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x72D8, native priority:0x5, native policy:UNKNOWN, vmstate:R, vm thread flags:0x00000000)\n3XMTHREADINFO2            (native stack address range from:0xB6CE3000, to:0xB74E4000, size:0x801000)\n3XMCPUTIME               CPU usage total: 0.319865924 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=778008 (0xBDF18)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at JNICrasher.doSomethingThatCrashes(Native Method)\n4XESTACKTRACE                at JNICrasher.main(JNICrasher.java:7)\n3XMTHREADINFO3           Native callstack:\n4XENATIVESTACK               (0xB6C6F663 [libj9prt29.so+0x3b663])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6C6F1CE [libj9prt29.so+0x3b1ce])\n4XENATIVESTACK               (0xB6C6F2C6 [libj9prt29.so+0x3b2c6])\n4XENATIVESTACK               (0xB6C6ED93 [libj9prt29.so+0x3ad93])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6C6ED07 [libj9prt29.so+0x3ad07])\n4XENATIVESTACK               (0xB6C6AA3D [libj9prt29.so+0x36a3d])\n4XENATIVESTACK               (0xB6C6C3A4 [libj9prt29.so+0x383a4])\n4XENATIVESTACK               (0xB667FA19 [libj9dmp29.so+0xfa19])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB66878CF [libj9dmp29.so+0x178cf])\n4XENATIVESTACK               (0xB6688083 [libj9dmp29.so+0x18083])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6680C0D [libj9dmp29.so+0x10c0d])\n4XENATIVESTACK               (0xB667F9D7 [libj9dmp29.so+0xf9d7])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB668B02F [libj9dmp29.so+0x1b02f])\n4XENATIVESTACK               (0xB668B4D3 [libj9dmp29.so+0x1b4d3])\n4XENATIVESTACK               (0xB66740F1 [libj9dmp29.so+0x40f1])\n4XENATIVESTACK               (0xB66726FA [libj9dmp29.so+0x26fa])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB66726A9 [libj9dmp29.so+0x26a9])\n4XENATIVESTACK               (0xB6676AE4 [libj9dmp29.so+0x6ae4])\n4XENATIVESTACK               (0xB668D75A [libj9dmp29.so+0x1d75a])\n4XENATIVESTACK               (0xB6A28DD4 [libj9vm29.so+0x81dd4])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6A289EE [libj9vm29.so+0x819ee])\n4XENATIVESTACK               (0xB6A29A40 [libj9vm29.so+0x82a40])\n4XENATIVESTACK               (0xB6C52B6A [libj9prt29.so+0x1eb6a])\n4XENATIVESTACK               __kernel_rt_sigreturn+0x0 (0xB7747410)\n4XENATIVESTACK               (0xB75330B6 [libffi29.so+0x50b6])\n4XENATIVESTACK               ffi_raw_call+0xad (0xB7531C53 [libffi29.so+0x3c53])\n4XENATIVESTACK               (0xB69BE4AB [libj9vm29.so+0x174ab])\n4XENATIVESTACK               (0xB6A665BC [libj9vm29.so+0xbf5bc])\n4XENATIVESTACK               (0xB6A15552 [libj9vm29.so+0x6e552])\n4XENATIVESTACK               (0xB6A30894 [libj9vm29.so+0x89894])\n4XENATIVESTACK               (0xB6A6F169 [libj9vm29.so+0xc8169])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6A6F1FA [libj9vm29.so+0xc81fa])\n4XENATIVESTACK               (0xB6A30994 [libj9vm29.so+0x89994])\n4XENATIVESTACK               (0xB6A2CE4C [libj9vm29.so+0x85e4c])\n4XENATIVESTACK               (0xB770487D [libjli.so+0x787d])\n4XENATIVESTACK               (0xB7719F72 [libpthread.so.0+0x6f72])\n4XENATIVESTACK               clone+0x5e (0xB763543E [libc.so.6+0xee43e])\n</code></pre> <p>The extract tells you that the current thread was <code>java/lang/Thread</code>, and information is provided about the Java call stack and native call stack (<code>3XMTHREADINFO3</code>) at the point at which the crash occurred. To simulate a crash caused by a bug in an application, this example calls a JNI method whose native implementation causes a crash. The Java call stack shows the call to the JNI native method (<code>JNIcrasher</code>), and the native call stack shows the point of failure. In this example, the native call stack does not include any function names to help you isolate the error in the native code. You can get this information from a system dump, which is usually produced alongside the Java dump. Open the system dump with the Dump viewer and use the <code>info thread</code> command to print the Java and native stack for the current thread.</p> <p>The next time you run the application, you can use the -XX:+ShowNativeStackSymbols=all command line option to display the corresponding function names in the native call stack.</p> <pre><code>4XENATIVESTACK               protectedBacktrace+0x12 (0x00007F3F9213E312 [libj9prt29.so+0x25312])\n4XENATIVESTACK               omrsig_protect+0x1e3 (0x00007F3F92142AD3 [libj9prt29.so+0x29ad3])\n4XENATIVESTACK               omrintrospect_backtrace_thread_raw+0xbf (0x00007F3F9213E80F [libj9prt29.so+0x2580f])\n4XENATIVESTACK               omrsig_protect+0x1e3 (0x00007F3F92142AD3 [libj9prt29.so+0x29ad3])\n4XENATIVESTACK               omrintrospect_backtrace_thread+0x70 (0x00007F3F9213E1D0 [libj9prt29.so+0x251d0])\n4XENATIVESTACK               setup_native_thread+0x1d2 (0x00007F3F9213F652 [libj9prt29.so+0x26652])\n4XENATIVESTACK               omrintrospect_threads_startDo_with_signal+0x474 (0x00007F3F921403F4 [libj9prt29.so+0x273f4])\n4XENATIVESTACK               omrsig_protect+0x1e3 (0x00007F3F92142AD3 [libj9prt29.so+0x29ad3])\n</code></pre>"},{"location":"dump_javadump/#java-outofmemoryerror","title":"Java OutOfMemoryError","text":"<p>In this scenario, the Java heap runs out of memory, causing an <code>OutOfMemoryError</code>, which automatically generates a Java dump file.</p> <p>The first section of the file (TITLE) tells you that a <code>systhrow</code> event triggered the Java dump as a result of an OOM (<code>java/lang/OutOfMemoryError</code>) for Java heap space.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"systhrow\" (00040000) Detail \"java/lang/OutOfMemoryError\" \"Java heap space\" received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/cheesemp/test/javacore.20210423.140244.18885.0003.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x104 (exclusive_vm_access+trace_disabled)\n</code></pre> <p>The MEMINFO section records how much memory is allocated to the Java heap (<code>1STHEAPTYPE Object Memory</code>), how much is in use, and how much is free. Solving your problem might be as simple as setting a larger heap size when you start your application.</p> <p>If you don't know what size the Java heap was set to, you might find that information in the ENVINFO section, which records the command-line options that were used when the application started. Look or search for the <code>1CIUSERARGS    UserArgs:</code> string and review the entries that are recorded for all lines that start <code>2CIUSERARG</code>. The Java heap size is set by the <code>-Xmx</code> option. If the size has not been set on the command line by <code>-Xmx</code>, the default value applies, which you can find in Default Settings.</p> <p>In this scenario, the solution to the problem is not an adjustment to the Java heap size. Here is the MEMINFO section:</p> <pre><code>0SECTION       MEMINFO subcomponent dump routine\nNULL           =================================\nNULL\n1STHEAPTYPE    Object Memory\nNULL           id         start      end        size       space/region\n1STHEAPSPACE   0xB6B49D20     --         --         --     Generational\n1STHEAPREGION  0xB6B4A078 0x95750000 0xB5470000 0x1FD20000 Generational/Tenured Region\n1STHEAPREGION  0xB6B49F10 0xB5470000 0xB54C0000 0x00050000 Generational/Nursery Region\n1STHEAPREGION  0xB6B49DA8 0xB54C0000 0xB5750000 0x00290000 Generational/Nursery Region\nNULL\n1STHEAPTOTAL   Total memory:         536870912 (0x20000000)\n1STHEAPINUSE   Total memory in use:  302603160 (0x12095B98)\n1STHEAPFREE    Total memory free:    234267752 (0x0DF6A468)\n</code></pre> <p>The output shows that only 56% of the Java heap is in use, so this suggests that the application is trying to do something suboptimal. To investigate further, you need to work out which thread was the current thread when the OOM occurred to see what it was trying to do. As in the previous scenario, you can find the current thread in the THREADS section. Here is an extract from the output:</p> <pre><code>0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 16\n2XMPOOLLIVE        Current total number of live threads: 16\n2XMPOOLDAEMON      Current total number of live daemon threads: 15\nNULL\n1XMCURTHDINFO  Current thread\n3XMTHREADINFO      \"main\" J9VMThread:0xB6B60C00, omrthread_t:0xB6B049D8, java/lang/Thread:0x95764520, state:R, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x1, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x49C6, native priority:0x5, native policy:UNKNOWN, vmstate:R, vm thread flags:0x00001020)\n3XMTHREADINFO2            (native stack address range from:0xB6CB5000, to:0xB74B6000, size:0x801000)\n3XMCPUTIME               CPU usage total: 8.537823831 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/StringBuffer.ensureCapacityImpl(StringBuffer.java:696)\n4XESTACKTRACE                at java/lang/StringBuffer.append(StringBuffer.java:486(Compiled Code))\n5XESTACKTRACE                   (entered lock: java/lang/StringBuffer@0x957645B8, entry count: 1)\n4XESTACKTRACE                at java/lang/StringBuffer.append(StringBuffer.java:428(Compiled Code))\n4XESTACKTRACE                at HeapBreaker.main(HeapBreaker.java:34(Compiled Code))\n3XMTHREADINFO3           Native callstack:\n4XENATIVESTACK               (0xB6C535B3 [libj9prt29.so+0x3b5b3])\n4XENATIVESTACK               (0xB6C36F3E [libj9prt29.so+0x1ef3e])\n4XENATIVESTACK               (0xB6C5311E [libj9prt29.so+0x3b11e])\n4XENATIVESTACK               (0xB6C53216 [libj9prt29.so+0x3b216])\n4XENATIVESTACK               (0xB6C52CE3 [libj9prt29.so+0x3ace3])\n4XENATIVESTACK               (0xB6C36F3E [libj9prt29.so+0x1ef3e])\n4XENATIVESTACK               (0xB6C52C57 [libj9prt29.so+0x3ac57])\n4XENATIVESTACK               (0xB6C4E9CD [libj9prt29.so+0x369cd])\n4XENATIVESTACK               (0xB6C502FA [libj9prt29.so+0x382fa])\n</code></pre> <p>To simulate a Java <code>OutOfMemoryError</code>, this example application repeatedly appends characters to a <code>StringBuffer</code> object in an infinite loop. The Java call stack shows the <code>HeapBreaker.main</code> method appending characters (<code>java/lang/StringGuffer.append</code>) until the method <code>java/lang/StringBuffer.ensureCapacityImpl()</code> throws the <code>OutOfMemoryError</code>.</p> <p>StringBuffer objects are wrappers for character arrays (<code>char[]</code>) and when the capacity of the underlying array is reached, the contents are automatically copied into a new, larger array. The new array is created in the <code>StringBuffer.ensureCapacity()</code> method, which more or less doubles the size of the old array. In this scenario, the array takes up all the remaining space in the Java heap.</p> <p>The MEMINFO section of the Java dump file can also tell you when an unexpectedly large allocation request causes an OOM. Look for the GC History (<code>1STGCHTYPE</code>) section, which details allocation requests that trigger GC activity. In the sample output you can see that a large allocation request (<code>requestedbytes=603979784</code>) triggered a global GC. When the GC could not free up sufficient space in the heap to satisfy the request, the allocation failure generated the OOM.</p> <pre><code>1STGCHTYPE     GC History\n3STHSTTYPE     14:29:29:580239000 GMT j9mm.101 -   J9AllocateIndexableObject() returning NULL! 0 bytes requested for object of class B6BBC300 from memory space 'Generational' id=B6B49D20\n3STHSTTYPE     14:29:29:579916000 GMT j9mm.134 -   Allocation failure end: newspace=2686912/3014656 oldspace=231597224/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:579905000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2686912/3014656 oldspace=231597224/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:579859000 GMT j9mm.475 -   GlobalGC end: workstackoverflow=0 overflowcount=0 memory=234284136/536870912\n3STHSTTYPE     14:29:29:579807000 GMT j9mm.90 -   GlobalGC collect complete\n3STHSTTYPE     14:29:29:579776000 GMT j9mm.137 -   Compact end: bytesmoved=301989896\n3STHSTTYPE     14:29:29:313899000 GMT j9mm.136 -   Compact start: reason=compact to meet allocation\n3STHSTTYPE     14:29:29:313555000 GMT j9mm.57 -   Sweep end\n3STHSTTYPE     14:29:29:310772000 GMT j9mm.56 -   Sweep start\n3STHSTTYPE     14:29:29:310765000 GMT j9mm.94 -   Class unloading end: classloadersunloaded=0 classesunloaded=0\n3STHSTTYPE     14:29:29:310753000 GMT j9mm.60 -   Class unloading start\n3STHSTTYPE     14:29:29:310750000 GMT j9mm.55 -   Mark end\n3STHSTTYPE     14:29:29:306013000 GMT j9mm.54 -   Mark start\n3STHSTTYPE     14:29:29:305957000 GMT j9mm.474 -   GlobalGC start: globalcount=9\n3STHSTTYPE     14:29:29:305888000 GMT j9mm.475 -   GlobalGC end: workstackoverflow=0 overflowcount=0 memory=234284136/536870912\n3STHSTTYPE     14:29:29:305837000 GMT j9mm.90 -   GlobalGC collect complete\n3STHSTTYPE     14:29:29:305808000 GMT j9mm.137 -   Compact end: bytesmoved=189784\n3STHSTTYPE     14:29:29:298042000 GMT j9mm.136 -   Compact start: reason=compact to meet allocation\n3STHSTTYPE     14:29:29:297695000 GMT j9mm.57 -   Sweep end\n3STHSTTYPE     14:29:29:291696000 GMT j9mm.56 -   Sweep start\n3STHSTTYPE     14:29:29:291692000 GMT j9mm.55 -   Mark end\n3STHSTTYPE     14:29:29:284994000 GMT j9mm.54 -   Mark start\n3STHSTTYPE     14:29:29:284941000 GMT j9mm.474 -   GlobalGC start: globalcount=8\n3STHSTTYPE     14:29:29:284916000 GMT j9mm.135 -   Exclusive access: exclusiveaccessms=0.016 meanexclusiveaccessms=0.016 threads=0 lastthreadtid=0xB6B61100 beatenbyotherthread=0\n3STHSTTYPE     14:29:29:284914000 GMT j9mm.469 -   Allocation failure cycle start: newspace=2678784/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=603979784\n3STHSTTYPE     14:29:29:284893000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2678784/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:284858000 GMT j9mm.560 -   LocalGC end: rememberedsetoverflow=0 causedrememberedsetoverflow=0 scancacheoverflow=0 failedflipcount=0 failedflipbytes=0 failedtenurecount=0 failedtenurebytes=0 flipcount=2 flipbytes=64 newspace=2678784/3014656 oldspace=80601248/533856256 loa=5338112/5338112 tenureage=0\n3STHSTTYPE     14:29:29:284140000 GMT j9mm.140 -   Tilt ratio: 89\n3STHSTTYPE     14:29:29:283160000 GMT j9mm.64 -   LocalGC start: globalcount=8 scavengecount=335 weakrefs=0 soft=0 phantom=0 finalizers=0\n3STHSTTYPE     14:29:29:283123000 GMT j9mm.135 -   Exclusive access: exclusiveaccessms=0.016 meanexclusiveaccessms=0.016 threads=0 lastthreadtid=0xB6B61100 beatenbyotherthread=0\n3STHSTTYPE     14:29:29:283120000 GMT j9mm.469 -   Allocation failure cycle start: newspace=753616/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=603979784\n3STHSTTYPE     14:29:29:283117000 GMT j9mm.133 -   Allocation failure start: newspace=753616/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=603979784\n3STHSTTYPE     14:29:29:269762000 GMT j9mm.134 -   Allocation failure end: newspace=2686928/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:269751000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:269718000 GMT j9mm.560 -   LocalGC end: rememberedsetoverflow=0 causedrememberedsetoverflow=0 scancacheoverflow=0 failedflipcount=0 failedflipbytes=0 failedtenurecount=0 failedtenurebytes=0 flipcount=0 flipbytes=0 newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112 tenureage=0\n3STHSTTYPE     14:29:29:268981000 GMT j9mm.140 -   Tilt ratio: 89\n3STHSTTYPE     14:29:29:268007000 GMT j9mm.64 -   LocalGC start: globalcount=8 scavengecount=334 weakrefs=0 soft=0 phantom=0 finalizers=0\n3STHSTTYPE     14:29:29:267969000 GMT j9mm.135 -   Exclusive access: exclusiveaccessms=0.016 meanexclusiveaccessms=0.016 threads=0 lastthreadtid=0xB6B61100 beatenbyotherthread=0\n3STHSTTYPE     14:29:29:267966000 GMT j9mm.469 -   Allocation failure cycle start: newspace=0/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=48\n3STHSTTYPE     14:29:29:267963000 GMT j9mm.133 -   Allocation failure start: newspace=0/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=48\n3STHSTTYPE     14:29:29:249015000 GMT j9mm.134 -   Allocation failure end: newspace=2686928/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:249003000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:248971000 GMT j9mm.560 -   LocalGC end: rememberedsetoverflow=0 causedrememberedsetoverflow=0 scancacheoverflow=0 failedflipcount=0 failedflipbytes=0 failedtenurecount=0 failedtenurebytes=0 flipcount=0 flipbytes=0 newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112 tenureage=0\n</code></pre> <p>Although the Java code that was used in this scenario deliberately triggered an <code>OutOfMemoryError</code> in a pronounced way, similar allocation issues can and do occur when dealing with large data sets such as XML files.</p> <p>The next step in diagnosing the problem is to open the system dump that gets generated automatically when an <code>OutOfMemoryError</code> occurs. Open the dump with the Eclipse Memory Analyzer\u2122 tool (MAT) and search for the <code>StringBuffer</code> object, which should provide further clues about what went wrong. A common example is seeing the same <code>String</code> duplicated over and over again, which might indicate that code is stuck in a loop.</p> <p> Note: If you want to use MAT to analyze your system dump, you must install the Diagnostic Tool Framework for Java (DTFJ) plug-in in the Eclipse IDE. Select the following menu items:</p> <pre><code>Help &gt; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt;\n</code></pre> <p>If, unlike the previous scenario, you receive an <code>OutOfMemoryError</code> and the MEMINFO section shows that there is very little space left on the Java heap, the current thread information is typically not important. The current thread is simply the thread that happened to be current when the space ran out. In this situation, you might want to increase your Java heap size. For help with this task, see How to do heap sizing.</p>"},{"location":"dump_javadump/#native-outofmemoryerror","title":"Native OutOfMemoryError","text":"<p>In this scenario, the VM runs out of native memory. Native memory is memory that is used by the VM for storing all virtualized resources and data that it needs for VM operations. Native memory that is available to the VM process is limited by the operating system. The native memory available to the VM might also be subject to additional limits imposed by the operating system, for example Unix <code>ulimits</code>.</p> <p>When a <code>NativeOutOfMemoryError</code> occurs, a Java dump is generated by default. The first section of the file (TITLE) tells you that a systhrow event triggered the Java dump as a result of an OOM (<code>java/lang/OutOfMemoryError</code>) for native memory.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"systhrow\" (00040000) Detail \"java/lang/OutOfMemoryError\" \"native memory exhausted\" received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/cheesemp/test/javacore.20210423.140244.19708.0003.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x104 (exclusive_vm_access+trace_disabled)\n</code></pre> <p>Sometimes, the current thread is responsible for causing the <code>NativeOutOfMemoryError</code>. Information about the current thread can be found in the THREADS section, as shown in the following output.</p> <pre><code>0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 16\n2XMPOOLLIVE        Current total number of live threads: 16\n2XMPOOLDAEMON      Current total number of live daemon threads: 15\nNULL\n1XMCURTHDINFO  Current thread\n3XMTHREADINFO      \"main\" J9VMThread:0xB6C60C00, omrthread_t:0xB6C049D8, java/lang/Thread:0xB55E3C10, state:R, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x1, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x4CFD, native priority:0x5, native policy:UNKNOWN, vmstate:R, vm thread flags:0x00001020)\n3XMTHREADINFO2            (native stack address range from:0xB6D4E000, to:0xB754F000, size:0x801000)\n3XMCPUTIME               CPU usage total: 3.654896026 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at sun/misc/Unsafe.allocateDBBMemory(Native Method)\n4XESTACKTRACE                at java/nio/DirectByteBuffer.&lt;init&gt;(DirectByteBuffer.java:127(Compiled Code))\n4XESTACKTRACE                at java/nio/ByteBuffer.allocateDirect(ByteBuffer.java:311)\n4XESTACKTRACE                at NativeHeapBreaker.main(NativeHeapBreaker.java:9)\n3XMTHREADINFO3           Native callstack:\n4XENATIVESTACK               (0xB6A9F5B3 [libj9prt29.so+0x3b5b3])\n...\n4XENATIVESTACK               (0xB582CC9C [libjclse7b_29.so+0x40c9c])\n4XENATIVESTACK               Java_sun_misc_Unsafe_allocateDBBMemory+0x88 (0xB5827F6B [libjclse7b_29.so+0x3bf6b])\n4XENATIVESTACK               (0x94A2084A [&lt;unknown&gt;+0x0])\n4XENATIVESTACK               (0xB6B2538B [libj9vm29.so+0x6c38b])\n4XENATIVESTACK               (0xB6B4074C [libj9vm29.so+0x8774c])\n4XENATIVESTACK               (0xB6B7F299 [libj9vm29.so+0xc6299])\n4XENATIVESTACK               (0xB6A82F3E [libj9prt29.so+0x1ef3e])\n4XENATIVESTACK               (0xB6B7F32A [libj9vm29.so+0xc632a])\n4XENATIVESTACK               (0xB6B4084C [libj9vm29.so+0x8784c])\n4XENATIVESTACK               (0xB6B3CD0C [libj9vm29.so+0x83d0c])\n4XENATIVESTACK               (0xB776F87D [libjli.so+0x787d])\n4XENATIVESTACK               (0xB7784F72 [libpthread.so.0+0x6f72])\n4XENATIVESTACK               clone+0x5e (0xB76A043E [libc.so.6+0xee43e])\n</code></pre> <p>For clarity in the <code>Native callstack</code> output, <code>...</code> indicates that some lines are removed.</p> <p>The Java call stack shows the transition from Java to native code (<code>sun/misc/Unsafe.allocateDBBMemory(Native Method)</code>), indicating a request for Direct Byte Buffer (DBB) storage. DBB storage is backed by native memory, with the Java heap containing only a reference to the native heap buffer. In this scenario, DBB storage is the likely culprit for this <code>NativeOutOfMemoryError</code>.</p> <p>The next step is to investigate the NATIVEMEMINFO section of the Java dump file, which reports the amount of memory used by the JRE process, broken down into component areas.</p> <pre><code>0SECTION       NATIVEMEMINFO subcomponent dump routine\nNULL           =================================\n0MEMUSER\n1MEMUSER       JRE: 3,166,386,688 bytes / 4388 allocations\n1MEMUSER       |\n2MEMUSER       +--VM: 563,176,824 bytes / 1518 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Classes: 3,104,416 bytes / 120 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Memory Manager (GC): 548,181,888 bytes / 398 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Heap: 536,932,352 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 11,249,536 bytes / 397 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Threads: 10,817,120 bytes / 147 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Stack: 115,584 bytes / 16 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Native Stack: 10,616,832 bytes / 17 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 84,704 bytes / 114 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Trace: 163,688 bytes / 268 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JVMTI: 17,320 bytes / 13 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JNI: 23,296 bytes / 55 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Port Library: 8,576 bytes / 74 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 860,520 bytes / 443 allocations\n1MEMUSER       |\n2MEMUSER       +--JIT: 3,744,728 bytes / 122 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Code Cache: 2,097,152 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Data Cache: 524,336 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 1,123,240 bytes / 120 allocations\n1MEMUSER       |\n2MEMUSER       +--Class Libraries: 2,599,463,024 bytes / 2732 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Harmony Class Libraries: 1,024 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--VM Class Libraries: 2,599,462,000 bytes / 2731 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--sun.misc.Unsafe: 2,598,510,480 bytes / 2484 allocations\n4MEMUSER       |  |  |  |\n5MEMUSER       |  |  |  +--Direct Byte Buffers: 2,598,510,480 bytes / 2484 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 951,520 bytes / 247 allocations\n1MEMUSER       |\n2MEMUSER       +--Unknown: 2,112 bytes / 16 allocations\nNULL\n</code></pre> <p>In the <code>VM Class Libraries</code> section, the amount of memory allocated for <code>Direct Byte Buffers</code> is shown. Because the <code>NativeOutOfMemoryError</code> was received on a small 32-bit system, a value of <code>2,598,510,480 bytes</code> indicates that the operating system has run out of memory. On a larger UNIX\u00ae system, the process might have run out of memory because of the <code>ulimit</code> setting. Increasing the value for <code>ulimit</code> might avoid the error, which you can do temporarily by setting <code>ulimit -f unlimited</code> in your current session.</p> <p>The theoretical maximum size for a 32-bit process is the size of the 32-bit address space, which is 4 GB. On most operating systems, a portion of the address space for each process is used by the kernel, such that the real limit for 32-bit processes is actually significantly less than 4 GB. As a result, running out of native memory with a 32-bit VM is quite common.</p> <p>The same 4 GB limit is also important if you are using a 64-bit VM with compressed references. In compressed references mode, all references to objects, classes, threads, and monitors are represented by 32-bit values for performance reasons, so these structures can be allocated only at 32-bit addresses. However, the operating system might place other allocations within this 4 GB of address space, and if this area becomes sufficiently full or fragmented, the VM throws a native <code>NativeOutOfMemoryError</code> error. These errors typically occur when the VM tries to create a new thread or load a class. The Current Thread History section should contain more information about what the thread was doing at the VM level when the <code>NativeOutOfMemoryError</code> error occurred.</p> <p>You can usually avoid this type of problem by using the <code>-Xmcrs</code> option to reserve a contiguous area of memory within the lowest 4 GB of memory at VM startup.</p> <p>Another common cause of a <code>NativeOutOfMemoryError</code> is when an application loads duplicate classes. Classes are allocated outside of the Java heap in native memory. If the value reported for <code>Classes</code> in the NATIVEMEMINFO section is very large, duplicate classes might be the cause of your problem. The Eclipse Memory Analyzer tool (MAT) can tell you if you have duplicate classes by using the Class Loader Explorer feature. Because a system dump is automatically generated as well as a Java dump in response to a <code>NativeOutOfMemoryError</code>, simply open the system dump in MAT to continue your diagnosis.</p>"},{"location":"dump_javadump/#deadlock","title":"Deadlock","text":"<p>Deadlocks occur when two threads attempt to synchronize on an object and lock an instance of a class. When this happens, your application stops responding and hangs. Generating a Java dump file will quickly tell you whether you have a deadlock situation. Trigger the Java dump by sending a SIGQUIT signal (<code>kill -3</code>) to the VM.</p> <p>The VM can detect the most common types of deadlock scenario involving Java monitors. If this type of deadlock is detected, information is provided in the LOCKS section. More complex deadlocks, including those that involve a mixture of native mutexes and Java monitors, are not detected.</p> <p>Here is the output from the code that was used to cause a common deadlock scenario:</p> <pre><code>NULL\n1LKDEADLOCK    Deadlock detected !!!\nNULL           ---------------------\nNULL\n2LKDEADLOCKTHR  Thread \"Worker Thread 2\" (0x94501D00)\n3LKDEADLOCKWTR    is waiting for:\n4LKDEADLOCKMON      sys_mon_t:0x08C2B344 infl_mon_t: 0x08C2B384:\n4LKDEADLOCKOBJ      java/lang/Object@0xB5666698\n3LKDEADLOCKOWN    which is owned by:\n2LKDEADLOCKTHR  Thread \"Worker Thread 3\" (0x94507500)\n3LKDEADLOCKWTR    which is waiting for:\n4LKDEADLOCKMON      sys_mon_t:0x08C2B3A0 infl_mon_t: 0x08C2B3E0:\n4LKDEADLOCKOBJ      java/lang/Object@0xB5666678\n3LKDEADLOCKOWN    which is owned by:\n2LKDEADLOCKTHR  Thread \"Worker Thread 1\" (0x92A3EC00)\n3LKDEADLOCKWTR    which is waiting for:\n4LKDEADLOCKMON      sys_mon_t:0x08C2B2E8 infl_mon_t: 0x08C2B328:\n4LKDEADLOCKOBJ      java/lang/Object@0xB5666688\n3LKDEADLOCKOWN    which is owned by:\n2LKDEADLOCKTHR  Thread \"Worker Thread 2\" (0x94501D00)\n</code></pre> <p>This output tells you that <code>Worker Thread 2</code> is waiting for <code>Worker Thread 3</code>, which is waiting for <code>Worker Thread 1</code>. Because <code>Worker Thread 1</code> is also waiting for <code>Worker Thread 2</code>, there is a deadlock. The next place to look is the output for Java and native stacks, in the THREADS section. By looking at the stack for each of these worker threads, you can trace the problem back to specific lines in your application code.</p> <p>In this example, you can see from the following output that for all worker threads, the stack traces (<code>4XESTACKTRACE</code>/<code>5XESTACKTRACE</code>) indicate a problem in line 35 of the application <code>DeadLockTest.java</code>:</p> <pre><code>3XMTHREADINFO      \"Worker Thread 1\" J9VMThread:0x92A3EC00, omrthread_t:0x92A3C2B0, java/lang/Thread:0xB5666778, state:B, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x13, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x52CF, native priority:0x5, native policy:UNKNOWN, vmstate:B, vm thread flags:0x00000201)\n3XMTHREADINFO2            (native stack address range from:0x9297E000, to:0x929BF000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.004365543 secs, current category=\"Application\"\n3XMTHREADBLOCK     Blocked on: java/lang/Object@0xB5666688 Owned by: \"Worker Thread 2\" (J9VMThread:0x94501D00, java/lang/Thread:0xB56668D0)\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at WorkerThread.run(DeadLockTest.java:35)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB5666678, entry count: 1)\n...\n3XMTHREADINFO      \"Worker Thread 2\" J9VMThread:0x94501D00, omrthread_t:0x92A3C8F0, java/lang/Thread:0xB56668D0, state:B, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x14, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x52D0, native priority:0x5, native policy:UNKNOWN, vmstate:B, vm thread flags:0x00000201)\n3XMTHREADINFO2            (native stack address range from:0x946BF000, to:0x94700000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.004555580 secs, current category=\"Application\"\n3XMTHREADBLOCK     Blocked on: java/lang/Object@0xB5666698 Owned by: \"Worker Thread 3\" (J9VMThread:0x94507500, java/lang/Thread:0xB5666A18)\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at WorkerThread.run(DeadLockTest.java:35)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB5666688, entry count: 1)\n...\n3XMTHREADINFO      \"Worker Thread 3\" J9VMThread:0x94507500, omrthread_t:0x92A3CC10, java/lang/Thread:0xB5666A18, state:B, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x15, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x52D1, native priority:0x5, native policy:UNKNOWN, vmstate:B, vm thread flags:0x00000201)\n3XMTHREADINFO2            (native stack address range from:0x9467E000, to:0x946BF000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.003657010 secs, current category=\"Application\"\n3XMTHREADBLOCK     Blocked on: java/lang/Object@0xB5666678 Owned by: \"Worker Thread 1\" (J9VMThread:0x92A3EC00, java/lang/Thread:0xB5666778)\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at WorkerThread.run(DeadLockTest.java:35)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB5666698, entry count: 1)\n</code></pre>"},{"location":"dump_javadump/#hang","title":"Hang","text":"<p>An application can hang for a number of reasons but the most common cause is excessive global garbage collection (GC) activity, where your application is repeatedly paused because your Java heap has almost run out of memory. You can identify this problem by looking at verbose GC output. Collect this output by specifying the <code>-verbose:gc</code> option.</p> <p>Deadlock situations can also manifest themselves as hangs. For more information on diagnosing this type of problem from a Java dump, see the deadlock scenario.</p> <p>If you have eliminated verbose GC activity and deadlocks, another common hang scenario involves threads that compete and wait for Java object locks. This type of problem can usually be diagnosed by examining a Java dump. The simplest hang scenario involving Java object locks is where a thread acquires a lock that other threads are waiting for, but it doesn't release the lock for some reason.</p> <p>The first place to look in the Java dump output is the LOCKS section. This section lists all the monitors and shows which threads have acquired a lock and which threads are waiting. If the hang is caused by a thread not releasing a lock that other threads need, you can see a list of waiting threads in the output.</p> <p>In this example scenario, the Java dump LOCKS section shows that <code>Worker Thread 0</code> (<code>3LKMONOBJECT</code>) has acquired a lock and there are 19 other worker threads waiting to obtain the lock.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       LOCKS subcomponent dump routine\nNULL           ===============================\nNULL\n1LKPOOLINFO    Monitor pool info:\n2LKPOOLTOTAL     Current total number of monitors: 1\nNULL\n1LKMONPOOLDUMP Monitor Pool Dump (flat &amp; inflated object-monitors):\n2LKMONINUSE      sys_mon_t:0x92711200 infl_mon_t: 0x92711240:\n3LKMONOBJECT       java/lang/Object@0xB56658D8: Flat locked by \"Worker Thread 0\" (J9VMThread:0x92A3EC00), entry count 1\n3LKWAITERQ            Waiting to enter:\n3LKWAITER                \"Worker Thread 1\" (J9VMThread:0x92703F00)\n3LKWAITER                \"Worker Thread 2\" (J9VMThread:0x92709C00)\n3LKWAITER                \"Worker Thread 3\" (J9VMThread:0x92710A00)\n3LKWAITER                \"Worker Thread 4\" (J9VMThread:0x92717F00)\n3LKWAITER                \"Worker Thread 5\" (J9VMThread:0x9271DC00)\n3LKWAITER                \"Worker Thread 6\" (J9VMThread:0x92723A00)\n3LKWAITER                \"Worker Thread 7\" (J9VMThread:0x92729800)\n3LKWAITER                \"Worker Thread 8\" (J9VMThread:0x92733700)\n3LKWAITER                \"Worker Thread 9\" (J9VMThread:0x92739400)\n3LKWAITER                \"Worker Thread 10\" (J9VMThread:0x92740200)\n3LKWAITER                \"Worker Thread 11\" (J9VMThread:0x92748100)\n3LKWAITER                \"Worker Thread 12\" (J9VMThread:0x9274DF00)\n3LKWAITER                \"Worker Thread 13\" (J9VMThread:0x92754D00)\n3LKWAITER                \"Worker Thread 14\" (J9VMThread:0x9275AA00)\n3LKWAITER                \"Worker Thread 15\" (J9VMThread:0x92760800)\n3LKWAITER                \"Worker Thread 16\" (J9VMThread:0x92766600)\n3LKWAITER                \"Worker Thread 17\" (J9VMThread:0x9276C300)\n3LKWAITER                \"Worker Thread 18\" (J9VMThread:0x92773100)\n3LKWAITER                \"Worker Thread 19\" (J9VMThread:0x92778F00)\nNULL\n</code></pre> <p>The next step is to determine why <code>Worker Thread 0</code> is not releasing the lock. The best place to start is the stack trace for this thread, which you can find by searching on the thread name or J9VMThread ID in the THREADS section.</p> <p>The following extract shows the details for <code>\"Worker Thread 0\" (J9VMThread:0x92A3EC00)</code>:</p> <pre><code>NULL\n3XMTHREADINFO      \"Worker Thread 0\" J9VMThread:0x92A3EC00, omrthread_t:0x92A3C280, java/lang/Thread:0xB56668B8, state:CW, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x13, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x511F, native priority:0x5, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000401)\n3XMTHREADINFO2            (native stack address range from:0x9297E000, to:0x929BF000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.000211878 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/Thread.sleep(Native Method)\n4XESTACKTRACE                at java/lang/Thread.sleep(Thread.java:941)\n4XESTACKTRACE                at WorkerThread.doWork(HangTest.java:37)\n4XESTACKTRACE                at WorkerThread.run(HangTest.java:31)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB56658D8, entry count: 1)\n</code></pre> <p>In the last line of this output, you can see where the thread acquired the lock. Working up from this line, you can see that <code>WorkerThread.run</code> was called, which in turn called <code>WorkerThread.doWork</code>. The stack shows that the thread then entered a call to <code>java/lang/Thread.sleep</code> in HangTest.java on line 37, which is preventing the thread from completing its work and releasing the lock. In this example, the <code>sleep</code> call was added to induce a hang, but in real-world scenarios the cause could be any blocking operation, such as reading from an input stream or socket. Another possibility is that the thread is waiting for another lock owned by yet another thread.</p> <p>It is important to remember that each Java dump represents a single snapshot in time. You should generate at least three Java dumps separated by a short pause, for example 30 seconds, and compare the output. This comparison tells you whether the threads involved are stuck in a fixed state or whether they are moving.</p> <p>In this example, the threads do not move and the investigation needs to focus on the logic in <code>WorkerThread.doWork</code> to understand why <code>Worker Thread 0</code> entered the <code>java/lang/Thread.sleep</code> call.</p> <p>Another common scenario is where each Java dump shows a number of threads waiting for a lock owned by another thread, but the list of waiting threads and the lock-owning thread change over time. In this case, the cause is likely to be a bottleneck caused by thread contention, where the threads are continually competing for the same lock. In severe cases, the lock is held only for a small amount of time but there are lots of threads trying to obtain it. Because more time is spent handling the lock and scheduling the thread than executing application code, the degradation in performance is manifested as a hang. Thread contention is usually caused by an application design problem. You can use a similar approach to the one used in this scenario to determine which lines of code are responsible for the contention.</p>"},{"location":"dump_systemdump/","title":"System dump","text":""},{"location":"dump_systemdump/#system-dump","title":"System dump","text":"<p>System dumps, often known as core dumps, are platform-specific and contain a raw binary dump of the process memory. This type of dump has a complete copy of the Java heap, including the contents of all Java objects in the application.</p>"},{"location":"dump_systemdump/#obtaining-system-dumps","title":"Obtaining system dumps","text":"<p>System dumps are produced in response to specific events. To discover which events generate a dump, run the <code>-Xdump:what</code> command. The following output captures the information shown for a system dump:</p> <pre><code>-Xdump:system:\n    events=gpf+abort+traceassert+corruptcache,\n    label=/home/user/core.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..0,\n    priority=999,\n    request=serial\n</code></pre> <p>This output shows that events such as a general protection fault (gpf) or native <code>abort()</code> call can trigger a system dump. For more information about controlling the behavior of dump agents, see Dump agents.</p>"},{"location":"dump_systemdump/#enabling-a-full-system-dump-aix-linux-and-macos","title":"Enabling a full system dump (AIX, Linux, and macOS)","text":"<p>If you require a system dump that contains details of all the native threads that are running, you must change the resource limits for your operating system. Otherwise, the native thread details that are stored in the dump are only for the native thread that was running when the VM ended.</p> <ol> <li> <p>Set the system resource limits by running the following commands:    <code>ulimit -c unlimited; ulimit -n unlimited; ulimit -d unlimited; ulimit -f unlimited;</code></p> <p>Where:</p> </li> </ol> <ul> <li><code>-c</code> sets core files</li> <li><code>-n</code> sets the number of open files</li> <li><code>-d</code> sets the data limit</li> <li><code>-f</code> sets the file limit</li> </ul> <ol> <li>For AIX systems, use the system management interface tool (SMIT) to enable a full CORE dump that is not a pre-430 style CORE dump. You can also set this configuration with the following command line option:</li> </ol> <p><code>chdev -l sys0 -a fullcore='true' -a pre430core='false'</code></p>"},{"location":"dump_systemdump/#analyzing-a-system-dump","title":"Analyzing a system dump","text":"<p>To examine a system dump you can use the Dump viewer (<code>jdmpview</code>), a platform-specific debugging tool, or the Eclipse Memory Analyzer\u2122 tool (MAT).</p> <p>If you want to use MAT to analyze your system dump, you must install the  Diagnostic Tool Framework for Java (DTFJ) plugin in the Eclipse IDE. Select the following menu items:</p> <pre><code>Help &gt; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java   \n</code></pre>"},{"location":"enhancementstoopenjdksecurity/","title":"Enhancements to OpenJDK security","text":""},{"location":"enhancementstoopenjdksecurity/#enhancements-to-openjdk-security","title":"Enhancements to OpenJDK security","text":"<p>Eclipse OpenJ9\u2122 includes the following enhancements to the OpenJDK security components.</p>"},{"location":"enhancementstoopenjdksecurity/#support-for-pkcs11-token-labels","title":"Support for PKCS#11 token labels","text":"<p>(z/OS\u00ae and Linux on IBM Z\u00ae only)</p> <p>On z/OS and Linux on IBM Z, OpenJ9 supports the use of an extra attribute, <code>tokenlabel</code>, in the SunPKCS11 configuration file. Use this attribute to assign a label to a PKCS#11 token.</p> <p>The number of slots and their order depend on the number of tokens in the ICSF token database, their values, and the SAF CRYPTOZ class protection profiles that are currently defined. The ICSF PKCS#11 support ensures that a token resides in its current slot only for the duration of a PKCS#11 session (if the token is not deleted). If you restart an application, or tokens are created or removed, the token might move to a different slot. An application that uses the <code>slot</code> or <code>slotListIndex</code> attributes might fail if it doesn\u2019t first check which slot the token is in. You can avoid this issue by using the <code>tokenlabel</code> attribute instead.</p> <p>You can specify only one of the attributes - <code>slot</code>, <code>slotListIndex</code>, or <code>tokenlabel</code>. If you do not specify any of these attributes, the default behavior is that the <code>slotListIndex</code> attribute is set to 0.</p> <p>For more information about the SunPKCS11 configuration file, see PKCS#11 Reference Guide.</p>"},{"location":"env_var/","title":"Environment variables","text":""},{"location":"env_var/#environment-variables","title":"Environment variables","text":"<p>Although the Eclipse OpenJ9\u2122 virtual machine (VM) recognizes many environment variables, most are superseded by command-line arguments. Use command-line arguments rather than environment variables, which are retained only for compatibility.</p> <p> Note: Environment variables are overridden by command-line arguments.</p>"},{"location":"env_var/#finding-and-setting-environment-variables","title":"Finding and setting environment variables","text":"<p>To show the current environment, run:</p> <ul> <li><code>set</code> (Windows\u2122)</li> <li><code>env</code> (AIX\u00ae, Linux\u00ae, and macOS\u00ae)</li> <li><code>set</code> (z/OS\u00ae)</li> </ul> <p>To show a particular environment variable, run:</p> <ul> <li><code>echo %ENVNAME%</code> (Windows)</li> <li><code>echo $ENVNAME</code> (AIX, Linux, macOS, and z/OS)</li> </ul> <p>Use values exactly as shown in the documentation. The names of environment variables are case-sensitive in AIX, Linux, macOS, and z/OS.</p> <p>To set the environment variable LOGIN_NAME to Fred, run:</p> <ul> <li><code>set LOGIN_NAME=Fred</code> (Windows)</li> <li><code>export LOGIN_NAME=Fred</code> (AIX/Linux/macOS: ksh or bash shells)</li> <li><code>setenv LOGIN_NAME Fred</code> (csh shells)</li> </ul> <p>These variables are set only for the current shell or command-line session.</p> <p>If you are setting multiple values for an environment variable in a list:</p> <ul> <li>On AIX, Linux, macOS, and z/OS the separator is typically a colon (:).</li> <li>On Windows the separator is typically a semicolon (;).</li> </ul>"},{"location":"env_var/#general-options","title":"General options","text":"<p>General VM environment variables are shown in the following table:</p> Environment\u00a0variable Usage information <code>OPENJ9_JAVA_COMMAND_LINE</code> This variable is set by the VM after it starts. Using this variable, you can find the command-line parameters set when the VM started. See <code>-XX:[+|-]OpenJ9CommandLineEnv</code> for more information. <code>OPENJ9_JAVA_OPTIONS=&lt;option&gt;</code> Set this variable to store default Java options, including -X, -D, or -verbose:gc style options. For example, -Xms256m -Djava.compiler. Any options set are overridden by equivalent options that are specified when Java is started. This variable does not support certain options, see the list in -Xoptionsfile. If you specify the name of a trace output file either directly, or indirectly, by using a properties file, the output file might be accidentally overwritten if you run utilities such as the trace formatter, dump extractor, or dump viewer. To avoid this problem, add %d, %p or %t to the trace file names. See -Xtrace:output. Note: The equivalent to <code>OPENJ9_JAVA_OPTIONS</code>, <code>IBM_JAVA_OPTIONS</code> is deprecated and will be removed in a future release. <code>JAVA_FONTS=&lt;list of directories&gt;</code> Set this environment variable to specify the font directory. Setting this variable is equivalent to setting the property <code>java.awt.fonts</code> on Windows operating systems, and <code>sun.java2d.fontpath</code> on other operating systems. <code>_JAVA_OPTIONS=&lt;option&gt;</code> Set this variable to add Java options to the end of the command line. Supported options and trace file issues are the same as for <code>OPENJ9_JAVA_OPTIONS</code>."},{"location":"env_var/#dump-agent-options","title":"Dump agent options","text":"<p>The preferred mechanism for controlling the production of dumps is by using the <code>-Xdump</code> option. However, these legacy environment variables are preserved and can still be used. The following table describes dump agent options:</p> Environment Variable Usage Information <code>JAVA_DUMP_OPTS</code> Used to control the conditions under which dumps are produced. <p>If you set agents for a condition by using the <code>JAVA_DUMP_OPTS</code> environment variable, default dump agents for that condition are disabled; however, any <code>-Xdump</code> options that are specified on the command line are used.</p> <p>The <code>JAVA_DUMP_OPTS</code> environment variable uses the following syntax:</p> <pre><code>JAVA_DUMP_OPTS=\"ON&lt;condition&gt;(&lt;agent&gt;[&lt;count&gt;],&lt;agent&gt;[&lt;count&gt;]),\nON&lt;condition&gt;(&lt;agent&gt;[&lt;count&gt;],...),...)\"\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;condition&gt;</code> is one of the following values:<ul> <li><code>ANYSIGNAL</code></li> <li><code>DUMP</code></li> <li><code>ERROR</code></li> <li><code>INTERRUPT</code></li> <li><code>EXCEPTION</code></li> <li><code>OUTOFMEMORY</code></li> </ul> </li> <li><code>&lt;agent&gt;</code> is one of the following values:<ul> <li><code>ALL</code></li> <li><code>NONE</code></li> <li><code>JAVADUMP</code></li> <li><code>SYSDUMP</code></li> <li><code>HEAPDUMP</code></li> <li><code>CEEDUMP</code> (z/OS specific)</li> </ul> </li> <li><code>&lt;count&gt;</code> is the number of times to run the specified agent for the specified condition. This value is optional. By default, the agent runs every time that the condition occurs.</li> </ul> <p><code>JAVA_DUMP_OPTS</code> is parsed by taking the leftmost occurrence of each condition, so duplicates are ignored. The following setting produces a system dump for the first error condition only:</p> <pre><code>ONERROR(SYSDUMP[1]),ONERROR(JAVADUMP)\n</code></pre> <p>Also, the <code>ONANYSIGNAL</code> condition is parsed before all others, so</p> <pre><code>ONINTERRUPT(NONE),ONANYSIGNAL(SYSDUMP)\n</code></pre> <p>has the same effect as</p> <pre><code>ONANYSIGNAL(SYSDUMP),ONINTERRUPT(NONE)\n</code></pre> <p>If the <code>JAVA_DUMP_TOOL</code> environment variable is set, that variable is assumed to specify a valid executable name and is parsed for replaceable fields, such as %pid. If %pid is detected in the string, the string is replaced with the VM's own process ID. The tool that is specified by <code>JAVA_DUMP_TOOL</code> is run after any system dump or heap dump is taken, before anything else.</p> <p>The dump settings are applied in the following order. Settings later in the list take precedence:</p> <ol> <li>Default VM dump behavior.</li> <li><code>-Xdump</code> command-line options that specify <code>-Xdump:&lt;type&gt;:defaults</code>, see OpenJ9 default options.</li> <li><code>DISABLE_JAVADUMP</code>, <code>IBM_HEAPDUMP</code>, and <code>IBM_HEAP_DUMP</code> environment variables.</li> <li><code>IBM_JAVADUMP_OUTOFMEMORY</code> and <code>IBM_HEAPDUMP_OUTOFMEMORY</code> environment variables.</li> <li><code>JAVA_DUMP_OPTS</code> environment variable.</li> <li>Remaining <code>-Xdump</code> command-line options.</li> </ol> <p>Setting <code>JAVA_DUMP_OPTS</code> affects only those conditions that you specify. Actions on other conditions are unchanged.</p>"},{"location":"env_var/#signal-mapping","title":"Signal mapping","text":"<p>When setting the <code>JAVA_DUMP_OPTS</code> environment variable, the mapping of operating system signals to the \"condition\" is shown in the following table:</p> Condition z/OS Windows Linux, macOS, and AIX EXCEPTION SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGSYS, SIGXFSV SIGILL, SIGSEGV, SIGFPE SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGXFSV INTERRUPT SIGINT, SIGTERM, SIGHUP SIGINT, SIGTERM SIGINT, SIGTERM, SIGHUP ERROR SIGABRT SIGABRT SIGABRT DUMP SIGQUIT SIGBREAK SIGQUIT"},{"location":"env_var/#java-dump-options","title":"Java dump options","text":"<p>The preferred mechanism for controlling the production of Java dumps is by using the <code>-Xdump:java</code> option. However, these legacy environment variables are preserved and can still be used.</p> Environment Variable Usage Information <code>DISABLE_JAVADUMP=[TRUE|FALSE]</code> Setting <code>DISABLE_JAVADUMP</code> to <code>TRUE</code> is the equivalent of using <code>-Xdump:java:none</code> and stops the default production of Java dumps. <code>IBM_JAVACOREDIR=&lt;directory&gt;</code> The default location into which the Java dump is written. On z/OS, the <code>_CEE_DMPTARG</code> environment variable is used instead. <code>IBM_JAVADUMP_OUTOFMEMORY=[TRUE|FALSE]</code> By setting this environment variable to <code>FALSE</code>, you disable Java dumps for an out-of-memory exception. When not set, a Java dump is generated when an out-of-memory exception is thrown but not caught and handled by the application. Set to <code>TRUE</code> to generate a dump when an out-of-memory exception is thrown, even if it is handled by the application. Set to <code>FALSE</code> to disable Java dumps for an out-of-memory exception. <code>TMPDIR=&lt;directory&gt;</code> This variable specifies an alternative temporary directory. This directory is used only when Java dumps and Heap dumps cannot be written to their target directories, or the current working directory. The default is <code>/tmp</code> (<code>C:\\temp</code> for Windows). <p> Note: You can use the dump agent <code>JAVA_DUMP_OPTS</code> variable to control the conditions under which Java dumps are produced.</p>"},{"location":"env_var/#heap-dump-options","title":"Heap dump options","text":"<p>The preferred mechanism for controlling the production of Java dumps is by using the <code>-Xdump:heap</code> option. However, these legacy environment variables are preserved and can still be used.</p> Environment Variable Usage Information <code>IBM_HEAPDUMP=[TRUE|FALSE]</code> Setting this option to <code>TRUE</code> enables heap dump production by using signals. <code>IBM_HEAP_DUMP=[TRUE|FALSE]</code> Setting this option to <code>TRUE</code> enables heap dump production by using signals. <code>IBM_HEAPDUMPDIR=&lt;directory&gt;</code> The default location into which the heap dump is written. On z/OS, the <code>_CEE_DMPTARG</code> environment variable is used instead. <code>IBM_HEAPDUMP_OUTOFMEMORY=[TRUE|FALSE]</code> Controls the generation of a heap dump when an out-of-memory exception is thrown. When not set, a heap dump is generated when an out-of-memory exception is thrown but not caught and handled by the application. Set to TRUE to generate a dump when an out-of-memory exception is thrown, even if it is handled by the application. Set to FALSE to disable heap dump for an out-of-memory exception. <code>IBM_JAVA_HEAPDUMP_TEST</code> Use this environment variable to cause the VM to generate both PHD and text versions of heap dumps. Equivalent to <code>opts=PHD+CLASSIC</code> on the <code>-Xdump:heap</code> option. <code>IBM_JAVA_HEAPDUMP_TEXT</code> Use this environment variable to cause the VM to generate a text (human readable) Heap dump. Equivalent to <code>opts=CLASSIC</code> on the <code>-Xdump:heap</code> option. <code>TMPDIR=&lt;directory&gt;</code> This variable specifies an alternative temporary directory. This directory is used only when Java dumps and heap dumps cannot be written to their target directories, or the current working directory. The default is <code>/tmp</code> (<code>C:\\temp</code> for Windows). <p> Note: You can use the dump agent <code>JAVA_DUMP_OPTS</code> variable to control the conditions under which Heap dumps are produced.</p>"},{"location":"env_var/#other-diagnostic-options","title":"Other diagnostic options","text":"<p>The following table lists other environment variables that can be set for diagnostic purposes:</p> Environment variable Usage Instructions <code>IBM_COREDIR=&lt;directory&gt;</code> Set this variable to specify an alternative location for system dumps, JIT dumps, and snap trace. On z/OS, <code>_CEE_DMPTARG</code> is used instead for snap trace, and transaction dumps are written to TSO according to <code>JAVA_DUMP_TDUMP_PATTERN</code>. On Linux and macOS, the dump is written to the directory that is specified directory by the operating system before being moved to the specified location. <code>IBM_JAVA_ABEND_ON_FAILURE=Y</code> (z/OS only) This setting tells the Java launcher to mark the Task Control Block (TCB) with an abend code if the OpenJ9 VM fails to load or is terminated by an uncaught exception. By default, the Java launcher does not mark the TCB. <code>JAVA_DUMP_TDUMP_PATTERN=&lt;string&gt;</code> (z/OS only) The specified <code>&lt;string&gt;</code> is passed to IEATDUMP to use as the data/set name for the Transaction Dump. The default <code>&lt;string&gt;</code> is <code>%uid.JVM.TDUMP.%job.D%y%m%d.T%H%M%S</code> (31-bit) or <code>%uid.JVM.%job.D%y%m%d.T%H%M%S.X&amp;amp;DS</code> (64-bit), where <code>%uid</code> is found from the C code fragment shown in Notes. <code>JAVA_THREAD_MODEL=&lt;string&gt;</code> <code>&lt;string&gt;</code> can be defined as one of the following values: NATIVE (all threads are created as <code>_MEDIUM_WEIGHT</code>), HEAVY (all threads are created as <code>_HEAVY_WEIGHT</code>), MEDIUM (same as NATIVE), or NULL. The default is NATIVE. <code>IBM_XE_COE_NAME=&lt;value&gt;</code> Set this variable to generate a system dump when the specified exception occurs. The value that is supplied is the package description of the exception; for example, <code>java/lang/InternalError</code>. A Signal 11 is followed by a JVMXE message and then the VM ends. <code>JAVA_PLUGIN_TRACE=TRUE</code> When this variable is set to <code>TRUE</code> or 1, a Java plug-in trace is produced for the session when an application runs. Traces are produced from both the Java and Native layer. By default, this variable is set to <code>FALSE</code>, so that a Java plug-in trace is not produced. <p> Notes: C code fragment to discover <code>%uid</code> for <code>JAVA_DUMP_TDUMP_PATTERN=&lt;string&gt;</code>:</p> <pre><code>pwd = getpwuid(getuid());\npwd-&gt;pw_name;\n</code></pre>"},{"location":"env_var/#deprecated-jit-options","title":"Deprecated JIT options","text":"<p>The following table describes deprecated environment variables for the JIT compiler:</p> Environment Variable Usage Information <code>IBM_MIXED_MODE_THRESHOLD</code> Use <code>-Xjit:count=&lt;value&gt;</code> instead of this variable. <code>JAVA_COMPILER</code> Use <code>-Djava.compiler=&lt;value&gt;</code> instead of this variable."},{"location":"gc/","title":"GC policies","text":""},{"location":"gc/#garbage-collection-policies","title":"Garbage collection policies","text":"<p>Eclipse OpenJ9\u2122 provides several garbage collection (GC) policies that are designed around different application workloads and service level agreements. Each GC policy consists of a set of characteristics and features that aim to optimize one or more performance aspects of a running application. These performance aspects include application throughput, memory footprint, average pause times, worst-case pause times, and startup time.</p> <p>Different policies require a Java heap that is configured in different ways in order to achieve different goals. The simplest configuration consists of a single area of memory, often referred to as a flat heap. Other configurations divide the heap into different areas or regions, which might contain objects of different ages (generations) or sizes.</p> <p>A GC cycle is a repeatable process that involves a set of GC operations. These operations process all or parts of the Java heap to complete a discrete function and are discussed in more detail in GC operations.</p> <p>GC policies use different GC cycles to manage different aspects of the heap. For example, the <code>gencon</code> policy runs a partial GC cycle on the nursery area of the heap to complete a scavenge operation. At other times, <code>gencon</code> also runs a global GC cycle on the entire Java heap to complete mark and sweep (and optionally compact) operations.  </p> <p>GC cycles might be divided into increments that run over a period of time to reduce maximum pause times. These increments might involve stop-the-world (STW) pauses that must halt application threads to give certain GC operations exclusive access to the Java heap. Alternatively, increments might include GC operations that can run concurrently with application processing.</p> <p>The following table shows the heap configuration and the GC cycles and operations used by different policies:</p> Policy Heap configuration GC cycles / operations <code>gencon</code> Two areas: nursery and tenure  Two generation groups: new/older Global GC cycle: concurrent mark-sweep operations, optionally followed by a compact operation  Partial GC cycle: STW scavenge operation or concurrent scavenge operation (if optionally enabled) <code>balanced</code> Multiple regions of equal size  Multiple generations Global GC mark cycle: incremental concurrent mark operation (global mark phase)  Partial GC cycle: STW copy forward operation and optional mark, sweep, or compact operations <code>optavgpause</code> One area: flat  One generation Global GC cycle: concurrent mark-sweep operations, optionally followed by a compact operation <code>optthruput</code> One area: flat  One generation Global GC cycle: STW mark-sweep operations, optionally followed by a compact operation <code>metronome</code> Multiple regions by size class  One generation Global GC cycle: incremental STW mark-sweep operation in small interruptible steps <code>nogc</code> One area: flat No GC cycles <p> Note: All OpenJ9 GC policies support compressed references on 64-bit platforms, which compresses heap pointers to 32 bits if the total heap size does not exceed the theoretical upper bound of 64 GB. Applications that require more heap space can select any heap size within the bounds imposed by the operating system and available system RAM, without using compressed references. For more information, see compressed references.</p>"},{"location":"gc/#policy-selection-and-tuning","title":"Policy selection and tuning","text":"<p>The default policy is the Generational Concurrent (<code>gencon</code>) GC policy, which suits a broad spectrum of applications. Choosing a different GC policy should be guided by the application dynamics and an observation of how the application interacts with the heap during startup and at steady state. To help with this analysis, all OpenJ9 GC policies are instrumented to collect a wide range of GC-related metric data for reporting in a GC log file.</p> <p>To enable GC logging for the OpenJ9 Java runtime, include the <code>-verbose:gc</code> option on the command line. By default, this option prints output to <code>stderr</code> but you can send the output to a log file by using <code>-Xverbosegclog</code>. You can then visualize the output by loading the GC log into the Garbage Collector and Memory Visualizer (GCMV) plugin for the Eclipse IDE. OpenJ9 Java GC logs can also be analyzed by some online services, such as GCEasy.</p> <p>The following sections provide more information about each policy and when you might choose it for your application. To select a GC policy other than <code>gencon</code>, specify the <code>-Xgcpolicy</code> option on the command line. To adjust the initial and maximum size of the Java heap, use the <code>-Xms</code> and <code>-Xmx</code> command line options. For generational GC policies, you can also set the <code>-Xmn</code>, <code>-Xmns</code>, and <code>-Xmnx</code> options.</p>"},{"location":"gc/#gencon-policy-default","title":"<code>gencon</code> policy (default)","text":"<p>The Generational Concurrent GC policy (<code>-Xgcpolicy:gencon</code>) is probably best suited if you have a transactional application, with many short-lived objects. This policy aims to minimize GC pause times without compromising throughput. This is the default policy employed by the VM, so if you want to use it you don't need to specify it on the command line when you start your application.</p> <p>If your application requires the allocation of objects of very different sizes and liveness on the Java heap, you might experience heap fragmentation, which in turn might lead to global heap compaction. In these circumstances, the Balanced GC policy might be more appropriate.</p>"},{"location":"gc/#gc-processing","title":"GC processing","text":"<p>With the <code>gencon</code> policy, the Java heap is divided into two main areas, the nursery area, where new objects are created and the tenure area, where objects are moved if they have reached tenure age.</p> <p>The nursery area is subdivided into two further areas, the allocate space and the survivor space. A partial GC cycle that involves a GC scavenge operation is used to reclaim memory from the nursery area. This process is illustrated in the following diagram, which shows a sequence of four main events:</p> <p></p> <ol> <li>Objects are created in the allocate space.</li> <li>The allocate space is full.</li> <li>A local GC scavenge process runs and reachable objects are either evacuated (copied) into the survivor space or into the tenure area if they have reached tenure age. Any objects that can't be reached are left untouched and subsequently cleared.</li> <li>The allocate and survivor spaces swap roles. The original survivor space becomes the allocate space where new objects are created, and the original allocate space becomes the survivor space ready for the next local GC scavenge process.</li> </ol> <p>The relative sizes of the allocate and survivor spaces are dynamically adjusted by a technique called tilting. When the nursery area is first created, it is evenly divided between the allocate and survivor spaces. If, after a GC scavenge operation runs, the amount of space required for the survivor area is comparatively small, the boundary between the two spaces is adjusted by tilting. For example, if the survivor space requires only 10% of the nursery area, the tilt ratio is adjusted to give 90% of the nursery area to the allocate space. With more space available for new objects, the frequency of scavenge cycles is reduced.</p> <p>The tenure age of an object is determined by the VM and reflects the number of times that an object has been copied between the allocate space and the survivor space. The age is in the range 1 - 14 and is adjusted dynamically by the VM depending on the object survival rate at particular ages. For example, if an object has a tenure age of <code>5</code>, it has been copied backwards and forwards between allocate and survivor spaces five times. If the VM sets a tenure age of <code>5</code> based on the percentage of space remaining in the nursery area, the next scavenge moves the object from the nursery to the tenure area. You can set an initial tenure age with the <code>-Xgc:scvTenureAge</code> option. You can also prevent the VM dynamically adjusting the tenure age by setting the <code>Xgc:scvNoAdaptiveTenure</code> option so that the initial age is maintained throughout the run time of the VM.</p> <p>Within the tenure area, new objects are allocated into the small object area (SOA), which is illustrated in the earlier diagram (see item 3). A large object area (LOA) is set aside for objects greater than 64 KB that cannot be allocated into the SOA to minimize fragmentation. The LOA is allocated by default but is reduced and removed after a few GC cycles if it isn't populated. To prevent the creation of an LOA, you can specify the <code>-Xnoloa</code> option on the command line when you start your application. When the tenure area is close to full a global GC cycle is triggered.</p> <p>The partial GC cycle (scavenge) reduces pause times by frequently reclaiming memory in the nursery area which, for a transactional application with many short-lived objects, has the most recyclable space. While most of the objects stay in the nursery area after the scavenge operation is complete, a small fraction are moved to the tenure area. Over time the tenure area might become full. So, whilst a partial GC cycle is operating on the nursery area, a concurrent global GC cycle also runs alongside normal program execution to mark and remove unreachable objects from the tenure area. These two GC approaches combine to provide a good trade-off between shorter pause times and consistent throughput.</p>"},{"location":"gc/#concurrent-scavenge","title":"Concurrent Scavenge","text":"<p>A special mode of the <code>gencon</code> policy is known as Concurrent Scavenge. This mode aims to further reduce the average time spent in STW pauses by collecting garbage from the nursery area in parallel with running application threads. Whilst aiming to reduce the average time, this mode does not improve the worst case pause time when compared to running <code>gencon</code> without Concurrent Scavenge enabled.</p> <p>To enable Concurrent Scavenge, see -Xgc:concurrentScavenge.</p> <p>This mode can be enabled with hardware-based support and software-based support:</p> <ul> <li> <p>Hardware-based support: (Linux on IBM Z\u00ae and z/OS\u00ae) This mode works on the IBM z14\u2122 and later mainframe system with the Guarded Storage (GS) Facility. The GS Facility provides hardware-based support to detect when potentially stale references to objects are accessed by an application. This means that the garbage collector can start processing objects in parts of the heap without halting an application because the GS Facility is on hand to spot accesses to an object and send a notification. The object that was ready to be swept away can be moved, and references to it can be reset.</p> </li> <li> <p>Software-based support: (64-bit: Linux on (x86-64, POWER, IBM Z\u00ae), AIX\u00ae, macOS\u00ae, and z/OS\u00ae) With software-based support, Concurrent Scavenge can be enabled without any pre-requisite hardware although the performance throughput is not as good as hardware-based support.</p> </li> </ul> <p>More information about Concurrent Scavenge mode can be found in the blog post Concurrent Scavenge Garbage Collection Policy.</p>"},{"location":"gc/#balanced-policy","title":"<code>balanced</code> policy","text":"<p>(64-bit only)</p> <p>The Balanced GC policy (<code>-Xgcpolicy:balanced</code>) evens out pause times and reduces the overhead of some of the costlier operations that are typically associated with garbage collection, such as compaction and class unloading. The Java heap is divided into a large number of regions (1,000 - 2,000), which are managed individually by an incremental generational collector to reduce the maximum pause time on large heaps and increase the efficiency of garbage collection. The aim of the policy is to avoid global garbage collections by matching object allocation and survival rates.</p>"},{"location":"gc/#when-to-use","title":"When to use","text":"<p>The Balanced policy might be a good alternative for applications that experience unacceptable pause times with <code>gencon</code>.</p> <ul> <li> <p>If you have problems with application pause times that are caused by global garbage collections, particularly compactions, this policy might improve application performance.</p> </li> <li> <p>If you are using large systems that have Non-Uniform Memory Architecture (NUMA) characteristics (x86 and POWER\u2122 platforms only), the Balanced policy might further improve application throughput.</p> </li> </ul> <p>However, even though pause times are typically evened out across GC operations, actual pause times are affected by object allocation rates, object survival rates, and fragmentation levels within the heap, and cannot therefore be bound to a certain maximum nor can a certain utilization level be guaranteed.</p>"},{"location":"gc/#gc-processing_1","title":"GC processing","text":"<p>During VM startup, the GC divides the heap memory into regions of equal size. These regions remain static for the lifetime of the VM and are the basic unit of garbage collection and allocation operations. For example, when the heap is expanded or contracted, the memory committed or released corresponds to a certain number of regions. Although the Java heap is a contiguous range of memory addresses, any region within that range can be committed or released from a pool as required. This enables the Balanced GC to contract the heap more dynamically and aggressively than other garbage collectors, which typically require the committed portion of the heap to be contiguous.</p> <p>Regions impose a maximum object size. Objects are always allocated within the bounds of a single region and are never permitted to span regions. The region size is always a power of two; for example, 512 KB, 1 MB, and so on (where KB is 2<sup>10</sup> bytes and MB is 2<sup>20</sup> bytes). The region size is selected at startup based on the maximum heap size. The collector chooses the smallest power of two which will result in less than 2048 regions, with a minimum region size of 512 KB. Except for small heaps (less than about 512 MB) the VM aims to have between 1024 and 2047 regions.</p> <p>Object ages are tracked for each region with a maximum of 24 possible generations. The following diagram illustrates the structure of the object heap:</p> <p></p> <p>The eden space is a set of regions of age 0, which contain the newest objects allocated. The size of the eden space is determined by the number of regions that it contains. When the region count for the eden space reaches a predetermined  threshold (taxation threshold), a partial GC cycle runs to reduce the number of used regions, typically by using a copy forward operation. Empty regions can then be assigned to the eden space from the pool. In specific cases, mark and compact operations might be used, for example, when there are not enough free survivor regions available. The partial GC cycle is a STW operation that always includes the eden space, but might include older regions. Objects from collectible regions of age N are moved into another region of the same age N or to an empty region that is assigned an age of N. Then, the ages of all regions across the heap are incremented by 1, except for the maximum age 24 regions. Regions of age 24 are included in partial GC collection sets in order to defragment them.</p> <p>Partial GC cycles work to reclaim free regions in the heap for allocating new objects. Because some objects from eden regions always survive, a partial GC cycle can reclaim only about 90% of this memory. To keep up with object allocation, partial GC cycles also reclaim free regions by defragmenting older regions. For example, a partial GC cycle that moves objects from 5 fragmented older regions into 2 empty regions, reclaims 3 regions for new object allocation. However, over time the overall amount of fragmented memory decreases and records about object liveness in older regions become less accurate. Eventually, the work done by partial GC cycles to reclaim memory cannot keep pace with memory consumption. Free regions become so scarce that a global mark operation (GMP), which is triggered by another taxation threshold, is required to build a new record of object liveness across the heap. A sweep operation uses this record to measure the amount of free memory in fragmented older regions, which later partial GC cycles can act upon to move objects and reclaim free regions.</p> <p>A global sweep operation also runs to reclaim memory so that it can create empty regions. The global sweep operation, while logically associated with the global mark operation, runs in the same STW increment as the first partial GC cycle after the mark operation completes. Because the GC cycle responsible for the global mark operation runs concurrently, it might overlap and interleave with a few partial GC cycles.</p> <p>With the <code>balanced</code> policy, a global GC cycle is sometimes required in addition to the global mark operations and partial GC cycle. This global GC cycle is rare, occurring only in very tight memory conditions when other GC cycles cannot free enough memory on the heap.</p> <p>Most objects are easily contained within the minimum region size of 512 KB. However, to support large arrays, which cannot be contained in a region, the <code>balanced</code> GC policy uses an arraylet representation in the heap. For more information about structure and layout, see Arraylets.</p> <p> Note: With arraylets, JNI access to array data might involve reconstituting arraylets as contiguous arrays, which can significantly slow down processing.</p> <p>To learn about the default heap size and the tuning options that can be used with the <code>balanced</code> policy, see <code>-Xgcpolicy:balanced</code>.</p>"},{"location":"gc/#optavgpause-policy","title":"<code>optavgpause</code> policy","text":"<p>The optimize for pause time policy (<code>-Xgcpolicy:optavgpause</code>) uses a global GC to manage a flat heap comprised of a single area and to compact the heap if the heap becomes fragmented. The global GC cycle starts preemptively so that the cycle finishes before the heap is exhausted. By anticipating global collections and initiating some mark operations ahead of collection, the <code>optavgpause</code> policy reduces GC pause times when compared to <code>optthruput</code>. However, the reduction in pause time comes at the expense of some performance throughput.</p>"},{"location":"gc/#when-to-use_1","title":"When to use","text":"<p>Consider using this policy if you have a large heap size (available on 64-bit platforms), because this policy limits the effect of increasing heap size on the length of the GC pause.</p> <p>Although <code>optavgpause</code> uses a write barrier to support concurrent mark operations, it does not use a generational write barrier. For some application workloads, such as those that frequently change large and old reference arrays, this strategy might be of greater benefit. However, in many situations, the default <code>gencon</code> policy offers better performance.</p> <p>By using a flat heap, <code>optavgpause</code> avoids potential issues with very large objects. With <code>gencon</code>, the heap is divided into areas (nursery and tenure) in order to manage generations of objects. Although there might be sufficient free space on the overall Java heap for a very large object, it might not fit into the nursery area. If the allocator does succeed in allocating a very large object, further GC cycles might be required to create enough contiguous free space.</p> <p>Overall, <code>optavgpause</code>, along with <code>optthruput</code>, is best suited to short-lived applications and to long-running services that involve concurrent sessions with short lifespans. Short-lived applications with adequate heap sizes usually complete without compaction. The flat heap fragments more slowly when session-bound objects are allocated and drop out of the live set in short overlapping clusters.</p>"},{"location":"gc/#gc-processing_2","title":"GC processing","text":"<p>The <code>optavgpause</code> policy requires a flat Java heap. A global GC cycle runs concurrent mark-sweep operations, optionally followed by compact operations. By running most operations concurrently with application threads, this strategy aims to reduce GC pause times as much as possible.</p>"},{"location":"gc/#optthruput-policy","title":"<code>optthruput</code> policy","text":"<p>The optimize for throughput policy (<code>-Xgcpolicy:optthruput</code>) uses a global GC cycle to manage a flat heap that is comprised of a single area and to compact the heap if the heap becomes fragmented. The global collector runs mark and sweep operations that are triggered by an allocation failure when the heap is exhausted. As a result, applications stop for long pauses while garbage collection takes place.</p>"},{"location":"gc/#when-to-use_2","title":"When to use","text":"<p>You might consider using this policy when a large heap application can tolerate longer GC pauses to obtain better overall throughput. Unlike <code>gencon</code>, the <code>optthruput</code> policy does not use object access barriers. In some workloads, the cost of these barriers might be high enough to make <code>optthruput</code> preferable. However, in many situations, the default <code>gencon</code> policy offers better performance.</p> <p>By using a flat heap, <code>optthruput</code> avoids potential issues with very large objects. With <code>gencon</code>, the heap is divided into areas (nursery and tenure) in order to manage generations of objects. Although there might be sufficient free space on the overall Java heap for a very large object, it might not fit into the nursery area. If the allocator does succeed in allocating a very large object, further GC cycles might be required to create enough contiguous free space.</p> <p>Overall, <code>optthruput</code>, along with <code>optavgpause</code>, is best suited to short-lived applications and to long-running services that involve concurrent sessions with short lifespans. Short-lived applications with adequate heap sizes usually complete without compaction. The flat heap fragments more slowly when session-bound objects are allocated and drop out of the live set in short overlapping clusters.</p>"},{"location":"gc/#gc-processing_3","title":"GC processing","text":"<p>The <code>optthruput</code> policy requires a flat Java heap. A  global GC cycle runs mark-sweep operations, optionally followed by compact operations. The cycle requires exclusive access to the heap, causing application threads to halt while operations take place. As such, long pauses can occur.</p>"},{"location":"gc/#metronome-policy","title":"<code>metronome</code> policy","text":"<p>(Linux on x86-64 and AIX platforms only)</p> <p>The metronome policy (<code>-Xgcpolicy:metronome</code>) is an incremental, deterministic garbage collector with short pause times. Applications that are dependent on precise response times can take advantage of this technology by avoiding potentially long delays from GC activity.</p>"},{"location":"gc/#when-to-use_3","title":"When to use","text":"<p><code>metronome</code> is designed for applications that require a precise upper bound on collection pause times as well as specified application utilization: the proportion of time that the application is permitted to use, with the remainder being devoted to GC. The <code>metronome</code> GC runs in short interruptible bursts to avoid long STW pauses.</p>"},{"location":"gc/#gc-processing_4","title":"GC processing","text":"<p>The Java heap is allocated as a contiguous range of memory, partitioned into small regions of equal size (~64 KB). The <code>metronome</code> policy does not dynamically resize the heap; the heap is always fully expanded, even if <code>-Xms</code> is not set to <code>-Xmx</code>.</p> <p>Each region of the heap is either empty, or contains only objects in one of 16 size classes. The heap also supports Arraylets for dealing with large arrays. This organization improves the use of available heap space, reducing the need for heap compaction and defragmentation, and providing more precise control over the incremental sweep operation.</p> <p> Note: With arraylets, JNI access to array data might involve reconstituting arraylets as contiguous arrays, which can significantly slow down processing.</p> <p>Although high application utilization is desirable for optimal throughput, the GC must be able to keep up with the application's memory allocation rate.</p> <p>A higher utilization typically requires a larger heap because the GC isn't allowed to run as much as a lower utilization would permit. The relationship between utilization and heap size is highly application dependent, and striking an appropriate balance requires iterative experimentation with the application and VM parameters. You might need to adjust heap size or pause time or target utilization to achieve an acceptable runtime configuration.</p> <p>To learn about default options and tuning options that can be used with the <code>metronome</code> policy, see <code>-Xgcpolicy:metronome</code>.</p>"},{"location":"gc/#nogc-policy","title":"<code>nogc</code> policy","text":"<p><code>-Xgcpolicy:nogc</code> handles only memory allocation and heap expansion, but doesn't reclaim any memory. The GC impact on runtime performance is therefore minimized, but if the available Java heap becomes exhausted, an <code>OutOfMemoryError</code> exception is triggered and the VM stops.</p>"},{"location":"gc/#when-to-use_4","title":"When to use","text":"<p>This policy is not suited to the majority of Java applications. However, the following use cases apply:</p> <ul> <li> <p>Testing during development</p> <ul> <li> <p>GC performance: Use <code>nogc</code> as a baseline when testing the performance of other GC policies, including the provision of a low-latency baseline.</p> </li> <li> <p>Application memory: Use <code>nogc</code> to test your settings for allocated memory. If you use <code>-Xmx</code> to set the heap size that should not be exceeded, your application terminates with a heap dump if it tries to exceed your memory limit.</p> </li> </ul> </li> <li> <p>Running applications with minimal or no GC requirements</p> <ul> <li> <p>You might use <code>nogc</code> when an application is so short-lived that allocated memory is never exhausted and running a full GC cycle is therefore a waste of resources.</p> </li> <li> <p>Similarly, when memory application is well understood or where there is rarely memory to be reclaimed, you might prefer to avoid unnecessary GC cycles and rely on a failover mechanism to occasionally restart the VM.</p> </li> </ul> </li> </ul> <p> Note: You should be especially careful when using any of the following techniques with <code>nogc</code> because memory is never released under this policy:</p> <ul> <li>Finalization  </li> <li>Direct memory access  </li> <li>Weak, soft, and phantom references</li> </ul>"},{"location":"gc/#troubleshooting","title":"Troubleshooting","text":"<p>You can diagnose problems with garbage collection operations by turning on verbose GC logging. By default, the information is printed to STDERR but can be redirected to a file by specifying the <code>-Xverbosegclog</code> option. The log files contain detailed information about all operations, including initialization, STW processing, finalization, reference processing, and allocation failures. For more information, see Verbose GC logs.</p> <p>If verbose logs do not provide enough information to help you diagnose GC problems, you can use GC trace to analyze operations at a more granular level. For more information, see -Xtgc.</p>"},{"location":"gc_overview/","title":"Garbage Collection (GC)","text":""},{"location":"gc_overview/#garbage-collection","title":"Garbage collection","text":"<p>To prevent applications running out of memory, objects in the Java heap that are no longer required must be reclaimed. This process is known as garbage collection (GC). When garbage is collected, the garbage collector must obtain exclusive access to the heap, which causes an application to pause while the cleanup is done. This pause is often referred to as a stop-the-world (STW) pause because an application must halt until the process completes. In general, the first step in the GC process is to mark the objects that are reachable, which means they are still in use. The next step is to sweep away the unmarked objects to reclaim memory. The final step is to compact the heap if the heap is badly fragmented.</p> <p>A GC cycle is a repeatable process that involves a set of GC operations. These operations process all or parts of the Java heap. When operating on the whole of the Java heap, the cycle is referred to as a global GC cycle; When operating on part of the heap, the cycle is referred to as a partial GC cycle.</p> <p>A global GC cycle can be triggered explicitly or implicitly according to the following rules:</p> <ul> <li>A global GC cycle is triggered implicitly if it occurs because of internal mechanisms, such as an allocation failure or a taxation threshold being reached.</li> <li>A global GC cycle is triggered explicitly if it is started directly by an application calling <code>System.gc()</code> or indirectly, for example when requesting a heap dump.</li> </ul> <p>Partial GC cycles are triggered only implicitly under the control of a particular GC policy. For more information about the GC policies available with Eclipse OpenJ9\u2122, see Garbage collection policies.</p> <p>The GC process is designed to operate without intervention from an application. Developers should not attempt to predict GC behavior, for example, by making calls to <code>System.gc()</code> to trigger a cycle or by using finalizers to clean up objects in memory. Such actions might degrade the performance of an application.</p>"},{"location":"gc_overview/#gc-operations","title":"GC operations","text":"<p>GC operations run discrete functions on the Java heap. For example, a mark operation traces all objects in the heap to determine which ones are reachable. A sweep operation runs to clear away unreachable objects. Together, a mark and sweep operation are capable of reclaiming used memory as part of a GC cycle. Not all GC cycles include operations to reclaim memory. For example, the <code>balanced</code> GC policy involves a global cycle that includes only a mark operation; reclaiming the memory with a sweep operation occurs as part of a separate partial GC cycle that evacuates younger regions and defragments older regions.</p> <p>A GC operation might complete in one step, or it might involve multiple steps. For example, a mark operation consists of three steps, as described in the following section.</p>"},{"location":"gc_overview/#gc-mark-operation","title":"GC mark operation","text":"<p>A mark operation identifies which objects on the Java heap are reachable from outside of the heap and which objects are unreachable. Reachable objects are in use and must be retained, whereas unreachable objects are not in use and can be cleared away as garbage.</p> <p>The process of marking involves a bit array called a mark map that is allocated by the VM at startup, based on the maximum heap size setting. Each bit in the mark map corresponds to 8 bytes of heap space. When an object is marked, its location in the heap is recorded by setting the appropriate bit in the mark map.</p> <p>A mark operation can be broken down into the following steps:</p> <ol> <li> <p>Initial</p> <p>A root object is an object that is accessible from outside of the heap such as a stack, class static field, or JNI reference. For other objects in the heap to be reachable, they must retain a connection from a root object. In the initial step, tracing identifies all root objects by running a root scan. Root objects are pushed onto a work stack for processing in the next step.</p> </li> <li> <p>Main</p> <p>The list of reachable root objects in the work stack is recursively traced for references to other objects in the heap. Objects that are not marked are new objects and these are added to the work stack. If an object is reachable, the appropriate bit is set in the mark map.</p> </li> <li> <p>Final</p> <p>The final step processes weakly reachable roots such as finalizable objects, weak references, monitor sets, and string sets. For more information about the processing of soft, weak, and phantom references, see Weak reference processing.</p> </li> </ol> <p>In general, helper threads are used in parallel to speed up mark operations on the heap. The helper threads share the work stack with the application thread and are involved in identifying root objects, tracing objects in the heap, and updating the mark map. By default, the number of helper threads is based on the number of CPUs reported by the operating system. You can control the number of helper threads available by specifying the -Xgcthreads command line option when starting your application.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"mark\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#concurrent-mark-processing","title":"Concurrent mark processing","text":"<p>A mark operation can run with exclusive access to the heap, which requires application threads to pause while processing takes place. Alternatively, it can run concurrently with application threads to avoid pauses in application processing.</p> <p>With concurrent mark, the process of root scanning is handed over to application stack threads, which populate the work stack with root objects in their stack. The root objects in the work stack are then traced by a background thread and by each application thread during a heap lock allocation to find reachable objects and update the mark map. Because the mark operation runs concurrently with application threads, any changes to objects that are already traced must be updated. This process works by using a write barrier that can flag the update and trigger a further scan of part of the heap.</p> <p>To track updates to objects, concurrent mark operations use single-byte cards in a card table. Each card corresponds to a 512-byte section of the Java heap. When an object is updated, the start address for the object in the heap is marked on the appropriate card. These cards are used to determine what must be retraced later in the GC cycle.</p> <p>A GC cycle that includes concurrent mark operations aims to trace all reachable objects and complete processing at the same time as the heap is exhausted. Continuous adjustments are made to the start time of each cycle to get as close to heap exhaustion as possible. When the heap is exhausted a sweep operation is able to reclaim memory. This operation requires a STW pause. Before sweep operations start, the root objects are rescanned and the cards are checked to determine which areas of memory must be retraced.</p> <p>An advantage of concurrent mark operations over STW mark operations is reduced pause times, because the garbage collector is able to identify garbage without halting application threads. Pause times are also more consistent because the collector is able to tune start times to maximize heap usage.</p> <p>Disadvantages of concurrent mark operations include the additional CPU for operating the write barrier and additional work for application threads to trace objects when requesting a heap lock.</p> <p>Concurrent mark operations are used by the <code>gencon</code> GC policy and the <code>optavgpause</code> GC policy.</p>"},{"location":"gc_overview/#incremental-concurrent-mark-processing","title":"Incremental concurrent mark processing","text":"<p>Incremental concurrent mark processing evens out pause times by avoiding global STW garbage collections. This type of marking is also known as the global mark phase, whereby mark operations take place incrementally across the entire heap. The global mark operations are interleaved with a partial GC cycle that is responsible for moving objects and clearing unreachable objects in the heap.</p> <p>These operations also use mark map in a card table to manage updates to objects that occur whilst mark operations are in progress. However, unlike the concurrent mark operations used by other policies, application threads are not involved in tracing objects; only background threads are used to trace objects and update the mark map.</p> <p>Incremental concurrent mark operations are used by the <code>balanced GC policy</code>.</p>"},{"location":"gc_overview/#gc-sweep-operation","title":"GC sweep operation","text":"<p>The purpose of a sweep operation is to identify memory that can be reclaimed for object allocation and update a central record, known as the freelist.</p> <p>sweep operations occur in 2 steps:</p> <ol> <li> <p>Initial</p> <p>This step analyzes the mark map for free memory.</p> </li> <li> <p>Final</p> <p>Based on the analysis, the sections of the heap are connected to the freelist.</p> </li> </ol> <p>As with mark operations, multiple helper threads can be used to sweep the Java heap in parallel to speed up processing times. Because these helper threads are the same ones that are used for parallel mark operations, the number of threads can be controlled by using the -Xgcthreads option.</p> <p>Parallel sweep operations run on 256 KB sections of the heap. Each helper thread scans a section at a time. The results are stored and used to generate a freelist of empty regions.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"sweep\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#concurrent-sweep-processing","title":"Concurrent sweep processing","text":"<p>Concurrent sweep processing works in tandem with concurrent mark processing and uses the same mark map. Concurrent sweep operations start after a STW collection and complete a section of the heap before concurrent mark operations continue.</p> <p>Concurrent sweep is used by the <code>optavgpause</code> GC policy.</p>"},{"location":"gc_overview/#gc-scavenge-operation","title":"GC scavenge operation","text":"<p>A GC scavenge operation is triggered by an allocation failure in the nursery area of the heap. The operation occurs in the following 3 steps:</p> <ol> <li> <p>Initial</p> <p>A root object is an object that is accessible from outside of the heap such as a stack, class static field, or JNI reference. For other objects in the heap to be reachable, they must retain a connection from a root object. In the initial step, tracing identifies all root objects by running a root scan. Root objects are pushed onto a work stack for processing in the next step.</p> </li> <li> <p>Main</p> <p>The list of reachable root objects in the work stack is recursively traced for references to other objects in the heap by using the hierarchical scan ordering mode (<code>-Xgc:hierarchicalScanOrdering</code>). If new objects are found, they are added to the work stack. If an object is reachable, it is copied from the allocate space to the survivor space in the nursery area or to the tenure area if the object has reached a particular age.</p> </li> <li> <p>Final</p> <p>The final step processes weakly reachable roots such as finalizable objects, weak references, monitor sets, and string sets. For more information about the processing of soft, weak, and phantom references, see Weak reference processing.</p> </li> </ol> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"scavenge\"&gt;</code> XML element. For more information, see Verbose GC logs.</p> <p>The scavenge operation is used by the <code>gencon</code> GC policy.</p>"},{"location":"gc_overview/#gc-copy-forward-operation","title":"GC copy forward operation","text":"<p>A GC copy forward operation is similar to a scavenge operation but is triggered by a taxation threshold being reached. The operation occurs in the following 3 steps:</p> <ol> <li> <p>Initial</p> <p>A root object is an object that is accessible from outside of the heap such as a stack, class static field, or JNI reference. For other objects in the heap to be reachable, they must retain a connection from a root object. In the initial step, tracing identifies all root objects by running a root scan. Root objects are pushed onto a work stack for processing in the next step.</p> </li> <li> <p>Main</p> <p>The list of reachable root objects in the work stack is recursively traced for references to other objects in the heap by using dynamic breadth first scan ordering mode (<code>-Xgc:dynamicBreadthFirstScanOrdering</code>). If new objects are found, they are added to the work stack. If an object is reachable, it is moved to another region of the same age or to an empty region of the same age in the heap. The age of all regions in the heap is then incremented by 1, except for the oldest region (age 24).</p> </li> <li> <p>Final</p> <p>The final step processes weakly reachable roots such as finalizable objects, weak references, monitor sets, and string sets. For more information about the processing of soft, weak, and phantom references, see Weak reference processing.</p> </li> </ol> <p>The operation aims to empty or evacuate fragmented regions that can then be reclaimed for new object allocation.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"copy forward\"&gt;</code> XML element. For more information, see Verbose GC logs.</p> <p>The copy forward operation is used by the <code>balanced GC policy</code>.</p>"},{"location":"gc_overview/#gc-classunloading-operation","title":"GC classunloading operation","text":"<p>The classunloading operation is single threaded, not parallel threaded.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"classunload\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#gc-compact-operation","title":"GC compact operation","text":"<p>Compaction of the heap is an expensive operation because when objects are moved to defragment the heap, the references to each object change. Therefore, compact operations do not occur by default but only when the following triggers occur:</p> <ul> <li>The <code>-Xcompactgc</code> option is specified on the command line.</li> <li>After sweeping the heap, there is not enough free space available to satisfy an allocation request.</li> <li>A <code>System.gc()</code> is requested and the last allocation failure that triggered a global GC cycle did not compact or <code>-Xcompactexplicitgc</code> is specified.</li> <li>At least half the previously available memory has been consumed by TLH allocations (ensuring an accurate sample) and the average TLH size falls to less than 1024 bytes.</li> <li>The largest object that the <code>gencon</code> GC policy failed to move to the tenure area in the most recent scavenge operation is bigger than the largest free slot in the tenure area.</li> <li>The heap is fully expanded and less than 4% of the tenure area is free.</li> <li>Less than 128 KB of the heap is free.</li> </ul> <p>The following two options can be used to control compaction:</p> <ul> <li><code>-Xcompactgc</code> forces compaction of the heap.</li> <li><code>-Xnocompactgc</code> avoids compaction of the heap as a result of all the triggers shown in the preceding list. However a compaction can still occur in rare circumstances.</li> </ul> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"compact\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#weak-reference-processing","title":"Weak reference processing","text":"<p>Weak reference processing includes soft references, weak references, and phantom references. These references are created by the user for specific use cases and allow some level of interaction with the garbage collector. For example, a soft reference to an object allows that object to persist in memory for a longer period of time before being cleared. For example, a software cache. The garbage collector handles the reference types in the order shown and with the behavior detailed in the following table:</p> Reference type Class Garbage collector behavior soft <code>java.lang.ref.SoftReference</code> A soft reference is cleared only when its referent is not marked for a number of GC cycles or if space on the heap is likely to cause an out of memory error. Use the -Xsoftrefthreshold option to control the collection of soft reference objects. weak <code>java.lang.ref.WeakReference</code> A weak reference is cleared as soon as its referent is not marked by a GC cycle. phantom <code>java.lang.ref.PhantomReference</code> A phantom reference is cleared automatically as soon as its referent is not marked by a GC cycle. The cleared reference is then added to the associated reference queue at the same time or later. <p>If your application uses the Java Native Interface (JNI) to interact with other application types, you can also create weak JNI object references. These references have a similar life cycle to a weak Java reference. The garbage collector processes weak JNI references after all other Java reference types.</p>"},{"location":"interface_dtfj/","title":"DTFJ","text":""},{"location":"interface_dtfj/#diagnostic-tool-framework-for-java","title":"Diagnostic Tool Framework for Java","text":"<p>The Diagnostic Tool Framework for Java\u2122 (DTFJ) is a Java application programming interface (API) that is used to support the building of Java diagnostic tools. DTFJ works with data from a system dump or a Java dump.</p> <p>On Linux and AIX\u00ae operating systems, you can get more information from a system dump if you also have copies of executable files and libraries. You can run the <code>jpackcore</code> utility to collect these files into a single archive for use in subsequent problem diagnosis. For more information, see Dump extractor.</p> <p>The DTFJ API helps diagnostic tools access the following information:  </p> <ul> <li>Memory locations stored in the dump (System dumps only)</li> <li>Relationships between memory locations and Java internals (System dumps only)</li> <li>Java threads running in the VM</li> <li>Native threads held in the dump (System dumps only)</li> <li>Java classes and their class loaders that were present</li> <li>Java objects that were present in the heap (System dumps only)</li> <li>Java monitors and the objects and threads they are associated with</li> <li>Details of the workstation on which the dump was produced (System dumps only)</li> <li>Details of the Java version that was being used</li> <li>The command line that launched the VM</li> </ul> <p>If your DTFJ application requests information that is not available in the Java dump, the API will return null or throw a <code>DataUnavailable</code> exception. You might need to adapt DTFJ applications written to process system dumps to make them work with Java dumps.</p> <p>DTFJ is implemented in pure Java and tools written using DTFJ can be cross-platform. Therefore, you can analyze a dump taken from one workstation on another (remote and more convenient) machine. For example, a dump produced on an AIX\u00ae Power\u00ae system can be analyzed on a Windows laptop.</p> <p>See the DTFJ API documentation. </p> <p> Note: If the code that loads DTFJ is in a module, the module must require the <code>openj9.dtfj</code> module. For example:</p> <pre><code>module MyModule {\n  requires openj9.dtfj;\n}\n</code></pre>"},{"location":"interface_dtfj/#using-the-dtfj-interface","title":"Using the DTFJ interface","text":"<p>To create applications that use DTFJ, you must use the DTFJ interface. Implementations of this interface have been written that work with system dumps and Java dumps.</p> <p>The diagram that follows illustrates the DTFJ interface. The starting point for working with a dump is to obtain an <code>Image</code> instance by using the <code>ImageFactory</code> class supplied with the concrete implementation of the API.</p>"},{"location":"interface_dtfj/#working-with-a-system-dump","title":"Working with a system dump","text":"<p>The following example shows how to work with a system dump. In this example, the only section of code that ties the dump to a particular implementation of DTFJ is the generation of the factory class. Change the factory if you want to use a different implementation.</p> <p>If there is a problem with the file that is passed to the <code>getImage()</code> method, an <code>IOException</code> is thrown and an appropriate message is issued. If a missing file is passed to the example shown, the following output is produced:</p> <pre><code>Could not find/use required file(s)\njava.io.FileNotFoundException: core_file.xml (The system cannot find the file specified.)\n        at java.io.FileInputStream.open(Native Method)\n        at java.io.FileInputStream.&lt;init&gt;(FileInputStream.java:135)\n        at com.ibm.dtfj.image.j9.ImageFactory.getImage(ImageFactory.java:47)\n        at com.ibm.dtfj.image.j9.ImageFactory.getImage(ImageFactory.java:35)\n        at DTFJEX1.main(DTFJEX1.java:23)Copy\n</code></pre> <p>In this case, the DTFJ implementation is expecting a dump file to exist. Different errors are caught if the file existed but was not recognized as a valid dump file.</p> Example of working with a system dump <pre><code>import java.io.File;\nimport java.util.Iterator;\nimport java.io.IOException;\n\nimport com.ibm.dtfj.image.CorruptData;\nimport com.ibm.dtfj.image.Image;\nimport com.ibm.dtfj.image.ImageFactory;\n\npublic class DTFJEX1 {\n    public static void main(String[] args) {\n        Image image = null;\n        if (args.length &gt; 0) {\n            File f = new File(args[0]);\n            try {\n                Class factoryClass = Class.forName(\"com.ibm.dtfj.image.j9.ImageFactory\");\n                ImageFactory factory = (ImageFactory) factoryClass.newInstance();\n                image = factory.getImage(f);\n            } catch (ClassNotFoundException e) {\n                System.err.println(\"Could not find DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IllegalAccessException e) {\n                System.err.println(\"IllegalAccessException for DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (InstantiationException e) {\n                System.err.println(\"Could not instantiate DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IOException e) {\n                System.err.println(\"Could not find/use required file(s)\");\n                e.printStackTrace(System.err);\n            }\n        } else {\n            System.err.println(\"No filename specified\");\n        }\n        if (image == null) {\n            return;\n        }\n\n        Iterator asIt = image.getAddressSpaces();\n        int count = 0;\n        while (asIt.hasNext()) {\n            Object tempObj = asIt.next();\n            if (tempObj instanceof CorruptData) {\n                System.err.println(\"Address Space object is corrupt: \"\n                        + (CorruptData) tempObj);\n            } else {\n                count++;\n            }\n        }\n        System.out.println(\"The number of address spaces is: \" + count);\n    }\n}\n</code></pre>"},{"location":"interface_dtfj/#working-with-a-java-dump","title":"Working with a Java dump","text":"<p>To work with a Java dump, change the factory class to <code>com.ibm.dtfj.image.javacore.JCImageFactory</code> and pass the Java dump file to the <code>getImage()</code> method.</p> Example of working with a Java dump <pre><code>import java.io.File;\nimport java.util.Iterator;\nimport java.io.IOException;\n\nimport com.ibm.dtfj.image.CorruptData;\nimport com.ibm.dtfj.image.Image;\nimport com.ibm.dtfj.image.ImageFactory;\n\npublic class DTFJEX2 {\n    public static void main(String[] args) {\n        Image image=null;\n\n        if (args.length &gt; 0) {\n            File javacoreFile = new File(args[0]);\n\n            try {\n                Class factoryClass = Class.forName(\"com.ibm.dtfj.image.javacore.JCImageFactory\");\n                ImageFactory factory = (ImageFactory) factoryClass.newInstance();\n                image = factory.getImage(javacoreFile);\n            } catch (ClassNotFoundException e) {\n                System.err.println(\"Could not find DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IllegalAccessException e) {\n                System.err.println(\"IllegalAccessException for DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (InstantiationException e) {\n                System.err.println(\"Could not instantiate DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IOException e) {\n                System.err.println(\"Could not find/use required file(s)\");\n                e.printStackTrace(System.err);\n            }\n        } else {\n            System.err.println(\"No filename specified\");\n        }\n        if (image == null) {\n            return;\n        }\n\n        Iterator asIt = image.getAddressSpaces();\n        int count = 0;\n        while (asIt.hasNext()) {\n            Object tempObj = asIt.next();\n            if (tempObj instanceof CorruptData) {\n                System.err.println(\"Address Space object is corrupt: \"\n                        + (CorruptData) tempObj);\n            } else {\n                count++;\n            }\n        }\n        System.out.println(\"The number of address spaces is: \" + count);\n    }\n}\n</code></pre>"},{"location":"interface_dtfj/#analyze-the-dump","title":"Analyze the dump","text":"<p>After you have obtained an <code>Image</code> instance, you can begin analyzing the dump. The <code>Image</code> instance is the second instance in the class hierarchy for DTFJ illustrated by the following diagram:</p> <p></p> <p>Some things to note from the diagram:</p> <ul> <li>The DTFJ interface is separated into two parts: classes with names that start with <code>Image</code> (the dump, a sequence of bytes with different contents on different platforms) and classes with names that start with <code>Java</code> (the Java internal knowledge).</li> <li><code>Image</code> and <code>Java</code> classes are linked using a <code>ManagedRuntime</code> class (which is extended by <code>JavaRuntime</code>).</li> <li>An <code>Image</code> object contains one <code>ImageAddressSpace</code> object (or, on z/OS\u00ae, possibly more).</li> <li>An <code>ImageAddressSpace</code> object contains one <code>ImageProcess</code> object (or, on z/OS, possibly more).</li> <li>Conceptually, you can apply the <code>Image</code> model to any program running with the <code>ImageProcess</code>. For the purposes of this document discussion is limited to the Eclipse OpenJ9\u2122 virtual machine implementations.</li> <li>There is a link from a <code>JavaThread</code> object to its corresponding <code>ImageThread</code> object. Use this link to find out about native code associated with a Java thread, for example JNI functions that have been called from Java.</li> <li>If a <code>JavaThread</code> was not running Java code when the dump was taken, the <code>JavaThread</code> object has no <code>JavaStackFrame</code> objects. In these cases, use the link to the corresponding <code>ImageThread</code> object to find out what native code was running in that thread. This situation is typically the case with the JIT compilation thread and Garbage Collection threads.</li> <li>The DTFJ interface enables you to obtain information about native memory. Native memory is memory requested from the operating system using library functions such as <code>malloc()</code> and <code>mmap()</code>. When the Java runtime allocates native memory, the memory is associated with a high-level memory category. For more information about native memory detailed in a Java dump, see Java dump: <code>NATIVEMEMINFO</code></li> </ul>"},{"location":"interface_dtfj/#dtfj-example-application","title":"DTFJ example application","text":"<p>This example is a fully working DTFJ application. Many DTFJ applications will follow a similar model.</p> Sample DTFJ application <pre><code>import java.io.File;\nimport java.util.Iterator;\nimport com.ibm.dtfj.image.CorruptData;\nimport com.ibm.dtfj.image.CorruptDataException;\nimport com.ibm.dtfj.image.DataUnavailable;\nimport com.ibm.dtfj.image.Image;\nimport com.ibm.dtfj.image.ImageAddressSpace;\nimport com.ibm.dtfj.image.ImageFactory;\nimport com.ibm.dtfj.image.ImageProcess;\nimport com.ibm.dtfj.java.JavaRuntime;\nimport com.ibm.dtfj.java.JavaThread;\nimport com.ibm.dtfj.image.ImageThread;\n\npublic class DTFJEX2\n{\n   public static void main( String[] args )\n   {\n      Image image = null;\n      if ( args.length &gt; 0 )\n      {\n         File f = new File( args[0] );\n         try\n         {\n            Class factoryClass = Class\n                  .forName( \"com.ibm.dtfj.image.j9.ImageFactory\" );\n            ImageFactory factory = (ImageFactory) factoryClass.newInstance( );\n            image = factory.getImage( f );\n         }\n         catch ( Exception ex )\n         { /*\n             * Should use the error handling as shown in DTFJEX1.\n             */\n            System.err.println( \"Error in DTFJEX2\" );\n            ex.printStackTrace( System.err );\n         }\n      }\n      else\n      {\n         System.err.println( \"No filename specified\" );\n      }\n\n      if ( null == image )\n      {\n         return;\n      }\n\n      MatchingThreads( image );\n   }\n\n   public static void MatchingThreads( Image image )\n   {\n      ImageThread imgThread = null;\n\n      Iterator asIt = image.getAddressSpaces( );\n      while ( asIt.hasNext( ) )\n      {\n         System.out.println( \"Found ImageAddressSpace...\" );\n\n         ImageAddressSpace as = (ImageAddressSpace) asIt.next( );\n\n         Iterator prIt = as.getProcesses( );\n\n         while ( prIt.hasNext( ) )\n         {\n            System.out.println( \"Found ImageProcess...\" );\n\n            ImageProcess process = (ImageProcess) prIt.next( );\n\n            Iterator runTimesIt = process.getRuntimes( );\n            while ( runTimesIt.hasNext( ) )\n            {\n               System.out.println( \"Found Runtime...\" );\n               JavaRuntime javaRT = (JavaRuntime) runTimesIt.next( );\n\n               Iterator javaThreadIt = javaRT.getThreads( );\n\n               while ( javaThreadIt.hasNext( ) )\n               {\n                  Object tempObj = javaThreadIt.next( );\n                  /*\n                   * Should use CorruptData handling for all iterators\n                   */\n                  if ( tempObj instanceof CorruptData )\n                  {\n                     System.out.println( \"We have some corrupt data\" );\n                  }\n                  else\n                  {\n                     JavaThread javaThread = (JavaThread) tempObj;\n                     System.out.println( \"Found JavaThread...\" );\n                     try\n                     {\n                        imgThread = (ImageThread) javaThread.getImageThread( );\n\n                        // Now we have a Java thread we can iterator\n                        // through the image threads\n                        Iterator imgThreadIt = process.getThreads( );\n\n                        while ( imgThreadIt.hasNext( ) )\n                        {\n                           ImageThread imgThread2 = (ImageThread) imgThreadIt\n                                 .next( );\n                           if ( imgThread.equals( imgThread2 ) )\n                           {\n                              System.out.println( \"Found a match:\" );\n                              System.out.println( \"\\tjavaThread \"\n                                    + javaThread.getName( )\n                                    + \" is the same as \" + imgThread2.getID( ) );\n                           }\n                        }\n                     }\n                     catch ( CorruptDataException e )\n                     {\n                        System.err.println( \"ImageThread was corrupt: \"\n                              + e.getMessage( ) );\n                     }\n                     catch ( DataUnavailable e )\n                     {\n                        System.out.println( \"DataUnavailable: \"\n                              + e.getMessage( ) );\n                     }\n                  }\n               }\n            }\n         }\n      }\n   }\n}\n</code></pre> <p>For clarity, the example does not perform full error checking when constructing the main Image object and does not perform <code>CorruptData</code> handling in all of the iterators. In a production environment, you use the techniques illustrated in the previous examples under Working with a system dump and Working with a Java dump.</p> <p>In the example, the program iterates through every available Java thread and checks whether it is equal to any of the available image threads. When they are found to be equal, the program displays the following message: \"Found a match\".</p> <p>The example demonstrates:</p> <ul> <li>How to iterate down through the class hierarchy.</li> <li>How to handle <code>CorruptData</code> objects from the iterators.</li> <li>The use of the <code>.equals</code> method for testing equality between objects.</li> </ul>"},{"location":"interface_jvmti/","title":"JVMTI","text":""},{"location":"interface_jvmti/#java-virtual-machine-tool-interface","title":"Java Virtual Machine Tool Interface","text":"<p>The Java\u2122 Virtual Machine Tool Interface (JVMTI) is a two-way interface that allows communication between the VM and a native agent. It replaces both the Java Virtual Machine Debug Interface (JVMDI) and Java Virtual Machine Profiler Interface (JVMPI).</p>"},{"location":"interface_jvmti/#overview","title":"Overview","text":"<p>The JVMTI allows third parties to develop debugging, profiling, and monitoring tools for the VM. The interface contains mechanisms for the agent to notify the VM about the kinds of information it requires, and also provides a means of receiving relevant notifications.</p> <p>Several agents can be attached to a VM at any one time.</p> <p>JVMTI agents can be loaded at startup using short or long forms of the command-line option:</p> <pre><code>-agentlib:&lt;agent-lib-name&gt;=&lt;options&gt;\n</code></pre> <p>or</p> <pre><code>-agentpath:&lt;path-to-agent&gt;=&lt;options&gt;\n</code></pre> <p>In the example that follows (see Sample JVMTI agent), the directory containing the <code>jdwp</code> library is assumed to  be on the library path. If you require a specific library, such as <code>jdwp</code>, with your JVMTI agent, you can specify the path at startup, for example:</p> <pre><code>-agentlib:jdwp=&lt;options&gt;\n</code></pre> <p>For more information about JVMTI, see https://docs.oracle.com/javase/8/docs/technotes/guides/management/index.html.</p> <p>For a guide about writing a JVMTI agent, see http://www.oracle.com/technetwork/articles/javase/jvmti-136367.html.</p>"},{"location":"interface_jvmti/#eclipse-openj9-extensions","title":"Eclipse OpenJ9 extensions","text":"<p>Eclipse OpenJ9\u2122 extensions to the JVMTI allow a JVMTI agent to query or automatically trigger operations in the VM, including the following tasks:</p> Task OpenJ9 extensions Get the OS thread ID <code>GetOSThreadID</code> Query, set, and reset the VM dump options <code>QueryVmDump</code>, <code>SetVmDump</code>, <code>ResetVmDump</code> Trigger a VM dump, and monitor JVMTI event functions when VM dumps start and end <code>TriggerVmDump</code>, <code>VMDumpStart</code>, <code>VMDumpEnd</code> Set VM trace options <code>SetVmTrace</code> Subscribe to and unsubscribe from VM tracepoints <code>RegisterTracePointSubscriber</code>, <code>DeregisterTracePointSubscriber</code> Query runtime environment native memory categories <code>GetMemoryCategories</code> Query and set VM log options <code>QueryVmLogOptions</code>, <code>SetVmLogOptions</code> Search for and remove a shared classes cache <code>IterateSharedCaches</code>, <code>DestroySharedCache</code> Subscribe to and unsubscribe from verbose garbage collection (GC) data logging <code>RegisterVerboseGCSubscriber</code>, <code>DeregisterVerboseGCSubscriber</code> <p>The definitions that you need when you write a JVMTI agent are provided in the header files <code>jvmti.h</code> and <code>ibmjvmti.h</code>, in the  <code>include</code> directory.</p>"},{"location":"interface_jvmti/#sample-jvmti-agent","title":"Sample JVMTI agent","text":"<p>The following sample shows you how to write a simple JVMTI agent that uses OpenJ9 extensions to the JVMTI.</p> Sample JVMTI agent written in C/C++, which uses the OpenJ9 extensions <pre><code>/*\n * tiSample.c\n *\n * Sample JVMTI agent to demonstrate the OpenJ9 JVMTI dump extensions\n */\n\n#include \"jvmti.h\"\n#include \"ibmjvmti.h\"\n\n/* Forward declarations for JVMTI callback functions */\nvoid JNICALL VMInitCallback(jvmtiEnv *jvmti_env, JNIEnv* jni_env, jthread thread);\nvoid JNICALL DumpStartCallback(jvmtiEnv *jvmti_env, char* label, char* event, char* detail, ...);\n\n\n/*\n * Agent_Onload()\n *\n * JVMTI agent initialisation function, invoked as agent is loaded by the VM\n */\nJNIEXPORT jint JNICALL Agent_OnLoad(JavaVM *jvm, char *options, void *reserved) {\n\n  jvmtiEnv *jvmti = NULL;\n  jvmtiError rc;\n  jint extensionEventCount = 0;\n  jvmtiExtensionEventInfo *extensionEvents = NULL;\n  jint extensionFunctionCount = 0;\n  jvmtiExtensionFunctionInfo *extensionFunctions = NULL;\n  int i = 0, j = 0;\n\n  printf(\"tiSample: Loading JVMTI sample agent\\n\");\n\n    /* Get access to JVMTI */\n    (*jvm)-&gt;GetEnv(jvm, (void **)&amp;jvmti, JVMTI_VERSION_1_0);\n\n     /* Look up all the JVMTI extension events and functions */\n   (*jvmti)-&gt;GetExtensionEvents(jvmti, &amp;extensionEventCount, &amp;extensionEvents);\n   (*jvmti)-&gt;GetExtensionFunctions(jvmti, &amp;extensionFunctionCount, &amp;extensionFunctions);\n\n    printf(\"tiSample: Found %i JVMTI extension events, %i extension functions\\n\", extensionEventCount, extensionFunctionCount);\n\n   /* Find the JVMTI extension event we want */\n   while (i++ &lt; extensionEventCount) {\n\n        if (strcmp(extensionEvents-&gt;id, COM_IBM_VM_DUMP_START) == 0) {\n            /* Found the dump start extension event, now set up a callback for it */\n            rc = (*jvmti)-&gt;SetExtensionEventCallback(jvmti, extensionEvents-&gt;extension_event_index, &amp;DumpStartCallback);\n            printf(\"tiSample: Setting JVMTI event callback %s, rc=%i\\n\", COM_IBM_VM_DUMP_START, rc);\n            break;\n        }\n        extensionEvents++; /* move on to the next extension event */\n    }\n\n    /* Find the JVMTI extension function we want */\n    while (j++ &lt; extensionFunctionCount) {\n        jvmtiExtensionFunction function = extensionFunctions-&gt;func;\n\n        if (strcmp(extensionFunctions-&gt;id, COM_IBM_SET_VM_DUMP) == 0) {\n            /* Found the set dump extension function, now set a dump option to generate javadumps on\n          thread starts */\n            rc = function(jvmti, \"java:events=thrstart\");\n            printf(\"tiSample: Calling JVMTI extension %s, rc=%i\\n\", COM_IBM_SET_VM_DUMP, rc);\n            break;\n        }\n        extensionFunctions++; /* move on to the next extension function */\n     }\n\n     return JNI_OK;\n}\n\n\n/*\n * DumpStartCallback()\n * JVMTI callback for dump start event (IBM JVMTI extension)  */\nvoid JNICALL\nDumpStartCallback(jvmtiEnv *jvmti_env, char* label, char* event, char* detail, ...) {\n      printf(\"tiSample: Received JVMTI event callback, for event %s\\n\", event);\n}\n</code></pre> <p>The sample JVMTI agent consists of two functions, <code>Agent_OnLoad()</code> and <code>DumpStartCallback()</code>:</p>"},{"location":"interface_jvmti/#agent_onload","title":"<code>Agent_OnLoad()</code>","text":"<p>This function is called by the VM when the agent is loaded at VM startup, which allows the JVMTI agent to modify VM behavior before initialization is complete. The sample agent obtains access to the JVMTI interface by using the JNI Invocation API function <code>GetEnv()</code>. The agent calls the APIs <code>GetExtensionEvents()</code> and <code>GetExtensionFunctions()</code> to find the JVMTI extensions that are supported by the VM. These APIs provide access to the list of extensions available in the <code>jvmtiExtensionEventInfo</code> and <code>jvmtiExtensionFunctionInfo</code> structures. The sample uses an extension event and an extension function in the following way:</p> <p>Extension event: The sample JVMTI agent searches for the extension event <code>VmDumpStart</code> in the list of <code>jvmtiExtensionEventInfo</code> structures, by using the identifier <code>COM_IBM_VM_DUMP_START</code> provided in <code>ibmjvmti.h</code>. When the event is found, the JVMTI agent calls the JVMTI interface <code>SetExtensionEventCallback()</code> to enable the event, providing a function <code>DumpStartCallback()</code> that is called when the event is triggered.</p> <p>Extension function: Next, the sample JVMTI agent searches for the extension function <code>SetVMDump</code> in the list of <code>jvmtiExtensionFunctionInfo</code> structures, by using the identifier <code>COM_IBM_SET_VM_DUMP</code> provided in <code>ibmjvmti.h</code>. The JVMTI agent calls the function by using the <code>jvmtiExtensionFunction</code> pointer to set a VM dump option <code>java:events=thrstart</code>. This option requests the VM to trigger a Java dump every time a VM thread is started.</p>"},{"location":"interface_jvmti/#dumpstartcallback","title":"<code>DumpStartCallback()</code>","text":"<p>This callback function issues a message when the associated extension event is called. In the sample code, <code>DumpStartCallback()</code> is used when the <code>VmDumpStart</code> event is triggered.</p>"},{"location":"interface_jvmti/#using-the-sample-jvmti-agent","title":"Using the sample JVMTI agent","text":"<ul> <li> <p>Build the sample JVMTI agent:</p> <p>Windows:</p> <pre><code>cl /I&lt;jre_path&gt;\\include /MD /FetiSample.dll tiSample.c /link /DLL\n</code></pre> <p>Linux, AIX\u00ae, and z/OS\u00ae:</p> <pre><code>gcc -I&lt;jre_path&gt;/include -o libtiSample.so -shared tiSample.c\n</code></pre> <p>where <code>&lt;jre_path&gt;</code> is the path to your Java runtime environment installation.</p> </li> <li> <p>To run the sample JVMTI agent, use the command:</p> <pre><code>java -agentlib:tiSample -version\n</code></pre> <p>When the sample JVMTI agent loads, messages are generated. When the JVMTI agent initiates a Java dump, the message <code>JVMDUMP010</code> is issued.</p> </li> </ul>"},{"location":"interface_jvmti/#api-reference","title":"API reference","text":"<p>The following sections provide reference information for the OpenJ9 extensions to the JVMTI.</p>"},{"location":"interface_jvmti/#getosthreadid","title":"<code>GetOSThreadID</code>","text":"<p>You can get the OS thread ID by using the <code>GetOSThreadID()</code> API:</p> <pre><code>jvmtiError GetOSThreadID(jvmtiEnv* jvmti_env, jthread thread, jlong * threadid_ptr);\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>thread</code>: The thread for which the ID is required.</li> <li><code>threadid_ptr</code>: A pointer to a variable, used to return the thread ID that corresponds to the thread specified by the <code>thread</code> parameter.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>threadid_ptr</code> parameter is null. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_INVALID_THREAD</code>: The thread is not valid. <code>JVMTI_ERROR_THREAD_NOT_ALIVE</code>: The VM state of the thread is not started or has died. <code>JVMTI_ERROR_UNATTACHED_THREAD</code>: The current thread is not attached to the VM. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI start or live phase.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.GetOSThreadID</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_GET_OS_THREAD_ID</code></p>"},{"location":"interface_jvmti/#queryvmdump","title":"<code>QueryVmDump</code>","text":"<p>You can query the VM dump options that are set for a VM by using the <code>QueryVmDump()</code> API:</p> <pre><code>jvmtiError QueryVmDump(jvmtiEnv* jvmti_env, jint buffer_size, void* options_buffer, jint* data_size_ptr)\n</code></pre> <p>This extension returns a set of dump option specifications as ASCII strings. The syntax of the option string is the same as the <code>-Xdump</code> command-line option, with the initial <code>-Xdump:</code> omitted. See -Xdump. The option strings are separated by newline characters. If the memory buffer is too small to contain the current VM dump option strings, you can expect the following results:</p> <ul> <li>The error message <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code> is returned.</li> <li>The variable for <code>data_size_ptr</code> is set to the required buffer size.</li> </ul> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>buffer_size</code>: The size of the supplied memory buffer in bytes.</li> <li><code>options_buffer</code>: A pointer to the supplied memory buffer.</li> <li><code>data_size_ptr</code>: A pointer to a variable, used to return the total size of the option strings.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>options_buffer</code> or <code>data_size_ptr</code> parameters are null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The supplied memory buffer in <code>options_buffer</code> is too small.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.QueryVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_QUERY_VM_DUMP</code></p>"},{"location":"interface_jvmti/#setvmdump","title":"<code>SetVmDump</code>","text":"<p>You can set VM dump options by using the <code>SetVmDump()</code> API:</p> <pre><code>jvmtiError SetVmDump(jvmtiEnv* jvmti_env, char* option)\n</code></pre> <p>The dump option is passed in as an ASCII character string. Use the same syntax as the <code>-Xdump</code> command-line option, with the initial <code>-Xdump:</code> omitted. See -Xdump.</p> <p>When dumps are in progress, the dump configuration is locked, and calls to <code>SetVmDump()</code> fail with a return value of <code>JVMTI_ERROR_NOT_AVAILABLE</code>.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>option</code>: The VM dump option string. Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The parameter option is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The parameter option contains an invalid <code>-Xdump</code> string.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.SetVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_SET_VM_DUMP</code></p>"},{"location":"interface_jvmti/#triggervmdump","title":"<code>TriggerVmDump</code>","text":"<p>You can trigger a VM dump and specify the type of dump you want by using the <code>TriggerVmDump()</code> API:</p> <pre><code>jvmtiError TriggerVmDump(jvmtiEnv* jvmti_env, char* option)\n</code></pre> <p>Choose the type of dump required by specifying an ASCII string that contains one of the supported dump agent types. See -Xdump. JVMTI events are provided at the start and end of the dump.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li> <p><code>option</code>: A pointer to the dump type string, which can be one of the following types:  </p> <p><code>stack</code> <code>java</code> <code>system</code> <code>console</code> <code>tool</code> <code>heap</code> <code>snap</code> <code>ceedump</code> (z/OS only)  </p> <p> Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.</p> </li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The option parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.TriggerVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_TRIGGER_VM_DUMP</code></p>"},{"location":"interface_jvmti/#resetvmdump","title":"<code>ResetVmDump</code>","text":"<p>You can reset VM dump options to the values at VM initialization by using the <code>ResetVmDump()</code> API:</p> <pre><code>jvmtiError ResetVmDump(jvmtiEnv* jvmti_env)\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: The JVMTI environment pointer.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.ResetVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_RESET_VM_DUMP</code></p>"},{"location":"interface_jvmti/#vmdumpstart","title":"<code>VMDumpStart</code>","text":"<p>The following JVMTI event function is called when a VM dump starts:</p> <pre><code>void JNICALL VMDumpStart(jvmtiEnv *jvmti_env, JNIEnv* jni_env, char* label, char* event, char* detail)\n</code></pre> <p>The event function provides the dump file name, the name of the JVMTI event, and the detail string from the dump event. The detail string provides additional information about the event that triggered the dump. This information is the same as the information detailed in the <code>JVMDUMP039I</code> message. For example:</p> <pre><code>JVMDUMP039I Processing dump event \"systhrow\", detail \"java/lang/OutOfMemoryError\" at 2014/10/17 13:31:03 - please wait.\"\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: JVMTI environment pointer.</li> <li><code>jni_env</code>: JNI environment pointer for the thread on which the event occurred.</li> <li><code>label</code>: The dump file name, including directory path.</li> <li><code>event</code>: The extension event name, such as <code>com.ibm.VmDumpStart</code>.</li> <li><code>detail</code>: The dump event detail string. The string can be empty.</li> </ul> <p>Returns</p> <p>None</p>"},{"location":"interface_jvmti/#vmdumpend","title":"<code>VMDumpEnd</code>","text":"<p>The following JVMTI event function is called when a VM dump ends:</p> <pre><code>void JNICALL VMDumpEnd(jvmtiEnv *jvmti_env, JNIEnv* jni_env, char* label, char* event, char* detail)\n</code></pre> <p>The event function provides the dump file name, the name of the JVMTI event, and the detail string from the dump event. The detail string provides additional information about the event that triggered the dump. This information is the same as the information detailed in the <code>JVMDUMP039I</code> message. For example:</p> <pre><code>JVMDUMP039I Processing dump event \"systhrow\", detail \"java/lang/OutOfMemoryError\" at 2014/10/17 13:31:03 - please wait.\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: JVMTI environment pointer.  </li> <li><code>jni_env</code>: JNI environment pointer for the thread on which the event occurred.  </li> <li><code>label</code>: The dump file name, including directory path.  </li> <li><code>event</code>: The extension event name <code>com.ibm.VmDumpEnd</code>.  </li> <li><code>detail</code>: The dump event detail string. The string can be empty.  </li> </ul> <p>Returns</p> <p>None</p>"},{"location":"interface_jvmti/#setvmtrace","title":"<code>SetVmTrace</code>","text":"<p>You can set VM trace options by using the <code>SetVmTrace()</code> API:</p> <pre><code>jvmtiError SetVmTrace(jvmtiEnv* jvmti_env, char* option)\n</code></pre> <p>The trace option is passed in as an ASCII character string. Use the same syntax as the <code>-Xtrace</code> command-line option, with the initial <code>-Xtrace:</code> omitted. See -Xtrace.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: JVMTI environment pointer.</li> <li><code>option</code>: Enter the VM trace option string. Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The option parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The option parameter contains an invalid <code>-Xtrace</code> string.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.SetVmTrace</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_SET_VM_TRACE</code></p>"},{"location":"interface_jvmti/#registertracepointsubscriber","title":"<code>RegisterTracePointSubscriber</code>","text":"<p>You can subscribe to VM tracepoints by using the <code>RegisterTracePointSubscriber()</code> API:</p> <pre><code>jvmtiError RegisterTracePointSubscriber(jvmtiEnv* jvmti_env, char *description, jvmtiTraceSubscriber subscriber, jvmtiTraceAlarm alarm, void *userData, void **subscriptionID)\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>description</code>: An ASCII character string that describes the subscriber.</li> <li><code>subscriber</code>: A function of type <code>jvmtiTraceSubscriber</code>.</li> <li><code>alarm</code>: A function pointer of type <code>jvmtiTraceAlarm</code>.</li> <li><code>user_data</code>: A pointer to user data. This pointer is passed to the subscriber and alarm functions each time these functions are called. This pointer can be a null value.</li> <li><code>subscription_id</code>: A pointer to a subscription identifier. This pointer is returned by the <code>RegisterTracePointSubscriber</code> call if successful. The value must be supplied to a future call to the <code>DeregisterTracePointSubscriber</code> API, which is used to unsubscribe from the VM tracepoint.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: One of the supplied parameters is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: VM trace is not available. <code>JVMTI_ERROR_INTERNAL</code>: An internal error occurred.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.RegisterTracePointSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_REGISTER_TRACEPOINT_SUBSCRIBER</code></p>"},{"location":"interface_jvmti/#jvmtitracesubscriber-function","title":"<code>jvmtiTraceSubscriber</code> function","text":"<p>The subscriber function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiTraceSubscriber)(jvmtiEnv *jvmti_env, void *record, jlong length, void *user_data);\n</code></pre> <p>The subscriber function must be of type <code>jvmtiTraceSubscriber</code>, which is declared in <code>ibmjvmti.h</code>.</p> <p>This function is called with each tracepoint record that is selected through the <code>-Xtrace:external</code> option.</p> <p>The tracepoint record that is supplied to the subscriber function is valid only for the duration of the function. If the subscriber wants to save the data, the data must be copied elsewhere.</p> <p>If the subscriber function returns an error, the alarm function is called, the subscription is disconnected, and no further tracepoints are sent to the subscriber.</p> <p>Subscriber function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>record</code>: A UTF-8 string that contains a tracepoint record.</li> <li><code>length</code>: The number of UTF-8 characters in the tracepoint record.</li> <li><code>user_data</code>: User data that is supplied when the subscriber is registered.</li> </ul>"},{"location":"interface_jvmti/#jvmtitracealarm-function","title":"<code>jvmtiTraceAlarm</code> function","text":"<p>The alarm function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiTraceAlarm)(jvmtiEnv *jvmti_env, void *subscription_id, void *user_data);\n</code></pre> <p>The alarm function must be of type <code>jvmtiTraceAlarm</code>, which is declared in <code>ibmjvmti.h</code>. This function is called if the subscriber function returns an error.</p> <p>Alarm function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>subscription_id</code>: The subscription identifier.</li> <li><code>user_data</code>: User data that is supplied when the subscriber is registered.</li> </ul>"},{"location":"interface_jvmti/#deregistertracepointsubscriber","title":"<code>DeregisterTracePointSubscriber</code>","text":"<p>You can unsubscribe from VM tracepoints by using the <code>DeregisterTracePointSubscriber()</code> API:</p> <pre><code>jvmtiError DeregisterTracePointSubscriber(jvmtiEnv* jvmti_env, void *userData, void *subscription_id)\n</code></pre> <p>After the <code>DeregisterTracePointSubscriber()</code> API is called, no further calls are made to the subscriber function.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>subscription_id</code>: The subscription identifier that is returned by the call to the RegisterTracePointSubscriber API.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>subscription_id</code> parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.DeregisterTracePointSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_DEREGISTER_TRACEPOINT_SUBSCRIBER</code></p>"},{"location":"interface_jvmti/#getmemorycategories","title":"<code>GetMemoryCategories</code>","text":"<p>You can query runtime environment native memory categories by using the <code>GetMemoryCategories()</code> API:</p> <pre><code>jvmtiError GetMemoryCategories(jvmtiEnv* env, jint version, jint max_categories, jvmtiMemoryCategory * categories_buffer, jint * written_count_ptr, jint * total_categories_ptr);\n</code></pre> <p>You can query the total native memory consumption of the runtime environment for each memory category by using this API. Native memory is memory requested from the operating system using library functions such as <code>malloc()</code> and <code>mmap()</code>. Runtime environment native memory use is grouped under high-level memory categories, as described in the <code>NATIVEMEMINFO</code> section of the Java dump topic. The data returned by the <code>GetMemoryCategories()</code> API is consistent with this format. See Java dump: NATIVEMEMINFO.</p> <p>The extension writes native memory information to a memory buffer specified by the user. Each memory category is recorded as a <code>jvmtiMemoryCategory</code> structure, whose format is defined in <code>ibmjvmti.h</code>.</p> <p>You can use the <code>GetMemoryCategories()</code> API to work out the buffer size you must allocate to hold all memory categories defined inside the VM. To calculate the size, call the API with a null <code>categories_buffer</code> argument and a non-null <code>total_categories_ptr</code> argument.</p> <p>Parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment.</li> <li><code>version</code>: The version of the <code>jvmtiMemoryCategory</code> structure that you are using. Use <code>COM_IBM_GET_MEMORY_CATEGORIES_VERSION_1</code> for this argument, unless you must work with an obsolete version of the <code>jvmtiMemoryCategory</code> structure.</li> <li><code>max_categories</code>: The number of <code>jvmtiMemoryCategory</code> structures that can fit in the <code>categories_buffer</code> memory buffer.</li> <li><code>categories_buffer</code>: A pointer to the memory buffer for holding the result of the <code>GetMemoryCategories()</code> call. The number of <code>jvmtiMemoryCategory</code> slots available in the <code>categories_buffer</code> memory buffer must be accurately specified with <code>max_categories</code>, otherwise <code>GetMemoryCategories()</code> can overflow the memory buffer. The value can be null.</li> <li><code>written_count_ptr</code>: A pointer to <code>jint</code> to store the number of <code>jvmtiMemoryCategory</code> structures to be written to the <code>categories_buffer</code> memory buffer. The value can be null.</li> <li><code>total_categories_ptr</code>: A pointer to <code>jint</code> to store the total number of memory categories declared in the VM. The value can be null.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_UNSUPPORTED_VERSION</code>: Unrecognized value passed for version. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: Illegal argument; <code>categories_buffer</code>, <code>count_ptr</code>, and <code>total_categories_ptr</code> all have null values. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>env</code> parameter is invalid. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: Memory category data is truncated because <code>max_categories</code> is not large enough.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.GetMemoryCategories</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_GET_MEMORY_CATEGORIES</code></p>"},{"location":"interface_jvmti/#queryvmlogoptions","title":"<code>QueryVmLogOptions</code>","text":"<p>You can query VM log options by using the <code>QueryVmLogOptions()</code> API:</p> <pre><code>jvmtiError QueryVmLogOptions(jvmtiEnv* jvmti_env, jint buffer_size, void* options, jint* data_size_ptr)\n</code></pre> <p>This extension returns the current log options as an ASCII string. The syntax of the string is the same as the <code>-Xsyslog</code> command-line option, with the initial <code>-Xsyslog:</code> omitted. For example, the string \"error,warn\" indicates that the VM is set to log error and warning messages only. For more information, see <code>-Xsyslog</code>.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.  </li> <li><code>buffer_size</code>: The size of the supplied memory buffer in bytes. If the memory buffer is too small to contain the current VM log option string, the <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code> error message is returned.  </li> <li><code>options_buffer</code>: A pointer to the supplied memory buffer.  </li> <li><code>data_size_ptr</code>: A pointer to a variable, used to return the total size of the option string.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>options</code> or <code>data_size_ptr</code> parameters are null. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The supplied memory buffer is too small.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.QueryVmLogOptions</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_QUERY_VM_LOG_OPTIONS</code></p>"},{"location":"interface_jvmti/#setvmlogoptions","title":"<code>SetVmLogOptions</code>","text":"<p>You can set VM log options by using the <code>SetVmLogOptions()</code> API:</p> <pre><code>jvmtiError SetVmLogOptions(jvmtiEnv* jvmti_env, char* options_buffer)\n</code></pre> <p>The log option is passed in as an ASCII character string. Use the same syntax as the <code>-Xsyslog</code> command-line option, with the initial <code>-Xsyslog:</code> omitted. For example, to set the VM to log error and warning messages, pass in a string containing \"error,warn\". For more information, see <code>-Xsyslog</code>.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>options_buffer</code>: A pointer to memory containing the log option.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The parameter option is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The parameter option contains an invalid <code>-Xsyslog</code> string.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.SetVmLogOptions</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_SET_VM_LOG_OPTIONS</code></p>"},{"location":"interface_jvmti/#iteratesharedcaches","title":"<code>IterateSharedCaches</code>","text":"<p>You can search for shared classes caches that exist in a specified cache directory by using the <code>IterateSharedCaches()</code> API:</p> <pre><code>jvmtiError IterateSharedCaches(jvmtiEnv* env, jint version, const char *cacheDir, jint flags, jboolean useCommandLineValues, jvmtiIterateSharedCachesCallback callback, void *user_data);\n</code></pre> <p>Information about the caches is returned in a structure that is populated by a user-specified callback function. You can specify the search directory in two ways:</p> <ul> <li>Set the value of <code>useCommandLineValues</code> to <code>true</code> and specify the directory on the command line. If the directory is not specified on the command line, the default location for the platform is used.</li> <li>Set the value of <code>useCommandLineValues</code> to <code>false</code> and use the <code>cacheDir</code> parameter. To accept the default location for the platform, specify <code>cacheDir</code> with a <code>null</code> value.</li> </ul> <p>Parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment.</li> <li><code>version</code>: Version information for <code>IterateSharedCaches</code>, which describes the <code>jvmtiSharedCacheInfo</code> structure passed to the <code>jvmtiIterateSharedCachesCallback</code> function. The values allowed are:<ul> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_1</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_2</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_3</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_4</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_5</code></li> </ul> </li> <li><code>cacheDir</code>: When the value of <code>useCommandLineValues</code> is <code>false</code>, specify the absolute path of the directory for the shared classes cache. If the value is <code>null</code>, the platform-dependent default is used.</li> <li><code>flags</code>: Reserved for future use. The only value allowed is <code>COM_IBM_ITERATE_SHARED_CACHES_NO_FLAGS</code>.</li> <li><code>useCommandLineValues</code>: Set this value to <code>true</code> when you want to specify the cache directory on the command line. Set this value to <code>false</code> when you want to use the <code>cacheDir</code> parameter.</li> <li><code>callback</code>: A function pointer to a user provided callback routine <code>jvmtiIterateSharedCachesCallback</code>.</li> <li><code>user_data</code>: User supplied data, passed as an argument to the callback function.  <pre><code>jint (JNICALL *jvmtiIterateSharedCachesCallback)(jvmtiEnv *env,jvmtiSharedCacheInfo *cache_info, void *user_data);\n</code></pre> </li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_UNSUPPORTED_VERSION</code>: The <code>version</code> parameter is not valid. <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>callback</code> parameter is null. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The shared classes feature is not enabled in the VM. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The <code>flags</code> parameter is not valid. <code>JVMTI_ERROR_INTERNAL</code>: This error is returned when the <code>jvmtiIterateSharedCachesCallback</code> returns <code>JNI_ERR</code>.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.IterateSharedCaches</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_ITERATE_SHARED_CACHES</code></p>"},{"location":"interface_jvmti/#jvmtiiteratesharedcachescallback-function","title":"<code>jvmtiIterateSharedCachesCallback</code> function","text":"<p>Callback function parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment when calling <code>COM_IBM_ITERATE_SHARED_CACHES</code>.</li> <li><code>cache_info</code>: A <code>jvmtiSharedCacheInfo</code> structure containing information about a shared cache.</li> <li><code>user_data</code>: User-supplied data, passed as an argument to <code>IterateSharedCaches</code>.</li> </ul> <p>Callback function returns</p> <p><code>JNI_OK</code>: Continue iterating. <code>JNI_ERR</code>: Stop iterating, which causes <code>IterateSharedCaches</code> to return <code>JVMTI_ERROR_INTERNAL</code></p>"},{"location":"interface_jvmti/#jvmtisharedcacheinfo-structure","title":"<code>jvmtiSharedCacheInfo</code> structure","text":"<p>The structure of <code>jvmtiSharedCacheInfo</code></p> <pre><code>typedef struct jvmtiSharedCacheInfo {\nconst char *name;      // the name of the shared cache\njboolean isCompatible; // if the shared cache is compatible with this VM\njboolean isPersistent; // true if the shared cache is persistent, false if its non-persistent\njint os_shmid;         // the OS shared memory ID associated with a non-persistent cache, -1 otherwise\njint os_semid;         // the OS shared semaphore ID associated with a non-persistent cache, -1 otherwise\njint modLevel;         // one of:\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA5\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA6\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA7\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA8\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA9\n                       //   from Java 10: the version number of the Java level on which the shared cache is created\njint addrMode;         // the address mode of the VM creating the shared cache: includes additional\n                       // information on whether it is a 64-bit compressedRefs cache when\n                       // COM_IBM_ITERATE_SHARED_CACHES_VERSION_3 or later is specified.\njboolean isCorrupt;    // if the cache is corrupted\njlong cacheSize;       // the total usable shared classes cache size, or -1 when isCompatible is false\njlong freeBytes;       // the number of free bytes in the shared classes cache, or -1 when isCompatible is false\njlong lastDetach;      // the last detach time specified in milliseconds since 00:00:00 on 1 January 1970 UTC,\n                       // or -1 when the last detach time is not available\njint cacheType;        // the type of the cache\njlong softMaxBytes;    // the soft limit for the available space in the cache\njint layer;            // the shared cache layer number\n} jvmtiSharedCacheInfo;\n</code></pre> <p> Notes:</p> <ul> <li> <p>The field <code>cacheType</code> is included when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_2</code> or later is specified.</p> </li> <li> <p><code>jvmtiSharedCacheInfo.addrMode</code> encodes both address mode and the compressed reference mode when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_3</code> or later is specified. In this case, use the following set of macros to access the address mode and compressed reference mode:</p> </li> </ul> <p>To get the address mode, use:</p> <pre><code>COM_IBM_ITERATE_SHARED_CACHES_GET_ADDR_MODE(jvmtiSharedCacheInfo.addrMode)\n</code></pre> <p>This macro returns one of the following values: <code>COM_IBM_SHARED_CACHE_ADDRMODE_32</code> <code>COM_IBM_SHARED_CACHE_ADDRMODE_64</code> </p> <p>To get the compressed references mode, use:</p> <pre><code>COM_IBM_ITERATE_SHARED_CACHES_GET_CMPRSSREF_MODE(jvmtiSharedCacheInfo.addrMode)\n</code></pre> <p>This macro returns one of the following values: <code>COM_IBM_ITERATE_SHARED_CACHES_UNKNOWN_COMPRESSED_POINTERS_MODE</code> <code>COM_IBM_ITERATE_SHARED_CACHES_COMPRESSED_POINTERS_MODE</code> <code>COM_IBM_ITERATE_SHARED_CACHES_NON_COMPRESSED_POINTERS_MODE</code> </p> <ul> <li> <p>The field <code>softMaxBytes</code> is included when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_4</code> or later is specified.</p> </li> <li> <p>The field <code>layer</code> is included when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_5</code> or later is specified. If the shared cache does not have a layer number, the value for <code>layer</code> is <code>-1</code>.</p> </li> </ul>"},{"location":"interface_jvmti/#destroysharedcache","title":"<code>DestroySharedCache</code>","text":"<p>You can remove a shared classes cache by using the <code>DestroySharedCache()</code> API:</p> <pre><code>jvmtiError DestroySharedCache(jvmtiEnv *env, const char *cacheDir, const char *name, jint persistence, jboolean useCommandLineValues, jint *internalErrorCode);\n</code></pre> <p>This extension removes a named shared classes cache of a given persistence type, in a given directory. You can specify the cache name, persistence type, and directory in one of these ways:</p> <ul> <li> <p>Set <code>useCommandLineValues</code> to <code>true</code> and specify the values on the command line. If a value is not available, the default values for the platform are used.</p> </li> <li> <p>Set <code>useCommandLineValues</code> to <code>false</code> and use the <code>cacheDir</code>, <code>persistence</code> and <code>cacheName</code> parameters to identify the cache to be removed. To accept the default value for <code>cacheDir</code> or <code>cacheName</code>, specify the parameter with a <code>null</code> value.</p> </li> </ul> <p>Parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment.</li> <li><code>cacheDir</code>: When the value of <code>useCommandLineValues</code> is <code>false</code>, specify the absolute path of the directory for the shared classes cache. If the value is <code>null</code>, the platform-dependent default is used.</li> <li><code>cacheName</code>: When the value of <code>useCommandLineValues</code> is <code>false</code>, specify the name of the cache to be removed. If the value is <code>null</code>, the platform-dependent default is used.</li> <li><code>persistence</code>: When the value of <code>useCommandLineValues</code> is false, specify the type of cache to remove. This parameter must have one of the following values: <code>PERSISTENCE_DEFAULT</code> (The default value for the platform). <code>PERSISTENT</code> <code>NONPERSISTENT</code> </li> <li><code>useCommandLineValues</code>: Set this value to <code>true</code> when you want to specify the shared classes cache name, persistence type, and directory on the command line. Set this value to <code>false</code> when you want to use the <code>cacheDir</code>, <code>persistence</code>, and <code>cacheName</code> parameters instead.</li> <li><code>internalErrorCode</code>: If not <code>null</code>, this value is set to one of the following constants when <code>JVMTI_ERROR_INTERNAL</code> is returned:  <ul> <li><code>COM_IBM_DESTROYED_ALL_CACHE</code>: Set when <code>JVMTI_ERROR_NONE is</code> returned.</li> <li><code>COM_IBM_DESTROYED_NONE</code>: Set when the function fails to remove any caches.  </li> <li><code>COM_IBM_DESTROY_FAILED_CURRENT_GEN_CACHE</code>: Set when the function fails to remove the existing current generation cache, irrespective of the state of older generation caches.  </li> <li><code>COM_IBM_DESTROY_FAILED_OLDER_GEN_CACHE</code>: Set when the function fails to remove any older generation caches. The current generation cache does not exist or is successfully removed.</li> </ul> </li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. No cache exists or all existing caches of all generations are removed. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The shared classes feature is not enabled in the VM. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The <code>persistence</code> parameter is not valid. <code>JVMTI_ERROR_INTERNAL</code>: Failed to remove any existing cache with the given name. See the value of the <code>internalErrorCode</code> parameter for more information about the failure.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.DestroySharedCache</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_DESTROY_SHARED_CACHE</code></p>"},{"location":"interface_jvmti/#registerverbosegcsubscriber","title":"<code>RegisterVerboseGCSubscriber</code>","text":"<p>You can subscribe to verbose garbage collection (GC) data logging by using the <code>RegisterVerboseGCSubscriber()</code> API:</p> <pre><code>jvmtiError RegisterVerboseGCSubscriber(jvmtiEnv* jvmti_env, char *description, jvmtiVerboseGCSubscriber subscriber, jvmtiVerboseGCAlarm alarm, void *user_data, void **subscription_id)\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>description</code>: An ASCII character string that describes the subscriber.</li> <li><code>subscriber</code>: A function of type <code>jvmtiVerboseGCSubscriber</code>.</li> <li><code>alarm</code>: A function pointer of type <code>jvmtiVerboseGCAlarm</code>.</li> <li><code>user_data</code>: A pointer to user data. This pointer is passed to the subscriber and alarm functions each time these functions are called. This pointer can be a null value.</li> <li><code>subscription_id</code>: A pointer to a subscription identifier. This pointer is returned by the <code>RegisterVerboseGCSubscriber</code> call if successful. The value must be supplied to a future call to <code>DeregisterVerboseGCSubscriber</code> API, which is used to unsubscribe from verbose GC data logging.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: One of the supplied parameters is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: GC verbose logging is not available. <code>JVMTI_ERROR_INTERNAL</code>: An internal error has occurred.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.RegisterVerboseGCSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_REGISTER_VERBOSEGC_SUBSCRIBER</code></p>"},{"location":"interface_jvmti/#jvmtiverbosegcsubscriber-function","title":"<code>jvmtiVerboseGCSubscriber</code> function","text":"<p>The subscriber function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiVerboseGCSubscriber)(jvmtiEnv *jvmti_env, const char *record, jlong length, void *user_data);\n</code></pre> <p>The subscriber function must be of type <code>jvmtiVerboseGCSubscriber</code>, which is declared in <code>ibmjvmti.h</code>.</p> <p>This function is called with each record of verbose logging data produced by the VM.</p> <p>This function runs under the same restrictions as the <code>GarbageCollectionStart</code> and <code>GarbageCollectionFinish</code> events in the standard JVMTI specification. For more information about these events, see the JVMTI Event Index for your OpenJDK version.</p> <p>The verbose logging record supplied to the subscriber function is valid only for the duration of the function. If the subscriber wants to save the data, the data must be copied elsewhere.</p> <p>If the subscriber function returns an error, the alarm function is called, and the subscription is deregistered.</p> <p>Subscriber function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>record</code>: An ASCII string that contains a verbose log record.</li> <li><code>length</code>: The number of ASCII characters in the verbose log record.</li> <li><code>user_data</code>: User data supplied when the subscriber is registered.</li> </ul>"},{"location":"interface_jvmti/#jvmtiverbosegcalarm-function","title":"<code>jvmtiVerboseGCAlarm</code> function","text":"<p>The alarm function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiVerboseGCAlarm)(jvmtiEnv *jvmti_env, void *subscription_id, void *user_data);\n</code></pre> <p>The alarm function must be of type <code>jvmtiVerboseGCAlarm</code>, which is declared in <code>ibmjvmti.h</code>. This function is called if the subscriber function returns an error.</p> <p>This function runs under the same restrictions as the <code>GarbageCollectionStart</code> and <code>GarbageCollectionFinish</code> events in the standard JVMTI specification. For more information about these events, see the JVMTI Event Index for your OpenJDK version.</p> <p>Alarm function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>user_data</code>: User data supplied when the subscriber is registered.</li> <li><code>subscription_id</code>: The subscription identifier.</li> </ul>"},{"location":"interface_jvmti/#deregisterverbosegcsubscriber","title":"<code>DeregisterVerboseGCSubscriber</code>","text":"<p>You can unsubscribe from verbose Garbage Collection (GC) data logging by using the <code>DeregisterVerboseGCSubscriber()</code> API:</p> <pre><code>jvmtiError DeregisterVerboseGCSubscriber(jvmtiEnv* jvmti_env, void *userData, void *subscription_id)\n</code></pre> <p>After the <code>DeregisterVerboseGCSubscriber()</code> API is called, no further calls are made to the previously registered subscriber function.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>subscription_id</code>: The subscription identifier that is returned by the call to the RegisterVerboseGCSubscriber() API.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>subscription_id</code> parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.DeregisterVerboseGCSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_DEREGISTER_VERBOSEGC_SUBSCRIBER</code></p>"},{"location":"interface_lang_management/","title":"Language Management","text":""},{"location":"interface_lang_management/#language-management-interface","title":"Language management interface","text":"<p>Eclipse OpenJ9\u2122 provides MXBean extensions to the standard <code>java.lang.management</code> API, which can be used to monitor and manage the Java\u2122 virtual machine. These extensions provide access to information about the state of the OpenJ9 VM and the environment in which it is running. The following tables list the MXBeans by package and describe the monitoring or management capabilities.</p> <p>Package: <code>com.ibm.lang.management</code></p> MXBean Description <code>GarbageCollectorMXBean</code> Discovers Garbage Collection (GC) operations (collection times, compactions, heap memory usage, and freed memory). <code>JvmCpuMonitorMXBean</code> Discovers CPU consumption by category (GC, JIT, or other threads). <code>MemoryMXBean</code> Discovers memory usage (minimum and maximum heap sizes, and shared classes cache sizes). <code>MemoryPoolMXBean</code> Discovers memory pool usage for specific GC policies. <code>OperatingSystemMXBean</code> Discovers information about the operating system (memory, CPU capacity/utilization). <code>RuntimeMXBean</code> Discovers information about the runtime environment (CPU load, Java process ID, and VM state) <code>ThreadMXBean</code> Discovers information about native thread IDs. <code>UnixOperatingSystemMXBean</code> Discovers information for Unix operating systems (memory, file descriptors, processors, processor usage, and hardware) <p>Package: <code>com.ibm.virtualization.management</code></p> MXBean Description <code>GuestOSMXBean</code> Discovers CPU and memory statistics of a virtual machine or logical partition as seen by the Hypervisor. <code>HypervisorMXBean</code> Discovers whether the operating system is running on a hypervisor and provides information about the hypervisor. <p>Package: <code>openj9.lang.management</code></p> MXBean Description <code>OpenJ9DiagnosticsMXBean</code> Configures and dynamically triggers dump agents. <p>For more information about using these MXBeans, read the API documentation. For Java 8, see the OpenJ9 Language Management API documentation. </p>"},{"location":"introduction/","title":"Getting started","text":""},{"location":"introduction/#getting-started-with-eclipse-openj9","title":"Getting started with Eclipse OpenJ9","text":"<p>Eclipse OpenJ9\u2122 is a high performance, scalable, Java\u2122 virtual machine (VM) implementation that is fully compliant with the Java Virtual Machine Specification.</p> <p>At run time, the VM interprets the Java bytecode that is compiled by the Java compiler. The VM acts as a translator between the language and the underlying operating system and hardware. A Java program requires a specific VM to run on a particular platform, such as Linux\u00ae, z/OS\u00ae, or Windows\u2122.</p> <p>This material provides information about the VM configuration and tuning options, together with the default settings. Follow the links provided for more detailed information.</p>"},{"location":"introduction/#configuring-your-system","title":"Configuring your system","text":"<p>Most Java applications should run on an OpenJDK that contains the OpenJ9 VM without changing anything on the underlying system. However, to get the most out of your system you might want to consider some configuration options. Read Configuring your system to learn more about the following options:</p> <ul> <li>Setting operating system environment variables, such as PATH and CLASSPATH.</li> <li>Increasing resource limits for running Java applications.</li> <li>Configuring large page memory allocation.</li> <li>Configuring Dynamic LPAR support on AIX\u00ae systems.</li> </ul>"},{"location":"introduction/#performance-tuning","title":"Performance tuning","text":"<p>OpenJ9 is configured to start with a set of default options that provide the optimal runtime environment for Java applications with typical workloads. However, if your application is atypical, you can improve performance by tuning the OpenJ9 VM. You can also improve performance by enabling hardware features or using specific APIs in your application code.</p>"},{"location":"introduction/#garbage-collection-policies","title":"Garbage collection policies","text":"<p>OpenJ9 includes several garbage collection policies. To learn more about these policies and the types of application workload that can benefit from them, see Garbage collection policies.</p>"},{"location":"introduction/#class-data-sharing","title":"Class data sharing","text":"<p>You can share class data between running VMs, which can reduce the startup time for a VM after the cache has been created. For more information, see Introduction to class data sharing.</p>"},{"location":"introduction/#native-data-operations","title":"Native data operations","text":"<p>If your Java application manipulates native data, consider writing your application to take advantage of methods in the Data Access Accelerator (DAA) API.</p> <p>The following functions are provided:</p> <ul> <li>Arithmetic, comparison, shifting, and validation operations for packed decimal data.</li> <li>Conversion operations between different binary coded decimal and Java binary types.</li> <li>Marshalling operations: marshalling and unmarshalling Java binary types, such as <code>short</code>, <code>int</code>, <code>long</code>, <code>float</code>, and <code>double</code>, to and from byte arrays.</li> </ul> <p>You can gain a number of benefits by using the APIs provided:</p> <ul> <li>Improved application performance by avoiding object creation and intermediate processing, which can also put pressure on the Java heap.</li> <li>Hardware acceleration by automatically exploiting available hardware features on specific platforms.</li> <li>Platform independence for applications that are developed to take advantage of Data Access Acceleration.</li> </ul> <p>For more information, see the API documentation.</p>"},{"location":"introduction/#cloud-optimizations","title":"Cloud optimizations","text":"<p>To improve the performance of applications that run in containers, try setting the following tuning options:</p> <ul> <li> <p>Use a shared classes cache (<code>-Xshareclasses -XX:SharedCacheHardLimit=200m -Xscmx60m</code>) with Ahead-Of-Time (AOT) compilation to improve your startup time. For persistence, store the cache in a volume that you map to your container. For more information, see Introduction to class data sharing and AOT Compiler.</p> </li> <li> <p>Use the -Xtune:virtualized option, which configures OpenJ9 for typical cloud deployments where VM guests are provisioned with a small number of virtual CPUs to maximize the number of applications that can be run. When enabled, OpenJ9 adapts its internal processes to reduce the amount of CPU consumed and trim down the memory footprint. These changes come at the expense of only a small loss in throughput.</p> </li> <li> <p>Provide access to the <code>/proc</code> file system for container detection on Linux systems since the detection code requires access to the <code>/proc/1/cgroup</code> and <code>/proc/1/sched</code> files. If you mount the <code>/proc</code> file system with the <code>hidepid=2</code> option on Linux systems and the VM does not have root privileges, it cannot access the <code>/proc</code> file system and the container detection fails. Even though the container detection fails, the VM does start with a warning message. For example:</p> <p><code>JVMPORT050W Failed to identify if the JVM is running inside a container; error message: fopen failed to open /proc/1/cgroup file with errno=2.</code></p> <p>Although the VM starts after the container detection fails, the VM assumes that it is running outside a container. Therefore, if the VM is running in a container, the VM cannot adapt to the container's limitations and might use an undesirable amount of resources. You can evaluate the impact on performance because of the container detection failure and take steps to resolve the performance issue, if so required. Some of the steps that you can take are as follows:</p> <ul> <li> <p>Remount the <code>/proc</code> file system with the <code>hidepid=0</code> option: You can use this option to allow the VM to access the <code>/proc</code> file system. This action allows all processes access to <code>/proc</code> not just the VM.</p> <pre><code># Remount /proc with hidepid=0 to read the contents of /proc/&lt;PID&gt;\nmount -o remount,rw,hidepid=0 /proc\n\n# Apply the change to /proc persistently by editing /etc/fstab\nproc            /proc           proc    rw,nosuid,nodev,noexec,relatime,hidepid=0   0 0\n</code></pre> </li> <li> <p>Remount the <code>/proc</code> file system with the <code>gid</code> and <code>hidepid=2</code> options: You can use this option to allow only certain processes to access the <code>/proc</code> file system. You can add the processes in a group and provide access to that group with the <code>gid</code> option.</p> <pre><code># Create a group to allow certain users to read the contents of /proc/&lt;PID&gt;\ngroupadd -g 1000 procaccess\n\n# Add a user to the group procaccess\nusermod -a -G procaccess &lt;USER&gt;\n\n# Remount /proc with the gid option to allow users in group procaccess to access /proc\nmount -o remount,rw,hidepid=2,gid=1000 /proc\n\n# Apply the change to /proc persistently by editing /etc/fstab\nproc            /proc           proc    rw,nosuid,nodev,noexec,relatime,hidepid=2,gid=1000   0 0\n</code></pre> </li> </ul> </li> </ul> <p>The OpenJ9 VM automatically detects when it is running in a docker container and uses a mechanism to detect when the VM is idle. When an idle state is detected, OpenJ9 runs a garbage collection cycle and releases free memory pages back to the operating system. The object heap is also compacted to make best use of the available memory for further application processing. Compaction is triggered by internal heuristics that look into the number of fragmented pages. Typically there is no need to force a compaction.</p> <p>For cloud services that charge based on memory usage, maintaining a small footprint can generate cost savings. For more information about tuning options that control this process, see <code>-XX:IdleTuningMinIdleWaitTime</code>.</p>"},{"location":"introduction/#cryptographic-operations","title":"Cryptographic operations","text":"<p>OpenJDK uses the in-built Java cryptographic implementation by default. However, native cryptographic implementations typically provide better performance. OpenSSL is a native open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which is well established and used with many enterprise applications. For more information, see OpenSSL.</p>"},{"location":"introduction/#exploiting-gpus","title":"Exploiting GPUs","text":"<p>OpenJ9 provides both the CUDA4J API  and the GPU API,  which enables you to develop applications that can take advantage of graphics processing unit (GPU) processing for suitable functions, such as sorting arrays. You can also enable the JIT compiler to offload certain processing tasks to a GPU by specifying the <code>-Xjit:enableGPU</code> option on the command line. When enabled, the JIT compiler determines when to offload tasks based on performance heuristics.</p> <p>GPU processing is supported only on Linux little-endian systems, such as x86-64 and IBM Power LE, and Windows x86-64 systems. For more information about enabling GPU processing, see Exploiting graphics processing units.</p> <p>Special consideration is needed when using the WDDM driver model for GPUs on Windows. Using the WDDM driver model means the GPU is also used as a display device and as such is subject to the Timeout Detection and Recovery (TDR) mechanism of Windows. If you are running demanding GPU workloads, you should increase the timeout from the default 2 seconds. More detail may be found in NVIDIA's Installation Guide for Windows.</p>"},{"location":"introduction/#hardware-acceleration","title":"Hardware acceleration","text":"<p>On AIX\u00ae systems that contain the Nest accelerator (NX) co-processor, OpenJ9 can take advantage of the <code>zlibNX</code> library. This library is an enhanced version of the <code>zlib</code> compression library that supports hardware-accelerated data compression and decompression. The <code>zlibNX</code> library is supported on AIX version 7.2 TL4 and later and must be installed on the system. The Nest accelerator (NX) co-processor is available on IBM POWER9\u00ae systems. To learn more about <code>zlibNX</code>, see Data compression by using the zlibNX library.</p>"},{"location":"introduction/#runtime-options","title":"Runtime options","text":"<p>Runtime options are specified on the command line and include system properties, standard options, nonstandard (-X) options, and -XX options. For a detailed list of runtime options, see OpenJ9 command-line options</p>"},{"location":"introduction/#default-settings","title":"Default settings","text":"<p>If you do not specify any options on the command line at run time, the OpenJ9 VM starts with default settings that define how it operates. For more information about these settings, see Default settings for the OpenJ9 VM.</p>"},{"location":"introduction/#using-jlink","title":"Using jlink","text":"<p>On Java 11 and later, you can use the <code>jlink</code> utility to create a custom OpenJ9 runtime image, which allows you to optimize image size. If you do not require translations from the English language, the translation files can be removed to further optimize the size. You can achieve this by specifying the <code>--exclude-files=**java_**.properties</code> option when you run <code>jlink</code>. The default English <code>java.properties</code> file is unaffected.</p>"},{"location":"introduction/#using-jpackage","title":"Using jpackage","text":"<p>(Linux, macOS, and Windows only)</p> <p>You can use the <code>jpackage</code> utility to package a Java application into a platform-specific package that includes all of the necessary dependencies. Full details of the tool are available at JEP 392: Packaging Tool. Instructions for using it and the various options available, are documented in the Oracle Tool Specifications: The jpackage Command.</p>"},{"location":"introduction/#troubleshooting","title":"Troubleshooting","text":"<p>The OpenJ9 diagnostic component contains extensive features to assist with problem determination. Diagnostic data is produced under default conditions, but can also be controlled by starting the VM with the -Xdump option or using the <code>com.ibm.jvm.Dump</code> API. You can also trace Java applications, methods, and VM operations by using the -Xtrace option.</p> <p>To get started, read Diagnostic tools and data.</p>"},{"location":"jit/","title":"JIT Compiler","text":""},{"location":"jit/#the-jit-compiler","title":"The JIT compiler","text":"<p>The Just-In-Time (JIT) compiler is a key component of the Eclipse OpenJ9\u2122 VM that improves the performance of Java applications by compiling platform-neutral Java bytecode into native machine code at run time. Without the JIT, the VM has to interpret the bytecodes itself - a process that requires extra CPU and memory.</p> <p>The JIT compiler doesn't compile every method that gets called because thousands of methods can be called at startup. Instead, OpenJ9 records the number of times a method is called. When the count reaches a pre-defined invocation threshold, JIT compilation is triggered. Once a method has been compiled by the JIT, the VM can call the compiled method rather than interpreting it.</p>"},{"location":"jit/#optimization-levels","title":"Optimization levels","text":"<p>The JIT compiler can compile a method at different optimization levels: cold, warm, hot, very hot (with profiling), or scorching. The hotter the optimization level, the better the expected performance, but the higher the cost in terms of CPU and memory.</p> <ul> <li>cold is used during startup processing for large applications where the goal is to achieve the best compiled code speed for as many methods as possible.</li> <li>warm is the workhorse; after start-up, most methods are compiled when they reach the invocation threshold.</li> </ul> <p>For higher optimization levels, the VM uses a sampling thread to identify methods that continue to take a lot of time. Methods that consume more than 1% are compiled at hot. Methods that consume more than 12.5% are scheduled for a scorching compilation. However, before that happens the methods are compiled at very hot with profiling to collect detailed profile data that is used by the scorching compilation.</p> <p>The higher optimization levels use special techniques such as escape analysis and partial redundancy elimination, or loop through certain optimization sequences more times. Although these techniques use more CPU and memory, the improved performance that is delivered by the optimizations can make the tradeoff worthwhile.</p>"},{"location":"jit/#troubleshooting","title":"Troubleshooting","text":"<p>The JIT compiler is enabled by default to optimize performance. However, if you experience a problem running your application, temporarily turning off the JIT will tell you whether the JIT is at fault.</p> <p>Because JIT starts at the same time as the VM, you can only modify JIT behavior at startup.</p> <p>There are a number of ways to disable the JIT:</p> <ul> <li>Specify <code>-Djava.compiler=NONE</code> on the command line.</li> <li>Specify <code>-Xint</code> on the command line, which turns off the JIT and AOT compiler. To eliminate problems with one or the other you can turn these compilers off selectively with the <code>-Xnojit</code> and <code>-Xnoaot</code> options.</li> <li>Call the <code>java.lang.Compiler</code> API programmatically.</li> </ul> <p> Note: <code>java.lang.Compiler</code> is deprecated for removal in Java SE 9.</p> <p>If turning off the JIT solves your problem, you can investigate JIT operations in more detail by using a number of options to control behavior.</p> <p>Turning on verbose logging with the <code>verbose</code> suboption causes the JIT to record all compiler operations. However, the log file can be difficult to read because there are so many complex operations occuring in rapid succession. Follow these steps to simplify operations, which helps you pinpoint the root cause:</p> Turn off multiple compilation threads <p>The JIT compiler can use more than one compilation thread, which typically improves startup performance. The number of threads is determined by the VM, depending on the system configuration. You can turn off multiple threads by using the <code>-XcompilationThreads</code> option, which simplifies the output in the verbose log.</p> Lower the invocation threshold <p>When the invocation count is set to <code>0</code>, the JIT compiles every method and your application will fail immediately when the method causing the problem is reached. You can alter the threshold with the <code>count</code> suboption.</p> Turn off inlining <p>Inlining is a complex process that generates larger and more complex code. To eliminate errors caused by these operations, use the <code>disableInlining</code> suboption.</p> Decrease the optimization levels <p>Use the <code>optlevel</code> suboption to gradually decrease the compiler optimization levels to see whether you can isolate the level at which your problem occurs.</p> <p>More information about these suboptions and the command line syntax is covered in -Xjit.</p>"},{"location":"jit/#understanding-jit-verbose-logs","title":"Understanding JIT verbose logs","text":"<p>At first glance, a JIT verbose log can look very complex. To help you understand the log we'll look at JIT compiler operations when you run the <code>java -version</code> command.</p> <p>The following option turns on verbose logging and directs output to a log file called <code>vlogfile</code>:</p> <pre><code>java -Xjit:verbose,vlog=vlogfile -version\n</code></pre> <p>The first section of the log includes lines that start with <code>#INFO:</code>, which provides information about the environment that the JIT is operating in. You can determine the version of the JIT and VM that you are using, and the type and number of processors that the JIT has access to.</p> <pre><code>#INFO:  _______________________________________\n#INFO:  Version Information:\n#INFO:       JIT Level  - e24e8aa9\n#INFO:       JVM Level  - 20180315_120\n#INFO:       GC Level   - e24e8aa9\n#INFO:  \n#INFO:  Processor Information:\n#INFO:       Platform Info:X86 Intel P6\n#INFO:       Vendor:GenuineIntel\n#INFO:       numProc=1\n#INFO:  \n#INFO:  _______________________________________\n#INFO:  AOT\n#INFO:  options specified:\n#INFO:       samplingFrequency=2\n#INFO:  \n#INFO:  options in effect:\n#INFO:       verbose=1\n#INFO:       vlog=vlogfile\n#INFO:       compressedRefs shiftAmount=0\n#INFO:       compressedRefs isLowMemHeap=1\n#INFO:  _______________________________________\n#INFO:  JIT\n#INFO:  options specified:\n#INFO:       verbose,vlog=vlogfile\n#INFO:  \n#INFO:  options in effect:\n#INFO:       verbose=1\n#INFO:       vlog=vlogfile\n#INFO:       compressedRefs shiftAmount=0\n#INFO:       compressedRefs isLowMemHeap=1\n#INFO:  StartTime: Apr 23 09:49:10 2018\n#INFO:  Free Physical Memory: 996188 KB\n#INFO:  CPU entitlement = 100.00\n</code></pre> <p>This section also shows the AOT and JIT options that are in force. The last few lines detail the start time of the compilation activity, how much free physical memory is available to the process, and the CPU entitlement.</p> <p>The information section is followed by a sequence of lines that describe the methods that are being compiled, as well as other events significant to the operation of the JIT compiler.</p> <p>Here is a typical line from the verbose log:</p> <pre><code>+ (cold) sun/reflect/Reflection.getCallerClass()Ljava/lang/Class; @ 00007FCACED1303C-00007FCACED13182 OrdinaryMethod - Q_SZ=0 Q_SZI=0 QW=1 j9m=00000000011E7EA8 bcsz=2 JNI compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <p>In this example:</p> <ul> <li>The method compiled is <code>sun/reflect/Reflection.getCallerClass()Ljava/lang/Class</code>.</li> <li>The <code>+</code> indicates that this method is successfully compiled. Failed compilations are marked by a <code>!</code>.</li> <li><code>(cold)</code> tells you the optimization level that was applied. Other examples might be <code>(warm)</code> or <code>(scorching)</code>.</li> <li><code>00007FCACED1303C-00007FCACED13182</code> is the code range where the compiled code was generated.</li> <li><code>Q</code> values provide information about the state of the compilation queues when the compilation occurred.</li> <li><code>bcsz</code> shows the bytecode size. In this case it is small because this is a native method, so the JIT is simply providing an accelerated JNI transition into the native <code>getCallerClass</code> method.</li> </ul> <p>Each line of output represents a method that is compiled.</p> <p>The following example requests information about the performance of JIT compiler threads, with output written to <code>vlogfile</code>.</p> <pre><code>java -Xjit:verbose={compilePerformance},vlog=vlogfile -version\n</code></pre> <p>The output generated by using this command adds the values <code>time</code> and <code>mem</code> into each line, as shown in the following example:</p> <pre><code>+ (cold) java/lang/System.getEncoding(I)Ljava/lang/String; @ 00007F29183A921C-00007F29183A936D OrdinaryMethod - Q_SZ=0 Q_SZI=0 QW=1 j9m=0000000000F13A70 bcsz=3 JNI time=311us mem=[region=704 system=16384]KB compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <ul> <li>time=311us reflects the amount of time taken to do the compilation.</li> <li>mem=[region=704 system=16384]KB reflects the amount of memory that was allocated during the compilation.</li> </ul> <p>The following example can be used to create verbose output that includes lines to show when compilation for a method starts and ends, and any methods that are inlined during the compilation.</p> <pre><code>java '-Xjit:verbose={compileStart|compileEnd|inlining},count=5,vlog=vlogfile' -XcompilationThreads1 -version\n</code></pre> <p> Note: The suboptions <code>count</code> and <code>-XcompilationThreads1</code> are included only to simplify the output for this example and are not recommended for production.</p> <p>The following section is taken from the output and describes the compilation and inlining of one method <code>java/lang/String.equals</code>:</p> <pre><code>(warm) Compiling java/lang/String.equals(Ljava/lang/Object;)Z  OrdinaryMethod j9m=0000000001300B30 t=90 compThread=0 memLimit=262144 KB freePhysicalMemory=969 MB\n#INL: 7 methods inlined into 4dce72bd java/lang/String.equals(Ljava/lang/Object;)Z @ 00007F53190A3E40\n#INL: #0: 4dce72bd #-1 inlined 4dce72bd@22 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #1: 4dce72bd #-1 inlined 4dce72bd@28 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #2: 4dce72bd #-1 inlined 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n#INL: #3: 4dce72bd #2 inlined bf62dcaf@121 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #4: 4dce72bd #2 inlined bf62dcaf@131 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #5: 4dce72bd #2 inlined bf62dcaf@156 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #6: 4dce72bd #2 inlined bf62dcaf@166 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: 4dce72bd called 4dce72bd@120 -&gt; f734b49c bcsz=233 java/lang/String.deduplicateStrings(Ljava/lang/String;Ljava/lang/String;)V\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n+ (warm) java/lang/String.equals(Ljava/lang/Object;)Z @ 00007F53190A3E40-00007F53190A40D0 OrdinaryMethod - Q_SZ=277 Q_SZI=277 QW=1667 j9m=0000000001300B30 bcsz=127 GCR compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <p>The first line is included as a result of setting the <code>compileStart</code> suboption and shows the start of the warm method compilation:</p> <pre><code>(warm) Compiling java/lang/String.equals(Ljava/lang/Object;)Z OrdinaryMethod j9m=0000000001300B30 t=90 compThread=0 memLimit=262144 KB freePhysicalMemory=969 MB\n</code></pre> <p>Similarly, the last line shows the successful compilation of this method, as denoted by the <code>+</code>:</p> <pre><code>+ (warm) java/lang/String.equals(Ljava/lang/Object;)Z @ 00007F53190A3E40-00007F53190A40D0 OrdinaryMethod - Q_SZ=277 Q_SZI=277 QW=1667 j9m=0000000001300B30 bcsz=127 GCR compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <p>The lines inbetween that start with <code>#INL</code> describe the inlining operations that took place. A total of 7 methods were inlined into <code>java/lang/String.equals</code>:</p> <p>The first three methods (<code>#0</code>, <code>#1</code>, <code>#2</code>) are inlined into the top level method, denoted as <code>#-1</code>:</p> <pre><code>#INL: #0: 4dce72bd #-1 inlined 4dce72bd@22 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #1: 4dce72bd #-1 inlined 4dce72bd@28 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #2: 4dce72bd #-1 inlined 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n</code></pre> <p>The next four methods (<code>#3</code>, <code>#4</code>, <code>#5</code>, <code>#6</code>) are inlined into the method denoted by <code>#2</code>.</p> <pre><code>#INL: #3: 4dce72bd #2 inlined bf62dcaf@121 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #4: 4dce72bd #2 inlined bf62dcaf@131 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #5: 4dce72bd #2 inlined bf62dcaf@156 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #6: 4dce72bd #2 inlined bf62dcaf@166 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n</code></pre> <p>Here's how to interpret the line for <code>#INL: #0:</code>:</p> <p>The method is inlined into <code>4dce72bd</code>, where <code>4dce72bd</code> is an internal pointer that corresponds to this method (in this case, <code>java/lang/String.equals(Ljava/lang/Object;)Z</code>). The value <code>@22</code> at the end of the pointer is a bytecode index, which describes the bytecode index of the call that is being inlined. The call is <code>81670d20 bcsz=37 java/lang/String.lengthInternal()I</code>, which shows the corresponding internal pointer, bytecode size (bcsz) and the name of the method that got inlined. Going through the <code>#INL</code> output line by line then:</p> <pre><code>java/lang/String.lengthInternal()I got inlined into its caller 4dce72bd at bytecode index @22.\njava/lang/String.lengthInternal()I also got inlined into its caller 4dce72bd at bytecode index @28.\njava/lang/String.regionMatchesInternal(...) got inlined at call reference 4dce72bd at bytecode index @104.\n</code></pre> <p>Then 4 distinct calls to <code>java/lang/String.charAtInternal(I[C)C</code> were also inlined into <code>java/lang/String.regionMatchesInternal(...)</code> :</p> <pre><code>#3 at bytecode index @121 of regionMatchesInternal\n#4 at bytecode index @131 of regionMatchesInternal\n#5 at bytecode index @156 of regionMatchesInternal\n#6 at bytecode index @166 of regionMatchesInternal\n</code></pre> <p>These were all the calls that the inliner decided to inline into the method being compiled. There is some additional output that describes calls to methods that weren't inlined:</p> <pre><code>#INL: 4dce72bd called 4dce72bd@120 -&gt; f734b49c bcsz=233 java/lang/String.deduplicateStrings(Ljava/lang/String;Ljava/lang/String;)V\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n</code></pre> <p>While the output does not specifically say why these methods were not inlined, the relatively larger bytecode size (<code>bcsz=233</code>) probably prevented the first method from being inlined. It's possible that, at a higher optimization level than cold, this <code>deduplicateStrings</code> method may get inlined. The <code>coldCalled</code> label on the last two lines, however, indicate that these calls are located in a part of the method that has not ever been executed, so the JIT decided that inlining those last two methods will probably increase compile time without much promise that it will improve performance.</p> <p>By reading the log in this way you can reconstruct the tree of inlines that are taking place as the compilation proceeds. You can see which methods are being inlined and which methods are not being inlined.</p>"},{"location":"jit/#see-also","title":"See also","text":"<ul> <li>Diagnosing a JIT or AOT problem</li> </ul>"},{"location":"jitserver/","title":"JITServer technology","text":""},{"location":"jitserver/#jitserver-technology","title":"JITServer technology","text":"<p>Linux\u00ae on x86, Linux on IBM Power\u00ae systems, and Linux on IBM Z\u00ae systems (64-bit only)</p> <p>JITServer technology decouples the JIT compiler from the VM and lets the JIT compiler run remotely in its own process. This mechanism prevents your Java\u2122 application suffering possible negative effects due to CPU and memory consumption caused by JIT compilation.</p> <p>This technology can improve quality of service, robustness, and performance of Java applications. You might want to try this technology if the following criteria are met:</p> <ul> <li>Your Java application is required to compile many methods using JIT in a relatively short time.</li> <li>The application is running in an environment with limited CPU or memory, which can worsen interference from the JIT compiler.</li> <li>The network latency between JITServer and client VM is relatively low.</li> </ul> <p>For more details about JITServer technology, including its advantages and disadvantages and when best to use it, see blog posts such as the following:</p> <ul> <li>Free your JVM from the JIT with JITServer Technology</li> <li>JITServer - Optimize your Java cloud-native applications</li> </ul> <p>For a more in-depth description of the JITServer design and implementation, see the following research paper:</p> <ul> <li>JITServer: Disaggregated Caching JIT Compiler for the JVM in the Cloud</li> </ul>"},{"location":"jitserver/#using-jitserver-technology","title":"Using JITServer technology","text":"<p>JITServer technology is not enabled by default: you must explicitly invoke it. Running OpenJ9 without either of the following options launches it as a regular VM with embedded JIT compilation.</p>"},{"location":"jitserver/#launch-eclipse-openj9-in-client-mode","title":"Launch Eclipse OpenJ9 in client mode","text":"<p>Use the following command-line option to launch Eclipse OpenJ9\u2122 in client mode. In this mode, the VM sends compilation requests to an available JITServer. The client operates as a regular VM with its own JIT compiler if a server is not available.</p> <pre><code> -XX:+UseJITServer\n</code></pre>"},{"location":"jitserver/#launch-openj9-in-server-mode","title":"Launch OpenJ9 in server mode","text":"<p>Use the following command to start a JITServer process that listens for incoming compilation requests:</p> <pre><code>jitserver\n</code></pre>"},{"location":"jitserver/#configuring-jitserver-technology","title":"Configuring JITServer technology","text":"<p>You can use command line options to further configure the JITServer and the client VM processes. For example:</p> <ul> <li><code>-XX:JITServerPort=&lt;port&gt;</code>: Specifies the port the server listens to for compilation requests</li> <li><code>-XX:JITServerAddress=&lt;address&gt;</code>: Specifies the name or IP of the server</li> <li><code>-XX:JITServerTimeout=&lt;timeout&gt;</code>: Specifies a timeout value in milliseconds for socket operations</li> <li><code>-XX:[+|-]JITServerShareROMClasses</code>: Specifies whether the server shares cached ROM classes between clients</li> <li><code>-XX:[+|-]JITServerLocalSyncCompiles</code>: Improves performance for real-time applications by compiling synchronous JIT compilations locally, with a remote asynchronous recompilation scheduled at a later point</li> <li><code>-XX:[+|-]JITServerLogConnections</code>: Enables logging of connection/disconnection events between the server and the client</li> <li><code>-XX:[+|-]JITServerMetrics</code>: Specifies whether the JITServer custom metrics exporter is enabled or disabled</li> <li><code>-XX:JITServerMetricsPort=&lt;port&gt;</code>: Specifies the port number on which the JITServer metrics are provided to a monitoring agent</li> <li><code>-XX:JITServerAOTCacheName=&lt;cache_name&gt;</code>: Specifies the name of the server-side AOT cache to use</li> <li><code>-XX:[+|-]JITServerUseAOTCache</code>: Specifies whether the server caches AOT-compiled methods</li> <li><code>-XX:JITServerAOTmx=&lt;size&gt;</code>: Specifies the maximum amount of memory that can be used by the JITServer AOT cache</li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code>: Specifies whether the JITServer server allows other JITServer instances to reuse AOT caches</li> <li><code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code>: Specifies the directory to be used for saving and loading JITServer AOT cache files</li> </ul> <p>If a JITServer server crashes, the client is forced to perform compilations locally. You can change this behavior by using the <code>-XX:[+|-]RequireJITServer</code> option so that the client crashes with an assert when it detects that the server is unavailable. This feature is useful when you are running a test suite with JITServer enabled and you want the server crash to cause the test to fail.</p>"},{"location":"jitserver/#security","title":"Security","text":"<p>You can encrypt network communication between the client VM and JITServer by using OpenSSL 1.0.x, 1.1.x, or 3.x. To enable encryption, you specify the private key and the certificate at the server and use the certificate at the client. For more information, see -XX:JITServerSSLCert / -XX:JITServerSSLKey / -XX:JITServerSSLRootCerts.</p>"},{"location":"jitserver/#tuning-jitserver","title":"Tuning JITServer","text":"<p>For best practices regarding JITServer configuration and tuning, see the document JITServer tuning and practical considerations.</p>"},{"location":"jitserver/#building-a-jdk-with-jitserver-technology","title":"Building a JDK with JITServer technology","text":"<p>If you want to build a JDK with JITServer technology, see Appendix A of Free your JVM from the JIT with JITServer Technology.</p>"},{"location":"jitserver/#see-also","title":"See also","text":"<ul> <li>The JIT compiler</li> </ul>"},{"location":"jitserver_tuning/","title":"JITServer tuning","text":""},{"location":"jitserver_tuning/#jitserver-tuning-and-practical-considerations","title":"JITServer tuning and practical considerations","text":""},{"location":"jitserver_tuning/#server-caches","title":"Server caches","text":""},{"location":"jitserver_tuning/#client-session-caches","title":"Client-session caches","text":"<p>Multiple client JVMs can be connected at the same time to a single JIT server. For each client, the server maintains a client-session cache with information about the environment the client is running in (Java classes, class hierarchy, profiling information, JVM options, etc.). Typically, the information in these caches is kept separately, per client. However, if you specify the <code>-XX:+JITServerShareROMClasses</code> option, the read-only part of the Java classes (ROMClasses in Eclipse OpenJ9\u2122 parlance) is shared between the different clients. This option can generate memory savings at the server when the connected clients run identical or similar Java applications.</p> <p>The client-session caches are deleted when the clients terminate, but this can happen only if the clients are shutdown gracefully, giving them the opportunity to send a termination message to the server. To address the scenario of clients ending abruptly, the server also deletes the cache for a client that hasn\u2019t issued a compilation request for 1000 minutes, or 5 minutes under memory pressure. If needed, you can change these values with the following options:</p> <pre><code>-Xjit:oldAge=&lt;time-in-ms&gt;,oldAgeUnderLowMemory=&lt;time-in-ms&gt;\n</code></pre>"},{"location":"jitserver_tuning/#jitserver-aot-cache","title":"JITServer AOT cache","text":"<p>The JITServer technology can cache AOT compiled methods at the server.  The JITServer can, therefore, avoid carrying out an AOT compilation when a compatible AOT method body already exists in the cache, thereby saving CPU resource and improving remote compilation latency. This mechanism works in conjunction with the dynamic AOT technology at the client and therefore the client needs to have the shared class cache (SCC) enabled (the SCC is the repository for the AOT code).</p> <p>When the JITServer receives an AOT compilation request, it checks its AOT cache for a compatible compiled method body. If one is not found, the server performs the AOT compilation, sends the response to the client JVM, then serializes the compiled method and stores it in its local AOT cache, for future use. If a compatible compiled method is found, the server sends the client the serialized compiled method from its cache, thus avoiding a compilation. The client deserializes the response, stores the result in its local SCC, and loads the compiled method as a regular dynamic AOT code.</p> <p>To enable this feature, specify the <code>-XX:+JITServerUseAOTCache</code> command line option, both at the server and at the client JVM.</p> <p>A JITServer instance can have several AOT caches, each with its own name. This addresses the situation when client JVMs with significantly different profiles of execution use the same JITServer instance. A client JVM can indicate a specific AOT cache it wants to use by providing its name with the following command-line option <code>-XX:JITServerAOTCacheName=&lt;cache_name&gt;</code>. If the client doesn't specify a name for the AOT cache, the server uses a cache named <code>default</code>.</p> <p>The maximum amount of memory that all the AOT cache instances combined can use at the server is 300 MB, by default. You can change this value by using the <code>-XX:JITServerAOTmx=&lt;size&gt;</code> option. When the cache size reaches the specified limit, new clients cannot create new AOT cache instances or add new compiled methods to the existing AOT cache instances.</p> <p>Typically, each JITServer server populates its own AOT caches independently of other existing servers. To help with JITServer auto-scaling, and in particular with scaling down to zero, JITServer instances can save their AOT caches to files by setting the <code>-XX:+JITServerAOTCachePersistence</code> command-line option. Other JITServer instances that are started later can load the existing AOT cache files into their memory, and then continue to gradually add new AOT compiled methods. Saving an AOT cache to a file is performed periodically based on the following conditions:</p> <ul> <li>The number of extra AOT methods added to the in-memory cache since the last save operation is equal to or more than the value specified by the <code>-Xjit:aotCachePersistenceMinDeltaMethods=&lt;number_of_methods&gt;</code> option (default value - 200 methods), and</li> <li>The time passed since the last AOT cache save is equal to or later than the time specified by the <code>-Xjit:aotCachePersistenceMinPeriodMs=&lt;milliseconds&gt;</code> option (default time gap - 10000 milliseconds).</li> </ul> <p>If the JITServer AOT cache feature and the <code>-Xshareclasses:readonly</code> option are both enabled at the same time at a JITServer client, the shared class cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p> <p>Current limitation:</p> <ul> <li>Caching works only for AOT compilation requests. For this reason, when JITServer AOT caching is enabled, the client JVM will attempt to generate as many AOT requests as possible.</li> </ul>"},{"location":"jitserver_tuning/#number-of-concurrent-clients","title":"Number of concurrent clients","text":"<p>The amount of CPU and memory resources consumed by the server is expected to increase with the number of connected clients. Finding the appropriate number of clients to connect to a server is a tricky proposition that depends on many factors: number of methods that need to be compiled by the clients, optimization levels for these compilations, how clients are started (staggered or not), how clients are shutdown (gracefully or not), etc.</p> <p>As a rule of thumb, you should have 10-20 JVMs simultaneously connected to a server with 1-2 GB of memory. With respect to CPU resources, in Kubernetes you might want to set a low \"request\" value at the server (1-2 vCPUs) and a larger \"limit\" value (4-8 vCPUs) in order to soak all those idle cycles. It is possible to connect even more clients to one server instance if memory and CPU resources are increased, but in general, two medium-sized server instances placed on different nodes are better than a single, larger server.</p>"},{"location":"jitserver_tuning/#alleviating-cpu-congestion-at-the-server","title":"Alleviating CPU congestion at the server","text":"<p>When too many clients connect to the server, the server can become flooded with compilation requests, leading to increased compilation times and slower start-up/ramp-up for applications. It should be noted that a client JVM issues most of its compilation requests during the start-up phase and ramp-up phase of an application, when load is first applied to it. Thus, from the CPU consumption point of view what matters is the number of clients that start-up or ramp-up concurrently. To alleviate the CPU strain on the server, you can start the client JVMs in a staggered fashion, rather than all at the same time. Sometimes the staggering happens naturally; for instance, when using Kubernetes horizontal pod auto-scaling, additional application instances are launched gradually as the load increases.</p> <p>Another idea is to use the <code>-Xjit:enableJITServerHeuristics</code> command line option at the clients. When this option is present, the client JVMs share some of the compilation burden by performing the cheap compilations locally and send only expensive compilations to the server. What constitutes a cheap compilation is determined by JIT heuristics that look at the method size, optimization level and the amount of CPU and memory available to the JVM.</p>"},{"location":"jitserver_tuning/#avoiding-memory-shortages-at-the-server","title":"Avoiding memory shortages at the server","text":"<p>Roughly speaking, the server uses two types of memory: 1. \"Scratch\" memory. This is allocated during a compilation (for JIT internal data structures) and released to the operating system at the end of the compilation. 2. \"Persistent\" memory. This is used for client-session caches and gets deleted only when a client terminates gracefully (or when the JITServer purging mechanism is triggered).</p> <p>The total amount of scratch memory at any given moment depends on how many compilations are in progress and how expensive those compilations are. To reduce this amount, you can start the clients in a staggered fashion as suggested previously, or reduce the number of compilation threads per client. Note that the latter already happens automatically: when the server senses that it is about to run out of memory, it provides feedback to the connected clients to reduce their number of active compilation threads.</p> <p>To reduce the amount of persistent memory, you can use the techniques described in section Server caches.</p>"},{"location":"jitserver_tuning/#traffic-encryption","title":"Traffic encryption","text":"<p>Enabling network encryption can increase the CPU overhead, both at the client and at the server. For this reason, you should turn on encryption only if needed. Note that some technologies like Istio, Weave, Linkerd, Calico, Cilium already encrypt all network traffic, so using JITServer encryption might be redundant.</p>"},{"location":"jitserver_tuning/#minimizing-application-stalls","title":"Minimizing application stalls","text":"<p>Usually, the compilation threads in OpenJ9 JVM execute in parallel with Java application threads. However, for correctness reasons a small number of compilations are performed synchronously, meaning that Java application threads have to wait for the compilation result before being allowed to execute the method being compiled. Since remote compilations typically take longer to complete due to network latency, application stalls caused by synchronous compilations can be more severe in a JITServer setting. If this becomes a problem, you should add the following command line option at the client:</p> <pre><code>-XX:+JITServerLocalSyncCompiles\n</code></pre> <p>This option instructs the client JVM to perform the synchronous compilations locally, at a low optimization level (thus the compilation is relatively quick), and to follow-on with remote asynchronous recompilations at a higher optimization level to avoid any performance loss.</p>"},{"location":"jitserver_tuning/#session-affinity","title":"Session affinity","text":"<p>For technical reasons, a client JVM must use a single JITServer at a time. In a Kubernetes environment, where a JITServer service can be backed up by several server instances, you can satisfy this requirement by using session affinity. Note that if a server crashes (or gets terminated by the Kubernetes controller) the clients can connect to another server instance. This scenario imposes some performance penalty because the client-session caches that the server maintains need to be built anew. Following is an example of a Kubernetes service definition that uses sessionAffinity:</p> <pre><code>apiVersion: v1\nkind: Service\nmetadata:\n  name: jitserver\nspec:\n  type: ClusterIP\nselector:\n    app: jitserver\n  ports:\n    - protocol: TCP\n      port: 38400\n      targetPort: 38400\n  sessionAffinity: ClientIP\n  sessionAffinityConfig:\n    clientIP:\n      timeoutSeconds: 86400\n</code></pre>"},{"location":"jitserver_tuning/#resilience","title":"Resilience","text":"<p>If the client JVM does not find a compatible server to connect to, compilations are performed locally, by the client itself. To account for the case where the server is temporarily unavailable (for example, server crash followed by Kubernetes launching another server instance), from time to time the client retries to connect to a server at the indicated address and port. The retry mechanism uses an exponential back-off where the retry interval is doubled with each unsuccessful attempt.</p>"},{"location":"jitserver_tuning/#monitoring","title":"Monitoring","text":""},{"location":"jitserver_tuning/#performance-metrics","title":"Performance metrics","text":"<p>You can enable the provision of performance metrics by specifying the <code>-XX:+JITServerMetrics</code> command line option. After enabling this option, you can use a monitoring tool that follows the OpenMetrics standard, such as Prometheus, to collect the data by issuing an HTTP <code>GET</code> request to the following url: <code>http://&lt;jitserveraddress&gt;:&lt;port&gt;/metrics</code>.</p> <p> Note: There is a limit of four concurrent <code>GET</code> requests at any given time.</p> <p>You can use the <code>-XX:JITServerMetricsSSLKey</code> and <code>-XX:JITServerMetricsSSLCert</code> options to encrypt the data with TLS or SSL.</p> <p>For more information, including the types of metrics that are provided, see the <code>-XX:[+|-]JITServerMetrics</code> topic.</p>"},{"location":"jitserver_tuning/#verbose-logging","title":"Verbose logging","text":"<p>You can inspect the behavior of a JITServer instance by using the OpenJ9 verbose logging facility. Note that if the name of the verbose log is not specified, the relevant information is printed to stderr. When you use the <code>-XX:+JITServerLogConnections</code> command line option, the server prints a message to the verbose log every time a new client JVM connects to it or disconnects from it. This is an easy way to determine that the clients are able to reach the server. Example of output:</p> <pre><code>#JITServer: t= 74232 A new client (clientUID=14692403771747196083) connected. Server allocated a new client session.\n#JITServer: t= 74282 A new client (clientUID=2599593246759846167) connected. Server allocated a new client session.\n#JITServer: t= 86281 Client (clientUID=14692403771747196083) disconnected. Client session deleted\n</code></pre> <p>The server has a heart-beat thread that periodically prints to the verbose log information related to the number of clients connected, the number of active compilation threads, the amount of CPU used, the amount of available memory and the number of times the internal server caches have been cleared. This last bit of information is important for diagnosing performance problems. The heart-beat information is enabled with the following option:</p> <pre><code>-Xjit:statisticsFrequency=&lt;period-in-ms&gt;\n</code></pre> <p>Example of output:</p> <pre><code>#JITServer: CurrentTime: Aug 06 17:25:15 2021\n#JITServer: Compilation Queue Size: 0\n#JITServer: Number of clients : 2\n#JITServer: Total compilation threads : 63\n#JITServer: Active compilation threads : 2\n#JITServer: Physical memory available: 14299 MB\n#JITServer: CpuLoad 206% (AvgUsage 25%) JvmCpu 113%\n...\n</code></pre> <p>A value greater than 0 for the <code>Compilation Queue Size</code> is a sign that the server is overloaded. Compilation requests that wait in the compilation queue face greater delays and run the risk of exceeding network timeouts. To avoid this scenario, you can reduce the number of connected clients, use the techniques described in section Alleviating CPU congestion at the server, or increase the number of compilation threads at the server by using the <code>-XcompilationThreads</code> option.</p> <p>Increasing the maximum number of client threads can improve performance in high network latency settings because there can be more in-progress concurrent compilation requests. Increasing the number of threads at the server can improve performance if the server has many CPU cores available and serves a large number of clients concurrently.</p> <p>More detailed diagnostics can be obtained with the option <code>-Xjit:verbose={JITServer},verbose={compilePerformance}</code>, which is typically used for debugging server behavior.</p>"},{"location":"legal/","title":"Legal","text":""},{"location":"legal/#legal","title":"Legal","text":"<p>License agreement, notices, copyright, and trademark information for the user documentation.</p>"},{"location":"legal/#license-agreement","title":"License agreement","text":"<p>See License</p>"},{"location":"legal/#notices","title":"Notices","text":"<p>See Notices</p>"},{"location":"legal/#copyright-information","title":"Copyright information","text":"<p>Eclipse OpenJ9\u2122 documentation is subject to the following copyright:</p> <pre><code>Copyright (c) 2017, 2023 IBM Corp.\n</code></pre>"},{"location":"legal/#trademarks","title":"Trademarks","text":"<p>IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at \"Copyright and trademark information\" here.</p> <p>Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.</p> <p>Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.</p> <p>Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.</p>"},{"location":"messages_intro/","title":"OpenJ9 messages","text":""},{"location":"messages_intro/#eclipse-openj9-vm-messages","title":"Eclipse OpenJ9 VM messages","text":"<p>Messages are issued by the Eclipse OpenJ9\u2122 virtual machine (VM) in response to certain conditions. Understanding what the messages mean can help you with problem determination.</p>"},{"location":"messages_intro/#message-categories","title":"Message categories","text":"<p>There are three main categories of message:</p> Information Information messages provide information about VM processing. For example, a dump information message is typically issued when a dump agent requests a dump. Warning Warning messages are issued by the VM to indicate conditions that might need user intervention. Error Error messages are issued by the VM when normal processing cannot proceed, because of unexpected conditions. <p>OpenJ9 virtual machine messages have the following format:</p> <pre><code>    JVM&lt;type&gt;&lt;number&gt;&lt;code&gt;\n</code></pre> <p>where:</p> <ul> <li><code>JVM</code> is a standard prefix.</li> <li><code>&lt;type&gt;</code> refers to the VM subcomponent that issued the message.</li> <li><code>&lt;number&gt;</code> is a unique numerical number.</li> <li><code>&lt;code&gt;</code> is one of the following codes:<ul> <li><code>I</code> - Information message</li> <li><code>W</code> - Warning message</li> <li><code>E</code> - Error message</li> </ul> </li> </ul> <p>These messages can help you with problem determination.</p> <p>By default, all error and some information messages are routed to the system log and also written to <code>stderr</code> or <code>stdout</code>. The specific information messages are <code>JVMDUMP039I</code>, <code>JVMDUMP032I</code>, and <code>JVMDUMP033I</code>, which provide valuable additional information about dumps produced by the VM. To route additional message types to the system log, or turn off message logging to the system log, use the <code>-Xsyslog</code> option. The <code>-Xsyslog</code> option does not affect messages written to the standard error stream (stderr). See OpenJ9 command-line options.</p> <p> Note: The <code>-Xsyslog</code> option replaces the <code>-Xlog</code> option in OpenJ9 version 0.24.0.</p>"},{"location":"messages_intro/#finding-logged-messages","title":"Finding logged messages","text":"<p>Logged messages can be found in different locations, according to platform.</p>"},{"location":"messages_intro/#finding-aix-messages","title":"Finding AIX messages","text":"<p>On AIX\u00ae, messages are logged by the syslog daemon (<code>/usr/sbin/syslogd</code>). Logged messages are written to the syslog file that is configured in <code>/etc/syslog.conf</code>. If the syslog daemon is not running, logged messages are lost.</p> <p>You can redirect messages from the syslog daemon to the AIX error log facility by performing the following configuration steps:</p> <ol> <li>Set up a redirect in the file <code>syslog.conf</code> so that syslog messages are sent to the error log, by adding the following line:</li> </ol> <pre><code>        user.debug errlog\n</code></pre> <ol> <li>If syslogd is already running, reload the updated configuration by running the following command:</li> </ol> <pre><code>        refresh -s syslogd\n</code></pre> <ol> <li>The updated configuration is used each time syslogd starts. 4.  Use the AIX errpt command or the System Management Interface Tool (SMIT) to read the messages sent to the error log.</li> </ol> <p>For more information about AIX logging, see: Error-logging overview.</p>"},{"location":"messages_intro/#finding-linux-messages","title":"Finding Linux messages","text":"<p>On Linux\u00ae, messages are logged by the syslog daemon. To find where messages are logged, check the syslog configuration file.</p>"},{"location":"messages_intro/#finding-macos-messages","title":"Finding macOS messages","text":"<p>On macOS\u00ae, messages are logged by the syslog daemon. However, on Sierra and High Sierra, syslog does not work. If <code>/var/log/system.log</code> is not available, <code>Console.app</code> can be used instead.</p>"},{"location":"messages_intro/#finding-windows-messages","title":"Finding Windows messages","text":"<p>On Windows\u2122, messages are logged in the application events section of the event viewer.</p>"},{"location":"messages_intro/#finding-zos-messages","title":"Finding z/OS messages","text":"<p>On z/OS\u00ae, messages are sent to the operator console. To see the messages, go from the ispf panel to the sdsf panel, then open the log panel.</p>"},{"location":"messages_intro/#obtaining-detailed-message-descriptions","title":"Obtaining detailed message descriptions","text":"<p>Detailed message information is available to help with problem diagnosis.</p> <p>Understanding the warning or error message issued by the VM can help you diagnose problems. All warning and error messages issued by the VM are listed by type in the messages guide: IBM\u00ae VM messages.</p> <p>The messages, error codes, and exit codes in this guide apply to multiple versions of the VM.</p> <p> Note: If the VM fills all available memory, the message number might be produced without a description for the error that caused the problem. Look for the message number in the relevant section of the J9 VM  Messages guide to see the message description and the additional information provided.</p>"},{"location":"migrating11to17/","title":"Migrating from Java 11 to Java 17","text":""},{"location":"migrating11to17/#migrating-from-java-11-to-java-17","title":"Migrating from Java 11 to Java 17","text":"<p>Support for OpenJDK 17 was added in Eclipse OpenJ9\u2122 version 0.29.1.</p> <p>The following new OpenJ9 changes apply when OpenJ9 is built with Java SE 17 class libraries. This information exists elsewhere in the documentation but is summarized here for convenience.</p>"},{"location":"migrating11to17/#support-for-jdk-enhancement-proposals-jep","title":"Support for JDK enhancement proposals (JEP)","text":"<p>The new JEPs that are supported are listed in the following topics:</p> <ul> <li>JDK 12: What's new in version 0.13.0</li> <li>JDK 13: What's new in version 0.16.0</li> <li>JDK 14: What's new in version 0.19.0</li> <li>JDK 15: What's new in version 0.22.0</li> <li>JDK 16: What's new in version 0.25.0</li> <li>JDK 17: What's new in version 0.29.1</li> </ul>"},{"location":"migrating11to17/#new-openj9-features-and-changes","title":"New OpenJ9 features and changes","text":"<p>The following table lists the new OpenJ9 features and notable changes with the OpenJ9 release in which they were added:</p> Features and changes OpenJ9 release Linux builds for all platforms use gcc 10.3 instead of gcc 7.5. See the list of build environments. 0.33.0 The default operating system stack size on x64 platforms is increased from 256 KB to 512 KB to accommodate vector support. You can change the operating system stack size by using the -Xmso option. 0.33.0"},{"location":"migrating8to11/","title":"Migrating from Java 8 to Java 11","text":""},{"location":"migrating8to11/#migrating-from-java-8-to-java-11","title":"Migrating from Java 8 to Java 11","text":"<p>Support for OpenJDK 11 was added in Eclipse OpenJ9\u2122 version 0.10.0.</p> <p>The following new OpenJ9 features and notable changes apply when OpenJ9 is built with Java SE 11 class libraries. This information exists elsewhere in the documentation but is summarized here for convenience.</p>"},{"location":"migrating8to11/#support-for-jdk-enhancement-proposals-jep","title":"Support for JDK enhancement proposals (JEP)","text":"<p>The new JEPs that are supported are listed in the following topics:</p> <ul> <li>JDK 9: What's new in version 0.9.0</li> <li>JDK 10: What's new in version 0.9.0</li> <li>JDK 11: What's new in version 0.10.0</li> </ul>"},{"location":"migrating8to11/#new-openj9-features-and-changes","title":"New OpenJ9 features and changes","text":"<p>The following table lists the new OpenJ9 features and notable changes with the OpenJ9 release in which they were added:</p> Features and changes OpenJ9 release The path that is specified by the default <code>-Xoptionsfile</code> value is the <code>&lt;java_home&gt;/lib</code> directory, where <code>&lt;java_home&gt;</code> is the directory for your runtime environment. For Java 8, the path is the VM directory that is listed in Directory conventions. First release Low-overhead heap profiling is supported. JEP 331 provides a mechanism for sampling Java heap allocations with a low overhead via the JVM Tool Interface (JVMTI). Restrictions: JEP 331 is implemented for OpenJ9 with the following limitations:<ul><li>The <code>balanced</code> and <code>metronome</code> garbage collection policies are not supported.</li><li>The JEP331 JVMTI agent and the Health Center agent both set a sampling interval, which by default is different. If both agents are used at the same time the Health Center agent will get incorrect results, unless the sampling intervals are adjusted to use the same value.</li></ul> 0.15.0 OpenSSL support for the ChaCha20 and ChaCha20-Poly1305 algorithms is available. The version of OpenSSL must be version 1.1.x or later. For more information, see <code>-Djdk.nativeChaCha20</code>. 0.15.0 The <code>-verbose:module</code> option, which writes information to stderr for each module that is loaded and unloaded, is now supported. 0.25.0 The default value of the <code>-XX:MaxDirectMemorySize</code> option, which limits the amount of heap memory that is used for direct byte buffers, is the same as the maximum heap size. For JDK 8, the VM default value is 87.5% of the maximum heap size. 0.32.0 OpenSSL support is added for the following algorithms:<ul><li><code>-Djdk.nativeXDHKeyAgreement</code></li><li><code>-Djdk.nativeXDHKeyGen</code></li></ul>The version of OpenSSL must be version 1.1.1 or later for the <code>-Djdk.nativeXDHKeyAgreement</code> and <code>-Djdk.nativeXDHKeyGen</code> algorithms. 0.40.0"},{"location":"openj9_defaults/","title":"Default settings","text":""},{"location":"openj9_defaults/#default-settings-for-the-eclipse-openj9-vm","title":"Default settings for the Eclipse OpenJ9\u2122 VM","text":"<p>The following tables provide a quick reference to the default settings for the VM when it is first installed.</p> <p>The last 2 columns show whether the default setting can be changed by a command-line parameter or an environment variable. Note that if both are set, the command-line parameter always takes precedence.</p> VM setting Default Command line Env. variable Javadump Enabled yes yes Heapdump Disabled yes yes System dump Enabled yes yes Snap traces Enabled yes yes JIT dump Enabled yes yes Verbose output Disabled yes no Compressed references (See Note 1) yes yes Boot classpath search Disabled yes no JNI checks Disabled yes no Remote debugging Disabled yes no Strict conformance checks Disabled yes no Quickstart Disabled yes no Remote debug info server Disabled yes no Reduced signaling Disabled yes no Signal handler chaining Enabled yes no Classpath Not set yes yes Class data sharing Disabled yes no Accessibility support Enabled no yes JIT compiler Enabled yes yes AOT compiler (See Note 2) Enabled yes no JIT debug options Disabled yes no Java2D max size of fonts with algorithmic bold 14 point no yes Java2D use rendered bitmaps in scalable fonts Enabled no yes Java2D freetype font rasterizing Enabled no yes Java2D use AWT fonts Disabled no yes <p> Notes:</p> <ol> <li> <p>On AIX\u00ae, Linux\u00ae, macOS\u00ae x86, and Windows\u2122: Enabled for -Xmx values \u2264 57 GB, otherwise disabled.</p> <p>On z/OS\u00ae: Enabled for -Xmx values \u2264 25 GB, otherwise disabled. With APAR OA49416, enabled for -Xmx values \u2264 57 GB.</p> <p>On macOS AArch64 (Apple silicon): Disabled.</p> </li> <li> <p>AOT is not used by the VM unless shared classes are also enabled.</p> </li> </ol> VM setting AIX Linux macOS Windows z/OS Command line Env. variable Default locale None None None N/A None no yes Time to wait before starting plug-in N/A Zero N/A N/A N/A no yes Temporary directory <code>/tmp</code> <code>/tmp</code> <code>/tmp</code> <code>c:\\temp</code> <code>/tmp</code> no yes Plug-in redirection None None None N/A None no yes IM switching Disabled Disabled Disabled N/A Disabled no yes IM modifiers Disabled Disabled Disabled N/A Disabled no yes Thread model N/A N/A N/A N/A Native no yes Initial stack size for Java Threads (32/64-bit). Use <code>-Xiss&lt;size&gt;</code> 2 KB 2 KB 2 KB 2 KB 2 KB yes no Maximum stack size for Java Threads (32-bit). Use <code>-Xss&lt;size&gt;</code> 320 KB 320 KB N/A 320 KB 320 KB yes no Maximum stack size for Java Threads (64-bit). Use <code>-Xss&lt;size&gt;</code> 1024 KB 1024 KB 1024 KB 1024 KB 1024 KB yes no Stack size for OS Threads (32-bit). Use <code>-Xmso&lt;size&gt;</code> 256 KB 256 KB N/A 32 KB 256 KB yes no Stack size for OS Threads (64-bit). Use <code>-Xmso&lt;size&gt;</code> 512 KB  512 KB (256 KB on IBM Z\u00ae) Earlier Java versions: 256 KB (512 KB on PPC)  Architecture: x86: 512 KB, AArch64 (Apple silicon): 256 KB Earlier Java versions: 256 KB  512 KB Earlier Java versions: 256 KB 1 MB yes no Initial heap size. Use <code>-Xms&lt;size&gt;</code> 8 MB 8 MB 8 MB 8 MB 8 MB yes no Maximum Java heap size. Use <code>-Xmx&lt;size&gt;</code> See Notes See Notes See Notes See Notes See Notes yes no Page size for the Java object heap and code cache (For restrictions, see the <code>-Xlp:codecache</code> and <code>-Xlp:objectheap</code> options). Operating system default Architecture: x86: 2 MB, IBM Z: 1 MB, Other architectures: Operating system default Architecture: x86: 4 KB, AArch64 (Apple silicon): 16 KB Operating system default 1M pageable yes no <p> Notes:</p> <p>The default value of <code>-Xmx</code> :</p> <ul> <li> <p>The value is 25% of the available memory with a maximum of 25 GB. However, where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB.</p> </li> <li> <p>On Linux\u00ae sytems, if the VM is running in a container and <code>-XX:+UseContainerSupport</code> is enabled, the value is 75% of the container memory limit, with a maximum of 25 GB. However, if the container memory limit is less than 1 GB, the value is 50% of the container memory limit. If the container memory limit is between 1GB and 2GB, the value is the container memory limit minus 512 MB.</p> </li> <li> <p>The default value is capped at 25 GB, which is the limit of heap size for 3-bit shift of compressed references (see <code>-Xcompressedrefs</code>), to prevent silent switching to 4-bit shift of compressed references, which has possible performance penalties. You can use the <code>-Xmx</code> option to overwrite the 25 GB limit.</p> </li> <li> <p> If you have set the <code>-XX:+OriginalJDK8HeapSizeCompatibilityMode</code> option for compatibility with earlier releases, the value is half the available memory with a minimum of 16 MB and a maximum of 512 MB. </p> </li> </ul> <p>Available memory is defined as being the smallest of two values: The real or physical memory or the RLIMIT_AS value.</p>"},{"location":"openj9_directories/","title":"Directory conventions","text":""},{"location":"openj9_directories/#directory-conventions","title":"Directory conventions","text":"<p>The following tables provide a quick reference to the Eclipse OpenJ9\u2122 VM directory location on different Java\u2122 versions and different platform architectures. Some pages refer to the VM directory location as <code>&lt;vm_dir&gt;</code>.</p> Operating system Java 8 Java 11 and later AIX\u00ae <code>&lt;install_dir&gt;/jre/lib/ppc[64]/default</code> <code>&lt;install_dir&gt;/</code> Linux\u00ae <code>&lt;install_dir&gt;/jre/lib/&lt;arch&gt;/default</code> <code>&lt;install_dir&gt;/</code> macOS\u00ae <code>&lt;install_dir&gt;/jre/lib/default</code> <code>&lt;install_dir&gt;/</code> Windows\u2122 <code>&lt;install_dir&gt;\\jre\\bin\\default</code> <code>&lt;install_dir&gt;\\</code> z/OS\u00ae <code>&lt;install_dir&gt;/jre/lib/s390[x]/default</code> <code>&lt;install_dir&gt;/</code> <p>Where:</p> <ul> <li><code>&lt;install_dir&gt;</code> is your JDK installation directory.</li> <li><code>&lt;arch&gt;</code> depends on the architecture your Linux distribution is running on. See the following table for possible values:</li> </ul> Architecture Value of <code>&lt;arch&gt;</code> x86 32-bit <code>i386</code> x86 64-bit <code>x86-64</code> IBM POWER\u00ae 32-bit (Big Endian) <code>ppc</code> IBM POWER 64-bit (Big Endian) <code>ppc64</code> IBM POWER 64-bit (Little Endian) <code>ppc64le</code> IBM Z\u00ae 31-bit <code>s390</code> IBM Z 64-bit <code>s390x</code>"},{"location":"openj9_newuser/","title":"New to OpenJ9?","text":""},{"location":"openj9_newuser/#new-to-eclipse-openj9","title":"New to Eclipse OpenJ9?","text":"<p>The Eclipse OpenJ9\u2122 virtual machine (VM) implements the Java Virtual Machine Specification. Most Java applications should run on an OpenJDK that contains the OpenJ9 VM without changing anything. However, because it is an independent implementation there are some differences compared to the HotSpot VM, which is the default OpenJDK VM and is also included in an Oracle JDK.</p>"},{"location":"openj9_newuser/#command-line-options","title":"Command-line options","text":"<p>Although OpenJ9 implements its own command-line interface, many HotSpot options are recognized and accepted by the VM for compatibility. Any <code>-XX:</code> options that are not recognized by the VM are ignored by default, which prevents an application failing to start. You can turn off this behavior with the -XX:-IgnoreUnrecognizedXXColonOptions option.</p> <p>For a list of compatible options, equivalent options, and options that need to be set for compatibility, see Switching to OpenJ9.</p>"},{"location":"openj9_newuser/#garbage-collection-policies","title":"Garbage collection policies","text":"<p>Eclipse OpenJ9 has a number of garbage collection (GC) policies designed around different types of applications and workloads. By default, OpenJ9 uses the Generational Concurrent (<code>gencon</code>) GC policy, which is best suited for transactional applications that have many short-lived objects. The policy aims to minimize GC pause times without compromising throughput. If you are using Java 8, the <code>gencon</code> policy is similar to the HotSpot CMS (concurrent mark sweep). If you are using Java 11, the OpenJ9 balanced (<code>balanced</code>) policy is most similar to the default HotSpot policy.</p> <p>If you have a different type of workload, you might want to select a different GC policy. For details about the available policies and when to choose them, see Garbage collection.</p>"},{"location":"openj9_newuser/#operational-tooling","title":"Operational tooling","text":"<p>If you are a Java application developer or you are responsible for managing large server or desktop deployments of a Java runtime environment, you probably use a number of tools for monitoring, management, and troubleshooting. Because OpenJ9 is an independent implementation, it has evolved with its own approach for these areas and, in some cases, its own unique tools.</p> <p>In other cases, tools have been added for compatibility with the reference implementation, but these tools might differ in behavior from equivalent tools in HotSpot. For a list of these tools, see Switching to OpenJ9 in the Tools section.</p>"},{"location":"openj9_newuser/#dumps-logs-and-trace-files","title":"Dumps, logs, and trace files","text":"<p>OpenJ9 contains extensive trace and debugging capabilities to help identify, isolate, and solve run time problems.</p> <ul> <li>Dump files: Various types of dump are produced by default in response to certain events and can also be triggered for a whole range of events by using the <code>com.ibm.jvm.Dump</code> API or by specifying <code>-Xdump</code> options on the command line. Dumps include Java dumps, heap dumps, system dumps, JIT dumps, stack dumps, and snap dumps (tracepoint data). For more information, see the <code>-Xdump</code> option.</li> <li>Verbose log files: Some components of OpenJ9 can also produce verbose output or log files to assist with problem determination, including class data sharing, garbage collection, and the JIT compiler.</li> <li>Trace files: The OpenJ9 implementation contains extensive tracepoints used to log information and exceptional conditions, with minimal impact on performance. Some tracepoints are enabled by default; others can be enabled on demand. For more information, see the <code>-Xtrace</code> option for tracing Java applications and the VM, and the <code>-Xtgc</code> option for tracing garbage collection.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, you probably make use of the monitoring and diagnostic tools that are provided with the VM. OpenJ9 has implemented a different approach to providing similar data; rather than running a number of different tools to obtain a different piece of information, the Java dump file provides a comprehensive set of information in one place. You can find the following information in an OpenJ9 Java dump:</p> <ul> <li>The system the VM is running on and the resources available.</li> <li>The Java execution environment, including the options set from the command line.</li> <li>The native memory used by the VM, broken down by VM component.</li> <li>Memory usage in the VM for the object heap and internal VM structures, such as the JIT code cache.</li> <li>Lock operations that protect shared resources during runtime.</li> <li>Java threads, native threads, and stack traces.</li> <li>Hook interfaces, for performance analysis.</li> <li>Details about the shared classes cache, if used.</li> <li>Detailed information about classloaders, together with a list of libraries and classes that are loaded.</li> </ul> <p>For more information, see Java dump.</p>"},{"location":"openj9_newuser/#tools","title":"Tools","text":"<p>OpenJ9 provides support for a number of monitoring and diagnostic tools that can be found in the Eclipse marketplace. Each tool provides a graphical user interface to help you visualize data and, in some cases, can provide tuning or debugging recommendations.</p> <ul> <li>Health Center: Provides real-time monitoring of running applications with minimal overhead over the network. You can monitor a whole range of operations including, class loading, CPU usage, GC heap and pause times, I/O activity, lock contention, method trace, native memory usage, profiling, and live threads. For more information, read the Health Center documentation.</li> <li>Garbage Collection Memory Vizualizer (GCMV): Plots GC and native memory data over time. You can view and save data as a report, raw log, tabulated data, or in graphical format. The tool helps to diagnose problems such as memory leaks with data presented in various visual formats for analysis. Tuning recommendations are also provided. For more information, read the GCMV documentation.</li> <li>Eclipse Memory Analyzer\u2122: Examines the Java object heap to help find memory leaks or reduce memory consumption. Support is available for OpenJ9 via the DTFJ interface (Install from the Eclipse Help menu; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java). More information about Eclipse MAT can be found on the project website page.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, the Java VisualVM utility is functionally similar to Health Center. Most of the other tools provided with HotSpot are not officially supported, but equivalent functionality is available in OpenJ9 through command-line options, dump agents, and AttachAPI.</p>"},{"location":"openj9_newuser/#interfaces","title":"Interfaces","text":"<p>OpenJ9 provides the following interfaces, which can be used for monitoring and diagnostic purposes:</p> <ul> <li>JVMTI: OpenJ9 supports the Java Virtual Machine Tool Interface (JVMTI) and provides extensions that allow JVMTI tools to obtain diagnostic information or trigger diagnostic operations in the VM. For more information about this interface, see Java Virtual Machine Tool Interface.</li> <li>DTFJ interface: The Diagnostic Tool Framework for Java (DTFJ) API allows custom applications to be written that can access a wide range of information in a system dump or a Java dump. DTFJ can be used with the Eclipse Memory Analyzer Toolkit (MAT) to examine the Java object heap for memory leaks and to reduce memory consumption. For more information about DTFJ, see Diagnostic Tool Framework for Java.</li> <li>java.lang.management API: OpenJ9 provides MXBean additions and extensions to this standard API, which enables you to use tools such as JConsole to monitor and manage your Java applications. For more information, see Language management interface.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, you might make use of certain <code>com.sun.management</code> interfaces. Although OpenJ9 implements some of these interfaces, a few are specific to the HotSpot VM. The following table indicates alternative classes or mechanisms that you can use for equivalent function in OpenJ9:</p> HotSpot-specific classes Alternatives for OpenJ9 <code>HotSpotDiagnosticMXBean</code> <code>OpenJ9DiagnosticsMXBean</code> (for heap dumps) <code>MissionControl</code> Use Health Center <code>MissionControlMXBean</code> Use Health Center <code>ThreadMXBean</code> <code>JvmCpuMonitorMXBean</code> (for thread time) <code>VMOption</code> OpenJ9 Java dump (option <code>-Xdump:java</code>) <code>DiagnosticCommandMBean</code> None <p> Note: OpenJ9 implements the following <code>com.sun.management</code> interfaces: <code>GarbageCollectorMXBean</code>, <code>GarbageCollectionNotificationInfo</code>, <code>GcInfo</code>, <code>OperatingSystemMXBean</code>, <code>UnixOperatingSystemMXBean</code>.</p> <p>For information about OpenJ9 application programming interfaces, see API documentation.</p>"},{"location":"openj9_newuser/#other-differences","title":"Other differences","text":"<p>This topic describes the differences between the HotSpot VM and the Eclipse OpenJ9 VM. Therefore, if you are currently using an OpenJDK with the default HotSpot VM and you want to switch to using an OpenJDK with the OpenJ9 VM, these are the only differences you might be concerned about. If however, you are using an Oracle JDK, you might want to learn about differences between other components that make up an Oracle JDK or an OpenJDK from the AdoptOpenJDK community. For more information, read the Migration guide.</p>"},{"location":"openj9_releases/","title":"Overview","text":""},{"location":"openj9_releases/#overview","title":"Overview","text":"<p>New releases of Eclipse OpenJ9\u2122 are set to coincide with critical patch updates and new versions of the Java\u2122 SE class libraries. To learn more about when these releases take place, and the OpenJ9 support lifecycle, see Supported environments.</p> <p>If you are interested in the content of future releases, plans are published in the Eclipse OpenJ9 project page.</p> <p>High level information about the features and changes in final releases of OpenJ9 can be found in the topics that follow.</p>"},{"location":"openj9_signals/","title":"Signal handling","text":""},{"location":"openj9_signals/#signal-handling","title":"Signal handling","text":"<p>Signals used by the Eclipse OpenJ9\u2122 VM include the following types:</p> <ul> <li>Exceptions (Exc): Raised synchronously by the operating system whenever an unrecoverable condition occurs (not applicable on Windows\u2122 systems).</li> <li>Errors (Err): Raised by the OpenJ9 VM when an unrecoverable condition occurs.</li> <li>Interrupts (Int): Raised asynchronously from outside a VM process to request a VM exit.</li> <li>Controls (Con): Other signals that are used by the VM for control purposes.</li> </ul> <p>For exceptions and errors, if the VM cannot handle the condition and recover, dumps are produced and a controlled shut down sequence takes place. Interrupts also cause the VM to enter a controlled shut down sequence, but without generating dumps. The shutdown sequence is equivalent to calling <code>System.exit()</code>, which results in the following steps:</p> <ol> <li>The VM calls the equivalent application signal handler.</li> <li>The VM calls any hooks installed by the application (unexpected shutdown hooks for exceptions or errors, shutdown or exit hooks for interrupts).</li> <li>The VM does any final clean up.</li> </ol> <p>Control signals are used for internal control purposes and do not cause the VM to end.</p> <p>The VM takes control of any signals for Java\u2122 threads. For non-Java threads, the VM passes control to an application handler, if one is installed. If the application does not install a signal handler, or signal chaining is turned off, the signal is either ignored or the default action is taken. Signal chaining is controlled by the <code>-Xsigchain</code> / <code>-Xnosigchain</code> command-line option.</p> <p>The signals relevant to each platform are detailed in the sections that follow.</p> <p>When reading each table, a number supplied after the signal name is the standard numerical value for that signal.</p> <p>Note that certain signals on VM threads cause OpenJ9 to shutdown. An application signal handler should not attempt to recover from these signals unless it no longer requires the VM.</p>"},{"location":"openj9_signals/#signals-on-linux","title":"Signals on Linux","text":"Signal Type Description Option to disable signal <code>SIGBUS (7)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (6)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (12)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (3)</code> Con Quit signal from a terminal, which triggers a Java dump by default <code>-Xrs</code> <code>SIGTRAP (5)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGRTMIN (34)</code> Con Used by the VM for thread introspection - <code>SIGRTMIN +1 (35)</code> Con Used by the VM for Runtime Instrumentation (Linux for IBM Z\u00ae systems only) - <code>SIGRTMAX -2 (62)</code> Con Used by the <code>java.net</code> class library code - <code>SIGCHLD (17)</code> Con Used by the <code>java.lang.Process</code> implementation - <p> Notes:</p> <ul> <li>The use of <code>SIGRTMIN</code> is configurable with the <code>-Xdump:suspendwith=&lt;num&gt;</code> option.</li> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signals-on-macos","title":"Signals on macOS","text":"Signal Type Description Option to disable signal <code>SIGBUS (10)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction)) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (6)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (31)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (3)</code> Con Quit signal from a terminal, which triggers a Java dump by default <code>-Xrs</code> <code>SIGTRAP (5)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGCHLD (20)</code> Con Used by the <code>java.lang.Process</code> implementation - <code>SIGUSR1 (30)</code> Con Used by the VM for thread introspection - <code>SIGIO (23)</code> Con Used by the <code>java.net</code> class library code - <p> Note:</p> <ul> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signals-on-windows","title":"Signals on Windows","text":"Signal Type Description Option to disable signal <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGBREAK</code> Con A break signal from a terminal. By default, this triggers a Java dump <code>-Xrs</code> <p> Notes:</p> <p>The following mechanisms are used by OpenJ9 for signal handling:</p> <ul> <li>structured exception handling (32-bit VM only)</li> <li><code>AddVectoredExceptionHandler()</code> API (64-bit JVM only)</li> <li><code>SetConsoleCtrlHandler()</code> applicable</li> </ul> <p>All mechanisms can be disabled by using the <code>-Xrs</code> option. However, only structured exception handling and the use of the <code>AddVectoredExceptionHandler()</code> API can be disabled  by using the <code>-Xrs:sync</code> option. The option <code>-Xnosigchain</code>, which turns off signal handler chaining, is ignored on Windows systems.</p>"},{"location":"openj9_signals/#signals-on-zos","title":"Signals on z/OS","text":"Signal Type Description Option to disable signal <code>SIGBUS (10)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction)) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (3)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (17)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (24)</code> Con Quit signal from a terminal, triggers a Java dump by default <code>-Xrs</code> <code>SIGTRAP (26)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGCHLD (20)</code> Con Used by the <code>java.lang.Process</code> implementation - <code>SIGUSR1 (16)</code> Con Used by the <code>java.net</code> class library code - <p> Note:</p> <ul> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signals-on-aix","title":"Signals on AIX","text":"Signal Type Description Option to disable signal <code>SIGBUS (10)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction)) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (6)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (31)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (3)</code> Con Triggers a Java dump by default <code>-Xrs</code> <code>No Name (40)</code> Con Used by the VM for control purposes <code>-Xrs</code> <code>SIGRECONFIG (58)</code> Con Reserved to detect changes to resources (CPUs, processing capacity, or physical memory) <code>-Xrs</code> <code>SIGTRAP (5)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGRTMIN (50)</code> Con Used by the VM for thread introspection - <code>SIGRTMAX -1 (56)</code> Con Used by the <code>java.net</code> class library code - <code>SIGCHLD (20)</code> Con Used by the <code>java.lang.Process</code> implementation - <p> Notes:</p> <ul> <li>VM performance is affected if you install a signal handler for SIGTRAP (5) or SIGRECONFIG (58) because these signals are used for internal control purposes.</li> <li>If you want to generate floating point exceptions, use the following call in your code to generate a <code>SIGFPE</code> signal: <code>fp_trap( P_TRAP_SYNC)</code>. Although you can use the C compiler <code>-qflttrap</code> setting to generate <code>SIGTRAP</code> signals to trap floating point exceptions, this mechanism can affect the JIT compiler.</li> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signal-chaining","title":"Signal chaining","text":"<p>Signal chaining allows application code to interoperate with VM signal handling. By linking and loading a shared library, certain calls can be intercepted so that the application handlers do not replace the VM signal handlers already installed by the VM. Instead, the application handlers are chained behind the VM handlers. If signals that are raised do not target the VM, the application handlers take over. Signals that can be chained include <code>signal()</code>, <code>sigset()</code>, and <code>sigaction()</code>.</p> <p>The following table shows the shared library that must be linked with the application that creates or embeds a VM, and the command line syntax to use with the compiler, where available:</p> Operating system Shared library Method for linking Linux\u00ae, macOS\u00ae, and z/OS\u00ae <code>libjsig.so</code> <code>gcc -L$JAVA_HOME/bin -ljsig -L$JAVA_HOME/lib/j9vm -ljvm &lt;java_application&gt;.c</code> Windows <code>jsig.dll</code> Link the DLL with the application that creates or embeds a VM AIX <code>libjsig.so</code> <code>cc_r [-q64] &lt;other_compile/link_parameter&gt; -L&lt;java_install_dir&gt; -ljsig -L&lt;java_install_dir&gt;/lib/j9vm -ljvm &lt;java_application&gt;.c</code> <p>In the absence of signal chaining, the VM does not allow application signal handlers for certain signals that are used internally by the VM, including the <code>SIGUSR2</code> signal. You can use the <code>-XX:-HandleSIGUSR2</code> option instead, whereby the VM signal handler is not installed on VM startup. Therefore, the application signal handler, if available, takes over the handling of the <code>SIGUSR2</code> signal. If there is no application signal handler, then the operating system's default signal handler is used.</p> <p>For more information about this option that affects the handling of the <code>SIGUSR2</code> signal, see <code>-XX:[+|-]HandleSIGUSR2</code>.</p> <p> Note: On Linux, macOS, and z/OS systems, you can use the <code>LD_PRELOAD</code> environment variable as an alternative method to the command line for linking the shared library as shown in the following list:</p> <ul> <li>bash and ksh shells: <code>export LD_PRELOAD=$JAVA_HOME/lib/libjsig.so; &lt;java_application&gt;</code></li> <li>csh shell: <code>setenv LD_PRELOAD=$JAVA_HOME/lib/libjsig.so; &lt;java_application&gt;</code></li> </ul>"},{"location":"openj9_signals/#see-also","title":"See also","text":"<ul> <li>-Xrs</li> <li>-Xsigcatch</li> <li>-Xsigchain</li> <li>-Xsignal (z/OS only)</li> </ul>"},{"location":"openj9_support/","title":"Supported environments","text":""},{"location":"openj9_support/#supported-environments","title":"Supported environments","text":"<p>The Eclipse OpenJ9\u2122 project source code can be built against multiple JDK levels starting with JDK8, so the question of support has a more complicated answer than at OpenJDK. Our community is committed to supporting JDK levels as long as they are supported at the OpenJDK open source project with a significant user base. Currently, Eclipse OpenJ9 produces a new release every quarter that can build against all JDK levels that are currently supported by the OpenJDK community. We are committed to accepting problem reports when using Eclipse OpenJ9 against a supported OpenJDK level, with fixes being delivered in each release of Eclipse OpenJ9.</p> <p>In order to track the OpenJDK 6-month release cadence, OpenJ9 also produces two releases a year that support only a single JDK level. These releases will occur in March and September with the intention of supporting only the corresponding new OpenJDK feature release.</p> <p>The following table summarizes which JDK levels are expected to be supported by which Eclipse OpenJ9 releases, along with projected release dates. All future dates and support expectations are predictions that might change depending on how the OpenJDK and OpenJ9 projects evolve over time. To keep this table concise, some rows and columns will be removed over time.</p>"},{"location":"openj9_support/#eclipse-openj9-releases","title":"Eclipse OpenJ9 releases","text":"OpenJ9 release Release date JDK8 (LTS) JDK11 (LTS) JDK17 (LTS) JDK20 JDK21 (LTS) 0.38.0 Apr 2023 yes yes yes 0.39.0 Jun 2023 (2) no no no yes 0.40.0 Jul 2023 yes yes yes yes 0.41.0 Oct 2023 yes yes yes no 0.42.0 Dec 2023 (1, 3) no no no no yes 0.43.0 Jan 2024 (1) yes yes yes no yes <p> Notes:</p> <ol> <li>These future OpenJ9 releases are expected, in line with our support statement.</li> <li>These OpenJ9 releases are feature releases that support a new OpenJDK release only.</li> <li>These OpenJ9 releases support a new LTS OpenJDK release only.</li> </ol> <p>For any issues or limitations of an Eclipse OpenJ9 release, read the release notes.</p>"},{"location":"openj9_support/#platform-support","title":"Platform support","text":"<p>The Eclipse OpenJ9 project is open to supporting any hardware or operating system platforms provided that we have community members available to maintain them. For practical reasons the Eclipse OpenJ9 JVM does not currently run on every platform.</p>"},{"location":"openj9_support/#openjdk-8","title":"OpenJDK 8","text":"<p>OpenJDK 8 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux\u00ae AArch64 x32 x64 ppc64le Z31 Z64 CentOS 6.10 no  yes yes no  no  no  CentOS 7.9 yes yes yes yes no  no  CentOS Stream 8 yes no yes yes no  no  Red Hat Enterprise Linux (RHEL) 6.10 no  yes yes no  no  no  RHEL 7.8 yes yes yes yes no yes RHEL 8.6 yes no yes yes no yes RHEL 9.0 no no yes yes no yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes yes yes Ubuntu 20.04 yes no yes yes no  yes Ubuntu 22.04 no no yes yes no  yes <p> Notes:</p> <ul> <li> <p>Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.12 (x) or 2.17 (others)</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> </li> <li> <p>Support for OpenJ9 on CentOS 6.10 might be available even though CentOS 6 is no longer supported by the CentOS project. However, this support is deprecated and will be removed in a future release. With the removal of support, the minimum glibc version (x) will be increased from 2.12 to 2.17.</p> </li> </ul> Windows\u2122 x32 x64 Windows 10 yes yes Windows 11 yes yes Windows Server 2016 yes yes Windows Server 2019 yes yes Windows Server 2022 yes yes macOS\u00ae x64 OS X\u00ae 10.10.0+ yes macOS 11 yes macOS 12 yes macOS 13 yes AIX\u00ae ppc32 ppc64 AIX 7.2 TL5 yes yes <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#openjdk-11","title":"OpenJDK 11","text":"<p>OpenJDK 11 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux (Note 1) AArch64 x64 ppc64le Z64 CentOS 6.10 no  yes no  no  CentOS 7.9 yes yes yes no  CentOS Stream 8 yes yes yes no  Red Hat Enterprise Linux (RHEL) 6.10 no  yes no  no  RHEL 7.8 yes yes yes yes RHEL 8.6 yes yes yes yes RHEL 9.0 no yes yes yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes Ubuntu 20.04 yes yes yes yes Ubuntu 22.04 no yes yes yes <p> Notes:</p> <ul> <li> <p>Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.12 (x) or 2.17 (others)</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> </li> <li> <p>Support for OpenJ9 on CentOS 6.10 might be available even though CentOS 6 is no longer supported by the CentOS project. However, this support is deprecated and will be removed in a future release. With the removal of support, the minimum glibc version (x) will be increased from 2.12 to 2.17.</p> </li> </ul> Windows x64 Windows 10 yes Windows 11 yes Windows Server 2016 yes Windows Server 2019 yes Windows Server 2022 yes macOS x64 AArch64 (Apple silicon) OS X 10.11+ yes no macOS 11 yes yes macOS 12 yes yes macOS 13 yes yes AIX ppc64 AIX 7.2 TL5 yes <p> Important: AIX OpenJ9 builds require the XL C++ Runtime 16.1.0.7 or later.</p> <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#openjdk-17","title":"OpenJDK 17","text":"<p>OpenJDK 17 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux (Note 1) AArch64 x64 ppc64le Z64 CentOS 7.9 yes yes yes no  CentOS Stream 8 yes yes yes no  RHEL 7.8 yes yes yes yes RHEL 8.6 yes yes yes yes RHEL 9.0 no yes yes yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes Ubuntu 20.04 yes yes yes yes Ubuntu 22.04 no yes yes yes <p> Note: Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.17</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> Windows x64 Windows 10 yes Windows 11 yes Windows Server 2016 yes Windows Server 2019 yes Windows Server 2022 yes macOS x64 AArch64 (Apple silicon) macOS 10.14+ yes no macOS 11 yes yes macOS 12 yes yes macOS 13 yes yes AIX ppc64 AIX 7.2 TL5 yes <p> Important: AIX OpenJ9 builds require the XL C++ Runtime 16.1.0.7 or later.</p> <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#openjdk-21","title":"OpenJDK 21","text":"<p>OpenJDK 21 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux (Note 1) AArch64 x64 ppc64le Z64 CentOS 7.9 yes yes yes no  CentOS Stream 8 yes yes yes no  RHEL 7.8 yes yes yes yes RHEL 8.6 yes yes yes yes RHEL 9.0 no yes yes yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes Ubuntu 20.04 yes yes yes yes Ubuntu 22.04 no yes yes yes <p> Note: Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.17</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> Windows x64 Windows 10 yes Windows 11 yes Windows Server 2016 yes Windows Server 2019 yes Windows Server 2022 yes macOS x64 AArch64 (Apple silicon) macOS 11 yes yes macOS 12 yes yes macOS 13 yes yes AIX ppc64 AIX 7.2 TL5 yes <p> Important: AIX OpenJ9 builds require the XL C++ Runtime 16.1.0.7 or later.</p> <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#build-environments","title":"Build environments","text":"<p>The project builds and tests OpenJDK with OpenJ9 on a number of platforms. The operating system and compiler levels for the build systems are shown in the following tables.</p>"},{"location":"openj9_support/#openjdk-8_1","title":"OpenJDK 8","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 6.10 gcc 7.5 Linux on POWER\u00ae LE 64-bit CentOS 7.9 gcc 7.5 Linux on IBM Z\u00ae 64-bit RHEL 7.9 gcc 7.5 Linux AArch64 64-bit CentOS 7.9 gcc 7.5 Windows x86 32-bit Windows Server 2019 Microsoft Visual Studio 2019 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2019 macOS x86 64-bit OSX 10.15.7 xcode 12.4 and clang 12.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 13.1.3"},{"location":"openj9_support/#openjdk-11_1","title":"OpenJDK 11","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 6.10 gcc 7.5 Linux on POWER LE 64-bit CentOS 7.9 gcc 7.5 Linux on IBM Z 64-bit RHEL 7.9 gcc 7.5 Linux AArch64 64-bit CentOS 7.9 gcc 7.5 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2019 macOS x86 64-bit macOS 10.15.7 xcode 12.4 and clang 12.0.0 macOS AArch64 macOS 11.5.2 xcode 13.0 and clang 13.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 16.1.0.11"},{"location":"openj9_support/#openjdk-17_1","title":"OpenJDK 17","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 7.9 gcc 10.3 Linux on POWER LE 64-bit CentOS 7.9 gcc 10.3 Linux on IBM Z 64-bit RHEL 7.9 gcc 10.3 Linux AArch64 64-bit CentOS 7.9 gcc 10.3 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2019 macOS x86 64-bit macOS 10.15.7 xcode 12.4 and clang 12.0.0 macOS AArch64 macOS 11.5.2 xcode 13.0 and clang 13.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 16.1.0.11"},{"location":"openj9_support/#openjdk-21-and-later","title":"OpenJDK 21 and later","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 7.9 gcc 11.2 Linux on POWER LE 64-bit CentOS 7.9 gcc 11.2 Linux on IBM Z 64-bit RHEL 7.9 gcc 11.2 Linux AArch64 64-bit CentOS 7.9 gcc 10.3 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2022 macOS x86 64-bit macOS 10.15.7 xcode 12.4 and clang 12.0.0 macOS AArch64 macOS 11.5.2 xcode 13.0 and clang 13.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 16.1.0.11"},{"location":"openssl/","title":"OpenSSL","text":""},{"location":"openssl/#openssl","title":"OpenSSL","text":"<p>OpenJDK uses the in-built Java\u2122 cryptographic implementation by default but Eclipse OpenJ9\u2122 also provides some support for the OpenSSL cryptographic library. OpenSSL is an open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which is well established and used with many enterprise applications. Because it is a native library, OpenSSL might provide better performance. To use OpenSSL cryptographic acceleration, install OpenSSL 1.0.x, 1.1.x, or 3.x on your system. The OpenSSL V1.0.x, V1.1.x, and V3.x implementations are currently supported for the Digest, CBC, GCM, RSA, ECDH key agreement, and EC key generation algorithms. The OpenSSL V1.1.x and V3.x implementations are also supported for the ChaCha20 and ChaCha20-Poly1305 algorithms. The OpenSSL V1.1.1 onwards implementations are supported for the XDH key agreement and XDH key generation algorithms.</p> <p>On Linux\u00ae and AIX\u00ae operating systems, the OpenSSL 1.0.x, 1.1.x, or 3.x library is expected to be found on the system path. If you use a package manager to install OpenSSL, the system path will be updated automatically. On Windows\u2122 and MacOS\u00ae the OpenSSL 3.x library is bundled. Later levels of some Linux operating systems also bundle OpenSSL 3.x.</p> <p>If you have multiple versions of OpenSSL on your system, the OpenJ9 VM uses the latest version.</p> <p> Note: OpenSSL 3.x does not support initialization vector (IV) sizes above 16 Bytes for the GCM algorithm. (In earlier OpenSSL versions, you can use such sizes but they might cause unpredictable behavior.) If you need to use a larger size, disable OpenSSL support for the GCM algorithm.</p> <p>OpenSSL support is enabled by default for all supported algorithms. If you want to limit support to specific algorithms, a number of system properties are available for tuning the implementation.</p> <p>Each algorithm can be disabled individually by setting the following system properties on the command line:</p> <ul> <li>To turn off Digest, set <code>-Djdk.nativeDigest=false</code></li> <li>To turn off ChaCha20 and ChaCha20-Poly1305, set <code>-Djdk.nativeChaCha20=false</code>.  Note:  These algorithms are not supported on Java 8 </li> <li>To turn off CBC, set <code>-Djdk.nativeCBC=false</code></li> <li>To turn off GCM, set <code>-Djdk.nativeGCM=false</code></li> <li>To turn off RSA, set <code>-Djdk.nativeRSA=false</code></li> <li>To turn off ECDH key agreement, set <code>-Djdk.nativeEC=false</code></li> <li>To turn off EC key generation, set <code>-Djdk.nativeECKeyGen=false</code></li> <li> To turn off XDH key agreement, set <code>-Djdk.nativeXDHKeyAgreement=false</code></li> <li>To turn off XDH key generation, set <code>-Djdk.nativeXDHKeyGen=false</code> </li> </ul> <p>You can turn off all the algorithms by setting the following system property on the command line:</p> <pre><code>-Djdk.nativeCrypto=false\n</code></pre> <p>To build a version of OpenJDK with OpenJ9 that includes OpenSSL support, follow the steps in our detailed build instructions:</p> <ul> <li>OpenJDK 8 with OpenJ9.</li> <li>OpenJDK 11 with OpenJ9.</li> <li>OpenJDK 17 with OpenJ9.</li> </ul> <p> Note: If you obtain an OpenJDK with OpenJ9 build that includes OpenSSL or build a version yourself that includes OpenSSL support, the following acknowledgments apply in accordance with the license terms:</p> <ul> <li>This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/).</li> <li>This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).</li> </ul>"},{"location":"shrc/","title":"Introduction","text":""},{"location":"shrc/#introduction-to-class-data-sharing","title":"Introduction to class data sharing","text":"<p>Sharing class data between Eclipse OpenJ9\u2122 VMs improves start up performance and reduces memory footprint. Consider the following outcomes for two VMs that are running similar Java applications but sharing class data:</p> <ul> <li> <p>Start up performance is improved by placing classes that each application needs when initializing into a shared classes cache. The next time the application runs, it takes less time to start because the classes are already available.</p> </li> <li> <p>Memory footprint is reduced by sharing common classes between the applications.</p> </li> </ul> <p>When class data sharing is enabled, OpenJ9 automatically creates shared memory that stores and shares the classes in memory between processes. This shared classes cache is updated dynamically; when an application loads new classes, the VM automatically stores them in the cache without any user intervention. By default, class data sharing is enabled for bootstrap classes, as described in Enabling class data sharing.</p> <p>When class data sharing is enabled, Ahead-of-time (AOT) compilation is also enabled by default, which dynamically compiles certain methods into AOT code at runtime. By using these features in combination, startup performance is further improved because the cached AOT code can be used to quickly enable native code performance for subsequent runs of your application. For more information about AOT, see AOT Compiler. Further performance improvements are gained by storing JIT data and profiles in the shared classes cache.</p> <p>The contents of a shared classes cache can include the following artifacts:</p> <ul> <li>Bootstrap classes</li> <li>Application classes</li> <li>Metadata that describes the classes</li> <li>AOT-compiled code</li> <li>JIT data</li> <li>GC hints (for initial Java heap size)</li> <li> Bootstrap <code>jar</code> file indexes</li> </ul>"},{"location":"shrc/#cache-utilities","title":"Cache utilities","text":"<p>Active caches can be managed by a set of cache utilities, which are invoked by specifying <code>-Xshareclasses</code> suboptions. These utilities control the following types of operations:</p> <ul> <li>Displaying information about the caches on a system.</li> <li>Adjusting the size of a cache and the amount of space that is reserved for AOT code or JIT data.</li> <li>Creating a snapshot of a non-persistent cache to save to disk and restoring the cache from disk.</li> <li>Troubleshooting cache problems.</li> <li>Removing unwanted caches on a system.</li> </ul> <p>These cache utilities are discussed in more detail in the sections that follow.</p>"},{"location":"shrc/#enabling-class-data-sharing","title":"Enabling class data sharing","text":"<p>Class data sharing is enabled by default for bootstrap classes, unless your application is running in a container. Default behavior includes the following characteristics:</p> <ul> <li>On Windows\u00ae, the cache is created in the user's <code>C:\\Users\\&lt;username&gt;\\AppData\\Local\\javasharedresources</code> directory. On z/OS\u00ae, the default cache directory is <code>/tmp/javasharedresources</code>. On other systems, the cache is created in the <code>.cache/javasharedresources</code> directory in the user's home directory, unless the <code>groupAccess</code> parameter is specified, in which case it is created in <code>/tmp/javasharedresources</code>. Please do not set the home directory on a NFS mount or shared mount across systems or LPARs.</li> <li>The cache name is <code>sharedcc_%u</code>, where <code>%u</code> is the current user name.</li> <li>If class data sharing fails, the VM still starts without printing any errors.</li> </ul> <p>Shared class behavior is controlled by specifying the -Xshareclasses option on the command line when you start your application. The default settings are equivalent to specifying the following suboptions:</p> <pre><code>-Xshareclasses:bootClassesOnly,nonFatal,silent\n</code></pre> <p>You can enable class data sharing for non-bootstrap classes as well as bootstrap classes, by omitting the <code>bootClassesOnly</code> suboption. You can also disable all class data sharing by using the <code>none</code> suboption.</p> <p>Further suboptions are available to configure a cache at startup, including name, location, and startup size. You can also use cache utilities to manage a shared classes cache after it is initialized and in use.</p> <p>A shared classes cache can be persistent or non-persistent according to the following definition:</p> <ul> <li>persistent caches are written to memory-mapped files and remain in place, even after a system is rebooted.</li> <li>non-persistent caches exist in shared memory and are automatically removed when the operating system is restarted.</li> </ul> <p>By default, a shared classes cache is persistent, except on the z/OS\u00ae platform, where persistent caches are not supported. If you are using a non-persistent cache, you can use a cache utility to create a snapshot of the cache, which can be reinitialized after a reboot. For more information see Saving a non-persistent shared classes cache.</p> <p>If you have multiple VMs and you do not change the default shared classes behavior, the VMs share a single default cache, assuming that the VMs are from a single Java installation. If the VMs are from different Java installations, the cache might be deleted and re-created.</p> <p>For a set of best practices when using class data sharing, see Creating a shared classes cache.</p>"},{"location":"shrc/#class-data-sharing-operations","title":"Class data sharing operations","text":"<p>When a VM loads a class and the class loader is enabled for class sharing, the VM looks in the shared classes cache to see if the class is already present. If the class is present and the classpath or URL to load the class is a match, the VM loads the class from the cache. Otherwise, it loads the class from the file system and writes it into the cache.</p> <p>The VM detects file system updates by storing timestamp values into the cache and comparing the cached values with actual values. In this way, the VM detects when a class might be invalidated and can mark the class as stale. These operations happen transparently when classes are loaded, so users can modify and update as many classes as they like during the lifetime of a shared class cache, knowing that the correct classes are always loaded. Stale classes are redeemed if the same class is subsequently fetched by the class loader from another VM and checked against the stale class in the cache.</p> <p>Occasionally, caches that are created from one version of the VM might not be compatible with caches that are created from a different version. This situation typically occurs when an update is made in OpenJ9 that changes the internal cache data structure. If a VM detects an incompatible cache at start up, it creates a new cache that can coexist, even if it has the same name. The VM detects a conflict by checking an internal shared classes cache generation number.</p> <p>Caches are not compatible between VMs that are using different object storage modes. For example, a 64-bit VM that uses compressed references to store 64-bit objects in a 32-bit representation, cannot share a cache with a 64-bit VM that is not using compressed references. For more information about object storage options, see Compressed references.</p> <p>In the OpenJ9 implementation of <code>java.net.URLClassLoader</code>, classes are read from and written to the cache using the public Helper API. Therefore, any class loader that extends <code>java.net.URLClassLoader</code> gets class sharing support for free provided that it continues to use the methods in <code>java.net.URLClassLoader</code> to load classes. Custom class loaders that do not extend <code>java.net.URLClassLoader</code> must be adapted to share class data as described in Support for custom class loaders.</p>"},{"location":"shrc/#aot-code-and-jit-data","title":"AOT code and JIT data","text":"<p>OpenJ9 can automatically store small amounts of AOT code and JIT data, which helps improve performance in the following ways:</p> <ul> <li>The JIT compiler dynamically compiles certain methods into AOT code at runtime. Subsequent VMs that attach to the cache can take advantage of the compiled code to start faster.</li> <li>The JIT compiler stores profiling data and various compilation hints into the shared classes cache. This data enables subsequent VMs that attach to the cache to start faster, run faster, or both.</li> </ul> <p>The default settings provide significant performance benefits. However, you can specify options on the command line to configure AOT code storage or JIT data storage in the shared classes cache, as shown in the following table:</p> Component Setting a minimum storage value Setting a maximum storage value Turning off storage AOT code <code>-Xscminaot&lt;size&gt;</code> <code>-Xscmaxaot&lt;size&gt;</code> <code>-Xshareclasses:noaot</code> JIT data <code>-Xscminjitdata&lt;size&gt;</code> <code>-Xscmaxjitdata&lt;size&gt;</code> <code>-Xshareclasses:nojitdata</code> <p>The following cache utilities are available to adjust the storage values when a cache is active:</p> Component Adjusting the minimum storage value Adjusting the maximum storage value AOT code <code>-Xshareclasses:adjustminaot</code> <code>-Xshareclasses:adjustmaxaot</code> JIT code <code>-Xshareclasses:adjustminjit</code> <code>-Xshareclasses:adjustmaxjit</code> <p>You can also use the <code>-Xshareclasses:findAotMethods</code> cache utility to list the AOT methods in a cache that match a method specification. This utility helps you identify methods that are causing a failure in an application. You can then invalidate the method without destroying the cache by using the <code>-Xshareclasses:invalidateAotMethods</code> cache utility. You can also revalidate an AOT method with the <code>-Xshareclasses:revalidateAotMethods</code> cache utility. To troubleshoot AOT problems, use the <code>-Xshareclasses:verboseAOT</code> suboption on the command line, which generates output about AOT code that is found or stored in the cache. For more information see <code>-Xshareclasses</code>.</p>"},{"location":"shrc/#creating-a-shared-classes-cache","title":"Creating a shared classes cache","text":"<p>The -Xshareclasses option is highly configurable, allowing you to specify where to create the cache, how much space to allocate, and more. The following best practices apply to using class data sharing:</p> <ul> <li> <p>Before starting your application, use the <code>-Xshareclasses:listAllCaches</code> cache utility to review and maintain the existing caches on your system.</p> <p>This option lists all the caches that exist in the default directory, including compatible and incompatible caches. You can also specify the <code>cacheDir</code> suboption to look for caches in a specified directory. Remove any obsolete caches, as described in Housekeeping.</p> </li> <li> <p>If you are creating a new cache, set an application-specific cache name (<code>-Xshareclasses:name=&lt;name&gt;</code>).</p> <p>If a cache with the specified name doesn't already exist, a new cache is created.</p> <p>This avoids sharing your application cache with a cache that is enabled by default or with another application that doesn't set a name, and ensures that the size of your application cache can be set appropriately and that cache space is used exclusively for your application.</p> <p> Note: You cannot change the size of a default cache that already exists by using the <code>-Xscmx</code> option, as that option has no effect on a pre-existing cache.</p> </li> <li> <p>Set a specific cache directory (<code>-Xshareclasses:cacheDir=&lt;directory&gt;</code>).</p> <p>Set a cache directory that is specific to your application, to  avoid sharing the default cache directory with the default cache, or other application caches that don't set a cache directory. Your application will be unaffected by a user running <code>java -Xshareclasses:destroyAll</code>. Please do not set the cache directory on a NFS mount or a shared mount across systems or LPARs.</p> <p>In addition, if you have VMs from different Java installations, of the same Java release and installed by the same user, each VM checks whether the existing default shared cache in the cache directory is from the same Java installation as the VM. If not, the VM deletes that shared cache, then creates a new one. Specifying a different cache directory for each Java installation avoids this situation.</p> </li> <li> <p>Ensure that the cache directory permissions are set appropriately (<code>-Xshareclasses:cacheDirPerm</code>).</p> <p>It is good practice to explicitly set permissions for the cache directory when the defaults are not appropriate. Access is controlled by operating system permissions and Java security permissions; read/write access is the default only for the current user. On Unix systems, you can use the <code>-Xshareclasses:groupAccess</code> suboption to allow read/write permissions for groups as well as users.</p> <p>On z/OS, a cache can be accessed only by a VM that is running in the same storage key as the VM that created the cache. If the keys do not match, permission to access the cache is denied.</p> </li> <li> <p>Set the <code>-Xshareclasses:nonfatal</code> option.</p> <p>In most cases, setting this option allows your application to start even if there is a problem opening or creating the shared cache. The VM will continue to start without class data sharing.</p> </li> <li> <p>Set a soft maximum size for the cache by specifying the -Xscmx option with the <code>-XX:SharedCacheHardLimit</code> option.</p> <p>For example, you might create a 64 MB shared cache and set a smaller value, such as 16 MB, for the <code>-Xscmx</code> option, to limit the data stored in the cache (<code>-XX:SharedCacheHardLimit=64m -Xscmx16m</code>). You can then adjust the soft maximum size by using the <code>-Xshareclasses:adjustsoftmx</code> cache utility or the  <code>MemoryMXBean.setSharedClassCacheSoftmxBytes()</code> method in the <code>com.ibm.lang.management</code> API. For more information, see Setting a soft maximum size.</p> </li> </ul>"},{"location":"shrc/#creating-layer-caches","title":"Creating layer caches","text":"<p>Creating a layered cache might be useful when you are building a Docker image.</p> <p>Normally, writing to an existing shared cache in a lower image layer results in Docker duplicating the shared cache to the top layer (following the Docker copy-on-write strategy). With a layered cache, you can instead write into a new cache in the top layer. The new cache builds on the existing cache, so space is saved in the image.</p> The following example shows a Docker container with four layers: <p></p> <ol> <li>The lowest layer is a Ubuntu Docker image.</li> <li> <p>The next layer is an OpenJ9 Docker image that is built on the Ubuntu image. As part of this image, the <code>-Xshareclasses:name=MyCache</code> suboption is used to create a cache called <code>MyCache</code>. The layer number assigned to this cache is <code>0</code>. The <code>listAllCaches</code> suboption shows the cache and the layer number:</p> <pre><code>java -Xshareclasses:listAllCaches\n...\nCache name              level         cache-type      feature         layer       OS shmid       OS semid       last detach time\n\nCompatible shared caches\nMyCache                 Java8 64-bit  persistent      cr              0                                         Mon Sep 23 11:41:04 2019\n</code></pre> </li> <li> <p>The next Docker layer up is a middleware image that is built on the OpenJ9 image. As part of this image, the <code>-Xshareclasses:name=MyCache,layer=1</code> suboption is used to create another cache called <code>MyCache</code>. Because the <code>layer=1</code> suboption is specified, this new cache is a layered cache, which builds on <code>MyCache</code> in the previous container layer. (Open Liberty starts two VMs, so if you instead use the <code>createLayer</code> suboption here, two layered caches are created, with layer numbers of 1 and 2.) Note that cache layers are different from, and independent of, container layers.</p> </li> <li> <p>In the same way, another Docker layer is added for an application, and another layered cache is created to add to <code>MyCache</code>. The <code>listAllCaches</code> suboption now shows all the caches and their layers:</p> <pre><code>java -Xshareclasses:listAllCaches\n...\nCache name              level         cache-type      feature         layer       OS shmid       OS semid       last detach time\n\nCompatible shared caches\nMyCache                 Java8 64-bit  persistent      cr              0                                         Mon Sep 23 11:41:04 2019\nMyCache                 Java8 64-bit  persistent      cr              1                                         Mon Sep 23 11:46:25 2019\nMyCache                 Java8 64-bit  persistent      cr              2                                         In use\n</code></pre> </li> </ol> <p>The caches are created in the same directory.</p> <p>When you use the <code>-Xshareclasses:name=MyCache</code> suboption in future Java commands, all the caches are started. The top-layer cache is started in read/write mode, and lower-layer caches are started in read-only mode. Modifying a lower-layer cache will invalidate all the caches in the layers above.</p> <p>The following options and cache utilities are available for creating, managing, and removing layered caches:</p> <ul> <li><code>-Xshareclasses:createLayer</code></li> <li><code>-Xshareclasses:layer</code></li> <li><code>-Xshareclasses:printTopLayerStats</code> (for example output, see printTopLayerStats)</li> <li><code>-Xshareclasses:destroyAllLayers</code></li> </ul>"},{"location":"shrc/#saving-a-non-persistent-shared-classes-cache","title":"Saving a non-persistent shared classes cache","text":"<p>As described in an earlier section, a shared classes cache can be persistent or non-persistent; persistent caches are memory-mapped files. By default, a cache is persistent on all platforms, except z/OS. Non-persistent caches are stored in shared memory and are removed when a system is rebooted. If you want to save a non-persistent cache beyond a reboot, you might want to consider taking a cache snapshot.</p> <p>To create a snapshot of a non-persistent shared classes cache, use the <code>-Xshareclasses:snapshotCache</code> cache utility. The snapshot has the same name and location as the shared cache, as specified by the <code>name</code> and <code>cacheDir</code> suboptions. The shared cache can be in use when the snapshot is taken, but VMs are blocked when they try to write to the shared cache while the cache data is copied to the file.</p> <p>Typically, after a system is reinitialized, the snapshot file is used to restore the copy of the non-persistent cache into shared memory, by using the <code>-Xshareclasses:restoreFromSnapshot</code> cache utility. Because this process removes all non-persistent caches from shared memory, restoring the cache from the snapshot file can result in better VM startup performance, because the contents of the shared cache, including classes and AOT code, do not have to be re-created.</p> <p>The <code>-Xshareclasses:listAllCaches</code> cache utility can be used to identify snapshots on a system.</p> <p>A snapshot can be created only if the user has sufficient permissions to create the destination snapshot file. If a snapshot of the same name exists already, it is overwritten. On platforms that support persistent caches, the <code>nonpersistent</code> suboption must be specified in order to create a snapshot. For information about removing snapshot files, see the <code>destroySnapshot</code> and <code>destroyAllSnapshots</code> cache utilities in Housekeeping.</p> <p> Notes:</p> <ul> <li>Persistent caches are not supported on z/OS.</li> <li>The <code>snapshotCache</code> and <code>restoreFromCache</code> cache utilities cannot be used on Windows systems.</li> </ul>"},{"location":"shrc/#housekeeping","title":"Housekeeping","text":"<p>Caches can be deleted if they contain many stale classes or if the cache is full and you want to create a bigger cache. Use one of the following utilities to remove unwanted caches:</p> <ul> <li><code>-Xshareclasses:destroy</code>: Removes specific caches when used with the <code>name</code>, <code>cacheDir</code>, and <code>nonpersistent</code> suboptions.</li> <li><code>-Xshareclasses:destroyAll</code>: Removes all the caches that are specified by the <code>cacheDir</code> and <code>nonpersistent</code> suboptions.</li> <li><code>-Xshareclasses:destroySnapshot</code>: Removes a cache snapshot from disk that is specified by <code>name</code> and <code>cacheDir</code> suboptions.</li> <li><code>-Xshareclasses:destroyAllSnapshots</code>: Removes all cache snapshots from disk that are found by specifying the <code>cacheDir</code> suboption.</li> <li><code>-Xshareclasses:destroyAllLayers</code>: Removes all shared cache layers that are specified by the <code>name</code> and <code>cacheDir</code> suboptions.</li> </ul> <p> Note: You must always use the utilities to remove non-persistent caches correctly from shared memory.</p> <p>Caches can also be removed if they are unused for a specified amount of time. To configure time-based housekeeping, use the -Xshareclasses:expire option.</p> <p>If you want to remove a cache but allow it to be re-created when the VM restarts, use the <code>-Xshareclasses:reset</code> option.</p>"},{"location":"shrc/#support-for-custom-class-loaders","title":"Support for custom class loaders","text":"<p>Classes are shared by the bootstrap class loader internally in the VM. The OpenJ9 implementation of <code>java.net.URLClassLoader</code> is modified to use <code>SharedClassURLClasspathHelper</code> and any class loaders that extend <code>java.net.URLClassLoader</code> can inherit this behavior. If you are using a custom class loader that does not extend <code>java.net.URLClassLoader</code>, you can use the Java Helper API to find and store classes in a shared classes cache.</p> <p>If a running application uses its own class loader and you are using a <code>SecurityManager</code>, you must grant the class loader permission to <code>SharedCachePermission</code> before they can share classes. To grant permission, add shared class permissions to the <code>java.policy</code> file by specifying the <code>ClassLoader</code> class name. Permissions can be set for <code>read</code>, <code>write</code>, or <code>read,write</code>. For example:</p> <pre><code>permission com.ibm.oti.shared.SharedClassPermission\n        \"com.abc.customclassloaders.*\", \"read,write\";\n</code></pre> <p>If a running application is calling the <code>com.ibm.oti.shared.SharedClassUtilities</code> APIs <code>getSharedCacheInfo()</code> or <code>destroySharedCache()</code>, you must also grant the code calling these APIs the appropriate <code>SharedClassesNamedPermission</code>. For example:</p> <pre><code>permission com.ibm.oti.shared.SharedClassesNamedPermission \"getSharedCacheInfo\";\npermission com.ibm.oti.shared.SharedClassesNamedPermission \"destroySharedCache\";\n</code></pre>"},{"location":"shrc/#the-java-shared-classes-helper-api","title":"The Java shared classes Helper API","text":"<p>The Java Helper API classes can be found in the <code>com.ibm.oti.shared</code> package.</p> <p>Each class loader that wants to share classes must get a <code>SharedClassHelper</code> object from a <code>SharedClassHelperFactory</code>. The <code>SharedClassHelper</code>, when created, has a one to one relationship with the class loader. That is, it belongs to the class loader that requested it and can only store classes defined by that class loader. The <code>SharedClassHelper</code> gives the class loader a simple API for finding and storing classes in the class cache to which the VM is connected. If the class loader is garbage collected, its <code>SharedClassHelper</code> is also garbage collected.</p> <p>The following main functions are available from the <code>SharedClassHelper</code> API:</p> <ul> <li><code>findSharedClass</code>: Used to check whether a class is already in the cache before looking for the class on the file system.</li> <li><code>storeSharedClass</code>: Used to store a class in the cache.</li> <li><code>setSharingFilter</code>: A filter that can be used to decide which classes are found and stored in the cache. This filter can be applied to a particular package by implementing the <code>SharedClassFilter</code> interface. To apply a filter to all non-bootstrap class loaders that share classes, specify the <code>-Dcom.ibm.oti.shared.SharedClassGlobalFilterClass</code> system property on the command line.</li> </ul> <p>You can also define partitions in a cache to store sets of classes separately from one another. For more information see <code>SharedClassHelper</code> cache partitions.</p> <p>Each class loader that wants to share data must get a <code>SharedDataHelper</code> object from a <code>SharedDataHelperFactory</code>. A <code>SharedDataHelperFactory</code> provides an interface that can be used to create <code>SharedDataHelpers</code>, which are used for storing Java byte array data. A <code>SharedDataHelper</code> also has a one to one relationship with a class loader, although a class loader can exist without a <code>SharedDataHelper</code>.</p>"},{"location":"shrc/#the-java-shared-classes-utility-api","title":"The Java shared classes utility API","text":"<p>The following APIs are available for obtaining information about a shared classes cache:</p> <ul> <li><code>com.ibm.oti.shared.SharedClassStatistics</code>: Obtains information about cache size, including free space, soft maximum limit, and the limits enforced for AOT and JIT data.</li> <li><code>com.ibm.oti.shared.SharedClassUtilities</code>: Obtains detailed information about a shared classes cache, including its size, name, type, and status.</li> <li><code>com.ibm.oti.shared.SharedClassCacheInfo</code>: Stores information about a shared classes cache and provides API methods to retrieve the information and remove caches. You can also use the <code>IterateSharedCaches</code> and <code>DestroySharedCache</code> JVMTI extensions.</li> </ul>"},{"location":"shrc/#support-for-bytecode-instrumentation","title":"Support for bytecode instrumentation","text":"<p>Modifying the bytecode of a set of classes at runtime is a useful mechanism for adding functions to a program, such as profiling or debugging. The JVM Tools Interface (JVMTI) includes hooks that allow you to instrument the byte code in this way. Alternatively, you can write your own Java agent that uses the <code>java.lang.instrument</code> API. Sharing classes that are changed before they are loaded adds complexity to the class sharing process.</p> <p>By default, if OpenJ9 detects that a JVMTI agent or <code>java.lang.instrument</code> agent has registered to modify class bytes, modified classes are not stored in the cache. Instead, the VM stores original class byte data in the cache, which allows classes to be retransformed.</p> <p>If you turn off bytecode instrumentation support by specifying <code>-Xshareclasses:disableBCI</code> and do not use a modification context to share modified classes safely, all bytecode is loaded from the file system for the agent to modify. When passed to the cache for storing, the VM compares the bytes with known classes of the same name. If a match is found, the class is reused. However, if a match is not found, the potentially modified class is stored in the cache in a way that prevents other VMs from loading it. In this situation, performance can be affected because the bytecode is always loaded from the file system and compared with existing classes in the cache. When bytecode instrumentation is turned off, classes loaded from the shared cache cannot be retransformed. For more information about using a modification context, see Sharing modified bytecode.</p>"},{"location":"shrc/#redefined-and-retransformed-classes","title":"Redefined and retransformed classes","text":"<p>The following rules exist for classes that are redefined or retransformed by JVMTI or <code>java.lang.instrument</code> agents:</p> <ul> <li> <p>Redefined classes contain replacement bytecode that is provided by an agent at run time by using the JVMTI <code>RedefineClasses</code> or <code>Instrumentation.redefineClasses</code> function. A typical use case is for debugging, where function is added for log output. These classes are never stored in the cache.</p> </li> <li> <p>Retransformed classes contain bytecode that can be changed without any reference to the original bytecode by using the JVMTI <code>RetransformClasses</code> or <code>Instrumentation.retransformClasses</code> functions. A typical use case is a profiling agent that adds or removes profiling calls with each retransformation. These classes can be modified multiple times and are not stored in the cache by default. If you want to store these modified classes for reuse, you can do so by setting the <code>-Xshareclasses:cacheRetransformed</code> suboption when you start your application. This option turns off bytecode instrumentation support, forcing cache creation into <code>-Xshareclasses:disableBCI</code> mode.</p> </li> </ul>"},{"location":"shrc/#sharing-modified-bytecode","title":"Sharing modified bytecode","text":"<p>Sharing modified bytecode can be advantageous for applications that use the same modifications because the transformation process needs to happen only once. OpenJ9 allows multiple VMs that are using the same or different types of class modifications to safely share the cache. However, when a class is modified and cached, it cannot be modified (retransformed) further.</p> <p>Modified bytecode can be shared safely by using a modification context. Use the <code>-Xshareclasses:disableBCI</code> and <code>-Xshareclasses:modified=&lt;modified_context&gt;</code> suboptions when you start your application, where <code>&lt;modified_context&gt;</code> is a user-defined description. The cache is structured so that any VM that is started with the same modification context can share the classes in a private area. The following outcomes apply to VMs that do not want to share the modified classes:</p> <ul> <li>A VM that is started without specifying a modification context shares classes outside of that area as normal.</li> <li>A VM that is started with a different modification context, shares classes in its own private area.</li> </ul>"},{"location":"shrc/#sharedclasshelper-cache-partitions","title":"<code>SharedClassHelper</code> cache partitions","text":"<p>Another method of structuring and protecting classes in the shared classes cache can be implemented by using the <code>SharedClassHelper</code> API with a custom class loader. This mechanism creates partitions by using a string key to identify a set of classes, which can be stored and retrieved by the class loader. A use case for this mechanism is Aspect Oriented Programming (AOP) where aspects are woven in to bytecode when a class is loaded into the VM. Being able to partition the cache provides a suitable level of granularity when you want to use different aspect paths.</p> <p>Although it is possible to combine partitions and modification contexts, this practice is not recommended because the cache will contain partitions within partitions.</p> <p> Note: Partitions are not supported by the bootstrap class loader or the default application class loader.</p>"},{"location":"shrc/#see-also","title":"See also","text":"<ul> <li>AOT compiler</li> <li>Class sharing article</li> <li>Diagnosing problems with class data sharing</li> </ul>"},{"location":"shrc_diag_util/","title":"Diagnosing problems","text":""},{"location":"shrc_diag_util/#diagnosing-problems-with-class-data-sharing","title":"Diagnosing problems with class data sharing","text":"<p>If you encounter problems with class data sharing, VM messages are typically generated that point to an underlying cause. In some situations, a cache might fail to initialize correctly. In other situations classes might not be found or stored in the shared classes cache. To provide more information about a problem, you can generate verbose output, use diagnostic cache utilities, or use the Eclipse OpenJ9\u2122 trace facility.</p>"},{"location":"shrc_diag_util/#initialization-problems","title":"Initialization problems","text":"<p>If you do not specify a directory for the shared classes cache by using the <code>cacheDir</code> suboption, the cache is created in the <code>javasharedresources</code> directory in the following default location:</p> <ul> <li>On Windows\u00ae systems, this directory is created in the user's <code>C:\\Users\\&lt;username&gt;\\AppData\\Local\\</code> directory.</li> <li>On z/OS\u00ae systems, this directory is created in the <code>/tmp</code> directory.</li> <li>On other systems, this directory is located in the <code>.cache</code> directory in the user's home directory. Do not set the user's home directory on an NFS mount or a shared mount across systems or LPARs.</li> </ul> <p>Initialization problems can occur on systems other than Windows because caches are created with read/write access for the user only and subsequent users do not have permission to write to the home directory. If you specify the <code>-Xshareclasses:groupAccess</code> suboption, the cache is created in the <code>/tmp</code> directory instead where all users have permission to write to the cache.</p> <p>For a persistent cache, initialization problems can also occur if there is insufficient disk space available or if you are attempting to locate the cache on a remote networked file system, which is not supported.</p> <p>For a non-persistent cache, a shared memory area is required. Check that your system is configured with sufficient resources as described in Setting shared memory values. If initialization problems persist, try deleting the cache by using the <code>-Xshareclasses:destroyAll</code> cache utility, which removes all known shared memory areas and semaphores for caches in the <code>cacheDir</code> specified or the default directory. These actions force the VM to re-create the cache.</p>"},{"location":"shrc_diag_util/#problems-finding-or-storing-classes","title":"Problems finding or storing classes","text":"<p>The most common cause for classes not being stored in the cache is due to space constraints. Make sure that you set an appropriate size for the cache, as described in Creating a shared classes cache. Setting a soft maximum size is recommended, because you can adjust the soft maximum size that is set for the cache after it is created. See Setting a soft maximum size.</p> <p>Storing classes can also be a problem if the cache is opened read-only or if the class does not exist on the file system because it is sourced from a URL location.</p> <p>If you are attempting to share modified bytecode, you must use a modification context, as described in Sharing modified bytecode. Otherwise, classes are stored in a private area that is not accessible to other VMs.</p> <p>If you are using a custom class loader, class path entries in the <code>SharedClassURLClasspathHelper</code> must be confirmed before classes can be found for these entries. More information about confirmed entries is available in the <code>SharedClassURLClasspathHelper</code> interface in the <code>com.ibm.oti.shared</code> API documentation.</p> <p>If you are instrumenting bytecode by using a JVMTI agent or <code>java.lang.instrument</code> agent, the following rules apply:</p> <ul> <li>Redefined classes are never stored in the cache.</li> <li>Retransformed classes are stored only if you specify the <code>-Xshareclasses:cacheRetransformed</code> suboption when you start your application.</li> </ul> <p>If a running application uses its own class loader and you are using a <code>SecurityManager</code>, you must grant the class loader permission to <code>SharedCachePermission</code> before they can share classes. For more information, see Support for custom class loaders.</p> <p>In very rare cases, problems with finding or storing classes might be due to cache corruption. If the VM detects that a cache is corrupt, it attempts to destroy the cache and re-create it. If the VM cannot re-create the cache, it starts only if the <code>-Xshareclasses:nonfatal</code> suboption is specified on the command line, but without using the shared cache. Try using the <code>-Xshareclasses:destroy</code> cache utility to remove the specific cache and re-create it. You might need to specify the <code>cacheDir=&lt;directory&gt;</code> and <code>name=&lt;cache_name&gt;</code> suboptions if the cache is not using the default settings.</p>"},{"location":"shrc_diag_util/#generating-verbose-output","title":"Generating verbose output","text":"<p>A number of <code>-Xshareclasses</code> suboptions are available for generating verbose output during class data sharing operations, which can help you identify the root cause of a problem.</p>"},{"location":"shrc_diag_util/#verbose","title":"<code>verbose</code>","text":"<p>The <code>-Xshareclasses:verbose</code> suboption provides basic output on cache usage. In the following example, a persistent cache is opened and attached to the VM for class sharing. Information is provided about the size of the cache, the unstored bytes due to the setting of a soft maximum size, and maximum AOT and JIT data size.</p> <pre><code>java -Xshareclasses:name=myCache,verbose HelloWorld\n[-Xshareclasses persistent cache enabled]\n[-Xshareclasses verbose output enabled]\nJVMSHRC237I Opened shared classes persistent cache myCache\nJVMSHRC246I Attached shared classes persistent cache myCache\nJVMSHRC765I Memory page protection on runtime data, string read-write data and partially filled pages is successfully enabled\nHello World\nJVMSHRC168I Total shared class bytes read=2532416. Total bytes stored=268156\nJVMSHRC818I Total unstored bytes due to the setting of shared cache soft max is 0. Unstored AOT bytes due to the setting of -Xscmaxaot is 0. Unstored JIT bytes due to the setting of -Xscmaxjitdata is 0.\n\n</code></pre>"},{"location":"shrc_diag_util/#verboseio","title":"<code>verboseIO</code>","text":"<p>The <code>-Xshareclasses:verboseIO</code> suboption provides more detailed information about class sharing operations. In the following example, some classes are found when the cache is accessed. However, class <code>openj9/internal/tools/attach/target/CommonDirectory</code> is not found and is therefore stored for sharing.</p> <pre><code>java -Xshareclasses:name=myCache,verboseIO HelloWorld\n[-Xshareclasses verbose I/O output enabled]\nFound class java/lang/Object in shared cache for class-loader id 0.\nFound class java/lang/J9VMInternals in shared cache for class-loader id 0.\nFound class com/ibm/oti/vm/VM in shared cache for class-loader id 0.\nFound class java/lang/J9VMInternals$ClassInitializationLock in shared cache for class-loader id 0.\n...\nFailed to find class openj9/internal/tools/attach/target/CommonDirectory in shared cache for class-loader id 0.\nStored class openj9/internal/tools/attach/target/CommonDirectory in shared cache for class-loader id 0 with URL /root/sdk/jre/lib/amd64/compressedrefs/jclSC180/vm.jar (index 0).\n...\n</code></pre> <p>The bootstrap class loader has an ID of <code>0</code>; other class loaders are given a unique ID. Class loaders follow the class loader hierarchy by asking the parent class loader for a class. If a parent fails to find the class in the cache, the child class loader stores the class in the cache.</p> <p>In some situations, verbose output might not show classes being found. For example, classes are typically not found if the class is stale, as described in Class data sharing operations. Stale classes are redeemed if the same class is subsequently fetched by the class loader from another VM and checked against the stale class in the cache.</p>"},{"location":"shrc_diag_util/#verboseaot","title":"<code>verboseAOT</code>","text":"<p>To troubleshoot AOT problems, use the <code>-Xshareclasses:verboseAOT</code> suboption on the command line, which generates output about AOT code that is found or stored in the cache.</p> <p>In the following example output, a populated cache is being accessed to look for compiled AOT code. Some AOT code is found, which can be shared, and some AOT code is stored for reuse.</p> <pre><code>java -Xshareclasses:name=myCache,verboseAOT HelloWorld\n[-Xshareclasses AOT verbose output enabled]\nFound AOT code for ROMMethod 0x00007F658005C180 in shared cache.\nFound AOT code for ROMMethod 0x00007F65800723EC in shared cache.\nFound AOT code for ROMMethod 0x00007F6580071D14 in shared cache.\nStored AOT code for ROMMethod 0x00007F65801847B8 in shared cache.\nStored AOT code for ROMMethod 0x00007F65800D38A4 in shared cache.\nStored AOT code for ROMMethod 0x00007F65800723CC in shared cache.\nFound AOT code for ROMMethod 0x00007F65800D38A4 in shared cache.\nStored AOT code for ROMMethod 0x00007F65800724C4 in shared cache.\n...\n</code></pre>"},{"location":"shrc_diag_util/#verbosehelper","title":"<code>verboseHelper</code>","text":"<p>To troubleshoot problems with custom class loaders that use the Java <code>SharedClassHelper</code> API, specify the <code>-Xshareclasses:verboseHelper</code> suboption. Information messages and error messages are generated in the output, which can help you diagnose problems with finding or storing classes in the shared cache.</p> <p>The following example output shows only information messages:</p> <pre><code>java -Xshareclasses:name=myCache,verboseHelper HelloWorld\n[-Xshareclasses Helper API verbose output enabled]\nInfo for SharedClassURLClasspathHelper id 1: Verbose output enabled for SharedClassURLClasspathHelper id 1\nInfo for SharedClassURLClasspathHelper id 1: Created SharedClassURLClasspathHelper with id 1\nInfo for SharedClassURLClasspathHelper id 2: Verbose output enabled for SharedClassURLClasspathHelper id 2\nInfo for SharedClassURLClasspathHelper id 2: Created SharedClassURLClasspathHelper with id 2\nInfo for SharedClassURLClasspathHelper id 1: There are no confirmed elements in the classpath. Returning null.\nInfo for SharedClassURLClasspathHelper id 2: There are no confirmed elements in the classpath. Returning null.\nInfo for SharedClassURLClasspathHelper id 2: setClasspath() updated classpath. No invalid URLs found\nInfo for SharedClassURLClasspathHelper id 2: Number of confirmed entries is now 1\nHello World\n</code></pre>"},{"location":"shrc_diag_util/#diagnostic-cache-utilities","title":"Diagnostic cache utilities","text":"<p>These utilities display information about the contents of a shared classes cache. Run the utilities by specifying them as suboptions of <code>-Xshareclasses</code>. The utilities run on the default cache unless you specify a cache by adding the <code>name=&lt;cache_name&gt;</code> and <code>cacheDir=&lt;directory&gt;</code> suboptions.</p>"},{"location":"shrc_diag_util/#printstats","title":"<code>printStats</code>","text":"<pre><code>-Xshareclasses:printStats\n-Xshareclasses:printStats,name=&lt;cache_name&gt;\n-Xshareclasses:printStats=&lt;data_type1&gt;[+&lt;data_type2&gt;][...],name=&lt;cache_name&gt;\n</code></pre> <p>Displays summary information about the cache. For layered caches, <code>-Xshareclasses:printStats</code> shows some information for the top layer cache, and summary information (bytes and counts only) for all layers combined. To see information for the top layer cache only, use <code>printTopLayerStats</code>.</p> <p>You can request more detail about items of a specific data type that are stored in the shared cache by using <code>printStats=&lt;data_type&gt;</code>. Use the plus symbol (+) to separate the data types. For example, use <code>printStats=romclass+url,name=myCache</code> to see information about <code>ROMClass</code> and <code>URL</code> items in all the layer caches of the cache called <code>Cache1</code>. The valid data types are as follows (case insensitive):</p> <ul> <li><code>help</code> (displays the list of valid data types)</li> <li><code>all</code> (equivalent to <code>printAllStats</code>)</li> <li><code>classpath</code></li> <li><code>url</code></li> <li><code>token</code></li> <li><code>romclass</code></li> <li><code>rommethod</code></li> <li><code>aot</code></li> <li><code>jitprofile</code></li> <li><code>jithint</code></li> <li><code>zipcache</code></li> <li><code>stale</code></li> <li><code>startuphint</code></li> </ul> <p>Example output for a traditional cache (no cache layers: <code>cache layer = 0</code>), with summary information only:</p> <pre><code>Current statistics for cache \"Cache1\":\n\nCache created with:\n        -Xnolinenumbers                      = false\n        BCI Enabled                          = true\n        Restrict Classpaths                  = false\n        Feature                              = cr\n\nCache contains only classes with line numbers\n\nbase address                         = 0x00007F60B807A000\nend address                          = 0x00007F60B905E000\nallocation pointer                   = 0x00007F60B81BE3A8\n\ncache layer                          = 0\ncache size                           = 16776608\nsoftmx bytes                         = 16776608\nfree bytes                           = 12740572\nReserved space for AOT bytes         = -1\nMaximum space for AOT bytes          = -1\nReserved space for JIT data bytes    = -1\nMaximum space for JIT data bytes     = -1\nMetadata bytes                       = 30440\nMetadata % used                      = 0%\nClass debug area size                = 1331200\nClass debug area used bytes          = 189358\nClass debug area % used              = 14%\n\nROMClass bytes                       = 1328040\nAOT bytes                            = 98404\nJIT data bytes                       = 168\nZip cache bytes                      = 1133704\nStartup hint bytes                   = 0\nData bytes                           = 114080\n\n# ROMClasses                         = 452\n# AOT Methods                        = 2\n# Classpaths                         = 1\n# URLs                               = 0\n# Tokens                             = 0\n# Zip caches                         = 21\n# Startup hints                      = 0\n# Stale classes                      = 0\n% Stale classes                      = 0%\n\n\nCache is 24% full\n\nCache is accessible to current user = true\n</code></pre> <p>Example output for a cache with 2 layers (<code>cache layer = 1</code>), with summary information only:</p> <pre><code>Current statistics for top layer of cache \"Cache1\":\n\nCache created with:\n        -Xnolinenumbers                      = false\n        BCI Enabled                          = true\n        Restrict Classpaths                  = false\n        Feature                              = cr\n\n\nbase address                         = 0x00007FCAB2766000\nend address                          = 0x00007FCAB374A000\nallocation pointer                   = 0x00007FCAB2766000\n\ncache layer                          = 1\ncache size                           = 16776608\nsoftmx bytes                         = 16776608\nfree bytes                           = 15299372\nReserved space for AOT bytes         = -1\nMaximum space for AOT bytes          = -1\nReserved space for JIT data bytes    = -1\nMaximum space for JIT data bytes     = -1\nClass debug area size                = 1331200\nClass debug area used bytes          = 0\nClass debug area % used              = 0%\n\nCache is 8% full\n\nCache is accessible to current user = true\n---------------------------------------------------------\n\nCurrent statistics for all layers of cache \"Cache1\":\n\nROMClass bytes                       = 1328040\nAOT bytes                            = 128924\nJIT data bytes                       = 812\nZip cache bytes                      = 1133704\nStartup hint bytes                   = 0\nData bytes                           = 114080\n\n# ROMClasses                         = 452\n# AOT Methods                        = 20\n# Classpaths                         = 1\n# URLs                               = 0\n# Tokens                             = 0\n# Zip caches                         = 21\n# Startup hints                      = 0\n# Stale classes                      = 0\n% Stale classes                      = 0%\n</code></pre> <p>The <code>Cache created with</code> section indicates the options that were used when the cache was created. <code>BCI Enabled</code> relates to the <code>-Xshareclasses:enableBCI</code> option (enabled by default) and <code>Restrict Classpaths</code> relates to the <code>-Xshareclasses:restrictClasspaths</code> option. <code>Feature = cr</code> indicates that the cache is a 64-bit compressed references cache.</p> <p>Line number information for classes in the cache is then shown with one of the following messages:</p> <ul> <li><code>Cache contains only classes with line numbers</code> : VM line number processing was enabled for all the classes that were stored in this shared cache (the <code>-Xlinenumbers</code> option is enabled by default). All classes in the cache contain line numbers if the original classes contained line number data.</li> <li><code>Cache contains only classes without line numbers</code> : The <code>-Xnolinenumbers</code> option was used to disable VM line number processing for all the classes that were stored in this shared cache, so none of the classes contain line numbers.</li> <li><code>Cache contains classes with line numbers and classes without line numbers</code> : VM line number processing was enabled for some classes and disabled for others (the <code>-Xnolinenumbers</code> option was specified when some of the classes were added to the cache).</li> </ul> <p>The following summary data is displayed:</p> <ul> <li><code>baseAddress</code> and <code>endAddress</code><ul> <li>The boundary addresses of the shared memory area that contains the classes. These addresses vary from run to run, depending on where the operating system allocates the memory.</li> </ul> </li> <li><code>allocation pointer</code><ul> <li>The address where <code>ROMClass</code> data is currently being allocated in the cache.</li> </ul> </li> <li><code>cache layer</code><ul> <li>The layer number that the cache stats relate to.</li> </ul> </li> <li><code>cache size</code> and <code>free bytes</code><ul> <li><code>cache size</code> shows the total size of the shared memory area in bytes</li> <li><code>free bytes</code> shows the free bytes that remain. The free space is not necessarily all available for storing new classes. The cache contains separate areas for different data, and can reserve space for AOT and JIT data, as shown by subsequent summary data.</li> </ul> </li> <li><code>softmx bytes</code><ul> <li>The soft maximum size for the cache. For more information, see <code>-Xscmx</code>.</li> </ul> </li> <li><code>ROMClass bytes</code><ul> <li>The number of bytes of class data in the cache, which does not include data that is stored in the class debug area (see separate output for the class debug area).</li> </ul> </li> <li><code>AOT bytes</code><ul> <li>The number of bytes of AOT-compiled code in the cache.</li> </ul> </li> <li><code>Reserved space for AOT bytes</code><ul> <li>The number of bytes reserved for AOT-compiled code in the cache.</li> </ul> </li> <li><code>Maximum space for AOT bytes</code><ul> <li>The maximum number of bytes of AOT-compiled code that can be stored in the cache.</li> </ul> </li> <li><code>JIT data bytes</code><ul> <li>The number of bytes of JIT-related data stored in the cache.</li> </ul> </li> <li><code>Reserved space for JIT data bytes</code><ul> <li>The number of bytes reserved for JIT-related data in the cache.</li> </ul> </li> <li><code>Maximum space for JIT data bytes</code><ul> <li>The maximum number of bytes of JIT-related data that can be stored in the cache.</li> </ul> </li> <li><code>Zip cache bytes</code><ul> <li>The number of zip entry cache bytes stored in the cache. On Java 11 and later, this value is zero unless a <code>jar</code> file is added to the boot classpath.</li> </ul> </li> <li><code>Startup hint bytes</code><ul> <li>The number of bytes of data stored to describe startup hints.</li> </ul> </li> <li><code>Data bytes</code><ul> <li>The number of bytes of non-class data stored by the VM.</li> </ul> </li> <li><code>Metadata bytes</code><ul> <li>The number of bytes of data stored to describe the cached classes.  Note: This field is available only in the top layer cache output or when a cache is not layered.</li> </ul> </li> <li><code>Metadata % used</code><ul> <li>The proportion of metadata bytes to class bytes, which indicates how efficiently cache space is being used. The value shown does consider the <code>Class debug area size</code>.</li> </ul> </li> <li><code>Class debug area size</code><ul> <li>The size in bytes of the class debug area. This area is reserved to store <code>LineNumberTable</code> and <code>LocalVariableTable</code> class attribute information.</li> </ul> </li> <li><code>Class debug area bytes used</code><ul> <li>The size in bytes of the Class Debug Area that contains data.</li> </ul> </li> <li><code>Class debug area % used</code><ul> <li>The percentage of the Class Debug Area that contains data.</li> </ul> </li> <li><code>ROMClasses</code><ul> <li>The number of classes in the cache. The cache stores <code>ROMClasses</code> (the class data itself, which is read-only) and information about the location from which the classes were loaded. This information is stored in different ways, depending on the Java <code>SharedClassHelper</code> API that was used to store the classes. For more information, see Support for custom class loaders.</li> </ul> </li> <li><code>AOT methods</code><ul> <li>Optionally, <code>ROMClass</code> methods can be compiled and the AOT code stored in the cache. The <code>AOT methods</code> information shows the total number of methods in the cache that have AOT code compiled for them. This number includes AOT code for stale classes.</li> </ul> </li> <li><code>Classpaths</code>, <code>URLs</code>, and <code>Tokens</code><ul> <li>The number of class paths, URLs, and tokens in the cache. Classes stored from a <code>SharedClassURLClasspathHelper</code> are stored with a Classpath. Classes stored using a <code>SharedClassURLHelper</code> are stored with a URL. Classes stored using a <code>SharedClassTokenHelper</code> are stored with a Token. Most class loaders, including the bootstrap and application class loaders, use a <code>SharedClassURLClasspathHelper</code>. The result is that it is most common to see class paths in the cache.</li> <li>The number of Classpaths, URLs, and Tokens stored is determined by a number of factors. For example, every time an element of a Classpath is updated, such as when a <code>.jar</code> file is rebuilt, a new Classpath is added to the cache. Additionally, if partitions or modification contexts are used, they are associated with the Classpath, URL, or Token. A Classpath, URL, or Token is stored for each unique combination of partition and modification context. For more information, see Sharing modified bytecode and <code>SharedClassHelper</code> cache partitions.</li> </ul> </li> <li><code>Zip caches</code><ul> <li>The number of <code>.zip</code> files that have entry caches stored in the shared cache. On Java 11 and later, this value is zero unless a <code>jar</code> file is added to the boot classpath.</li> </ul> </li> <li><code>Startup hints</code><ul> <li>The number of startup hints stored in the cache. There can be a startup hint for each unique set of command line options used to start the VM.</li> </ul> </li> <li><code>Stale classes</code><ul> <li>The number of classes that have been marked as \"potentially stale\" by the cache code, because of a VM or Java application update. See Class data sharing operations.</li> </ul> </li> <li><code>% Stale classes</code><ul> <li>The percentage of classes in the cache that are stale.</li> </ul> </li> <li><code>Cache is XXX% full</code><ul> <li>The percentage of the cache that is currently used. This line is displayed only if the soft maximum size is not set. This value is calculated as follows:<ul> <li><code>% Full = (('Cache Size' - 'Free Bytes') * 100) / ('Cache Size')</code></li> </ul> </li> </ul> </li> <li><code>Cache is XXX% soft full</code><ul> <li>The percentage of the soft maximum size that is currently used. This line is displayed only if the soft maximum size is set. The <code>free bytes</code> in the cache statistics means the free bytes within the soft maximum limit. This value is calculated as follows:<ul> <li><code>% soft Full = (('Soft max bytes' - 'Free Bytes') * 100) / ('Soft max  bytes')</code></li> </ul> </li> <li>For more information about the soft maximum size, see <code>-Xscmx</code>.</li> </ul> </li> <li><code>Cache is accessible to current user</code><ul> <li>Whether the current user can access the cache.</li> </ul> </li> </ul>"},{"location":"shrc_diag_util/#printallstats","title":"<code>printAllStats</code>","text":"<pre><code>-Xshareclasses:printAllStats\n-Xshareclasses:printAllStats,name=&lt;cache_name&gt;\n</code></pre> <p>Displays the contents of the cache in chronological order. You can use this output to see the history of updates that were made to the cache. For layered caches, some information is shown for the top layer cache only, and some is shown for all layers combined. To see information for the top layer cache only, use <code>printTopLayerStats=all</code>.</p> <p>Each entry in the output starts with a VM ID, so you can see which VM wrote the associated data. Here are example entries for various types of cache data, with explanations:</p>"},{"location":"shrc_diag_util/#class-paths","title":"Class paths","text":"<p>The following example shows one class path with 4 entries:</p> <pre><code>    1: 0x2234FA6C CLASSPATH\n            /myVM/Apps/application1.jar\n            /myVM/Apps/application2.jar\n            /myVM/Apps/application3.jar\n            /myVM/Apps/application4.jar\n</code></pre> <ul> <li><code>1</code>: the ID of the VM that wrote this data.</li> <li><code>0x2234FA6C</code>: the address where this data is stored.</li> <li><code>CLASSPATH</code>: the type of data that was written.</li> </ul>"},{"location":"shrc_diag_util/#romclasses","title":"ROMClasses","text":"<p>This example shows an entry for a single <code>ROMClass</code>:</p> <pre><code>    1: 0x2234F7DC ROMCLASS: java/lang/Runnable at 0x213684A8\n            Index 1 in class path 0x2234FA6C\n</code></pre> <ul> <li><code>1</code>: the ID of the VM that wrote this data.</li> <li><code>0x2234F7DC</code>: the address where the metadata about the class is stored.</li> <li><code>ROMCLASS</code>: the type of data that was stored.</li> <li><code>java/lang/Runnable</code>: the name of the class.</li> <li><code>0x213684A8</code>: the address where the class was stored.</li> <li><code>Index 1</code>: the index in the class path where the class was loaded from.</li> <li><code>0x2234FA6C</code>: the address of the class path against which this class is stored.</li> </ul> <p>Stale classes are marked with <code>!STALE!</code>. Any partition or modification context that is used when the class is stored is also shown.</p>"},{"location":"shrc_diag_util/#aot-methods","title":"AOT methods","text":"<p>This example shows an entry for one AOT-compiled method:</p> <pre><code>    1: 0x00007F841A800554 AOT: hashCode Signature: ()I Address: 0x00007F83F6859280\n            for ROMClass java/lang/Object at 0x00007F83F6859000.\n</code></pre> <ul> <li><code>1</code>: the ID of the VM that wrote this data.</li> <li><code>0x00007F841A800554</code>: the address where the data is stored.</li> <li><code>AOT</code>: the type of data that was stored.</li> <li><code>hashCode</code>: the method for which AOT-compiled code is stored.</li> <li><code>()I</code>: the signature of the ROM method.</li> <li><code>0x00007F83F6859280</code>: the ROM method address.</li> <li><code>java/lang/Object</code>: the class that contains the method.</li> <li><code>0x00007F83F6859000</code>: the address of the class that contains the method.</li> </ul> <p>Stale methods are marked with <code>!STALE!</code>.</p>"},{"location":"shrc_diag_util/#urls-and-tokens","title":"URLs and tokens","text":"<p>The output for these data types has the same format as that for class paths, but with a single entry. A <code>Token</code> is a string that is passed to the Java <code>SharedClassHelper</code> API.</p>"},{"location":"shrc_diag_util/#zip-entry-caches","title":"Zip entry caches","text":"<p>The following example shows 4 separate entries for zip entry caches:</p> <pre><code>    1: 0x042FE07C ZIPCACHE: luni-kernel.jar_347075_1272300300_1 Address: 0x042FE094 Size: 7898\n    1: 0x042FA878 ZIPCACHE: luni.jar_598904_1272300546_1 Address: 0x042FA890 Size: 14195\n    1: 0x042F71F8 ZIPCACHE: nio.jar_405359_1272300546_1 Address: 0x042F7210 Size: 13808\n    1: 0x042F6D58 ZIPCACHE: annotation.jar_13417_1272300554_1 Address: 0x042F6D70 Size: 1023\n</code></pre> <ul> <li><code>1</code> : the ID of the VM that wrote this data.</li> <li><code>0x042FE07C</code> : the address where the metadata for the zip entry cache is stored.</li> <li><code>ZIPCACHE</code> : the type of data that was stored.</li> <li><code>luni-kernel.jar_347075_1272300300_1</code> : the name of the zip entry cache.</li> <li><code>0x042FE094</code> : the address where the data is stored.</li> <li><code>7898</code> : the size of the stored data, in bytes.</li> </ul>"},{"location":"shrc_diag_util/#jit-data","title":"JIT data","text":"<p>Information about JIT data is shown in <code>JITPROFILE</code> and <code>JITHINT</code> entries. For example:</p> <pre><code>    1: 0xD6290368 JITPROFILE: getKeyHash Signature: ()I Address: 0xD55118C0\n    for ROMClass java/util/Hashtable$Entry at 0xD5511640.\n    2: 0xD6283848 JITHINT: loadClass Signature: (Ljava/lang/String;)Ljava/lang/Class; Address: 0xD5558F98\n    for ROMClass com/ibm/oti/vm/BootstrapClassLoader at 0xD5558AE0.\n</code></pre>"},{"location":"shrc_diag_util/#startup-hints","title":"Startup hints","text":"<p>Information about startup hints is shown in <code>STARTUP HINTS KEY</code> and <code>STARTUP HINTS DETAIL</code>. For example:</p> <pre><code>    1: 0x000000002237C6E0 STARTUP HINTS KEY: -Xoptionsfile=jre\\bin\\compressedrefs\\options.default -Xlockword:mode=default -Xjcl:jclse29 -Dcom.ibm.oti.vm.bootstrap.library.path=jre\\bin\\compressedrefs;jre\\bin -Djava.home=jre -Djava.ext.dirs=jre\\lib\\ext -Duser.dir=bin -Djava.class.path=. -Dsun.java.launcher=SUN_STANDARD Address: 0x000000002237C700 Size: 96\n    STARTUP HINTS DETAIL Flags: 1 DATA1: 1677721 DATA2: 5033165\n</code></pre>"},{"location":"shrc_diag_util/#printtoplayerstats","title":"<code>printTopLayerStats</code>","text":"<p>Use this utility with a layered cache. This utility works in the same way as <code>printStats</code>. By default, this utility shows information for the top layer cache. To view statistics for a specific layer, use the <code>layer=&lt;number&gt;</code> option. For example, to show statistics for the second layer in a 2-layer cache, run <code>printTopLayerStats,layer=1</code>.</p> <p>Example output:</p> <pre><code>Current statistics for cache \"Cache1\":\n\nCache created with:\n        -Xnolinenumbers                      = false\n        BCI Enabled                          = true\n        Restrict Classpaths                  = false\n        Feature                              = cr\n\n\nbase address                         = 0x00007F234C054000\nend address                          = 0x00007F234D038000\nallocation pointer                   = 0x00007F234C054000\n\ncache layer                          = 1\ncache size                           = 16776608\nsoftmx bytes                         = 16776608\nfree bytes                           = 15299372\nReserved space for AOT bytes         = -1\nMaximum space for AOT bytes          = -1\nReserved space for JIT data bytes    = -1\nMaximum space for JIT data bytes     = -1\nMetadata bytes                       = 792\nMetadata % used                      = 0%\nClass debug area size                = 1331200\nClass debug area used bytes          = 0\nClass debug area % used              = 0%\n\nROMClass bytes                       = 0\nAOT bytes                            = 30520\nJIT data bytes                       = 644\nZip cache bytes                      = 0\nStartup hint bytes                   = 0\nData bytes                           = 114080\n\n# ROMClasses                         = 0\n# AOT Methods                        = 18\n# Classpaths                         = 0\n# URLs                               = 0\n# Tokens                             = 0\n# Zip caches                         = 0\n# Startup hints                      = 0\n# Stale classes                      = 0\n% Stale classes                      = 0%\n\n\nCache is 8% full\n\nCache is accessible to current user = true\n</code></pre>"},{"location":"shrc_diag_util/#using-the-trace-facility","title":"Using the trace facility","text":"<p>Trace output contains very detailed information that might be used by a VM developer to diagnose complex problems with class data sharing. Trace is configured by using the <code>-Xtrace</code> option and the binary output of the trace facility must be processed by the Trace formatter into a human-readable format.</p> <p>The trace component for class data sharing is <code>j9shr</code>. Five levels of trace are available, starting from basic initialization and runtime information in level 1 up to the most detailed trace output in level 5.</p> <p>To trace memory-mapped files, shared memory, and shared semaphores, include the <code>j9prt</code> trace component.</p> <p>To trace operations with Java Helper API methods, include the <code>j9jcl</code> trace component.</p>"},{"location":"tool_builder/","title":"Option builder","text":""},{"location":"tool_builder/#option-builder-tools","title":"Option builder tools","text":"<p>You can modify many of the command-line options by specifying a number of parameters.</p> <p>Several of the options have many available parameters that you can combine in numerous ways to achieve the effect you want.</p> <p>Tools are available for the following options to help you select these parameters correctly, achieve the correct combinations, and avoid conflicts:</p> <ul> <li> <p>-Xdump</p> </li> <li> <p>-Xtrace</p> </li> </ul>"},{"location":"tool_jcmd/","title":"Java command (jcmd) tool","text":""},{"location":"tool_jcmd/#java-diagnostic-command-jcmd-tool","title":"Java diagnostic command (<code>jcmd</code>) tool","text":"<p>Use the <code>jcmd</code> tool to run diagnostic commands on a specified VM.</p> <p> Note: Running diagnostic commands can significantly affect the performance of the target VM.</p> <p>The command syntax is as follows:</p> <pre><code>jcmd [&lt;options&gt;] [&lt;vmid&gt; &lt;arguments&gt;]\n</code></pre> <p>Where:</p> <ul> <li> <p>The available <code>&lt;options&gt;</code> are:    </p> <ul> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jcmd</code> command. You can use multiple <code>-J</code> options, for example: <code>jcmd -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-h</code>: prints the <code>jcmd</code> help</li> </ul> </li> <li> <p><code>&lt;vmid&gt;</code> is the Attach API virtual machine identifier for the Java\u2122 VM process. This ID is often, but not always, the same as the operating system process ID. One example where the ID might be different is if you specified the system property <code>-Dcom.ibm.tools.attach.id</code> when you started the process. You can use the <code>jps</code> command to find the VMID.</p> </li> <li> <p>The available <code>arguments</code> are:</p> <ul> <li><code>help</code>: shows the diagnostic commands that are available for this VM. This list of commands can vary between VMs.</li> <li><code>help &lt;command&gt;</code>: shows help information for the specified diagnostic command</li> <li><code>&lt;command&gt; [&lt;command_arguments&gt;]</code>: runs the specified diagnostic command, with optional command arguments</li> </ul> </li> </ul> <p>Examples:</p> <pre><code>jcmd 31452 Thread.print\njcmd 31452 help Dump.heap\njcmd 31452 Dump.heap myHeapDump\n</code></pre> <p> Restrictions: This tool is not supported and is subject to change or removal in future releases. Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to Eclipse OpenJ9\u2122. For information about the differences between these two implementations, see Switching to OpenJ9.</p> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations.</li> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jdmpview/","title":"Dump viewer","text":""},{"location":"tool_jdmpview/#dump-viewer-jdmpview","title":"Dump viewer (<code>jdmpview</code>)","text":"<p>The dump viewer is a command-line tool that allows you to examine the contents of system dumps produced from the Eclipse OpenJ9\u2122 VM. The dump viewer allows you to view both Java\u2122 and native information from the time the dump was produced. You can run the dump viewer on one platform to work with dumps from another platform.</p> <p>For long running tasks, the dump viewer can also be run in batch mode.</p> <p>The dump viewer is useful for diagnosing <code>OutOfMemoryError</code> exceptions in Java\u2122 applications. For problems like general protection faults (GPFs), system abends, and SIGSEGVs, a system debugger such as gdb (Linux) provides more information.</p>"},{"location":"tool_jdmpview/#syntax","title":"Syntax","text":""},{"location":"tool_jdmpview/#starting-the-dump-viewer","title":"Starting the dump viewer","text":"<p><code>jdmpview [-J&lt;vm option&gt;] (-core &lt;core file&gt; | -zip &lt;zip file&gt;) [-notemp]</code></p> Input option Explanation <code>-core &lt;core file&gt;</code> Specifies a dump file. <code>-zip &lt;zip file&gt;</code> Specifies a compressed file containing the core file (produced by the dump extractor (<code>jpackcore</code>) tool on AIX\u00ae, Linux\u00ae, and macOS\u00ae systems). <code>-notemp</code> By default, when you specify a file by using the <code>-zip</code> option, the contents are extracted to a temporary directory before processing. Use the <code>-notemp</code> option to prevent this extraction step, and run all subsequent commands in memory. <code>-J-Dcom.ibm.j9ddr.path.mapping=&lt;mappings&gt;</code> The variable <code>&lt;mappings&gt;</code> is a list of native library mappings of the form <code>old-path=new-path</code>, using the usual path separator (a semi-colon (';') on Windows, and a colon (':') on other platforms). <code>-J-Dcom.ibm.j9ddr.library.path=&lt;path&gt;</code> The variable <code>&lt;path&gt;</code> is a list of paths to search for native libraries, using the usual path separator (a semi-colon (';') on Windows, and a colon (':') on other platforms). <p> Note: The <code>-core</code> option can be used with the <code>-zip</code> option to specify the core file in the compressed file. With these options, <code>jdmpview</code> shows multiple contexts, one for each source file that it identified in the compressed file.</p> <p> Note: On AIX and Linux, some <code>jdmpview</code> commands must locate the executable and the native libraries that are referenced by the core. For example, commands that relate to call-sites. A common scenario involves using <code>jdmpview</code> to examine core files that originate on different systems. However, if the executable and the libraries are in their original locations, <code>jdmpview</code> might not consider them. Therefore, first check the executable and the list of native libraries by running <code>jdmpview</code> on a core with the <code>info mod</code> command.</p> <ul> <li> <p>One way to assist <code>jdmpview</code> to locate those files is by specifying on the command line one or both of the path mapping option (<code>-J-Dcom.ibm.j9ddr.path.mapping=&lt;mappings&gt;</code>) and the library path option (<code>-J-Dcom.ibm.j9ddr.library.path=&lt;path&gt;</code>).</p> </li> <li> <p>Alternatively, on the system where the core file was produced, you can use <code>jpackcore</code> to collect all the relevant files into a single zip archive. That archive can be unpacked, possibly on another system, into a new, empty directory. Running <code>jdmpview</code> in that new directory (where the core file will be located) should enable it to find all the data it needs, including information that might not be included in the core file itself, such as symbols or sections. When you use an archive produced by <code>jpackcore</code>, setting the path or library mapping system properties should not be necessary.</p> </li> </ul> <p>On z/OS\u00ae, you can copy the dump to an HFS file and supply that as input to <code>jdmpview</code>, or you can supply a fully qualified MVS\u2122 data set name. For example:</p> <pre><code>&gt; jdmpview -core USER1.JVM.TDUMP.SSHD6.D070430.T092211\nDTFJView version 4.29.5, using DTFJ version 1.12.29003\nLoading image from DTFJ...\n</code></pre> <p>MVS data set names may contain the dollar sign ($). Names that contain a dollar sign must be enclosed by single quotation marks ('). For example:</p> <pre><code>&gt; jdmpview -core 'USER1.JVM.$TDUMP.SSH$D7.D141211.T045506'\n</code></pre> <p>After <code>jdmpview</code> processes the dump files, a session starts, showing this message:</p> <pre><code>For a list of commands, type \"help\"; for how to use \"help\", type \"help help\"\n&gt;\n</code></pre> <p>If you run the <code>jdmpview</code> tool on a compressed file that contains multiple dumps, the tool detects and shows all the dump files, whether these are system dumps, Java dumps, or heap dumps. Because of this behavior, more than one context might be displayed when you start <code>jdmpview</code>. To switch context, type <code>context &lt;n&gt;</code>, where <code>&lt;n&gt;</code> is the context value for the dump you want to investigate.</p> <p>On z/OS, a system dump can contain multiple address spaces and an address space can contain multiple VM instances. In this case, the context allows you to select the address space and VM instance within the dump file. The following z/OS example shows address spaces (<code>ASID</code>), with two JVMs occupying address space <code>0x73</code> (context 5 and 6). The current context is 5 (<code>CTX:5&gt;</code>), shown with an asterisk. To view the JVM in context 6, you can switch by specifying <code>context 6</code>.  </p> <pre><code>CTX:5&gt; context\nAvailable contexts (* = currently selected context) :\n\n0 : ASID: 0x1 : No JRE : No JRE\n1 : ASID: 0x3 : No JRE : No JRE\n2 : ASID: 0x4 : No JRE : No JRE\n3 : ASID: 0x6 : No JRE : No JRE\n4 : ASID: 0x7 : No JRE : No JRE\n*5 : ASID: 0x73 EDB: 0x83d2053a0 : JRE 1.8.0 z/OS s390x-64 build 20181117_128845 (pmz6480-20181120_01)\n6 : ASID: 0x73 EDB: 0x8004053a0 : JRE 1.8.0 z/OS s390x-64 build 20181117_128845 (pmz6480-20181120_01)\n7 : ASID: 0x73 EDB: 0x4a7bd9e8 : No JRE\n8 : ASID: 0xffff : No JRE : No JRE\n</code></pre> <p>If you are using <code>jdmpview</code> to view Java dumps and heap dumps, some options do not produce any output. For example, a heap dump doesn't contain the information requested by the <code>info system</code> command, but does contain information requested by the <code>info class</code> command.</p> <p>If you are viewing a dump where there are a large number of objects on the heap, you can speed up the performance of <code>jdmpview</code> by ensuring that your system has enough memory available and does not need to page memory to disk. To achieve this, start <code>jdmpview</code> with a larger heap size by specifying the <code>-Xmx</code> option. Use the <code>-J</code> option to pass the <code>-Xmx</code> command line option to the JVM. For example:</p> <pre><code>jdmpview -J-Xmx&lt;n&gt; -core &lt;core file&gt;\n</code></pre> <p>The options available to the dump viewer session are shown under Session parameters</p>"},{"location":"tool_jdmpview/#starting-in-batch-mode","title":"Starting in batch mode","text":"<p>For long running or routine jobs, <code>jdmpview</code> can be used in batch mode.</p> <p>You can run a single command without specifying a command file by appending the command to the end of the <code>jdmpview</code> command line. For example:</p> <pre><code>jdmpview -core mycore.dmp info class\n</code></pre> <p>When specifying jdmpview commands that accept a wildcard parameter, you must replace the wildcard symbol with <code>ALL</code> to prevent the shell interpreting the wildcard symbol. For example, in interactive mode, the command <code>info thread *</code> must be specified in the following way:</p> <pre><code>jdmpview -core mycore.dmp info thread ALL\n</code></pre> <p>Batch mode is controlled with the following command line options:</p> Option Explanation -cmdfile &lt;path to command file&gt; A file that contains a series of jdmpview commands, which are read and run sequentially. -charset &lt;character set name&gt; The character set for the commands specified in -cmdfile (name must be a supported charset as defined in java.nio.charset.Charset. For example, US-ASCII) -outfile &lt;path to output file&gt; The file to record any output generated by commands. -overwrite If the file specified in -outfile exists, this option overwrites the file. -append If the file specified in -outfile exists, new output messages are appended to the end of that file. The -append and -overwrite options cannot be used at the same time. <p>The command file can have empty lines that contain spaces, or comment lines that start with // or #. These lines are ignored by jdmpview. Example command file:</p> <pre><code>// commands.txt\ninfo system\ninfo proc\n</code></pre> <p>To run jdmpview in batch mode, using this command file, specify:</p> <pre><code>jdmpview -outfile out.txt [-overwrite|-append] -cmdfile commands.txt -core &lt;path to core file&gt;\n</code></pre> <p>When the output file exists, you need to specify either the <code>-overwrite</code> option or the <code>-append</code> option. If you do not, an error message is generated.</p>"},{"location":"tool_jdmpview/#processing-output","title":"Processing output","text":"<p>You can redirect command output to a file, or pipe the command output to another command.</p> <p>To redirect jdmpview command output to a file, use one of the following formats:</p> <pre><code>command &gt; &lt;target_file&gt;\n</code></pre> <p>If the target file exists, this redirection overwrites the content within it.</p> <pre><code>command &gt;&gt; &lt;target_file&gt;\n</code></pre> <p>If the target file exists, this redirection appends the output to it.</p> <p>Where <code>&lt;target_file&gt;</code> is the file name, which can include the full path to the file.</p> <p>To pipe <code>jdmpview</code> command output to another command, use the vertical bar (|) character. For example:</p> <pre><code>command | grep string\n</code></pre> <p>You can chain more than two commands together by using multiple vertical bar characters.</p> <p>The following commands can be used to interrogate the output:</p> <ul> <li><code>charsFrom</code></li> <li><code>charsTo</code></li> <li><code>grep</code></li> <li><code>tokens</code></li> </ul>"},{"location":"tool_jdmpview/#using-charsfrom","title":"Using <code>CharsFrom</code>","text":"<p>Use the <code>charsFrom</code> command after the vertical bar character to exclude all characters that come before a specified pattern in a resulting line.</p> <pre><code>charsFrom &lt;options&gt; pattern\n</code></pre> <p>Where <code>&lt;options&gt;</code>:</p> <ul> <li><code>-e</code> or <code>-exclude</code> : Exclude the matched pattern from the resulting line. By default, the matched pattern is included in the resulting line.</li> <li><code>-keep</code> : Keep lines that do not contain a match to the pattern. By default, lines that do not contain a match are excluded from the results.</li> <li><code>-i</code> or <code>-ignoreCase</code> : Ignore case.</li> </ul> <p>For example, the following command displays resulting lines that contain the pattern <code>jre</code>, and trims each line to exclude all characters that come before this pattern:</p> <pre><code>&gt; info mod | charsFrom jre\njre/lib/ppc64/libzip.so @ 0x0, sections:\njre/lib/ppc64/libdbgwrapper80.so @ 0x0, sections:\njre/lib/ppc64/libverify.so @ 0x0, sections:\njre/lib/ppc64/libjava.so @ 0x0, sections:\njre/lib/ppc64/compressedrefs/libjclse7b_28.so @ 0x0, sections:\n</code></pre>"},{"location":"tool_jdmpview/#using-charsto","title":"Using <code>CharsTo</code>","text":"<p>Use the <code>CharsTo</code> command after the vertical bar character to include the characters in a resulting line until a specific pattern is found.</p> <pre><code>charsTo &lt;options&gt; pattern\n</code></pre> <p>Where <code>&lt;options&gt;</code>:</p> <ul> <li><code>-include</code> : Include the matched pattern in the resulting line. By default, the matched pattern is excluded from the resulting line.</li> <li><code>-keep</code> : Keep lines that do not contain a match to the pattern. By default, lines that do not contain a match are excluded from the results.</li> <li><code>-i</code> or <code>-ignoreCase</code> : Ignore case.</li> </ul> <p>For example, the following command displays lines that contain the pattern <code>@</code>, and trims each line to exclude all characters from <code>@</code> onwards:</p> <pre><code>&gt; info mod | charsTo @\nbin/java\n/usr/lib64/gconv/UTF-16.so\n/test/sdk/lib/ppc64le/libnet.so\n/test/sdk/lib/ppc64le/libnio.so\n/test/sdk/lib/ppc64le/libzip.so\n/test/sdk/lib/ppc64le/libjsig.so\nlibjsig.so\n</code></pre> <p>You can also use <code>charsFrom</code> and <code>charsTo</code> together, separated by a vertical bar character. For example, the following command displays lines that contain the pattern <code>lib</code>, and trims each line to exclude all characters that come before this pattern, as well as all characters from the pattern <code>@</code> :</p> <pre><code>&gt; info mod | charsFrom lib | charsTo @\nlib/ppc64le/libzip.so\nlib/ppc64le/libjsig.so\nlib/ppc64le/libverify.so\nlib/ppc64le/libjava.so\nlib/ppc64le/compressedrefs/libj9jit29.so\n</code></pre> <p> Note: The line will not be displayed if the <code>charsFrom</code> and <code>charsTo</code> are used together, but only one of the patterns are matched in a line. Furthermore, the line will not be displayed if both patterns are matched in a line, but the <code>charsTo</code> pattern appears before, and not after, the <code>charsFrom</code> pattern.</p>"},{"location":"tool_jdmpview/#using-grep","title":"Using <code>grep</code>","text":"<p>Use the <code>grep</code> command after the vertical bar character to show which lines match a specified pattern.</p> <pre><code>grep &lt;options&gt; pattern\n</code></pre> <p>Where <code>&lt;options&gt;</code>:</p> <ul> <li><code>-i</code> : Ignore case.</li> <li><code>-r</code>, <code>-G</code>, or <code>--regex</code>: Use a regular expression as defined in the Java documentation of the java.utils.regex.Pattern class.</li> <li><code>-b</code> or <code>--block</code> : Show blocks of lines where at least one of the lines matches the pattern. Blocks of lines are separated by empty lines.</li> <li><code>-A</code> &lt;NUM&gt; or +&lt;NUM&gt; : Show at most &lt;NUM&gt; lines after the matching line. For example <code>grep -A 2 &lt;pattern&gt;</code> or <code>grep +2 &lt;pattern&gt;</code>.</li> <li><code>-B</code> &lt;NUM&gt; or -&lt;NUM&gt; : Show at most &lt;NUM&gt; lines before the matching line.</li> <li><code>-C</code> &lt;NUM&gt; or +-&lt;NUM&gt; : Show at most &lt;NUM&gt; lines before and after the matching line.</li> <li><code>-v</code> or <code>--invert-match</code> : Use with the grep command to show lines that do not match the pattern. These options are equivalent to the <code>grep</code> command.</li> <li><code>-F</code> or <code>--fixed-strings</code> : Do not treat the asterisk (*) as a wildcard character. Use these options with the <code>-r</code>, <code>-G</code>, or <code>--regex</code> options.</li> </ul> <p>Pattern rules:</p> <ul> <li>An asterisk (*) in a pattern is treated as a wildcard character unless you specify the <code>-F</code> or <code>--fixed-strings</code> options.</li> <li>If a pattern contains spaces, enclose the pattern in a pair of double quotation marks (\").</li> <li>If a pattern contains double quotation marks, enclose the pattern in a pair of single quotation marks (').</li> <li> <p>You can specify multiple sub-patterns to match by using the following format, but only if you do not use the <code>-r</code>, <code>-G</code>, or <code>--regex</code> options:</p> <p><code>\"[pattern1|pattern2|...|patternN]\"</code> </p> <p>The initial and trailing double quotation marks and brackets ([ ]) are required. Use a vertical bar character to separate the sub-patterns. Quotation marks and the vertical bar are not allowed in a sub-pattern. Spaces are allowed in the middle of a sub-pattern, but leading and trailing spaces will be trimmed.</p> </li> <li> <p>Use the <code>grep</code> command to show lines that do not match the pattern.</p> </li> </ul> <p>In the following example, the command displays the number of instances and total heap size for the <code>java/lang/String</code> class:</p> <pre><code>&gt; info class | grep java/lang/String\n94 7688 [Ljava/lang/String;\n1822 58304 java/lang/String               \n1 16 java/lang/String$CaseInsensitiveComparator              \n0 0 java/lang/String$UnsafeHelpers\n</code></pre> <p>In the following example, the command uses two pipes in combination to display the number of instances and total heap size for the <code>java/lang/StringCoding.StringDecoder</code> class:</p> <pre><code>&gt; info class | grep java/lang/String | grep -i decoder\n1 48 java/lang/StringCoding$StringDecoder\n</code></pre>"},{"location":"tool_jdmpview/#using-tokens","title":"Using <code>tokens</code>","text":"<p>Use the <code>tokens</code> command after the vertical bar character to isolate specified tokens in the resulting lines.</p> <pre><code>tokens [options] range[,range][..range]\n</code></pre> <p>You can define range in the following formats:</p> <ul> <li><code>x</code></li> <li><code>x,y</code></li> <li><code>x..y</code></li> </ul> <p>A set of rules applies to these formats:</p> <ul> <li><code>x</code> or <code>y</code> can be prefixed with <code>-</code>. This means that <code>x</code> or <code>y</code> are counting backwards from the end of a list. For example, a <code>y</code> value of <code>-1</code> represents the last token in a list, while -2 represents the penultimate token in a list.</li> <li><code>x</code> must represent a token that either precedes or is at the same position as <code>y</code>.</li> </ul> <p>In this format, if <code>x</code> is omitted, it is assumed to be <code>1</code>. If <code>y</code> is omitted, it is assumed to be <code>-1</code>.</p> <p>For example, the following command displays the first and second token for each resulting line:</p> <pre><code>&gt; info mmap | grep -r ^0x | tokens 1,2\n0x0000000000012fff 0x000000000000d000\n0x0000000000017fff 0x0000000000004000\n0x00000000009dafff 0x0000000000018000\n0x00000000009fffff 0x000000000001f000\n0x0000000000cbefff 0x0000000000002000\n0x0000000000d76fff 0x0000000000001000\n0x0000000003145fff 0x0000000000071000\n0x0000000003b93fff 0x0000000000003000\n</code></pre>"},{"location":"tool_jdmpview/#session-parameters","title":"Session parameters","text":"<p>When <code>jdmpview</code> is started, many parameters can be used during the session to interrogate the system dump data, which are divided into general and expert parameters. The general parameters are documented in this section. To see a list of expert parameters, use the <code>!j9help</code> option.</p>"},{"location":"tool_jdmpview/#j9help","title":"!j9help","text":"<pre><code>    !j9help\n</code></pre> Lists all expert parameters that can be used in a session, with a brief description. <p> Note: The expert parameters are subject to change and not intended as a supported interface.</p>"},{"location":"tool_jdmpview/#cd","title":"cd","text":"<pre><code>    cd &lt;directory_name&gt;\n</code></pre> Changes the working directory to <code>&lt;directory_name&gt;</code>. The working directory is used for log files. Logging is controlled by the <code>set logging</code> command. Use the <code>pwd</code> command to query the current working directory."},{"location":"tool_jdmpview/#cmdfile","title":"cmdfile","text":"<pre><code>    cmdfile &lt;directory_name&gt;\n</code></pre> Runs all of the commands in a file. The commands are read line by line and run sequentially. Empty lines, and lines that start with // or #, are ignored. Use the option charset to identify the character set that is used in the chosen file. The character set must be supported, as defined in <code>java.nio.charset.Charset</code>, such as <code>US-ASCII</code>."},{"location":"tool_jdmpview/#deadlock","title":"deadlock","text":"<p>This command detects deadlock situations in the Java application that was running when the system dump was produced. Example output:</p> <pre><code>deadlock loop:\nthread: Thread-2 (monitor object: 0x9e32c8) waiting for =&gt;\nthread: Thread-3 (monitor object: 0x9e3300) waiting for =&gt;\nthread: Thread-2 (monitor object: 0x9e32c8)\n</code></pre> <p>In this example, the deadlock analysis shows that <code>Thread-2</code> is waiting for a lock held by <code>Thread-3</code>, which is in turn waiting for a lock held earlier by <code>Thread-2</code>.</p> <p>Threads are identified by their Java thread name, whereas object monitors are identified by the address of the object in the Java heap. You can obtain further information about the threads using the <code>info thread *</code> command. You can obtain further information about the monitors using the <code>x/J &lt;0xaddr&gt;</code> command.</p>"},{"location":"tool_jdmpview/#find","title":"find","text":"<pre><code>    find &lt;pattern&gt;,&lt;start_address&gt;,&lt;end_address&gt;,&lt;memory_boundary&gt;, &lt;bytes_to_print&gt;,&lt;matches_to_display&gt;\n</code></pre> <p>This command searches for <code>&lt;pattern&gt;</code> in the memory segment from <code>&lt;start_address&gt;</code> to <code>&lt;end_address&gt;</code> (both inclusive), and shows the number of matching addresses you specify with <code>&lt;matches_to_display&gt;</code>. You can also display the next <code>&lt;bytes_to_print&gt;</code> bytes for the last match.</p> <p>By default, the <code>find</code> command searches for the pattern at every byte in the range. If you know the pattern is aligned to a particular byte boundary, you can specify <code>&lt;memory_boundary&gt;</code> to search every <code>&lt;memory_boundary&gt;</code> bytes. For example, if you specify a <code>&lt;memory_boundary&gt;</code> of \"4\", the command searches for the pattern every 4 bytes.</p>"},{"location":"tool_jdmpview/#findnext","title":"findnext","text":"Finds the next instance of the last string passed to <code>find</code> or <code>findptr</code>. It repeats the previous <code>find</code> or <code>findptr</code> command, depending on which one was issued last, starting from the last match."},{"location":"tool_jdmpview/#findptr","title":"findptr","text":"<pre><code>    findptr &lt;pattern&gt;,&lt;start_address&gt;,&lt;end_address&gt;,&lt;memory_boundary&gt;,&lt;bytes_to_print&gt;,&lt;matches_to_display&gt;\n</code></pre> <p>Searches memory for the given pointer. <code>findptr</code> searches for <code>&lt;pattern&gt;</code> as a pointer in the memory segment from <code>&lt;start_address&gt;</code> to <code>&lt;end_address&gt;</code> (both inclusive), and shows the number of matching addresses you specify with <code>&lt;matches_to_display&gt;</code>. You can also display the next <code>&lt;bytes_to_print&gt;</code> bytes for the last match.</p> <p>By default, the <code>findptr</code> command searches for the pattern at every byte in the range. If you know the pattern is aligned to a particular byte boundary, you can specify <code>&lt;memory_boundary&gt;</code> to search every <code>&lt;memory_boundary&gt;</code> bytes. For example, if you specify a <code>&lt;memory_boundary&gt;</code> of \"4\", the command searches for the pattern every 4 bytes.</p>"},{"location":"tool_jdmpview/#help","title":"help","text":"<pre><code>    help [&lt;command_name&gt;]\n</code></pre> Shows information for a specific command. If you supply no parameters, help shows the complete list of supported commands."},{"location":"tool_jdmpview/#history","title":"history","text":"<pre><code>    history|his [-r][&lt;N&gt;]\n</code></pre> Recalls and displays the history of commands that you have run. The default behavior is to display the 20 most recent commands. If you use the argument <code>&lt;N&gt;</code>, then N commands are displayed. For example, if you run history 35, then the 35 most recent commands are displayed. You can also use the <code>-r</code> option with <code>&lt;N&gt;</code> to run the Nth most recent command in your history. Using the <code>-r</code> option alone runs the most recent command in your history."},{"location":"tool_jdmpview/#info-thread","title":"info thread","text":"<pre><code>    info thread [*|all|&lt;native_thread_ID&gt;|&lt;zos_TCB_address&gt;]\n</code></pre> <p>Displays information about Java and native threads. The following information is displayed for all threads (\"*\"), or the specified thread:</p> <ul> <li>Thread id</li> <li>Registers</li> <li>Stack sections</li> <li>Thread frames: procedure name and base pointer</li> <li>Thread properties: list of native thread properties and their values. For example: thread priority.</li> <li>Associated Java thread, if applicable:<ul> <li>Name of Java thread</li> <li>Address of associated <code>java.lang.Thread</code> object</li> <li>State (shown in JVMTI and <code>java.lang.Thread.State</code> formats)</li> <li>The monitor the thread is waiting for</li> <li>Thread frames: base pointer, method, and filename:line</li> </ul> </li> </ul> <p>If you supply no parameters, the command shows information about the current thread.</p>"},{"location":"tool_jdmpview/#info-system","title":"info system","text":"<p>Displays the following information about the system that produced the core dump:</p> <ul> <li>Amount of memory</li> <li>Operating system</li> <li>Virtual machine or virtual machines present</li> </ul>"},{"location":"tool_jdmpview/#info-class","title":"info class","text":"<pre><code>    info class [&lt;class_name&gt;] [-sort:&lt;name&gt;|&lt;count&gt;|&lt;size&gt;]\n</code></pre> Displays the inheritance chain and other data for a given class. <p>If a class name is passed to info class, the following information is shown about that class:</p> <ul> <li>Name</li> <li>ID</li> <li>Superclass ID</li> <li>Class loader ID</li> <li>Modifiers</li> <li>Number of instances and total size of instances</li> <li>Inheritance chain</li> <li>Fields with modifiers (and values for static fields)</li> <li>Methods with modifiers</li> </ul> <p>If no parameters are passed to <code>info class</code>, the following information is shown:</p> <ul> <li>The number of instances of each class.</li> <li>The total size of all instances of each class.</li> <li>The class name</li> <li>The total number of instances of all classes.</li> <li>The total size of all objects.</li> </ul> <p>The <code>sort</code> option allows the list of classes to be sorted by name (default), by number of instances of each class, or by the total size of instances of each class.</p>"},{"location":"tool_jdmpview/#info-proc","title":"info proc","text":"<p>Displays threads, command-line arguments, environment variables, and shared modules of the current process.</p> <p>To view the shared modules used by a process, use the <code>info sym</code> command.</p>"},{"location":"tool_jdmpview/#info-jitm","title":"info jitm","text":"<p>Displays JIT compiled methods and their addresses:</p> <ul> <li>Method name and signature</li> <li>Method start address</li> <li>Method end address</li> </ul>"},{"location":"tool_jdmpview/#info-lock","title":"info lock","text":"Displays a list of available monitors and locked objects."},{"location":"tool_jdmpview/#info-sym","title":"info sym","text":"Displays a list of available modules. For each process in the address spaces, this command shows a list of module sections for each module, their start and end addresses, names, and sizes."},{"location":"tool_jdmpview/#info-mmap","title":"info mmap","text":"<pre><code>    info mmap [&lt;address&gt;] [-verbose] [-sort:&lt;size&gt;|&lt;address&gt;]\n</code></pre> Displays a summary list of memory sections in the process address space, with start and end address, size, and properties. If an address parameter is specified, the results show details of only the memory section containing the address. If <code>-verbose</code> is specified, full details of the properties of each memory section are displayed. The <code>-sort</code> option allows the list of memory sections to be sorted by size or by start address (default)."},{"location":"tool_jdmpview/#info-mod","title":"info mod","text":"Displays a list of native library modules in the process address space, which includes file paths and other information about each module."},{"location":"tool_jdmpview/#info-heap","title":"info heap","text":"<pre><code>    info heap [*|&lt;heap_name&gt;*]\n</code></pre> <p>If no parameters are passed to this command, the heap names and heap sections are shown.</p> <p>Using either \"*\" or a heap name shows the following information about all heaps or the specified heap:</p> <ul> <li>Heap name</li> <li>(Heap size and occupancy)</li> <li>Heap sections<ul> <li>Section name</li> <li>Section size</li> <li>Whether the section is shared</li> <li>Whether the section is executable</li> <li>Whether the section is read only</li> </ul> </li> </ul>"},{"location":"tool_jdmpview/#heapdump","title":"heapdump","text":"<pre><code>    heapdump [&lt;heaps&gt;]\n</code></pre> Generates a Java heap dump to a file. You can select which Java heaps to dump by listing the heap names, separated by spaces. To see which heaps are available, use the <code>info heap</code> command. By default, all Java heaps are dumped."},{"location":"tool_jdmpview/#hexdump","title":"hexdump","text":"<pre><code>    hexdump &lt;hex_address&gt; &lt;bytes_to_print&gt;\n</code></pre> Displays a section of memory in a hexdump-like format. Displays <code>&lt;bytes_to_print&gt;</code> bytes of memory contents starting from <code>&lt;hex_address&gt;</code>."},{"location":"tool_jdmpview/#_1","title":"+","text":"Displays the next section of memory in hexdump-like format. This command is used with the hexdump command to enable easy scrolling forwards through memory. The previous hexdump command is repeated, starting from the end of the previous one."},{"location":"tool_jdmpview/#-","title":"-","text":"Displays the previous section of memory in hexdump-like format. This command is used with the hexdump command to enable easy scrolling backwards through memory. The previous hexdump command is repeated, starting from a position before the previous one."},{"location":"tool_jdmpview/#pwd","title":"pwd","text":"Displays the current working directory, which is the directory where log files are stored."},{"location":"tool_jdmpview/#quit","title":"quit","text":"Exits the core file viewing tool; any log files that are currently open are closed before exit."},{"location":"tool_jdmpview/#set-heapdump","title":"set heapdump","text":"Configures Heapdump generation settings.<pre><code>set heapdump &lt;options&gt;\n</code></pre> <p>where <code>&lt;options&gt;</code> are:</p> <ul> <li><code>phd</code>: Set the Heapdump format to Portable Heapdump, which is the default.</li> <li><code>txt</code>: Set the Heapdump format to classic.</li> <li><code>file &lt;file&gt;</code>: Set the destination of the Heapdump.</li> <li><code>multiplefiles [on|off]</code>: If multiplefiles is set to on, each Java heap in the system dump is written to a separate file. If multiplefiles is set to off, all Java heaps are written to the same file. The default is off.</li> </ul>"},{"location":"tool_jdmpview/#set-logging","title":"set logging","text":"<pre><code>    set logging &lt;options&gt;\n</code></pre> <p>Configures logging settings, starts logging, or stops logging. This parameter enables the results of commands to be logged to a file, where <code>&lt;options&gt;</code> are:</p> <ul> <li><code>[on|off]</code>: Turns logging on or off. (Default: off)</li> <li><code>file &lt;filename&gt;</code>: Sets the file to log to. The path is relative to the directory returned by the pwd command, unless an absolute path is specified. If the file is set while logging is on, the change takes effect the next time logging is started. Not set by default.</li> <li><code>overwrite [on|off]</code>: Turns overwriting of the specified log file on or off. When overwrite is off, log messages are appended to the log file. When overwrite is on, the log file is overwritten after the set logging command. (Default: off)</li> <li><code>redirect [on|off]</code>: Turns redirecting to file on or off, with off being the default. When logging is set to on:<ul> <li>A value of on for redirect sends non-error output only to the log file.</li> <li>A value of off for redirect sends non-error output to the console and log file.</li> </ul> </li> </ul> <p>Redirect must be turned off before logging can be turned off. (Default: off)</p>"},{"location":"tool_jdmpview/#show-heapdump","title":"show heapdump","text":"<pre><code>    show heapdump &lt;options&gt;\n</code></pre> Displays the current heap dump generation settings."},{"location":"tool_jdmpview/#show-logging","title":"show logging","text":"<pre><code>    show logging &lt;options&gt;\n</code></pre> <p>Displays the current logging settings:</p> <ul> <li>set_logging = [on|off]</li> <li>set_logging_file =</li> <li>set_logging_overwrite = [on|off]</li> <li>set_logging_redirect = [on|off]</li> <li>current_logging_file =</li> </ul> <p>The file that is currently being logged to might be different from set_logging_file, if that value was changed after logging was started.</p>"},{"location":"tool_jdmpview/#whatis-hex_address","title":"whatis <code>&lt;hex_address&gt;</code>","text":"Displays information about <code>whatis</code> stored at the given memory address, <code>&lt;hex_address&gt;</code>. This command examines the memory location at <code>&lt;hex_address&gt;</code> and tries to find out more information about this address. For example:<pre><code>&gt; whatis 0x8e76a8\n\nheap #1 - name: Default@19fce8\n0x8e76a8 is within heap segment: 8b0000 -- cb0000\n0x8e76a8 is start of an object of type java/lang/Thread\n</code></pre>"},{"location":"tool_jdmpview/#x-examine","title":"x/ (examine)","text":"<p>Passes the number of items to display and the unit size, as listed in the following table, to the sub-command. For example, <code>x/12bd</code>.</p> Abbreviation Unit Size b Byte 8-bit h Half word 16-bit w Word 32-bit g Giant word 64-bit <p>This command is similar to the use of the <code>x/</code> command in gdb, including the use of defaults.</p>"},{"location":"tool_jdmpview/#xj-class_name0xaddr","title":"x/J [<code>&lt;class_name&gt;</code>|<code>&lt;0xaddr&gt;</code>]","text":"<p>Displays information about a particular object, or all objects of a class. If <code>&lt;class_name&gt;</code> is supplied, all static fields with their values are shown, followed by all objects of that class with their fields and values. If an object address (in hex) is supplied, static fields for that object's class are not shown; the other fields and values of that object are printed along with its address.</p> <p> Note: This command ignores the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#xd-0xaddr","title":"x/D &lt;<code>0xaddr</code>&gt;","text":"<p>Displays the integer at the specified address, adjusted for the hardware architecture this dump file is from. For example, the file might be from a big-endian architecture.</p> <p> This command uses the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#xx-0xaddr","title":"x/X &lt;<code>0xaddr</code>&gt;","text":"<p>Displays the hex value of the bytes at the specified address, adjusted for the hardware architecture this dump file is from. For example, the file might be from a big-endian architecture.</p> <p> Note: This command uses the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#xk-0xaddr","title":"x/K &lt;<code>0xaddr</code>&gt;","text":"<p>Where the size is defined by the pointer size of the architecture, this parameter shows the value of each section of memory. The output is adjusted for the hardware architecture this dump file is from, starting at the specified address. It also displays a module with a module section and an offset from the start of that module section in memory if the pointer points to that module section. If no symbol is found, it displays a \"*\" and an offset from the current address if the pointer points to an address in 4KB (4096 bytes) of the current address. Although this command can work on an arbitrary section of memory, it is probably more useful on a section of memory that refers to a stack frame. To find the memory section of a thread stack frame, use the info thread command.</p> <p> Note: This command uses the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#example","title":"Example","text":"<p>This example session illustrates a selection of the commands available and their use.</p> <p>In the example session, which is generated on a Linux system, some lines have been removed for clarity (and terseness).</p> <p>User input is prefaced by a greater than symbol (&gt;).</p> <pre><code>    test@madras:~/test&gt; sdk/bin/jdmpview -core core.20121116.154147.16838.0001.dmp\n    DTFJView version 4.29.5, using DTFJ version 1.12.29003\n    Loading image from DTFJ...\n\n    For a list of commands, type \"help\"; for how to use \"help\", type \"help help\"\n    Available contexts (* = currently selected context) :\n\n    Source : file:///home/test/core.20121116.154147.16838.0001.dmp\n            *0 : PID: 16867 : JRE 1.8.0 Linux ppc64-64 build 20121115_128521 (pxp6480-20121116_01 )\n\n    &gt; help\n    +                                              displays the next section of memory in hexdump-like format\n    -                                              displays the previous section of memory in hexdump-like format\n    cd                                             changes the current working directory, used for log files\n    close                     [context id]         closes the connection to a core file\n    context                   [ID|asid ID]         switch to the selected context\n    deadlock                                       displays information about deadlocks if there are any\n    exit                                           Exit the application\n    find                                           searches memory for a given string\n    findnext                                       finds the next instance of the last string passed to \"find\"\n    findptr                                        searches memory for the given pointer\n    heapdump                                       generates a PHD or classic format heapdump\n    help                      [command name]       displays list of commands or help for a specific command\n    hexdump                                        outputs a section of memory in a hexdump-like format\n    info                      &lt;component&gt;          Information about the specified component\n    info class                &lt;Java class name&gt;    Provides information about the specified Java class\n    info heap                 [*|heap name]        Displays information about Java heaps\n    info jitm                                      Displays JIT'ed methods and their addresses\n    info lock                                      outputs a list of system monitors and locked objects\n    info mmap                                      Outputs a list of all memory segments in the address space\n    info mod                                       outputs module information\n    info proc                                      shortened form of info process\n    info process                                   displays threads, command line arguments, environment\n    info sym                                       an alias for 'mod'\n    info sys                                       shortened form of info system\n    info system                                    displays information about the system the core dump is from\n    info thread                                    displays information about Java and native threads\n    log                       [name level]         display and control instances of java.util.logging.Logger\n    open                      [path to core or zip] opens the specified core or zip file\n    plugins                                        Plugin management commands\n                         list                      Show the list of loaded plugins for the current context\n                       reload                      Reload plugins for the current context\n                     showpath                      Show the DTFJ View plugin search path for the current context\n                      setpath                      Set the DTFJ View plugin search path for the current context\n    pwd                                            displays the current working directory\n    quit                                           Exit the application\n    set                       [logging|heapdump]   Sets options for the specified command\n    set heapdump                                   configures heapdump format, filename and multiple heap support\n    set logging                                    configures several logging-related parameters, starts/stops logging\n                           on                      turn on logging\n                          off                      turn off logging\n                         file                      turn on logging\n                    overwrite                      controls the overwriting of log files\n    show                      [logging|heapdump]   Displays the current set options for a command\n    show heapdump                                  displays heapdump settings\n    show logging                                   shows the current logging options\n    whatis                    [hex address]        gives information about what is stored at the given memory address\n    x/d                       &lt;hex address&gt;        displays the integer at the specified address\n    x/j                       &lt;object address&gt; [class name] displays information about a particular object or all objects of a class\n    x/k                       &lt;hex address&gt;        displays the specified memory section as if it were a stack frame parameters\n    x/x                       &lt;hex address&gt;        displays the hex value of the bytes at the specified address\n\n    &gt; set logging file log.txt\n    logging turned on; outputting to \"/home/test/log.txt\"\n\n    &gt; info system\n    Machine OS:     Linux\n    Hypervisor:     PowerVM\n    Machine name:   madras\n    Machine IP address(es):\n                    9.20.88.155\n    System memory:  8269201408\n\n    Dump creation time: 2015/08/10 14:44:36:019\n    Dump creation time (nanoseconds): 21314421467539\n\n    Java version:\n    JRE 1.8.0 Linux ppc64-64 build 20121115_128521 (pxp6490-20121116_01)\n\n    JVM start time: 2015/08/10 14:44:05:690\n    JVM start time (nanoseconds): 21284086192267\n\n    &gt; info thread *\n    native threads for address space\n     process id: 16838\n\n      thread id: 16839\n       registers:\n\n       native stack sections:\n       native stack frames:\n       properties:\n       associated Java thread:\n        name:          main\n        Thread object: java/lang/Thread @ 0x2ffd1e08\n        Priority:      5\n        Thread.State:  RUNNABLE\n        JVMTI state:   ALIVE RUNNABLE\n        Java stack frames:\n         bp: 0x0000000000085b28  method: void com/ibm/jvm/Dump.SystemDumpImpl()  (Native Method)\n          objects: &lt;no objects in this frame&gt;\n         bp: 0x0000000000085b40  method: void com/ibm/jvm/Dump.SystemDump()  source: Dump.java:41\n          objects: &lt;no objects in this frame&gt;\n         bp: 0x0000000000085b68  method: void mySystemDump.main(String[])  source: mySystemDump.java:29\n          objects: &lt;no objects in this frame&gt;\n    ===Lines Removed===\n\n        name:          GC Worker\n        id:            16860\n        Thread object: java/lang/Thread @ 0x3001b980\n        Priority:      5\n        Thread.State:  WAITING\n        JVMTI state:   ALIVE WAITING WAITING_INDEFINITELY IN_OBJECT_WAIT\n          waiting to be notified on: \"MM_ParallelDispatcher::workerThread\" with ID 0x1004cbc8 owner name: &lt;unowned&gt;\n        Java stack frames: &lt;no frames to print&gt;\n\n        name:          GC Worker\n        id:            16861\n        Thread object: java/lang/Thread @ 0x3001c180\n        Priority:      5\n        Thread.State:  WAITING\n        JVMTI state:   ALIVE WAITING WAITING_INDEFINITELY IN_OBJECT_WAIT\n          waiting to be notified on: \"MM_ParallelDispatcher::workerThread\" with ID 0x1004cbc8 owner name: &lt;unowned&gt;\n        Java stack frames: &lt;no frames to print&gt;\n\n        name:          Signal Dispatcher\n        id:            16847\n        Thread object: com/ibm/misc/SignalDispatcher @ 0x3000f268\n        Priority:      5\n        Thread.State:  RUNNABLE\n        JVMTI state:   ALIVE RUNNABLE\n        Java stack frames:\n         bp: 0x00000000000df748  method: int com/ibm/misc/SignalDispatcher.waitForSignal()  (Native Method)\n          objects: &lt;no objects in this frame&gt;\n         bp: 0x00000000000df788  method: void com/ibm/misc/SignalDispatcher.run()  source: SignalDispatcher.java:54\n          objects: 0x30015828 0x30015828\n    ===Lines Removed===\n\n\n    &gt; info heap *\n\n             Heap #1:  Generational@fff78303d30\n              Section #1:  Heap extent at 0x100d0000 (0x300000 bytes)\n               Size:        3145728 bytes\n               Shared:      false\n               Executable:  false\n               Read Only:   false\n              Section #2:  Heap extent at 0x2ffd0000 (0x80000 bytes)\n               Size:        524288 bytes\n               Shared:      false\n               Executable:  false\n               Read Only:   false\n              Section #3:  Heap extent at 0x30050000 (0x80000 bytes)\n               Size:        524288 bytes\n               Shared:      false\n               Executable:  false\n               Read Only:   false\n\n    &gt; info class java/lang/String\n    name = java/lang/String\n\n            ID = 0x37c00    superID = 0x30300\n            classLoader = 0x2ffe9b58    modifiers: public final\n\n            number of instances:     2146\n            total size of instances: 51504 bytes\n\n    Inheritance chain....\n            java/lang/Object\n               java/lang/String\n\n    Fields......\n              static fields for \"java/lang/String\"\n                private static final long serialVersionUID = -6849794470754667710 (0xa0f0a4387a3bb342)\n                public static final java.util.Comparator CASE_INSENSITIVE_ORDER = &lt;object&gt; @ 0x2ffd0278\n                private static final char[] ascii = &lt;object&gt; @ 0x2ffd02c8\n                private static String[] stringArray = &lt;object&gt; @ 0x2ffd0298\n                private static final int stringArraySize = 10 (0xa)\n                static boolean enableCopy = false\n                private static int seed = -126504465 (0xfffffffff875b1ef)\n                private static char[] startCombiningAbove = &lt;object&gt; @ 0x100d0c40\n                private static char[] endCombiningAbove = &lt;object&gt; @ 0x100d0cc0\n                private static final char[] upperValues = &lt;object&gt; @ 0x100d0d40\n                private static final java.io.ObjectStreamField[] serialPersistentFields = &lt;object&gt; @ 0x2ffd0920\n\n              non-static fields for \"java/lang/String\"\n                private final char[] value\n                private final int offset\n                private final int count\n                private int hashCode\n                private int hashCode32\n\n    Methods......\n\n    Bytecode range(s): :  private static native int getSeed()\n    Bytecode range(s): fff76d8ce48 -- fff76d8ce5e:  public void &lt;init&gt;()\n    Bytecode range(s): fff76d8ce88 -- fff76d8cecd:  private void &lt;init&gt;(String, char)\n    Bytecode range(s): fff76d8cf10 -- fff76d8cf19:  public void &lt;init&gt;(byte[])\n    Bytecode range(s): fff76d8cf40 -- fff76d8cf4a:  public void &lt;init&gt;(byte[], int)\n    Bytecode range(s): fff76d8cf7c -- fff76d8cfb5:  public void &lt;init&gt;(byte[], int, int)\n    Bytecode range(s): fff76d8cff8 -- fff76d8d065:  public void &lt;init&gt;(byte[], int, int, int)\n    Bytecode range(s): fff76d8d0c4 -- fff76d8d10c:  public void &lt;init&gt;(byte[], int, int, String)\n    ===Lines Removed===\n\n    &gt; whatis  0x2ffd0298\n            heap #1 - name: Generational@fff78303d30\n                    0x2ffd0298 is within heap segment: 2ffd0000 -- 30050000\n                    0x2ffd0298 is the start of an object of type [Ljava/lang/String;\n</code></pre>"},{"location":"tool_jextract/","title":"Dump extractor","text":""},{"location":"tool_jextract/#dump-extractor-jpackcore","title":"Dump extractor (<code>jpackcore</code>)","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae)</p> <p>On some operating systems, copies of executable files and libraries are required for a full analysis of a core dump (you can get some information from the dump without these files, but not as much). Run the <code>jpackcore</code> utility to collect these extra files and package them into an archive file along with the core dump. To analyze the output, use the dump viewer (<code>jdmpview</code>).</p> <p> Note: This tool replaces OpenJ9 <code>jextract</code>, which is deprecated in Eclipse OpenJ9\u2122 version 0.26.0.</p> <p> The OpenJ9 <code>jextract</code> tool is removed from Java 21 and later. </p>"},{"location":"tool_jextract/#syntax","title":"Syntax","text":"<pre><code>jpackcore [-r] [-x] &lt;core file name&gt; [&lt;zip_file&gt;]\n</code></pre> <p>where:</p> <ul> <li><code>-r</code> forces the <code>jpackcore</code> utility to proceed when the system dump is created from an SDK with a different build ID. See Restriction.</li> <li><code>-x</code> causes the <code>jpackcore</code> utility to omit the system dump itself from the archive produced. In its place, the file <code>excluded-files.txt</code> is added which names the excluded file.</li> <li><code>&lt;core file name&gt;</code> is the name of the system dump.</li> <li><code>&lt;zip_file&gt;</code> is the name you want to give to the processed file. If you do not specify a name, output is written to <code>&lt;core file name&gt;.zip</code> by default. The output is written to the same directory as the core file.</li> </ul> <p> Restriction: You should run <code>jpackcore</code> on the same system that produced the system dump in order to collect the correct executables and libraries referenced in the system dump. You should also run <code>jpackcore</code> using the same VM level, to avoid any problems. From Eclipse OpenJ9 V0.24.0, the utility always checks that the build ID of the SDK that created the dump file matches the <code>jpackcore</code> build ID. Where these IDs do not match, the following exception is thrown:</p> <pre><code>J9RAS.buildID is incorrect (found XXX, expecting YYY). This version of jpackcore is incompatible with this dump (use '-r' option to relax this check).\n</code></pre> <p>To continue, despite the mismatch, use the <code>-r</code> option.</p>"},{"location":"tool_jextract/#see-also","title":"See also","text":"<ul> <li>Dump viewer (<code>jdmpview</code>)</li> </ul>"},{"location":"tool_jmap/","title":"Java memory map (jmap) tool","text":""},{"location":"tool_jmap/#java-memory-map-jmap-tool","title":"Java memory map (<code>jmap</code>) tool","text":"<p>Use the <code>jmap</code> tool to get memory information for a particular Java\u2122 process, or list of processes. The tool shows statistics about classes on the heap, including the number of objects and their aggregate size. The command syntax is as follows:</p> <pre><code>jmap [&lt;option&gt;] [&lt;vmid&gt;]\n</code></pre> <p><code>&lt;vmid&gt;</code> is the Attach API virtual machine identifier for the Java process. This ID is typically the same as the operating system process ID, unless you specified the <code>-Dcom.ibm.tools.attach.id</code> system property when you started the process.</p> <p>VMID is shown in <code>jps</code> or other Attach API-based tools. Multiple VMIDs can be specified, separated by a space.</p> <p>If you do not specify a VMID, the command reads input from <code>stdin</code>. You can therefore get information for all processes by piping the output of the <code>jps</code> command to <code>jmap</code>:</p> <p><code>jps -q | jmap -histo</code></p> <p>IDs of dead processes are silently ignored.</p> <p>On its own, <code>jmap</code> prints help information. To obtain memory information, a <code>-histo</code> argument must be supplied, where the available <code>&lt;options&gt;</code> are as follows:</p> <ul> <li><code>-histo</code>: Prints statistics about classes on the heap, including the number of objects and their aggregate size</li> <li><code>-histo:live</code>: Prints statistics for live objects only</li> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jmap</code> command. You can use multiple <code>-J</code> options, for example: <code>jmap -J-Xms2m -J-Xmx10m</code></li> </ul> <p>The output has the following format:</p> <pre><code>num   object count     total size    class name\n-------------------------------------------------\n  1           3354         107328    [C\n  2            717          57360    java.lang.Class\n  3           2427          38832    java.lang.String\n  4             50          13200    [J\n  5            717          11472    java.lang.J9VMInternals$ClassInitializationLock\n  6            342           8208    java.lang.StringBuilder\n  7            151           7248    jdk.internal.org.objectweb.asm.Item\n  8            396           6336    [Ljava.lang.Object;\n</code></pre> <p> Restrictions: This tool is not supported and is subject to change or removal in future releases. Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to Eclipse OpenJ9\u2122.</p> <p>The following tool limitations apply:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations. You can display information for remote processes by  using <code>ssh user@host jmap &lt;options&gt; &lt;pid&gt;</code>.</li> <li>Displaying data from core dumps is not supported; use <code>jdmpview</code> instead.</li> <li>Other options , such as <code>-F</code> (force a dump of an unresponsive process) can be accomplished using <code>kill -QUIT &lt;pid&gt;</code>.</li> </ul> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jps/","title":"Java process status (jps)","text":""},{"location":"tool_jps/#java-process-status-jps-tool","title":"Java process status (<code>jps</code>) tool","text":"<p>Use the <code>jps</code> tool to query running Java\u2122 processes. The tool shows information for every Java process that is owned by the current user ID on the current host. The command syntax is as follows:</p> <pre><code>jps [&lt;options&gt;]\n</code></pre> <p>where the available <code>&lt;options&gt;</code> are as follows:    </p> <ul> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jps</code> command. You can use multiple <code>-J</code> options, for example: <code>jps -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-l</code>: prints the application package name</li> <li><code>-q</code>: prints only the virtual machine identifiers</li> <li><code>-m</code>: prints the application arguments</li> <li><code>-v</code>: prints the Java VM arguments, including those that are produced automatically</li> </ul> <p>The output has the following format:</p> <pre><code>&lt;VMID&gt; [[&lt;class_name&gt;|&lt;jar_name&gt;|\"Unknown\"] [&lt;application_args&gt;][&lt;vm_args&gt;]]\n</code></pre> <p>where <code>VMID</code> is the Attach API virtual machine identifier for the Java process. This ID is often, but not always, the same as the operating system process ID. One example where the ID might be different is if you specified the system property <code>-Dcom.ibm.tools.attach.id</code> when you started the process.</p> <p>For example:</p> <pre><code>$ jps -l\n5462  org.foo.bar.MyApplication\n14332 openj9.tools.attach.diagnostics.Jps\n\n$ jps -q\n5462\n14332\n</code></pre> <p> Restrictions: This tool is not supported and is subject to change or removal in future releases. Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to Eclipse OpenJ9\u2122.</p> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Does not list Java processes on other hosts, to enhance security</li> <li>Does not list Java processes owned by other users</li> <li>Does not list non-OpenJ9 Java processes</li> <li>Does not list processes whose attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jstack/","title":"Java stack (jstack) tool","text":""},{"location":"tool_jstack/#java-stack-jstack-tool","title":"Java stack (<code>jstack</code>) tool","text":"<p>Use the <code>jstack</code> tool to obtain Java stack traces and thread information for processes. The tool is similar to the HotSpot tool of the same name; the Eclipse OpenJ9\u2122 version of <code>jstack</code> is an independent implementation, added for compatibility.</p> <p>The command syntax is as follows:</p> <pre><code>jstack &lt;options&gt;* &lt;pid&gt;*\n</code></pre> <p>Where <code>&lt;pid&gt;*</code> is a list of process IDs. If none are supplied, the process IDs are read from <code>stdin</code>, which allows a user running a Bourne or equivalent shell to query all processes via <code>jps -q | jstack</code>. IDs of inactive processes are silently ignored. The output contains Java stacks and thread information of the specified processes (equivalent to the information provided in <code>java.lang.management.ThreadInfo</code>).</p> <p>The values for <code>&lt;options&gt;*</code> are as follows:</p> <ul> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jstack</code> command. You can use multiple <code>-J</code> options, for example: <code>jstack -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-p</code>: prints the system and agent properties of the process</li> <li><code>-l</code>: prints more verbose output, including information about locks</li> <li><code>-h</code>: prints help information</li> </ul> <p> Restrictions:</p> <ul> <li>This tool is not supported and is subject to change or removal in future releases.</li> <li>Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to OpenJ9. For more information about differences, see Switching to OpenJ9.</li> </ul> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations.</li> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jstat/","title":"Java statistics monitoring (jstat) tool","text":""},{"location":"tool_jstat/#java-statistics-monitoring-jstat-tool","title":"Java statistics monitoring (<code>jstat</code>) tool","text":"<p>Use the <code>jstat</code> tool to obtain Java Virtual Machine (JVM) statistics. The tool is similar to the HotSpot tool of the same name; the Eclipse OpenJ9\u2122 version of <code>jstat</code> is an independent implementation, added for compatibility.</p> <p>The command syntax is as follows:</p> <pre><code>jstat [&lt;option&gt;] [&lt;vmid&gt;]\n</code></pre> <p>where <code>vmid</code> is the Attach API virtual machine identifier for the Java process. This ID is typically the same as the operating system process ID, unless you specified the -Dcom.ibm.tools.attach.id system property when you started the process.</p> <p>VMID is shown in Java process status (jps) tool or other Attach API-based tools.</p> <p>On its own, <code>jstat</code> prints help information. The values for <code>&lt;option&gt;</code> are as follows:</p> <ul> <li><code>-J</code>: supplies arguments to the JVM that is running the <code>jstat</code> command. You can use multiple <code>-J</code> options, for example: <code>jstat -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-h</code>: prints help information</li> <li><code>-options</code>: lists the available command options</li> <li><code>-class</code>: displays classloading statistics</li> </ul> <p>The output has the following format:</p> <pre><code>Class Loaded    Class Unloaded\n         860                 0\n</code></pre> <p> Restrictions:</p> <ul> <li>This tool is not supported and is subject to change or removal in future releases.</li> <li>Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to OpenJ9. For more information about differences, see Switching to OpenJ9.</li> </ul> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations.</li> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_migration/","title":"Switching to OpenJ9","text":""},{"location":"tool_migration/#switching-to-eclipse-openj9","title":"Switching to Eclipse OpenJ9","text":"<p>Eclipse OpenJ9\u2122 provides the following tools, which might differ in behavior from the HotSpot equivalent.</p> <p> Note: For information about HotSpot equivalences and differences for items other than tools, see New to Eclipse OpenJ9?</p>"},{"location":"tool_migration/#java-diagnostic-command-tool-jcmd","title":"Java diagnostic command tool (<code>jcmd</code>)","text":"<p>Runs diagnostic commands on a specified VM. The main difference from the HotSpot <code>jcmd</code> tool is that the following options are not currently supported:</p> <ul> <li>The <code>-f</code> option to read commands from a file.</li> <li>The <code>Perfcounter.print</code> option for displaying performance counters for the target VM.</li> <li>Selecting VMs by main class instead of VMID.</li> <li>Specifying <code>0</code> as a VMID to target all VMs.</li> </ul>"},{"location":"tool_migration/#java-memory-map-tool-jmap","title":"Java memory map tool (<code>jmap</code>)","text":"<p>Displays information about classes on the heap, including the number of objects and their aggregate size. The main differences from the HotSpot <code>jmap</code> tool are as follows:</p> <ul> <li>Uses the Attach API.</li> <li>Displays information only for local processes that are owned by the current user, due to security considerations. You can display information for remote processes by using <code>ssh user@host jmap &lt;option&gt; &lt;vmid&gt;</code>, where <code>&lt;vmid&gt;</code> is the Attach API virtual machine identifier for the Java\u2122 process.</li> <li>Does not support displaying data from core dumps; use Dump viewer instead.</li> <li>Does not include a <code>-F</code> option to force a dump of an unresponsive process. User <code>kill -QUIT &lt;pid&gt;</code> instead, where <code>&lt;pid&gt;</code> is the process identifier.</li> </ul> <p>For more information, see <code>jmap</code>.</p>"},{"location":"tool_migration/#java-process-status-jps","title":"Java process status (<code>jps</code>)","text":"<p>Displays information about running Java processes. The main differences from the HotSpot <code>jps</code> tool are as follows:</p> <ul> <li>Runs on Windows\u00ae, AIX\u00ae, and z/OS\u00ae, as well as Linux\u00ae.</li> <li>Uses the Attach API.</li> <li>Shows processes on the current host only.</li> <li>There is no <code>-V</code> option.</li> </ul> <p>For more information, see <code>Java process status</code>.</p>"},{"location":"tool_migration/#java-stack-jstack-tool","title":"Java stack (<code>jstack</code>) tool","text":"<p>Displays information about Java stack traces and thread information for processes. The main differences from the HotSpot <code>jstack</code> tool are as follows:</p> <ul> <li>In the interests of security, the OpenJ9 implementation of <code>jstack</code> prints only information about local processes that are owned by the current user.</li> <li>Printing data for core dumps is not supported. Use the Dump viewer instead.</li> <li>There is no <code>-m</code> option. Printing data for native stack frames is not supported.</li> <li>There is no <code>-F</code> option to force a dump, although this might be accomplished using <code>kill -QUIT &lt;pid&gt;</code> on some platforms.</li> </ul> <p>For more information, see <code>jstack</code>.</p>"},{"location":"tool_migration/#java-statistics-monitoring-jstat-tool","title":"Java statistics monitoring (<code>jstat</code>) tool","text":"<p>Displays information about Java statistics for processes. The main difference from the HotSpot <code>jstat</code> tool is that this tool only provides the number of classes loaded and the number of class unloaded.</p> <p>For more information, see <code>jstat</code>.</p>"},{"location":"tool_traceformat/","title":"Trace formatter","text":""},{"location":"tool_traceformat/#trace-formatter-traceformat","title":"Trace formatter (<code>traceformat</code>)","text":"<p>The trace formatter is a Java\u2122 program that converts binary trace point data in a trace file to a readable form. The formatter requires the <code>TraceFormat.dat</code> and <code>J9TraceFormat.dat</code> files, which contain the formatting templates. The formatter produces a file that contains header information about the VM that produced the binary trace file, a list of threads for which trace points were produced, and the formatted trace points with their time stamp, thread ID, trace point ID, and trace point data.</p>"},{"location":"tool_traceformat/#syntax","title":"Syntax","text":"<p>To use the trace formatter on a binary trace file type:</p> <pre><code>    traceformat &lt;input_file&gt;  [&lt;output_file&gt;] &lt;parameters&gt;\n</code></pre> <p>Where <code>&lt;input_file&gt;</code> is the name of the binary trace file to be formatted, and <code>&lt;output_file&gt;</code> is the name of the output file. If you do not specify an output file, the output file is called <code>input_file.fmt</code>.</p> <p>The size of the heap that is needed to format the trace is directly proportional to the number of threads present in the trace file. For large numbers of threads the formatter might run out of memory, generating the error <code>OutOfMemoryError</code>. In this case, increase the heap size by using the <code>-Xmx</code> option.</p>"},{"location":"tool_traceformat/#parameters","title":"Parameters","text":"<p>The following <code>&lt;parameters&gt;</code> are available with the trace formatter:</p> Option Explanation <code>-datfile=&lt;file1.dat&gt;[,&lt;file2.dat&gt;]</code> A comma-separated list of trace formatting data files. By default, the following files are used:$JAVA_HOME/lib/J9TraceFormat.dat and $JAVA_HOME/lib/TraceFormat.dat <code>-format_time=yes|no</code> Specifies whether to format the time stamps into human readable form. The default is <code>yes</code>. <code>-help</code> Displays usage information. <code>-indent</code> Indents trace messages at each <code>Entry</code> trace point and outdents trace messages at each <code>Exit</code> trace point. The default is not to indent the messages. <code>-summary</code> Prints summary information to the screen without generating an output file. <code>-threads=&lt;thread id&gt;[,&lt;thread id&gt;]...</code> Filters the output for the given thread IDs only. thread id is the ID of the thread, which can be specified in decimal or hex (0x) format. Any number of thread IDs can be specified, separated by commas. <code>-timezone=+|-HH:MM</code> Specifies the offset from UTC, as positive or negative hours and minutes, to apply when formatting time stamps. <code>-verbose</code> Output detailed warning and error messages, and performance statistics."},{"location":"tool_traceformat/#examples","title":"Examples","text":"<p>The following example shows output from running the trace formatter command:</p> <pre><code>    C:\\test&gt;traceformat sample.trc\n    Writing formatted trace output to file sample.trc.fmt\n    Processing 0.4921875Mb of binary trace data\n    Completed processing of 6983 tracepoints with 0 warnings and 0 errors\n</code></pre> <p>The formatted trace output looks similar to the following extract, which is truncated to show the key areas of information:</p> <pre><code>    Trace Summary\n\n    Service level:\n    JRE 1.8.0 Windows 7 amd64-64 build  (pwa6480sr2-20150624_06(SR2))\n\n    JVM startup options:\n    -Xoptionsfile=c:\\build\\pwa6480sr2-20150624\\sdk\\lib\\compressedrefs\\options.default\n    ....\n\n    Processor information:\n    Arch family:         AMD64\n    Processor Sub-type:  Opteron\n    Num Processors:      8\n    Word size:           64\n\n    Trace activation information::\n    FORMAT=c:\\build\\pwa6480sr2-20150624\\sdk\\lib;.\n    MAXIMAL=all{level1}\n    EXCEPTION=j9mm{gclogger}\n    MAXIMAL=all{level2}\n    output=sample\n\n    Trace file header:\n    JVM start time: 08:58:35.527000000\n    Generations:    1\n    Pointer size:   8\n\n    Active threads\n    ....\n    0x000000000f155f00  Attach API wait loop\n    0x000000000f18b200  Thread-1\n    0x000000000f190200  Thread-3\n\n\n     Trace Formatted Data\n\n    Time (UTC)          Thread ID          Tracepoint ID Type   Tracepoint Data\n    08:58:35.527291919 *0x000000000f010500 j9trc.0       Event  Trace engine initialized for VM = 0x3ad4d0\n    08:58:35.527349836  0x000000000f010500 j9prt.0       Event  Trace engine initialized for module j9port\n    08:58:35.527354040  0x000000000f010500 j9thr.0       Event  Trace engine initialized for module j9thr\n    08:58:35.529409621 *0x000000000f01eb00 j9trc.5       Event  Thread started VMthread = 0xf01eb00, name = (unnamed thread), nativeID = 0x24a798\n    ....\n    08:58:35.536134516  0x000000000f010500 j9vm.1        Entry &gt;Create RAM class from ROM class 0x3cab680 in class loader 0x3042338\n    08:58:35.536136384  0x000000000f010500 j9vm.80       Event  ROM class 0x3cab680 is named java/lang/Object\n    08:58:35.536200373  0x000000000f010500 j9vm.2        Exit  &lt;Created RAM class 0xf03ef00 from ROM class 0x3cab680\n</code></pre>"},{"location":"version0.10/","title":"Version 0.10.0","text":""},{"location":"version0.10/#whats-new-in-version-0100","title":"What's new in version 0.10.0","text":"<p>The following new features and notable changes since v.0.9.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments.</li> <li>Change to the default shared classes cache size for OpenJDK 8 builds</li> <li>New information for the SHARED CLASSES section of a Javadump file</li> <li>Support for OpenJDK HotSpot options</li> <li> New JDK 11 features</li> </ul>"},{"location":"version0.10/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.10/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.10.0 supports OpenJDK 11, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 11</li> </ul> <p>OpenJDK 11 with Eclipse OpenJ9 is a long term support (LTS) release and supersedes OpenJDK 10 with Eclipse OpenJ9.</p> <p>Although it is possible to build an OpenJDK v8 with the OpenJ9 0.10.0 release level, testing at the project is not complete and therefore support is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments</p>"},{"location":"version0.10/#change-to-the-default-shared-classes-cache-size","title":"Change to the default shared classes cache size","text":"<p>For OpenJDK 8 builds, the default shared classes cache size is increased from 16 MB to 300 MB, with a \"soft\" maximum limit for the initial size of the cache set to 64 MB. Certain exceptions apply. For more information, see -Xshareclasses. The new default also applies to OpenJDK 11 builds.</p>"},{"location":"version0.10/#new-information-for-the-shared-classes-section-of-a-java-dump-file","title":"New information for the SHARED CLASSES section of a Java dump file","text":"<p>The value of the soft maximum size (<code>-Xscmx</code>) of the shared classes cache is now recorded in the <code>SHARED CLASSES</code> section of a Java dump file against the string <code>2SCLTEXTSMB</code>. For example output, see Java dump.</p>"},{"location":"version0.10/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li>-XX:HeapDumpPath</li> <li>-XX:[+|-]HeapDumpOnOutOfMemory</li> <li>-XX:ActiveProcessorCount</li> </ul>"},{"location":"version0.10/#new-jdk-11-features","title":"New JDK 11 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 181: Nest-Based Access Control</li> <li>JEP 309: Dynamic Class-File Constants</li> <li>JEP 320: Remove the Java EE and CORBA Modules</li> <li>JEP 321: HTTP Client (Standard)</li> <li>JEP 323: Local-Variable Syntax for Lambda Parameters</li> <li>JEP 324: Key Agreement with Curve25519 and Curve448</li> <li>JEP 329: ChaCha20 and Poly1305 Cryptographic Algorithms</li> <li>JEP 330: Launch Single-File Source-Code Programs</li> <li>JEP 332: Transport Layer Security (TLS) 1.3</li> <li>JEP 335: Deprecate the Nashorn JavaScript Engine</li> <li>JEP 336: Deprecate the Pack200 Tools and API</li> </ul> <p>You can find the full list of features for JDK 11 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.10/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.9.0 and version 0.10.0 releases, see the Release notes.</p>"},{"location":"version0.11/","title":"Version 0.11.0","text":""},{"location":"version0.11/#whats-new-in-version-0110","title":"What's new in version 0.11.0","text":"<p>The following new features and notable changes since version 0.10.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments.</li> <li> OpenSSL is now supported for improved native cryptographic performance</li> <li> Changes to the location of the default shared cache and cache snapshot directory</li> <li>New class data sharing suboptions</li> <li>Container awareness in the Eclipse OpenJ9\u2122 VM is now enabled by default</li> <li>Pause-less garbage collection mode is now available on Linux x86 platforms</li> <li>You can now restrict identity hash codes to non-negative values</li> <li>Support for OpenJDK HotSpot options</li> </ul>"},{"location":"version0.11/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.11/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9 release 0.11.0 provides limited support for the macOS\u00ae platform on OpenJDK 11. Early builds of OpenJDK 11 with OpenJ9 on macOS are available at the AdoptOpenJDK project at the following link:</p> <ul> <li>OpenJDK version 11</li> </ul> <p>Support for macOS on OpenJDK 8 is coming soon.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments</p>"},{"location":"version0.11/#openssl-is-now-supported-for-improved-native-cryptographic-performance","title":"OpenSSL is now supported for improved native cryptographic performance","text":"<p>OpenSSL is a native open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which provides improved cryptographic performance compared to the in-built OpenJDK Java cryptographic implementation. The OpenSSL V1.1.x implementation is enabled by default and  supported for the Digest, CBC, and GCM algorithms. Binaries obtained from AdoptOpenJDK include OpenSSL v1.1.x (see Note). For more information about tuning the OpenSSL implementation, see Performance tuning.</p> <p> Note: Currently, OpenSSL is not bundled as part of the AdoptOpenJDK AIX binary due to an unresolved problem.</p> <p></p>"},{"location":"version0.11/#changes-to-the-location-of-the-default-shared-cache-and-cache-snapshot-directory","title":"Changes to the location of the default shared cache and cache snapshot directory","text":"<p>To increase security, the default shared classes cache directory is changed on non-Windows platforms from <code>/tmp/javasharedresources/</code> to the user's home directory, unless you specify <code>-Xshareclasses:groupAccess</code>. If you use the <code>groupAccess</code> suboption, the default directory is unchanged because some members of the group might not have access to the user home directory.</p> <p> Note: For persistent caches, the shared classes cache directory cannot be on an NFS mount. If your user home directory is on an NFS mount, either move it or use the <code>-Xshareclasses:cacheDir=&lt;directory&gt;</code> suboption to specify a different directory for the cache.</p> <p>In general, caches cannot be shared across different Java releases, so you cannot re-use a cache that was created by a previous level of Java 11; if you use the name and cacheDir suboptions to specify an existing cache, the VM attempts to delete the cache and create a new one. However, on Windows, the cache cannot be deleted if it is in use, in which case the VM continues to use the existing cache.</p> <p>You can find and remove old caches or snapshots by using the following command-line options:</p> <p>For persistent caches: - <code>-Xshareclasses:cacheDir=/tmp/javasharedresources/,listAllCaches</code> to find the cache - <code>-Xshareclasses:cacheDir=/tmp/javasharedresources/,name=&lt;cacheName&gt;,destroy</code> to remove the cache</p> <p>For nonpersistent caches or snapshots: - <code>-Xshareclasses:cacheDir=/tmp,listAllCaches</code> to find the item - <code>-Xshareclasses:cacheDir=/tmp,name=&lt;snapshotName&gt;,destroySnapshot</code> to remove the item</p> <p></p>"},{"location":"version0.11/#new-class-data-sharing-suboptions","title":"New class data sharing suboptions","text":"<p><code>-Xshareclasses:bootClassesOnly</code>: disables caching of classes that are loaded by non-bootstrap class loaders. This suboption also enables the <code>nonfatal</code> suboption, which allows the VM to start even if there was an error creating the shared classes cache.</p> <p><code>-Xshareclasses:fatal</code>: prevents the VM from starting if there was an error creating the shared classes cache. You might want to enable this suboption when using the -Xshareclasses:bootClassesOnly suboption, to troubleshoot problems when creating the cache.</p>"},{"location":"version0.11/#container-awareness-in-the-openj9-vm-is-now-enabled-by-default","title":"Container awareness in the OpenJ9 VM is now enabled by default","text":"<p>When using container technology, applications are typically run on their own and do not need to compete for memory. If the VM detects that it is running in a container environment, and a memory limit for the container is set, the VM automatically adjusts the maximum default Java heap size.</p> <p>In earlier releases, this behavior was enabled by setting the <code>-XX:+UseContainerSupport</code> option. This setting is now the default. For more information about the Java heap size set for a container, see -XX:[+|-]UseContainerSupport.</p>"},{"location":"version0.11/#pause-less-garbage-collection-mode-is-now-available-on-linux-x86-platforms","title":"Pause-less garbage collection mode is now available on Linux x86 platforms","text":"<p>Pause-less garbage collection mode is aimed at large heap, response-time sensitive applications. When enabled, the VM attempts to reduce GC pause times. In earlier releases, pause-less garbage collection mode (<code>-Xgc:concurrentScavenge</code>) was available only on IBM z14 hardware. This mode is now available on 64-bit x86 Linux platforms.</p> <p> Restrictions:</p> <ul> <li>The Generational Concurrent (<code>gencon</code>) garbage collection policy must be used. (This is the default policy.)</li> <li>Compressed references must be used. See <code>-Xcompressedrefs</code>. Compressed references are enabled by default when the maximum heap size (<code>-Xmx</code>) \u2264 57 GB. The concurrent scavenge option is ignored if the maximum heap size is &gt; 57 GB.</li> </ul>"},{"location":"version0.11/#you-can-now-restrict-identity-hash-codes-to-non-negative-values","title":"You can now restrict identity hash codes to non-negative values","text":"<p>OpenJ9 allows both positive and negative identity hashcodes, which can be problematic if your program (incorrectly) assumes hashcodes can only be positive. However, you can now use the -XX:[+|-]PositiveIdentityHash option to limit identity hash codes to non-negative values.</p>"},{"location":"version0.11/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li>-XX:MaxHeapSize</li> <li>-XX:InitialHeapSize</li> </ul>"},{"location":"version0.11/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.10.0 and version 0.11.0 releases, see the Release notes.</p>"},{"location":"version0.12/","title":"Version 0.12.0","text":""},{"location":"version0.12/#whats-new-in-version-012x","title":"What's new in version 0.12.x","text":""},{"location":"version0.12/#version-0120","title":"Version 0.12.0","text":"<p>The following new features and notable changes since version 0.11.0 are included in this release:</p> <ul> <li>Improved flexibility for managing the size of the JIT code cache</li> </ul> <ul> <li>Idle-tuning is enabled by default when Eclipse OpenJ9\u2122 runs in a docker container</li> <li>Changes to default shared classes cache directory permissions (not Windows)</li> <li> OpenSSL is now supported for improved native cryptographic performance</li> <li>Improved support for pause-less garbage collection</li> <li>RSA algorithm support for OpenSSL</li> <li><code>IBM_JAVA_OPTIONS</code> is deprecated</li> </ul> <p> Warning: Following the release of OpenJ9 0.12.0, an intermittent problem was identified with OpenSSL V1.1.x acceleration of the cryptographic Digest algorithm. For more information about the issue, see #4530. You can turn off the Digest algorithm by setting the -Djdk.nativeDigest system property to <code>false</code>. A new release of OpenJ9 (0.12.1) is available that disables the Digest algorithm by default.</p>"},{"location":"version0.12/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.12/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9 release 0.12.0 provides support for OpenJDK 8 with OpenJ9 and OpenJDK 11 with OpenJ9. In this release support is extended to the 64-bit macOS\u00ae platform on OpenJDK with OpenJ9.</p> <p>Builds for all platforms are available from the AdoptOpenJDK project at the following links:</p> <ul> <li>OpenJDK 8 with OpenJ9</li> <li>OpenJDK 11 with OpenJ9</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.12/#improved-flexibility-for-managing-the-size-of-the-jit-code-cache","title":"Improved flexibility for managing the size of the JIT code cache","text":"<p>The JIT code cache stores the native code of compiled Java\u2122 methods. By default, the size of the code cache is 256 MB for a 64-bit VM and 64 MB for a 31/32-bit VM. In earlier releases the size of the code cache could be increased from the default value by using the <code>-Xcodecachetotal</code> command line option. In this release the size can also be decreased by using this option, with a minimum size of 2 MB. The size of the JIT code cache also affects the size of the JIT data cache, which holds metadata about compiled methods. If you use the <code>-Xcodecachetotal</code> option to manage the size of the code cache, the size of the data cache is adjusted by the same proportion. For more information, see <code>-Xcodecachetotal</code>.</p>"},{"location":"version0.12/#idle-tuning-is-enabled-by-default-when-openj9-runs-in-a-docker-container","title":"Idle-tuning is enabled by default when OpenJ9 runs in a docker container","text":"<p>In an earlier release, a set of idle-tuning options were introduced to manage the footprint of the Java heap when the OpenJ9 VM is in an idle state. These options could be set manually on the command line. In this release, the following two options are enabled by default when OpenJ9 is running in a container:</p> <ul> <li><code>-XX:[+|-]IdleTuningGcOnIdle</code>, which runs a garbage collection cycle and releases free memory pages back to the operating system when the VM state is set to idle.</li> <li><code>-XX:[+|-]IdleTuningCompactOnIdle</code>, which compacts the object heap to reduce fragmentation when the VM state is set to idle.</li> </ul> <p>By default, the VM must be idle for 180 seconds before the status is set to idle. To control the wait time before an idle state is set, use the <code>-XX:IdleTuningMinIdleWaitTime</code> option. To turn off idle detection, set the value to <code>0</code>.</p>"},{"location":"version0.12/#changes-to-default-shared-classes-cache-directory-permissions-not-windows","title":"Changes to default shared classes cache directory permissions (not Windows)","text":"<p>If you do not use the <code>cachDirPerm</code> suboption to specify permissions for a shared classes cache directory, and the cache directory is not the <code>/tmp/javasharedresources</code> default, the following changes apply:</p> <ul> <li>When creating a new cache directory, the default permissions are now stricter.</li> <li>If the cache directory already exists, permissions are now unchanged (previously, when a cache was opened using this directory, the permissions would be set to 0777).</li> </ul> <p>For more information, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.12/#openssl-is-now-supported-for-improved-native-cryptographic-performance","title":"OpenSSL is now supported for improved native cryptographic performance","text":"<p>OpenSSL is a native open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which provides improved cryptographic performance compared to the in-built OpenJDK Java cryptographic implementation. The OpenSSL V1.1.x implementation is enabled by default and  supported for the Digest, CBC, and GCM algorithms. Binaries obtained from AdoptOpenJDK include OpenSSL v1.1.x (see Note). For more information about tuning the OpenSSL implementation, see Performance tuning.</p> <p> Note: OpenJDK 8 with OpenJ9 includes OpenSSL support since version 0.11.0. Currently, OpenSSL is not bundled as part of the AdoptOpenJDK AIX binaries due to an unresolved problem.</p> <p></p>"},{"location":"version0.12/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Concurrent scavenge mode is now supported on 64-bit Windows operating systems.</p> <p>In Eclipse OpenJ9 version 0.11.0, support was added for <code>-Xgc:concurrentScavenge</code> on Linux x86-64 virtual machines that use compressed references. In this release, support is now available for Linux x86-64 large-heap virtual machines (non-compressed references).</p> <p>For more information, see the <code>-Xgc:concurrentScavenge</code> option.</p>"},{"location":"version0.12/#rsa-algorithm-support-for-openssl","title":"RSA algorithm support for OpenSSL","text":"<p>OpenSSL v1.1 support for the RSA algorithm is added in this release, providing improved cryptographic performance. OpenSSL support is enabled by default. If you want to turn off support for the RSA algorithm, set the <code>-Djdk.nativeRSA</code> system property to <code>false</code>.</p>"},{"location":"version0.12/#ibm_java_options-is-deprecated","title":"<code>IBM_JAVA_OPTIONS</code> is deprecated","text":"<p>The VM environment variable <code>IBM_JAVA_OPTIONS</code> is deprecated and is replaced by <code>OPENJ9_JAVA_OPTIONS</code>. <code>IBM_JAVA_OPTIONS</code> will be removed in a future release. For more information about the use of this variable, see the general options in Environment variables.</p>"},{"location":"version0.12/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.11.0 and version 0.12.0 releases, see the Release notes.</p>"},{"location":"version0.12/#version-0121","title":"Version 0.12.1","text":"<p>The following change is implemented since version 0.12.0:</p> <p>By default, OpenJ9 provides native cryptographic acceleration using OpenSSL version 1.1.x for the Digest, CBC, GCM, and RSA algorithms. Under certain circumstances acceleration of the Digest algorithm was found to cause a segmentation error. Cryptographic acceleration of the Digest algorithm is now turned off by default. The system property <code>-Djdk.nativeDigest</code> cannot be used to turn on support. This property is ignored by the VM.</p>"},{"location":"version0.12/#full-release-information_1","title":"Full release information","text":"<p>Release notes to describe the changes between Eclipse OpenJ9 version 0.12.0 and version 0.12.1 releases, can be found in the OpenJ9 GitHub repository.</p>"},{"location":"version0.13/","title":"Version 0.13.0","text":""},{"location":"version0.13/#whats-new-in-version-0130","title":"What's new in version 0.13.0","text":"<p>The following new features and notable changes since version 0.12.1 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> Support for OpenSSL 1.0.2</li> <li> New Java\u2122 process status tool</li> <li>Writing a Java dump to STDOUT or STDERR</li> <li>Better diagnostic information for Linux systems that implement control groups</li> <li>Improved support for pause-less garbage collection</li> <li> New JDK 12 features</li> </ul>"},{"location":"version0.13/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.13/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.13.0 supports OpenJDK 12, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 12</li> </ul> <p>OpenJDK 12 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.12.0. Features mentioned in these release notes are not available in these builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.13.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.13/#support-for-openssl-102","title":"Support for OpenSSL 1.0.2","text":"<p>OpenSSL cryptographic support is extended to include OpenSSL 1.0.2 for the Digest, CBC, GCM, and RSA algorithms. Support is enabled by default. On Linux and AIX platforms, the OpenSSL libraries are expected to be available on the system path. For more information about cryptographic acceleration with OpenSSL, see Cryptographic operations.</p> <p>In addition, support for the OpenSSL Digest algorithm is re-enabled in this release following the resolution of issue #4530.</p> <p> Warning: Earlier versions of OpenJDK with OpenJ9 from the AdoptOpenJDK project bundle OpenSSL as part of the binary package. On Linux and AIX systems, OpenSSL is no longer bundled and the libraries are expected to be available on the system path.</p> <p></p>"},{"location":"version0.13/#new-java-process-status-tool","title":"New Java process status tool","text":"<p>A Java process status tool (<code>jps</code>) is available for querying running Java processes. For more information, see Java process status.</p> <p></p>"},{"location":"version0.13/#writing-a-java-dump-to-stdout-or-stderr","title":"Writing a Java dump to STDOUT or STDERR","text":"<p>You can now write a Java dump file to STDOUT or STDERR by using the <code>-Xdump</code> command-line option. See Writing to <code>STDOUT</code>/<code>STDERR</code> for details.</p>"},{"location":"version0.13/#better-diagnostic-information-for-linux-systems-that-implement-control-groups","title":"Better diagnostic information for Linux systems that implement control groups","text":"<p>If you use control groups (cgroups) to manage resources on Linux systems, information about CPU and memory limits is now recorded in a Java dump file. This information is particularly important for applications that run in Docker containers, because when resource limits are set inside a container, the Docker Engine relies on cgroups to enforce the settings. If you are getting a Java <code>OutOfMemoryError</code> error because a container limit has been set on the amount of memory available to an application and this allocation is not sufficient, you can diagnose this problem from the Java dump file. You can find the cgroup information in the ENVINFO section. For sample output, see Java dump (ENVINFO).</p>"},{"location":"version0.13/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Concurrent scavenge mode is now supported on the following platforms:</p> <ul> <li>Linux on POWER LE</li> <li>AIX</li> </ul> <p>For more information, see the <code>-Xgc:concurrentScavenge</code> option.</p>"},{"location":"version0.13/#new-jdk-12-features","title":"New JDK 12 features","text":"<p>The following feature is supported by OpenJ9:</p> <ul> <li>JEP 334: JVM Constants API</li> </ul> <p>The following feature is implemented in OpenJDK and available in any builds of OpenJDK 12 with OpenJ9:</p> <ul> <li>JEP 325: Switch Expressions (Preview) </li> </ul> <p>You can find the full list of features for JDK 12 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.13/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.12.1 and version 0.13.0 releases, see the Release notes.</p>"},{"location":"version0.14/","title":"Version 0.14.0","text":""},{"location":"version0.14/#whats-new-in-version-014x","title":"What's new in version 0.14.x","text":""},{"location":"version0.14/#version-0140","title":"Version 0.14.0","text":"<p>The following new features and notable changes since version 0.13.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Support for OpenSSL 1.0.2</li> <li>New option for ignoring or reporting unrecognized -XX: options</li> <li>Improved support for pause-less garbage collection</li> <li>New Java stack (<code>jstack</code>) tool for obtaining stack traces and thread information</li> <li>New Java process status (<code>jps</code>) tool</li> <li>New experimental option to improve the performance of JVMTI watched fields</li> <li>New option to prevent a network query being used to determine host name and IP address</li> <li>Changes to the shared classes cache generation number</li> <li>Change to the default native stack size on 64-bit z/OS\u00ae</li> </ul>"},{"location":"version0.14/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.14/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.14.0 supports OpenJDK 8, 11, and 12. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 12</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.14/#support-for-openssl-102","title":"Support for OpenSSL 1.0.2","text":"<p>OpenJ9 release 0.13.0 introduced support for OpenSSL 1.0.2 for Java 12. In this release, support is extended to Java 8 and Java 11. OpenSSL is enabled by default for the CBC, Digest, GCM, and RSA cryptographic algorithms. On Linux\u00ae and AIX\u00ae platforms, the OpenSSL libraries are expected to be available on the system path. For more information about cryptographic acceleration with OpenSSL, see Cryptographic operations.</p> <p> Note: Support for the OpenSSL Digest algorithm on Java 8 and 11 is re-enabled in this release following the resolution of issue #4530.</p> <p> Warning: Earlier versions of OpenJDK with OpenJ9 from the AdoptOpenJDK project bundle OpenSSL as part of the binary package. On Linux and AIX systems, OpenSSL is no longer bundled and the libraries are expected to be available on the system path.</p>"},{"location":"version0.14/#new-option-for-ignoring-or-reporting-unrecognized-xx-options","title":"New option for ignoring or reporting unrecognized -XX: options","text":"<p>By default, unrecognized <code>-XX:</code> command-line options are ignored, which prevents an application failing to start. You can now use  <code>-XX:-IgnoreUnrecognizedXXColonOptions</code> to turn off this behavior, so that unrecognized <code>-XX:</code> options are reported instead. For more information, see <code>-XX:[+|-]IgnoreUnrecognizedXXColonOptions</code>.</p>"},{"location":"version0.14/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Support for Concurrent scavenge mode is now extended to Linux on POWER\u00ae BE architectures. For more information, see <code>-Xgc:concurrentScavenge</code>.</p>"},{"location":"version0.14/#new-jstack-tool-for-obtaining-stack-traces-and-thread-information","title":"New jstack tool for obtaining stack traces and thread information","text":"<p>For compatibility with the reference implementation, OpenJ9 now includes an independent implementation of the <code>jstack</code> tool. To learn how to use the tool and about any differences compared to the HotSpot tool of the same name, see Java stack tool.</p>"},{"location":"version0.14/#new-jps-tool","title":"New jps tool","text":"<p>OpenJ9 release 0.13.0 introduced support for the <code>jps</code> tool for Java 12. In this release, support is added for Java 8 and 11. The <code>jps</code> tool can be used to  query running Java processes. For more information, see Java process status.</p>"},{"location":"version0.14/#new-experimental-option-to-improve-the-performance-of-jvmti-watched-fields","title":"New experimental option to improve the performance of JVMTI watched fields","text":"<p>The <code>-XX:[+|-]JITInlineWatches</code> option is introduced in this release. When enabled, the option turns on experimental JIT operations that are intended to improve the performance of JVMTI watched fields. This option is currently supported only on x86 platforms (Windows\u00ae, macOS\u00ae, and Linux).</p>"},{"location":"version0.14/#new-option-to-prevent-a-network-query-being-used-to-determine-host-name-and-ip-address","title":"New option to prevent a network query being used to determine host name and IP address","text":"<p>By default, a network query is used to determine the host name and IP address for troubleshooting purposes. To avoid your program waiting to time out if a nameserver cannot be contacted, you can now prevent the query from being performed. For more information, see <code>-XX:[+|-]ReadIPInfoForRAS</code>.</p>"},{"location":"version0.14/#changes-to-the-shared-classes-cache-generation-number","title":"Changes to the shared classes cache generation number","text":"<p>On all platforms, the format of classes that are stored in the shared classes cache is changed, which causes the JVM to create a new shared classes cache, rather than re-creating or reusing an existing cache. To save space, all existing shared caches can be removed unless they are in use by an earlier release. For more information about destroying a shared classes cache, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.14/#change-to-the-default-native-stack-size-on-64-bit-zos","title":"Change to the default native stack size on 64-bit z/OS","text":"<p>The default stack size for operating system threads on 64-bit z/OS is changed from 384 KB to the operating system minimum of 1 MB. For more information about this setting, see <code>-Xmso</code>.</p>"},{"location":"version0.14/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.13.0 and version 0.14.0 releases, see the Release notes.</p>"},{"location":"version0.14/#version-0142","title":"Version 0.14.2","text":"<p>The following new features and notable changes since version 0.14.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Support for OpenSSL 1.0.1</li> <li>OpenSSL Digest algorithm disabled</li> </ul>"},{"location":"version0.14/#features-and-changes_1","title":"Features and changes","text":""},{"location":"version0.14/#binaries-and-supported-environments_1","title":"Binaries and supported environments","text":"<p>OpenJ9 release 0.14.2 supports OpenJDK 8 and 11. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> </ul> <p>The Windows (MSI) installer for OpenJDK v8 (64-bit) can now be used to optionally install the IcedTea-Web package, which provides equivalent functionality to Java Web Start. For more information about the installer, see the AdoptOpenJDK Installation page. For more information about migrating to IcedTea-Web, read the AdoptOpenJDK Migration Guide.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.14/#support-for-openssl-101","title":"Support for OpenSSL 1.0.1","text":"<p>OpenSSL version 1.0.1 support is now enabled; Earlier releases supported only OpenSSL 1.0.2 and 1.1.x. On Linux\u00ae and AIX\u00ae platforms, the OpenSSL libraries are expected to be available on the system path. For more information about cryptographic acceleration with OpenSSL, see Cryptographic operations.</p>"},{"location":"version0.14/#openssl-digest-algorithm-disabled","title":"OpenSSL Digest algorithm disabled","text":"<p>Due to issue #5611, the Digest algorithm is disabled.</p>"},{"location":"version0.15/","title":"Version 0.15.1","text":""},{"location":"version0.15/#whats-new-in-version-0151","title":"What's new in version 0.15.1","text":"<p>The following new features and notable changes since version 0.14.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Performance improvements for JVMTI watched fields</li> <li>Support for pause-less garbage collection on IBM Z systems</li> <li> ChaCha20 algorithm support for OpenSSL</li> <li> OpenSSL Digest algorithm disabled</li> <li>Support for OpenJDK HotSpot options</li> <li>Support for Transparent Huge Pages (THP)</li> <li> Support for low-overhead heap profiling (JEP 331)</li> <li>New Java memory map (jmap) tool</li> <li>Automatically setting an initial heap size</li> <li>Removal of -Xdiagnosticscollector option</li> <li>Change in behaviour of -XX:[+|-]IdleTuningCompactOnIdle</li> <li>Addition of heuristics for compaction during idle GC</li> <li>Change in shared classes behavior for checking timestamps of <code>jar</code> or <code>zip</code> files</li> </ul>"},{"location":"version0.15/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.15/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 0.15.0 and 0.15.1 supports OpenJDK 8, 11, and 12.</p> <p>Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 12</li> </ul> <p> Note: The binaries at AdoptOpenJDK are labeled 0.15.1 due to a missing change.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.15/#performance-improvements-for-jvmti-watched-fields","title":"Performance improvements for JVMTI watched fields","text":"<p>OpenJ9 version 0.14.0 introduced the <code>-XX:[+|-]JITInlineWatches</code> option, which, when enabled, turned on experimental JIT operations to improve the performance of JVMTI watched fields. Following successful results, this option is now enabled by default. This option is now also supported on z/OS\u00ae and Linux for IBM Z\u00ae, in addition to x86 platforms (Windows\u00ae, macOS\u00ae, and Linux).</p>"},{"location":"version0.15/#support-for-pause-less-garbage-collection-on-ibm-z-systems","title":"Support for pause-less garbage collection on IBM Z systems","text":"<p>Support for Concurrent scavenge mode is now extended to Linux on IBM Z\u00ae systems and z/OS\u00ae. For more information, see <code>-Xgc:concurrentScavenge</code>.</p>"},{"location":"version0.15/#chacha20-algorithm-support-for-openssl","title":"ChaCha20 algorithm support for OpenSSL","text":"<p>The ChaCha20 and ChaCha20-Poly1305 algorithms can now use OpenSSL on Java 11. For more information, see <code>-Djdk.nativeChaCha20</code>. </p>"},{"location":"version0.15/#openssl-digest-algorithm-disabled","title":"OpenSSL Digest algorithm disabled","text":"<p>Due to issue #5611, the Digest algorithm is disabled. This algorithm was disabled for Java 8 and 11 in release 0.14.2, which did not support Java 12.</p>"},{"location":"version0.15/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the <code>-XX:OnOutOfMemoryError</code> OpenJDK HotSpot option is now supported by OpenJ9.</p>"},{"location":"version0.15/#support-for-transparent-huge-pages-thp","title":"Support for Transparent Huge Pages (THP)","text":"<p>The VM now supports the allocation of huge pages on Linux when you use the <code>madvise</code> (<code>/sys/kernel/mm/transparent_hugepage/enabled</code>) setting. To enable this feature, set <code>-XX:+TransparentHugePage</code> on the command line when you start your application. This option is currently not enabled by default.</p>"},{"location":"version0.15/#support-for-low-overhead-heap-profiling","title":"Support for low-overhead heap profiling","text":"<p>JEP 331 provides a mechanism for sampling Java heap allocations with a low overhead via the JVM Tool Interface (JVMTI).</p> <p> Restrictions: JEP 331 is implemented for OpenJ9 with the following limitations:</p> <ul> <li>The <code>balanced</code> and <code>metronome</code> garbage collection policies are not supported.</li> <li>The JEP331 JVMTI agent and the Health Center agent both set a sampling interval, which by default is different. If both agents are used at the same time the Health Center agent will get incorrect results, unless the sampling intervals are adjusted to use the same value. </li> </ul>"},{"location":"version0.15/#new-java-memory-map-tool","title":"New Java memory map tool","text":"<p>The Java memory map (jmap) tool is similar to the HotSpot tool of the same name, and can be used to print statistics about classes on the heap, including the number of objects and their aggregate size. For usage information, see Java memory map (jmap) tool.</p>"},{"location":"version0.15/#automatically-setting-an-initial-heap-size","title":"Automatically setting an initial heap size","text":"<p>OpenJ9 can now learn and set an appropriate initial heap size for an application as an alternative to a user manually sizing and setting an <code>-Xms</code> value. The VM records the size of the heap when startup processing ends, writing this data to the shared classes cache. An average value is set over a few restarts, helping to ensure that the value used for the initial heap size is as accurate as possible. The heap size recorded is specific to the application command line, therefore a different hint is stored for every unique command line.</p> <p>To turn on this behavior, set the <code>-XX:+UseGCStartupHints</code> option on the command line when you start your application.</p>"},{"location":"version0.15/#removal-of-xdiagnosticscollector-option","title":"Removal of -Xdiagnosticscollector option","text":"<p>This option was redundant and has now been removed. If you try to use this option on the command line, the VM outputs this error message:</p> <p><code>JVMJ9VM007E Command-line option unrecognised: -Xdiagnosticscollector</code></p>"},{"location":"version0.15/#change-in-behaviour-of-xxidletuningcompactonidle","title":"Change in behaviour of -XX:IdleTuningCompactOnIdle","text":"<p>-XX:[+|-]IdleTuningCompactOnIdle is now no longer effective when -XX:+IdleTuningGcOnIdle is not specified.</p>"},{"location":"version0.15/#heuristics-for-compaction-during-idle-gc","title":"Heuristics for compaction during idle GC","text":"<p>OpenJ9 now automatically compacts the heap when certain triggers are met during idle garbage collection (GC). As a result of this change, <code>-XX:[+|-]IdleTuningCompactOnIdle</code> is deprecated.</p>"},{"location":"version0.15/#change-in-shared-classes-behavior-for-checking-timestamps-of-jar-or-zip-files","title":"Change in shared classes behavior for checking timestamps of <code>jar</code> or <code>zip</code> files","text":"<p>In earlier releases, the shared classes cache checks timestamps of <code>jar</code> or <code>zip</code> files every time a class is loaded and reloads a class if the timestamp has changed. This behavior is now changed; timestamps are checked only when <code>zip</code> or <code>jar</code> files are added to class loaders and used for the first time to look for a class, which can improve class-loading performance. If <code>jar</code> or <code>zip</code> files are updated after a class loader starts loading classes from them, an older version of the class might be loaded from the shared classes cache. To revert to the behavior of earlier releases, set the <code>-Xshareclasses:checkURLTimestamps</code> option on the command line when you start your application.</p> <p> Note: Multiple <code>-Xshareclasses:</code> options are not combined, only the last one is used.</p>"},{"location":"version0.15/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.14.0 and version 0.15.1 releases, see the Release notes.</p>"},{"location":"version0.16/","title":"Version 0.16.0","text":""},{"location":"version0.16/#whats-new-in-version-0160","title":"What's new in version 0.16.0","text":"<p>The following new features and notable changes since version 0.15.1 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Some class data sharing is enabled by default</li> <li>Automatic setting of initial heap size is enabled by default</li> <li>Option to share VM anonymous classes</li> <li>Performance improvements for JVMTI watched fields on Power Systems</li> <li>Linux on x86: Support for Transparent Huge Pages (THP)</li> <li>New Java\u2122 diagnostic command (<code>jcmd</code>) tool</li> <li>Changes to the shared classes cache generation number</li> <li> The <code>-Xverify:none</code> and <code>-noverify</code> options are deprecated</li> <li> New JDK 13 features</li> </ul>"},{"location":"version0.16/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.16/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.16.0 supports OpenJDK 13, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 13</li> </ul> <p>OpenJDK 13 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.15.2. Features mentioned in these release notes are not available in these builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.16.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.16/#some-class-data-sharing-is-enabled-by-default","title":"Some class data sharing is enabled by default","text":"<p>Class data sharing is enabled by default for bootstrap classes, unless your application is running in a container. You can use the <code>-Xshareclasses</code> option to change the default behavior, including using <code>-Xshareclasses:none</code> to disable all class data sharing. For more information, see Introduction to class data sharing.</p>"},{"location":"version0.16/#automatic-setting-of-initial-heap-size-is-enabled-by-default","title":"Automatic setting of initial heap size is enabled by default","text":"<p>OpenJ9 version 0.15.1 introduced the <code>-XX:[+|-]UseGCStartupHints</code> option, which, when enabled, turned on the automatic learning and setting of an appropriate heap size for an application. This option is now enabled by default.</p>"},{"location":"version0.16/#option-to-share-vm-anonymous-classes","title":"Option to share VM anonymous classes","text":"<p>Prior to version 0.16.0, anonymous classes, those created by <code>Unsafe.defineAnonymousClass</code>, were not stored in the shared classes cache. They are now stored there by default, which means they are available for ahead-of-time (AOT) compilation, potentially improving startup performance. A new command, -XX:[+|-]ShareAnonymousClasses, is introduced that enables you to stop anonymous classes being stored in the shared classes cache.</p>"},{"location":"version0.16/#performance-improvements-for-jvmti-watched-fields-on-power-systems","title":"Performance improvements for JVMTI watched fields on Power Systems","text":"<p>OpenJ9 version 0.14.0 introduced the <code>-XX:[+|-]JITInlineWatches</code> option, which turns on JIT operations to improve the performance of JVMTI watched fields. This option, which was enabled by default in version 0.15.1, is now also supported on AIX\u00ae and Linux on Power Systems\u2122.</p>"},{"location":"version0.16/#linux-on-x86-support-for-transparent-huge-pages-thp","title":"Linux\u00ae on x86: Support for Transparent Huge Pages (THP)","text":"<p>When you use the <code>madvise</code> (<code>/sys/kernel/mm/transparent_hugepage/enabled</code>) setting on Linux on x86 systems, THP is now enabled by default. To disable this feature, set <code>-XX:-TransparentHugePage</code> on the command line when you start your application. The THP setting on other systems remains disabled by default when you use <code>madvise</code>, but can be enabled by setting <code>-XX:+TransparentHugePage</code>.</p>"},{"location":"version0.16/#new-jcmd-tool","title":"New jcmd tool","text":"<p>For compatibility with the reference implementation, OpenJ9 now includes an independent implementation of the <code>jcmd</code> tool  for running diagnostic commands on a VM. For more information, see Java diagnostic command tool.</p>"},{"location":"version0.16/#changes-to-the-shared-classes-cache-generation-number","title":"Changes to the shared classes cache generation number","text":"<p>The format of classes that are stored in the shared classes cache is changed, which causes the JVM to create a new shared classes cache rather than re-creating or reusing an existing cache. To save space, you can remove all existing shared caches unless they are in use by an earlier release. As a result of the format change, a <code>layer</code> column now appears in the output of the <code>-Xshareclasses:listAllCaches</code> option. This change is to support a future enhancement.</p> <p>For more information about the <code>-Xshareclasses</code> option, including the <code>destroy</code> options that you can use to remove caches, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.16/#the-xverifynone-and-noverify-options-are-deprecated","title":"The <code>-Xverify:none</code> and <code>-noverify</code> options are deprecated","text":"<p>The option <code>-Xverify:none</code> (and its equivalent <code>-noverify</code>) is deprecated in Java 13. Both options might be removed in a future release. OpenJ9 issues a warning if these options are used in Java 13 and later versions. </p>"},{"location":"version0.16/#new-jdk-13-features","title":"New JDK 13 features","text":"<p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 13 with OpenJ9:</p> <ul> <li>JEP 353: Reimplement the Legacy Socket API</li> <li>JEP 354: Switch Expressions (Preview)</li> <li>JEP 355: Text Blocks (Preview)</li> </ul> <p>You can find the full list of features for JDK 13 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.16/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.15.1 and version 0.16.0 releases, see the Release notes.</p>"},{"location":"version0.17/","title":"Version 0.17.0","text":""},{"location":"version0.17/#whats-new-in-version-0170","title":"What's new in version 0.17.0","text":"<p>The following new features and notable changes since version 0.16.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New shared classes cache suboptions for layered caches</li> <li>New shared classes cache suboption to skip disk space check</li> <li>Option to share 'Unsafe' classes</li> <li>Option to record class relationships in the verifier</li> <li>Support for the IBM z15\u00ae processor</li> <li>Digest algorithm is re-enabled</li> <li>Direct Dump Reader (DDR) VM restriction removed</li> <li>The format of the HOOKS section of a Java dump has changed</li> <li>LUDCL caching disabled by default</li> </ul>"},{"location":"version0.17/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.17/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.17.0 supports OpenJDK 8, 11, and 13. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 13</li> </ul> <p> Note: The Windows\u00ae and macOS\u00ae binaries from the AdoptOpenJDK community for OpenJDK 8, 11, and 13 have been updated to OpenSSL v1.1.1d. Look for the following release names to identify these packages:</p> <ul> <li>OpenJDK 8: <code>jdk8u232-b09.1_openj9-0.17.0</code></li> <li>OpenJDK 11: <code>jdk-11.0.5+10.1_openj9-0.17.0</code></li> <li>OpenjDK 13: <code>jdk-13.0.1+9.1_openj9-0.17.0)</code></li> </ul> <p> Note: The last release of OpenJDK 8 and 11 from AdoptOpenJDK is Eclipse OpenJ9 0.15.1. To read about other features and changes in the VM since 0.15.1, check the Version 0.16.0 release notes too.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.17/#new-shared-classes-cache-suboptions-for-layered-caches","title":"New shared classes cache suboptions for layered caches","text":"<p>(Experimental, 64-bit only)</p> <p>New suboptions are available for creating layered caches, where a cache builds on another cache with the same name. You can use these suboptions to save space when building a Docker container, for example.</p> <p> Note: Because these suboptions are experimental, do not use them in a production environment.</p> <p>The new options are:</p> <ul> <li><code>createLayer</code></li> <li><code>layer=&lt;number&gt;</code> (see this section for more information about layered caches)</li> <li><code>printTopLayerStats</code></li> <li><code>destroyAllLayers</code></li> </ul>"},{"location":"version0.17/#new-shared-classes-cache-suboption-to-skip-disk-space-check","title":"New shared classes cache suboption to skip disk space check","text":"<p>When creating a persistent shared classes cache, the OpenJ9 VM checks that there is sufficient disk space available on the file system. For file systems that do not support the checking of free space, you can set the <code>-Xshareclasses:noPersistentDiskSpaceCheck</code> option, which causes the VM to skip the space checking operation. If there isn't enough disk space available when the cache is written, a SIGBUS or SIGSEGV signal occurs and the VM ends. For more information, see the -Xshareclasses:noPersistentDiskSpaceCheck option.</p>"},{"location":"version0.17/#option-to-share-unsafe-classes","title":"Option to share 'Unsafe' classes","text":"<p>Classes created through <code>Unsafe.defineClass</code> are now stored by default in the shared classes cache. You can use the <code>-XX:-ShareUnsafeClasses</code> option to change the default behavior. For more information, see -XX:[+|-]ShareUnsafeClasses.</p>"},{"location":"version0.17/#option-to-record-class-relationships-in-the-verifier","title":"Option to record class relationships in the verifier","text":"<p>A new command line option <code>-XX:+ClassRelationshipVerifier</code> allows you to record class relationships in the verifier, which avoids unnecessary class loading and reduces VM startup time. This is a new approach to bytecode verification that delays validating the relationships between classes until the classes are required to be loaded for a program's execution thus loading only those classes that are needed. For more information, see -XX:[+|-]ClassRelationshipVerifier.</p>"},{"location":"version0.17/#support-for-the-ibm-z15-processor","title":"Support for the IBM z15 processor","text":"<p>This release adds JIT compiler support for exploiting z15 instructions.</p>"},{"location":"version0.17/#digest-algorithm-is-re-enabled","title":"Digest algorithm is re-enabled","text":"<p>Issue #5611 is fixed, so support for the Digest algorithm is re-enabled. For more information about this support, see Cryptographic operations.</p>"},{"location":"version0.17/#direct-dump-reader-ddr-vm-restriction-removed","title":"Direct Dump Reader (DDR) VM restriction removed","text":"<p>Prior to this version, you had to use a 32-bit VM to look at a 32-bit core, and a 64-bit VM to look at a 64-bit core when using DDR. This restriction has now been removed.</p>"},{"location":"version0.17/#the-format-of-the-hooks-section-of-a-java-dump-has-changed","title":"The format of the HOOKS section of a Java dump has changed","text":"<p>The format of the <code>HOOKS</code> section of a Java dump, which shows internal VM event callbacks, has changed:</p> <ul> <li>Recorded times have been changed from milliseconds to microseconds to provide increased precision.</li> <li>A new field, <code>3HKTOTALTIME</code>, is included, which gives the total duration of previous events.</li> <li>The hook data is now reset after each Java dump.</li> </ul> <p>For more information and an example of the new format, see Java dump: HOOKS</p>"},{"location":"version0.17/#ludcl-caching-disabled-by-default","title":"LUDCL caching disabled by default","text":"<p>By caching the Latest User Defined Class Loader (LUDCL), Java applications that use deserialization extensively can see a performance improvement. This capability is controlled by the -Dcom.ibm.enableClassCaching system property and is now disabled by default due to issue #7332.</p> <p> Note: Versions of the documentation before 0.17.0 incorrectly identified this property as disabled by default when it was actually enabled by default in the VM.</p>"},{"location":"version0.17/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.16 and version 0.17.0 releases, see the Release notes.</p>"},{"location":"version0.18/","title":"Version 0.18.1","text":""},{"location":"version0.18/#whats-new-in-version-0181","title":"What's new in version 0.18.1","text":"<p>The following new features and notable changes since version 0.17.0 are included in this release:</p> <ul> <li>Binaries and supported environments</li> <li>Technical preview of JITServer technology</li> <li><code>jextract</code> now available on macOS\u00ae for OpenJDK version 8</li> <li>New shared-classes cache suboption to turn off timestamp checking</li> <li>Removal of restriction on layered shared cache</li> <li><code>-Xmso</code> 1 MB minimum value on z/OS\u00ae 64-bit</li> <li><code>jstat</code>: new Java\u2122 statistics monitoring tool</li> <li><code>-XX:+TransparentHugePage</code> is enabled by default on more Linux\u00ae systems</li> <li>New exit dump agent and <code>ExitOnOutOfMemoryError</code> option</li> <li>LUDCL caching enabled by default</li> <li>Terabytes suffix support for <code>-X</code> and <code>-XX</code> options that take a size</li> <li>Improved support for pause-less garbage collection</li> <li><code>-Xgc:noConcurrentScavenge</code> option</li> <li>Support for OpenJDK HotSpot options</li> <li>Shared classes cache suboptions for layered caches no longer experimental</li> <li><code>-Djava.lang.string.substring.nocopy</code> option</li> </ul>"},{"location":"version0.18/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.18/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 releases 0.18.0 and 0.18.1 support OpenJDK 8, 11, and 13. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 13</li> </ul> <p> Note: Binaries at AdoptOpenJDK that are labeled 0.18.1 include additional bug fixes. For more information, see the release notes.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.18/#technical-preview-of-jitserver-technology","title":"Technical preview of JITServer technology","text":"<p>A technical preview of JITServer technology is included in this release. It's currently available for OpenJDK 8 and OpenJDK 11 running on Linux on x86-64.</p> <p>JITServer technology decouples the JIT compiler from the VM and lets the JIT compiler run remotely in its own process. This mechanism prevents your Java application suffering possible negative effects due to CPU and memory consumption caused by JIT compilation. This technology can improve quality of service, robustness, and even performance of Java applications. For more information, see JITServer technology.</p>"},{"location":"version0.18/#jextract-now-available-on-macos-for-openjdk-version-8","title":"<code>jextract</code> now available on macOS for OpenJDK version 8","text":"<p>The <code>jextract</code> tool is now available on macOS platforms (as well as AIX\u00ae and Linux) for all current versions of OpenJDK: 8, 11, and 13.</p>"},{"location":"version0.18/#new-shared-classes-cache-suboption-to-turn-off-timestamp-checking","title":"New shared-classes cache suboption to turn off timestamp checking","text":"<p>You can set the <code>-Xshareclasses:noTimestampChecks</code> option to turn off timestamp checking in shared classes. For more information, see the -Xshareclasses:noTimestampChecks option.</p>"},{"location":"version0.18/#removal-of-restriction-on-layered-shared-cache","title":"Removal of restriction on layered shared cache","text":"<p>In the previous release, there is a restriction that the <code>jvmtiSharedCacheInfo.isCorrupt</code> field and the <code>SharedClassCacheInfo.isCacheCorrupt()</code> method cannot detect a corrupted cache that has a layer number other than <code>0</code>. This restriction is now removed. See the Shared classes API documentation. </p>"},{"location":"version0.18/#-xmso-1-mb-minimum-value-on-zos-64-bit","title":"<code>-Xmso</code> 1 MB minimum value on z/OS 64-bit","text":"<p>On z/OS 64-bit, <code>-Xmso</code> has a 1 MB minimum value, to match the minimum stack space provided by the operating system. If you set a value smaller than 1 MB, the value is ignored.</p>"},{"location":"version0.18/#jstat-new-java-statistics-monitoring-tool","title":"<code>jstat</code>: new Java statistics monitoring tool","text":"<p>For compatibility with the HotSpot implementation, OpenJ9 now includes an independent implementation of the <code>jstat</code> tool for retrieving statistics on a VM. For more information, see Java statistics monitoring tool.</p>"},{"location":"version0.18/#-xxtransparenthugepage-is-enabled-by-default-on-more-linux-systems","title":"<code>-XX:+TransparentHugePage</code> is enabled by default on more Linux systems","text":"<p>-XX:+TransparentHugePage is enabled by default on Linux systems for POWER\u00ae and IBM Z\u00ae as well as x86 systems. This option takes affect only when Transparent Huge Pages (THP) is set to <code>madvise</code> on your system. When Transparent Huge Pages are used, your application footprint might increase.</p>"},{"location":"version0.18/#new-exit-dump-agent-and-exitonoutofmemoryerror-option","title":"New exit dump agent and <code>ExitOnOutOfMemoryError</code> option","text":"<p>The new exit dump agent shuts down the VM when the specified event occurs. The exit agent is at priority level 0 and the tool agent has been moved to priority level 1 to aid in mimicking the behavior of HotSpot options. For more information about dump agents, see <code>-Xdump</code>.</p> <p>OpenJ9 now supports the HotSpot option <code>-XX:[+|-]ExitOnOutOfMemoryError</code>. You can set this option to have the VM shut down when a <code>java.lang.OutOfMemory</code> error is thrown by the VM or in Java code. The exit dump agent is used in the implementation of <code>-XX:[+|-]ExitOnOutOfMemoryError</code>.</p>"},{"location":"version0.18/#ludcl-caching-enabled-by-default","title":"LUDCL caching enabled by default","text":"<p>By caching the Latest User Defined Class Loader (LUDCL), Java applications that use deserialization extensively can see a performance improvement. This capability is controlled by the <code>-Dcom.ibm.enableClassCaching</code> system property and is now enabled by default. This feature was disabled for the 0.17.0 release due to issue #7332 which has now been resolved.</p>"},{"location":"version0.18/#terabytes-suffix-support-for-x-and-xx-options-that-take-a-size","title":"Terabytes suffix support for <code>-X</code> and <code>-XX</code> options that take a size","text":"<p>OpenJ9 now supports 't' and 'T' suffixes (indicating terabytes) for <code>-X</code> and <code>-XX</code> options that take a <code>&lt;size&gt;</code> parameter.</p>"},{"location":"version0.18/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Support for Concurrent scavenge mode is now extended to macOS. For more information, see <code>-Xgc:concurrentScavenge</code>.</p>"},{"location":"version0.18/#-xgcnoconcurrentscavenge-option","title":"<code>-Xgc:noConcurrentScavenge</code> option","text":"<p>The previously undocumented option <code>-Xgc:noConcurrentScavenge</code> disables pause-less garbage collection.</p>"},{"location":"version0.18/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li>-XX:ParallelGCThreads</li> <li>-XX:ConcGCThreads</li> <li>-XX:ParallelCMSThreads</li> </ul>"},{"location":"version0.18/#shared-classes-cache-suboptions-for-layered-caches-no-longer-experimental","title":"Shared classes cache suboptions for layered caches no longer experimental","text":"<p>The suboptions for creating layered caches are no longer marked experimental.</p> <p>The new options are:</p> <ul> <li><code>createLayer</code></li> <li><code>layer=&lt;number&gt;</code> (see this section for more information about layered caches)</li> <li><code>printTopLayerStats</code></li> <li><code>destroyAllLayers</code></li> </ul>"},{"location":"version0.18/#-djavalangstringsubstringnocopy-option","title":"<code>-Djava.lang.string.substring.nocopy</code> option","text":"<p>The previously undocumented Java 8 option <code>-Djava.lang.string.substring.nocopy=true</code> avoids String sharing by String.substring(), which is the same behavior as the Oracle HotSpot VM.</p>"},{"location":"version0.18/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.17.0 and version 0.18.0 releases, see the Release notes.</p>"},{"location":"version0.19/","title":"Version 0.19.0","text":""},{"location":"version0.19/#whats-new-in-version-0190","title":"What's new in version 0.19.0","text":"<p>The following new features and notable changes since version 0.18.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Option to print code cache usage to <code>stderr</code> at VM shutdown</li> <li> <code>StringBuffer</code> and <code>StringBuilder</code> above 1 G grow to the maximum size</li> <li> jpackage packaging tool platform support</li> <li> Extended messages for <code>NullPointerException</code> not yet implemented</li> <li>Compiler changes for Linux</li> <li> New JDK 14 features</li> </ul>"},{"location":"version0.19/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.19/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.19.0 supports OpenJDK 14, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 14</li> </ul> <p>OpenJDK 14 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.18.0. Features mentioned in these release notes are not available in these builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.19.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.19/#option-to-print-code-cache-usage-to-stderr-at-vm-shutdown","title":"Option to print code cache usage to <code>stderr</code> at VM shutdown","text":"<p>A new command line option -XX:+PrintCodeCache allows you to print the code cache memory usage to <code>stderr</code> when the VM shuts down.</p>"},{"location":"version0.19/#stringbuffer-and-stringbuilder-above-1-g-grow-to-the-maximum-size","title":"<code>StringBuffer</code> and <code>StringBuilder</code> above 1 G grow to the maximum size","text":"<p>A 1 G <code>char[]</code> or larger <code>StringBuffer</code> and <code>StringBuilder</code> now immediately grows to the maximum possible size for all current versions of Java, including Java 8. For Java 8 only, you can revert to the previous behavior of growing only as much as necessary to accommodate the <code>String</code> being added, by using the option, <code>-Djava.lang.stringBuffer.growAggressively=false</code>.</p>"},{"location":"version0.19/#jpackage-packaging-tool-platform-support","title":"jpackage packaging tool platform support","text":"<p>The <code>jpackage</code> utility is described in JEP 343 as a tool that \"packages a Java application into a platform-specific package that includes all of the necessary dependencies.\" Full details of the tool are available at JEP 343: Packaging Tool. Be aware that <code>jpackage</code> is supported on only the following OpenJ9 platforms: Linux\u00ae, macOS\u00ae, and Windows\u2122. It is not supported on AIX\u00ae or z/OS\u00ae platforms.</p>"},{"location":"version0.19/#extended-messages-for-nullpointerexception-not-yet-implemented","title":"Extended messages for <code>NullPointerException</code> not yet implemented","text":"<p>JEP 358: Helpful NullPointerExceptions provides extended messages when a <code>NullPointerException</code> is generated by the Java 14 VM and you have enabled the feature. However, be aware that this is not implemented in OpenJ9 at this time.</p>"},{"location":"version0.19/#compiler-changes-for-linux","title":"Compiler changes for Linux","text":"<p>Linux x86 64-bit, Linux on POWER\u00ae LE 64-bit, and Linux on IBM Z\u00ae 64-bit have all moved to the gcc 7.5 compiler. See Supported environments.</p>"},{"location":"version0.19/#new-jdk-14-features","title":"New JDK 14 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 343: Packaging Tool (Incubator) Restrictions: <code>jpackage</code> is supported on only the following OpenJ9 platforms: Linux\u00ae, macOS\u00ae, and Windows\u2122. It is not supported on AIX\u00ae or z/OS\u00ae platforms.</li> <li>JEP 352: Non-Volatile Mapped Byte Buffers</li> <li>JEP 358: Helpful NullPointerExceptions</li> <li>JEP 359: Records (Preview)</li> </ul> <p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 14 with OpenJ9:</p> <ul> <li>JEP 305: Pattern Matching for instanceof (Preview) </li> <li>JEP 361: Switch Expressions (Standard)</li> <li>JEP 367: Remove the Pack200 Tools and API</li> <li>JEP 368: Text Blocks (Second Preview)</li> </ul> <p>You can find the full list of features for JDK 14 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.19/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.18.0 and version 0.19.0 releases, see the Release notes.</p>"},{"location":"version0.20/","title":"Version 0.20.0","text":""},{"location":"version0.20/#whats-new-in-version-0200","title":"What's new in version 0.20.0","text":"<p>The following new features and notable changes since version 0.19.0 are included in this release:</p> <ul> <li>Binaries and supported environments</li> <li> Limited support for 64-bit Linux on ARM</li> <li><code>-XX:[+|-]ExitOnOutOfMemoryError</code> option behavior update</li> <li>New <code>-XX:[+|-]GlobalLockReservation</code> option added</li> <li> Change to default maximum heap size for Java 8</li> <li>Change to <code>jcmd</code> default options</li> </ul>"},{"location":"version0.20/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.20/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.20.0 supports OpenJDK 8, 11, and 14. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 14</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.20/#limited-support-for-64-bit-linux-on-arm","title":"Limited support for 64-bit Linux on ARM","text":"<p>Limited support is available in this release for the 64-bit ARM (AArch64) architecture. An early access build on OpenJDK 11 is available from the AdoptOpenJDK community. See the OpenJ9 release notes for any known issues that are still being worked on before this platform is fully supported.  </p>"},{"location":"version0.20/#-xx-exitonoutofmemoryerror-option-behavior-update","title":"<code>-XX:[+|-]ExitOnOutOfMemoryError</code> option behavior update","text":"<p>The <code>-XX:[+|-]ExitOnOutOfMemoryError</code> option is updated to exit only on VM <code>OutOfMemoryErrors</code> instead of both VM and Java\u2122 thrown errors to match the HotSpot option. See <code>-XX:[+|-]ExitOnOutOfMemoryError</code> for more details about this option.</p>"},{"location":"version0.20/#new-xx-globallockreservation-option-added","title":"New <code>-XX:[+|-]GlobalLockReservation</code> option added","text":"<p>(AIX\u00ae and Linux on Power Systems\u2122 only)</p> <p>Option <code>-XX:[+|-]GlobalLockReservation</code> enables a new optimization targeted towards more efficient handling of locking and unlocking Java  objects. See <code>-XX:[+|-]GlobalLockReservation</code> for more details about this option.</p>"},{"location":"version0.20/#change-to-default-maximum-heap-size-for-java-8","title":"Change to default maximum heap size for Java 8","text":"<p>For consistency with Java 11, the default maximum heap size (<code>-Xmx</code>) is changed to be 25% of the available memory with a maximum of 25 GB. Where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB. If you want to revert to the default setting in earlier releases of OpenJ9, use the -XX:+OriginalJDK8HeapSizeCompatibilityMode option.</p>"},{"location":"version0.20/#change-to-jcmd-default-options","title":"Change to <code>jcmd</code> default options","text":"<p>The Java diagnostic command (<code>jcmd</code>) tool no longer requires a filename when used with the <code>Dump.java</code>, <code>Dump.snap</code>, or <code>Dump.system</code> options. See <code>jcmd</code> for more information about the tool.</p>"},{"location":"version0.20/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.19.0 and version 0.20.0 releases, see the Release notes.</p>"},{"location":"version0.21/","title":"Version 0.21.0","text":""},{"location":"version0.21/#whats-new-in-version-0210","title":"What's new in version 0.21.0","text":"<p>The following new features and notable changes since version 0.20.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Application Programming Interface (API) documentation</li> <li>Performance improvements</li> <li>New <code>-XX:[+|-]HandleSIGABRT</code> option added</li> <li>New <code>-XX:[+|-]PrintFlagsFinal</code> option added</li> <li>Update to <code>NoClassDefFoundError</code> exception message</li> <li>macOS\u00ae shared libraries version updated</li> </ul>"},{"location":"version0.21/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.21/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.21.0 supports OpenJDK 8, 11, and 14. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 14</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.21/#application-programming-interface-api-documentation","title":"Application Programming Interface (API) documentation","text":"<p>API documentation that applies to OpenJ9 can now be found in this user documentation for both JDK 8 and JDK 11. The documentation includes links to Oracle API documentation for information that is not specific to OpenJ9. See API overview.</p>"},{"location":"version0.21/#performance-improvements","title":"Performance improvements","text":"<ul> <li> <p>If the -Xtune:virtualized command line option is used, the default JIT scratch memory limit is now reduced from 256 MB to 16 MB. This reduces the peak from JIT compilation activity, allowing you to size containers more easily, based on the particular application's memory usage.</p> </li> <li> <p>If the JIT is running in a container and no swap space is defined, the JIT dynamically adjusts its scratch memory consumption based on the amount of free physical memory available, to avoid out-of-memory (OOM) occurrences.</p> </li> <li> <p>Several performance features were added to the AArch64 JIT compiler implementation that led to a throughput improvement on multiple applications of at least 20%. The most notable improvements were seen in global register allocation, recompilation (without profiling), CUDA support, concurrent scavenge GC policy, and the inlined code sequence for object allocations.</p> </li> </ul>"},{"location":"version0.21/#new-xx-handlesigabrt-option-added","title":"New <code>-XX:[+|-]HandleSIGABRT</code> option added","text":"<p>This option affects the handling of the operating system signal <code>SIGABRT</code>. For compatibility with the reference implementation, set <code>-XX:-HandleSIGABRT</code>. For more information, see <code>-XX:[+|-]HandleSIGABRT</code>. </p>"},{"location":"version0.21/#new-xx-printflagsfinal-option-added","title":"New <code>-XX:[+|-]PrintFlagsFinal</code> option added","text":"<p>This release provides an initial implementation of the <code>-XX:[+|-]PrintFlagsFinal</code> option. It is currently incomplete and outputs only a subset of parameters. Over time, we expect more options to be added to the output. See <code>-XX:[+|-]PrintFlagsFinal</code> for more details about this option.</p>"},{"location":"version0.21/#update-to-noclassdeffounderror-exception-message","title":"Update to <code>NoClassDefFoundError</code> exception message","text":"<p>The order in which class names are printed in a <code>NoClassDefFoundError</code> exception message now matches the output reported by HotSpot.</p> <p>For example, in the following exception message:</p> <pre><code>java.lang.NoClassDefFoundError: mypackage/Main (wrong name: Main)\n</code></pre> <p><code>mypackage/Main</code> is the class name encountered by the VM in the <code>.class</code> file, but \"wrong name\" <code>Main</code> was the provided class name. Prior to this update to the exception message, the encountered class name and the provided class name were swapped in the <code>NoClassDefFoundError</code> exception message.</p>"},{"location":"version0.21/#macos-shared-libraries-version-updated","title":"macOS shared libraries version updated","text":"<p>The version information for shared libraries on macOS has been updated from 0.0.0 to 1.0.0. If an application has linked against a shared library from a previous OpenJ9 release, it needs to be re-linked against the new release. Failure to re-link causes an error <code>Incompatible library version</code>, <code>requires version 0.0.0</code>.</p>"},{"location":"version0.21/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.20.0 and version 0.21.0 releases, see the Release notes.</p>"},{"location":"version0.22/","title":"Version 0.22.0","text":""},{"location":"version0.22/#whats-new-in-version-0220","title":"What's new in version 0.22.0","text":"<p>The following new features and notable changes since version 0.21.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Performance improvements</li> <li>New <code>-XX:[+|-]PortableSharedCache</code> option added</li> <li>Methods in <code>com.ibm.lang.management.MemoryMXBean</code> deprecated and replaced</li> <li> <code>java.lang.System.mapLibraryName()</code> string suffix</li> <li> New JDK 15 features</li> </ul>"},{"location":"version0.22/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.22/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.22.0 supports OpenJDK 15. Binaries are available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 15</li> </ul> <p>OpenJDK 15 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.21.0. Features mentioned in these release notes are not available in these Java 8 and 11 builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.22.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.22/#performance-improvements","title":"Performance improvements","text":"<p>The performance of zero initializing Java heap memory improved on the IBM Z\u00ae platform because of a change to use <code>memset</code> instead of an outdated handcrafted assembly sequence in the JVM.</p>"},{"location":"version0.22/#new-xx-portablesharedcache-option-added","title":"New <code>-XX:[+|-]PortableSharedCache</code> option added","text":"<p>On x86 only, the <code>-XX:[+|-]PortableSharedCache</code> option enables you to choose whether AOT code should be generated using an older processor (Intel\u00ae Sandybridge) feature set, which therefore allows the AOT code to be portable. This feature is particularly relevant for packaging a shared classes cache into a container image (for example, applications deployed on the cloud in the form of Docker containers) because the processor on which the container image is built is likely to be different from the processor on which the container is deployed. For more information, see <code>-XX:[+|-]PortableSharedCache</code>.</p>"},{"location":"version0.22/#methods-in-comibmlangmanagementmemorymxbean-deprecated-and-replaced","title":"Methods in <code>com.ibm.lang.management.MemoryMXBean</code> deprecated and replaced","text":"<p>The methods <code>com.ibm.lang.management.MemoryMXBean.getGCMasterThreadCpuUsed()</code> and <code>com.ibm.lang.management.MemoryMXBean.getGCSlaveThreadsCpuUsed()</code> are deprecated for removal in Java 16. The recommended methods to be used are <code>com.ibm.lang.management.MemoryMXBean.getGCMainThreadCpuUsed()</code> and <code>com.ibm.lang.management.MemoryMXBean.getGCWorkerThreadsCpuUsed()</code> respectively.</p> <p>For more information see Java 8: <code>com.ibm.lang.management.MemoryMXBean</code> and for Java 11: <code>com.ibm.lang.management.MemoryMXBean</code></p>"},{"location":"version0.22/#javalangsystemmaplibraryname-string-suffix","title":"<code>java.lang.System.mapLibraryName()</code> string suffix","text":"<p>On AIX\u00ae systems, <code>java.lang.System.mapLibraryName(libname)</code> returns a representation of a native library in a platform-specific string with a <code>.so</code> suffix.</p>"},{"location":"version0.22/#new-jdk-15-features","title":"New JDK 15 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 360: Sealed Classes (Preview)</li> <li>JEP 371: Hidden Classes</li> <li>JEP 384: Records (Second Preview)</li> </ul> <p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 14 with OpenJ9:</p> <ul> <li>JEP 339: Edwards-Curve Digital Signature Algorithm (EdDSA) </li> <li>JEP 372: Remove the Nashorn JavaScript Engine</li> <li>JEP 373: Reimplement the Legacy DatagramSocket API</li> <li>JEP 375: Pattern Matching for instanceof (Second Preview)</li> <li>JEP 378: Text Blocks</li> <li>JEP 385: Deprecate RMI Activation for Removal</li> </ul> <p>You can find the full list of features for JDK 15 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.22/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.21.0 and version 0.22.0 releases, see the Release notes.</p>"},{"location":"version0.23/","title":"Version 0.23.0","text":""},{"location":"version0.23/#whats-new-in-version-0230","title":"What's new in version 0.23.0","text":"<p>The following new features and notable changes since version 0.22.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li><code>-XX:[+|-]PortableSharedCache</code> option behavior update</li> <li><code>-XX:[+|-]IdleTuningCompactOnIdle</code> option now inactive</li> <li>Support for OpenJDK HotSpot options</li> <li>Extended platform support for the JITServer technology preview</li> </ul>"},{"location":"version0.23/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.23/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.23.0 supports OpenJDK 8, 11, and 15. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 15</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.23/#-xx-portablesharedcache-option-behavior-update","title":"<code>-XX:[+|-]PortableSharedCache</code> option behavior update","text":"<p>The <code>-XX:[+|-]PortableSharedCache</code> option is updated to improve the portability of AOT-compiled code further. This update allows AOT-compiled code to be portable across OpenJ9 VMs that use compressed references and have a heap size of 1 MB to 28 GB when this option is enabled. This option might introduce a small (1-2%) steady-state throughput penalty when compressed references are used and the heap size is between 1 MB and 3 GB. See <code>-XX:[+|-]PortableSharedCache</code> for more details about this option.</p>"},{"location":"version0.23/#-xx-idletuningcompactonidle-option-now-inactive","title":"<code>-XX:[+|-]IdleTuningCompactOnIdle</code> option now inactive","text":"<p>Setting the <code>-XX:[+|-]IdleTuningCompactOnIdle</code> option now has no effect. A compaction is triggered by internal heuristics that look into the number of fragmented pages. Typically there is no need to force a compaction. This option was deprecated in release 0.15.0, and will be removed in the future. See <code>-XX:[+|-]IdleTuningCompactOnIdle</code> for details about this option.</p>"},{"location":"version0.23/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li><code>-XX:[+|-]AlwaysPreTouch</code></li> </ul>"},{"location":"version0.23/#extended-platform-support-for-the-jitserver-technology-preview","title":"Extended platform support for the JITServer technology preview","text":"<p>Platform support for the JITServer technology preview is now extended to 64-bit Linux\u00ae on IBM Power\u00ae systems, and 64-bit Linux on IBM Z\u00ae systems. JITServer decouples the JIT compiler from the OpenJ9 VM, freeing up CPU and memory for an application. JITServer runs in its own process, either locally or on a remote machine, where resources can be separately managed. This preview was initially introduced in Eclipse OpenJ9 V0.18.1 for Linux on 64-bit x86 systems. For more information, see JITServer technology (technical preview).</p>"},{"location":"version0.23/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.22.0 and version 0.23.0 releases, see the Release notes.</p>"},{"location":"version0.24/","title":"Version 0.24.0","text":""},{"location":"version0.24/#whats-new-in-version-0240","title":"What's new in version 0.24.0","text":"<p>The following new features and notable changes since version 0.23.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Changes to message logging</li> <li>Support for the <code>JAVA_OPTIONS</code> environment variable</li> <li><code>-XX:[+|-]PortableSharedCache</code> option support update</li> <li> <code>-XX:[+|-]ShareAnonymousClasses</code> option behavior update</li> <li>Additional parameters for <code>jcmd Dump</code> commands</li> <li>Change in behavior for the <code>jextract</code> utility</li> <li>New diagnostic suboption for <code>-Xcheck:jni</code> for fatal JNI errors</li> <li>Improved diagnostic information in a Java dump file on processor features</li> <li>Helm chart available for deploying JITServer</li> </ul>"},{"location":"version0.24/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.24/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.24.0 supports OpenJDK 8, 11, and 15.</p> <p>Windows\u00ae builds for Java\u2122 8 are now compiled with Microsoft\u00ae Visual Studio 2013. The Visual Studio redistributable files included with the build are updated to match.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.24/#changes-to-message-logging","title":"Changes to message logging","text":"<p>JEP 158 introduces the <code>-Xlog</code> option as a common logging system for all components of a Java virtual machine. To avoid confusion with the reference implementation, the <code>-Xsyslog</code> option replaces the existing OpenJ9 <code>-Xlog</code> option for message logging. For compatibility with the reference implementation, a limited set of <code>-Xlog</code> suboptions are supported.</p> <p>A new option, <code>-XX:[+|-]LegacyXlogOption</code>, controls how <code>-Xlog</code> is processed when set on the command line.</p> <ul> <li>When <code>-XX:-LegacyXlogOption</code> is set, the <code>-Xlog</code> option is recognized when a form of this option  runs that requests garbage collection (GC) logging.<ul> <li>If any <code>-Xlog</code> GC log requests are set, these options are mapped to the equivalent OpenJ9 verbose GC command line options. For more information, see <code>-Xlog</code>.</li> </ul> </li> <li>Setting <code>-XX:+LegacyXLogOption</code> provides backward compatibility with the legacy <code>-Xlog</code> option, which can be specified on the command line with the parameters documented for the <code>-Xsyslog</code> option. That is, these options can be used interchangeably. If you rely on the legacy <code>-Xlog</code> option and cannot easily migrate to the <code>-Xsyslog</code> option, you must set this option on the command line.</li> </ul>"},{"location":"version0.24/#support-for-the-java_options-environment-variable","title":"Support for the <code>JAVA_OPTIONS</code> environment variable","text":"<p>For compatibility with the reference implementation, OpenJ9 now supports the <code>JAVA_OPTIONS</code> environment variable. This environment variable  can be used to set command line options, as described in OpenJ9 command-line options and Environment variables. Options specified by <code>JAVA_OPTIONS</code> can be overridden by options specified by <code>OPENJ9_JAVA_OPTIONS</code>.</p>"},{"location":"version0.24/#-xx-portablesharedcache-option-support-update","title":"<code>-XX:[+|-]PortableSharedCache</code> option support update","text":"<p>The <code>-XX:[+|-]PortableSharedCache</code> option is now supported on IBM Z\u00ae and POWER\u00ae platforms. AOT-compiled code that is generated with this option is guaranteed to be portable across IBM z10 or newer microarchitectures on IBM Z platforms and IBM POWER8\u00ae or newer microarchitectures on POWER platforms. See <code>-XX:[+|-]PortableSharedCache</code> for more details about this option.</p>"},{"location":"version0.24/#-xx-shareanonymousclasses-option-behavior-update","title":"<code>-XX:[+|-]ShareAnonymousClasses</code> option behavior update","text":"<p>In earlier releases of OpenJ9, the <code>-XX:[+|-]ShareAnonymousClasses</code> option enables and disables the storage of VM anonymous classes in the shared classes cache. From OpenJ9 0.24.0 for OpenJDK 15 binaries, this option also controls the storage of hidden classes. See <code>-XX:[+|-]ShareAnonymousClasses</code> for more details about this option.</p>"},{"location":"version0.24/#additional-parameters-for-jcmd-dump-commands","title":"Additional parameters for <code>jcmd Dump</code> commands","text":"<p>You can now include additional parameters for <code>jcmd Dump</code> commands as indicated in the following list:</p> <ul> <li><code>Dump.system</code>, <code>Dump.heap</code>, <code>Dump.java</code>, and <code>Dump.snap</code> accept an optional <code>request=&lt;requests&gt;</code> parameter.</li> <li><code>Dump.heap</code> accepts an optional <code>opts=&lt;options&gt;</code> parameter.</li> </ul> <p>These parameters, including the <code>&lt;file path&gt;</code> parameter, can be in any order. The default for both system and heap dumps is now: <code>request=exclusive+prepwalk</code>. For further details, refer to the following <code>-Xdump</code> suboptions: <code>request=&lt;requests&gt;</code> and <code>opts=&lt;options&gt;</code>. For more information about <code>jcmd</code>, see Java diagnostic command (jcmd) tool.</p>"},{"location":"version0.24/#change-in-behavior-for-the-jextract-utility","title":"Change in behavior for the <code>jextract</code> utility","text":"<p>The <code>jextract</code> utility gathers relevant files following a system dump to assist with problem determination. It is important that the <code>jextract</code> utility is run from the same SDK that generated the dump. From this release, if the build ID of the <code>jextract</code> utility does not match the build ID of the SDK that is recorded in the system dump, an exception message is generated. To force <code>jextract</code> to continue, a new option, <code>-r</code>, is introduced. For more information, see Dump extractor.</p>"},{"location":"version0.24/#new-diagnostic-suboption-for-xcheckjni-for-fatal-jni-errors","title":"New diagnostic suboption for <code>-Xcheck:jni</code> for fatal JNI errors","text":"<p>A new <code>abortonerror</code> suboption for <code>-Xcheck:jni</code> provides diagnostic data when fatal JNI errors occur. For more information, run <code>-Xcheck:jni:help</code>.</p>"},{"location":"version0.24/#improved-diagnostic-information-in-a-java-dump-file-on-processor-features","title":"Improved diagnostic information in a Java dump file on processor features","text":"<p>The ENVINFO section of a Java dump file now includes further information about processor features. This information helps to diagnose problems associated with JIT and AOT compilations that depend on underlying hardware. For an example that shows the information provided when JIT is enabled, see the CPU Information (<code>2CIJITFEATURE</code>,<code>2CIAOTFEATURE</code>) section in the Java dump topic.</p>"},{"location":"version0.24/#helm-chart-available-for-deploying-jitserver","title":"Helm chart available for deploying JITServer","text":"<p>A Helm Chart is now available for easier deployment of JITServer technology in a Kubernetes or OpenShift cluster. You can find the chart (openj9-jitserver-chart) in the JITServer Helm repository, which contains a complete set of usage instructions. For an introduction to JITServer technology, see JITServer (tech. preview).</p>"},{"location":"version0.24/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.23.0 and version 0.24.0 releases, see the Release notes.</p>"},{"location":"version0.25/","title":"Version 0.25.0","text":""},{"location":"version0.25/#whats-new-in-version-0250","title":"What's new in version 0.25.0","text":"<p>The following new features and notable changes since version 0.24.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> New JDK 16 features</li> <li> Support for the <code>-verbose:module</code> option</li> <li>Enabling <code>zlibNX</code> hardware-accelerated data compression and decompression on AIX</li> <li>z/OS support for the <code>%sysname</code> dump token</li> <li>Single build for compressed references and non-compressed references</li> </ul>"},{"location":"version0.25/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.25/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.25.0 supports OpenJDK 16. OpenJDK 16 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 release 0.25.0, testing at the project is not complete and therefore support for new features that apply to these Java versions is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.25/#new-jdk-16-features","title":"New JDK 16 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 338: Vector API (incubator)<ul> <li>OpenJ9 adds optimizations for this feature.</li> </ul> </li> <li>JEP 390: Warnings for value-based classes<ul> <li>OpenJ9 adds option <code>-XX:DiagnoseSyncOnValueBasedClasses=&lt;number&gt;</code> for compatibility with the reference implementation.</li> </ul> </li> <li>JEP 395: Records</li> <li>JEP 397: Sealed Classes (second preview)</li> </ul> <p>The following features will be supported by OpenJ9 in a future release:</p> <ul> <li>JEP 389: Foreign linker API (incubator)</li> <li>JEP 393: Foreign-memory access API (third incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 16 with OpenJ9:</p> <ul> <li>JEP 347: Enable C++ 14 language features</li> <li>JEP 380: Unix-domain socket channels</li> <li>JEP 394: Pattern matching for <code>instanceof</code></li> <li>JEP 396: Strongly encapsulate JDK internals by default</li> <li>JEP 392: Packaging tool<ul> <li>(Linux\u00ae, macOS\u00ae, and Windows\u2122 only) Promoted from incubation to a production-ready feature in this release. See Using <code>jpackage</code> for details.</li> </ul> </li> </ul> <p>You can find the full list of features for JDK 16 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p> <p> Note: Applications might be adversely affected by JEP 396 if they make use of internal APIs. You should update your application to use standard APIs. To temporarily work around this problem, set <code>--illegal-access=permit</code> on the command line, which prints a warning that is similar to the following example when an illegal access call is made:</p> <pre><code>WARNING: An illegal reflective access operation has occurred\nWARNING: Illegal reflective access by org.openj9.test.com.ibm.jit.Test_JITHelpers (file:/home/jenkins/workspace/Test_openjdk11_j9.functional_ppc64_aix_Nightly_testList_1/jvmtest/functional/Java8andUp/GeneralTest.jar) to field java.lang.String.value\nWARNING: Please consider reporting this to the maintainers of org.openj9.test.com.ibm.jit.Test_JITHelpers\nWARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations\nWARNING: All illegal access operations will be denied in a future release\n</code></pre>"},{"location":"version0.25/#support-for-the-verbosemodule-option","title":"Support for the <code>-verbose:module</code> option","text":"<p>The <code>-verbose:module</code> option is now supported for Java 11 and later releases. This option writes information to <code>stderr</code> for each module that is loaded and unloaded.</p>"},{"location":"version0.25/#enabling-zlibnx-hardware-accelerated-data-compression-and-decompression-on-aix","title":"Enabling <code>zlibNX</code> hardware-accelerated data compression and decompression on AIX","text":"<p>By default, AIX\u00ae uses the system <code>zlib</code> library for data compression and decompression.</p> <p>On systems that contain the Nest accelerator (NX) co-processor, OpenJ9 now uses the <code>zlibNX</code> library instead, if it is installed. To learn more about hardware acceleration and the <code>zlibNX</code> library, see Hardware acceleration.</p>"},{"location":"version0.25/#zos-support-for-the-sysname-dump-token","title":"z/OS support for the <code>%sysname</code> dump token","text":"<p>The <code>%sysname</code> dump token is added on z/OS, which equates to the SYSNAME sysparm. See Dump agent tokens.</p>"},{"location":"version0.25/#single-build-for-compressed-references-and-non-compressed-references","title":"Single build for compressed references and non-compressed references","text":"<p>A single build now supports both compressed references and non-compressed references. The object reference mode is selected at run time based on the specified heap size (<code>-Xmx</code>) or by using command-line options that control the selection of compressed references.</p> <p>If you used a large heap build for an earlier release of OpenJ9 because you did not require compressed references, you might need to turn it off if compressed references mode is being selected automatically at run time. Use the <code>-Xnocompressedrefs</code> option when you start your application.</p> <p>The <code>compressedrefs</code> directory is no longer present in the single build.</p> <p>To learn about the benefits of using compressed references, see Compressed references.</p>"},{"location":"version0.25/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.24.0 and version 0.25.0 releases, see the Release notes.</p>"},{"location":"version0.26/","title":"Version 0.26.0","text":""},{"location":"version0.26/#whats-new-in-version-0260","title":"What's new in version 0.26.0","text":"<p>The following new features and notable changes since version 0.25.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Dump extractor tool deprecated</li> </ul>"},{"location":"version0.26/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.26/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.26.0 supports OpenJDK 8, 11, and 16.</p> <p>For OpenJDK 8 and 11 builds that contain OpenJ9, see Version 0.25.0 for additional changes that have now been fully tested for these versions.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.26/#dump-extractor-tool-deprecated","title":"Dump extractor tool deprecated","text":"<p>The dump extractor tool, <code>jextract</code>, is deprecated in this release and replaced with the <code>jpackcore</code> tool. This tool uses the same syntax and parameters as <code>jextract</code> to collect diagnostic files for analysis. The change is necessary because the reference implementation will be introducing a tool in a future release that is also called <code>jextract</code>.</p> <p>For more information, see Dump extractor.</p>"},{"location":"version0.26/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.25.0 and v0.26.0 releases, see the Release notes.</p>"},{"location":"version0.27/","title":"Version 0.27.1","text":""},{"location":"version0.27/#whats-new-in-version-0271","title":"What's new in version 0.27.1","text":"<p>The following new features and notable changes since version 0.26.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New <code>-XX:[+|-]AdaptiveGCThreading</code> option added</li> <li>Improved time zone information added to Java dump files</li> <li>Change in default behavior for the <code>balanced</code> garbage collection policy</li> <li>Stop parsing the JAVA_OPTIONS environment variable</li> <li>Global lock reservation enabled by default</li> <li>Increase in default operating system stack size on PPC64 platforms</li> <li>New <code>-x</code> option added to <code>jpackcore</code> / <code>jextract</code></li> </ul>"},{"location":"version0.27/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.27/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.27.1 supports OpenJDK 8, 11, and 16.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.27/#new-xx-adaptivegcthreading-option-added","title":"New <code>-XX:[+|-]AdaptiveGCThreading</code> option added","text":"<p>Adaptive threading is enabled by default, which automatically tunes the number of active parallel garbage collection (GC) threads. When this feature is enabled, the GC thread count is dynamically adjusted from collection cycle to cycle to account for changes in the the amount of time that parallel threads spend doing useful GC work (such as object graph traversal) compared to time spent synchronizing among themselves. When GC work decreases, fewer threads are used, which reduces the overhead, effectively reducing GC pause times. Resources are freed up for other processing activities.</p> <p>Use the <code>-xgcmaxthreads</code> option with the <code>-XX:+AdaptiveGCThreading</code> option to specify a thread count limit.</p>"},{"location":"version0.27/#improved-time-zone-information-added-to-java-dump-files","title":"Improved time zone information added to Java dump files","text":"<p>To help with troubleshooting, additional time zone information is added to Java\u2122 dump files. Two new fields are included, the date and time in UTC (<code>1TIDATETIMEUTC</code>) and the time zone according to the local system (<code>1TITIMEZONE</code>). For more information, see the Java dump <code>TITLE</code> section.</p>"},{"location":"version0.27/#change-in-default-behavior-for-the-balanced-garbage-collection-gc-policy","title":"Change in default behavior for the <code>balanced</code> garbage collection (GC) policy","text":"<p>In this release, a new scan mode, <code>-Xgc:dynamicBreadthFirstScanOrdering</code>, is used during <code>balanced</code> GC copy forward operations that is expected to improve performance.</p> <p>For more information about this type of operation, see GC copy forward operation.</p> <p>You can revert to the behavior in earlier releases by setting <code>-Xgc:breadthFirstScanOrdering</code> when you start your application.</p>"},{"location":"version0.27/#stop-parsing-the-java_options-environment-variable","title":"Stop parsing the JAVA_OPTIONS environment variable","text":"<p>The 0.24 release started parsing the JAVA_OPTIONS environment variable. This variable was added in error and has been removed. The _JAVA_OPTIONS environment variable (with different behavior) is added for compatibility.</p>"},{"location":"version0.27/#global-lock-reservation-enabled-by-default","title":"Global lock reservation enabled by default","text":"<p>(AIX\u00ae and Linux on Power Systems\u2122 only)</p> <p>Global lock reservation is now enabled by default. This is an optimization targeted towards more efficient handling of locking and unlocking Java objects. The older locking behavior can be restored via the <code>-XX:-GlobalLockReservation</code> option. See -XX:[+|-]GlobalLockReservation for more details.</p>"},{"location":"version0.27/#increase-in-default-operating-system-stack-size-on-ppc64-platforms","title":"Increase in default operating system stack size on PPC64 platforms","text":"<p>The default operating system stack size on AIX and Linux PPC64 is increased from 256KB to 512KB. You can change the operating system stack size by using the -Xmso option.</p>"},{"location":"version0.27/#new-x-option-recognized-by-jpackcore-jextract","title":"New <code>-x</code> option recognized by <code>jpackcore</code> / <code>jextract</code>","text":"<p>The new option, <code>-x</code>, causes the system dump to be omitted from the archive created. In its place, the file <code>excluded-files.txt</code> is added, which names the excluded file. For more information, see Dump extractor.</p>"},{"location":"version0.27/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.26.0 and v0.27.1 releases, see the Release notes.</p>"},{"location":"version0.29.1/","title":"Version 0.29.1","text":""},{"location":"version0.29.1/#whats-new-in-version-0291","title":"What's new in version 0.29.1","text":"<p>The following new features and notable changes since version 0.29.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> New JDK 17 features</li> </ul>"},{"location":"version0.29.1/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.29.1/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.29.1 supports OpenJDK 17.</p> <p>AArch64 Linux is now a fully supported, production-ready target for OpenJDK 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.29.1/#new-jdk-17-features","title":"New JDK 17 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 409: Sealed Classes<ul> <li>Promoted from preview to a production-ready feature in this release.</li> </ul> </li> <li>JEP 411: Deprecate the Security Manager for Removal</li> </ul> <p>The following features will be supported by OpenJ9 in a future release:</p> <ul> <li>JEP 391: macOS/AArch64 Port</li> <li>JEP 412: Foreign Function &amp; Memory API (Incubator)</li> <li>JEP 414: Vector API (Second Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 17 with OpenJ9:</p> <ul> <li> <p>JEP 306: Restore Always-Strict Floating-Point Semantics</p> </li> <li> <p>JEP 356: Enhanced Pseudo-Random Number Generators</p> </li> <li>JEP 382: New macOS Rendering Pipeline</li> <li>JEP 398: Deprecate the Applet API for Removal</li> <li>JEP 403: Strongly Encapsulate JDK Internals</li> <li>JEP 406: Pattern Matching for switch (Preview)</li> <li>JEP 407: Remove RMI Activation</li> <li>JEP 415: Context-Specific Deserialization Filters</li> </ul> <p>You can find the full list of features for JDK 17 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p> <p> Note: Applications might be adversely affected by JEP 403 if they make use of internal APIs. You should update your application to use standard APIs. To temporarily work around this problem, use <code>--add-opens</code>, <code>--add-exports</code> on the command line for each package required.</p>"},{"location":"version0.29.1/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.29.0 and v0.29.1 releases, see the Release notes.</p>"},{"location":"version0.29/","title":"Version 0.29.0","text":""},{"location":"version0.29/#whats-new-in-version-0290","title":"What's new in version 0.29.0","text":"<p>The following new features and notable changes since version 0.27.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>JITServer technology is fully supported on some  systems</li> <li>New <code>-XX:[+|-]UTFCache</code> option added</li> <li><code>-Xsoftmx</code> updates for gencon</li> </ul>"},{"location":"version0.29/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.29/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.29.0 supports OpenJDK 8 and 11.</p> <p>AArch64 Linux is now a fully supported, production-ready target for OpenJDK 8 and 11.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.29/#jitserver-technology-is-fully-supported-on-some-systems","title":"JITServer technology is fully supported on some systems","text":"<p>JITServer technology is now a fully supported feature on Linux\u00ae on x86 and Linux on IBM Power\u00ae systems (64-bit only). This feature remains a technical preview for Linux on IBM Z\u00ae systems (64-bit only). For more information, see JITServer technology.</p>"},{"location":"version0.29/#new-xx-utfcache-option-added","title":"New <code>-XX:[+|-]UTFCache</code> option added","text":"<p>A UTF to String cache is added to enhance reflection performance. The cache is enabled by default but can be disabled using the <code>-XX:[+|-]UTFCache</code> option.</p>"},{"location":"version0.29/#-xsoftmx-updates-for-gencon","title":"<code>-Xsoftmx</code> updates for gencon","text":"<p>When using gencon, the <code>-Xsoftmx</code> limit is proportional to the maximum amount of nursery space specified relative to the <code>-Xmx</code> value.</p>"},{"location":"version0.29/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.27.0 and v0.29.0 releases, see the Release notes.</p>"},{"location":"version0.30.1/","title":"Version 0.30.1","text":""},{"location":"version0.30.1/#whats-new-in-version-0301","title":"What's new in version 0.30.1","text":"<p>The following new features and notable changes since version 0.30.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Creation of system dumps on macOS 12</li> </ul>"},{"location":"version0.30.1/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.30.1/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.30.1 supports OpenJDK 8, 11 and 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.30.1/#creation-of-system-dumps-on-macos-12","title":"Creation of system dumps on macOS 12","text":"<p>Creation of system (core) dumps on macOS 12 or later is now possible.</p>"},{"location":"version0.30.1/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.30.0 and v0.30.1 releases, see the Release notes.</p>"},{"location":"version0.30/","title":"Version 0.30.0","text":""},{"location":"version0.30/#whats-new-in-version-0300","title":"What's new in version 0.30.0","text":"<p>The following new features and notable changes since version 0.29.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Changes to the shared classes cache generation number</li> <li>Ignored options now captured in java dumps</li> <li>New <code>-XX:[+|-]EnsureHashed</code> option added</li> <li>Redesigned heap resizing for the <code>balanced</code> GC policy</li> </ul>"},{"location":"version0.30/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.30/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.30.0 supports OpenJDK 8, 11 and 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.30/#changes-to-the-shared-classes-cache-generation-number","title":"Changes to the shared classes cache generation number","text":"<p>The format of classes that are stored in the shared classes cache is changed, which causes the JVM to create a new shared classes cache rather than re-creating or reusing an existing cache. To save space, you can remove all existing shared caches unless they are in use by an earlier release. For more information about the <code>-Xshareclasses</code> option, including the <code>destroy</code> options that you can use to remove caches, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.30/#ignored-options-captured-in-java-dumps","title":"Ignored options captured in java dumps","text":"<p>For improved compatibility with other Java implementations, OpenJ9 ignores many command-line options. If any were ignored, they are now listed in the java dump files. For example, the command</p> <pre>\njava -Xdump:java:events=vmstop -XX:+UseCompressedOop -XX:CompressedClassSpaceSize=528482304 -version\n</pre> <p>would yield the following in the ENVINFO section after the complete list of all command-line arguments</p> <pre>\n1CIIGNOREDARGS Ignored Args:\n2CIIGNOREDARG            -XX:+UseCompressedOop\n2CIIGNOREDARG            -XX:CompressedClassSpaceSize=528482304\n</pre>"},{"location":"version0.30/#new-xx-ensurehashed-option-added","title":"New <code>-XX:[+|-]EnsureHashed</code> option added","text":"<p>This option specifies the classes whose objects should be assigned hash values or those classes that should be ignored. This option might improve performance for applications that frequently hash objects of a certain type. See -XX:[+|-]EnsureHashed for more details.</p>"},{"location":"version0.30/#redesigned-heap-resizing-for-the-balanced-gc-policy","title":"Redesigned heap resizing for the <code>balanced</code> GC policy","text":"<p>Heap resizing heuristics have been redesigned for the <code>balanced</code> GC policy. This includes both total heap resizing including eden and non-eden components independently, and also balancing between these two components when the heap is fully expanded. The heuristics now combine both the CPU overhead (for Partial GCs as well as Global Mark Phase) and the heap occupancy criteria. The balancing between eden and non-eden for fully expanded heaps is far more dynamic (instead of being mostly fixed in the ratio 1:4).</p> <p>As a consequence, there should typically be less need for heap sizing tuning options, most notably for eden sizing options -Xmn, -Xmns, and -Xmnx.</p> <p>Also, a new soft limit pause target is added for Partial GCs, which defaults to 200ms. This criterion is combined with the PGC CPU overhead criterion for a balanced compromise between minimizing footprint, maximizing throughput, and meeting the paused time target.</p> <p>More details about the new heuristics can be found at:</p> <p>https://blog.openj9.org/2021/09/24/balanced-gc-performance-improvements-eden-heap-sizing-improvements/</p> <p>The heuristics now obey the following existing options that were previously used for the <code>optthruput</code>, <code>optavgpause</code>, and <code>gencon</code> GC policies:</p> <ul> <li>-Xmint/-Xmaxt</li> <li>-Xgc:dnssExpectedTimeRatioMaximum/Minimum</li> </ul> <p>The heuristics also use the -Xgc:targetPausetime option that was previously used only for the <code>metronome</code> GC policy.</p> <p>For more information about GC policies, see Garbage collection policies.</p>"},{"location":"version0.30/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.29.0 and v0.30.0 releases, see the Release notes.</p>"},{"location":"version0.32/","title":"Version 0.32.0","text":""},{"location":"version0.32/#whats-new-in-version-0320","title":"What's new in version 0.32.0","text":"<p>The following new features and notable changes since version 0.30.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Creation of system dumps on macOS 12</li> <li>Support for OpenJDK HotSpot options</li> <li><code>SharedClassStatistics</code> API updated</li> <li>Support for OpenSSL 3.0.x</li> <li>New <code>-XX:[+|-]OpenJ9CommandLineEnv</code> option added</li> <li>JITServer technology support for Linux on IBM Z\u00ae systems</li> <li> Modified default value for <code>-XX:MaxDirectMemorySize</code></li> <li> New JDK 18 features</li> </ul>"},{"location":"version0.32/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.32/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.32.0 supports OpenJDK 8, 11, 17, and 18.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.32/#creation-of-system-dumps-on-macos-12","title":"Creation of system dumps on macOS\u00ae 12","text":"<p>You can now create system (core) dumps on macOS 12 or later.</p>"},{"location":"version0.32/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li><code>-XX:[+|-]ShowHiddenFrames</code>. This option specifies whether generated hidden <code>MethodHandle</code> frames are displayed in a stack trace.</li> </ul>"},{"location":"version0.32/#sharedclassstatistics-api-updated","title":"<code>SharedClassStatistics</code> API updated","text":"<p>You can now use the <code>SharedClassStatistics</code> API to get the name, path, and directory of a shared classes cache. Depending on the operating system, you can also get the number of attached VMs for a non-persistent cache. This information is available through the following new methods: <code>cacheDir()</code>, <code>cacheName()</code>, <code>cachePath()</code>, and <code>numberAttached()</code>. For more information, see the API documentation.</p>"},{"location":"version0.32/#support-for-openssl-30x","title":"Support for OpenSSL 3.0.x","text":"<p>OpenSSL 3.0.x is supported but on Linux only. The JITServer technology feature currently does not support OpenSSL 3.0.x. For more information about OpenSSL support, see <code>Cryptographic operations</code>.</p>"},{"location":"version0.32/#new-xx-openj9commandlineenv-option-added","title":"New <code>-XX:[+|-]OpenJ9CommandLineEnv</code> option added","text":"<p>This option specifies whether the VM captures the command line in the environment variable <code>OPENJ9_JAVA_COMMAND_LINE</code>. For more information, see <code>-XX:[+|-]OpenJ9CommandLineEnv</code>.</p>"},{"location":"version0.32/#jitserver-support-for-linux-on-ibm-z-systems","title":"JITServer support for Linux on IBM Z\u00ae systems","text":"<p>JITServer technology is now a fully supported feature on Linux on IBM Z\u00ae systems (64-bit only). For more information, see JITServer technology.</p>"},{"location":"version0.32/#modified-default-value-for-xxmaxdirectmemorysize","title":"Modified default value for <code>-XX:MaxDirectMemorySize</code>","text":"<p>The default value of the <code>-XX:MaxDirectMemorySize</code> option, which limits the amount of heap memory that is used for direct byte buffers, is now the same as the maximum heap size.</p>"},{"location":"version0.32/#new-jdk-18-features","title":"New JDK 18 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 400: UTF-8 by Default</li> <li>JEP 416: Reimplement Core Reflection with Method Handles</li> <li>JEP 421: Deprecate Finalization for Removal</li> </ul> <p>The following features will be supported by OpenJ9 in a future release:</p> <ul> <li>JEP 391: macOS/AArch64 Port<ul> <li>An early access build is available in this release</li> </ul> </li> <li>JEP 417: Vector API (Third Incubator)</li> <li>JEP 419: Foreign Function &amp; Memory API (Second Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 18 with OpenJ9:</p> <ul> <li>JEP 408: Simple Web Server</li> <li>JEP 413: Code Snippets in Java API Documentation</li> <li>JEP 418: Internet-Address Resolution SPI</li> <li>JEP 420: Pattern Matching for switch (Second Preview)</li> </ul> <p>You can find the full list of features for JDK 18 at the OpenJDK project.</p>"},{"location":"version0.32/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.30.0 and v0.32.0 releases, see the Release notes.</p>"},{"location":"version0.33/","title":"Version 0.33.x","text":""},{"location":"version0.33/#whats-new-in-version-033x","title":"What's new in version 0.33.x","text":"<p>The following new features and notable changes since version 0.32.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>JITServer technology feature updated</li> <li> XL C++ Runtime required on AIX</li> <li> Linux reference compiler updated to gcc 10.3</li> <li>The maximum number of JIT compilation threads is increased</li> <li> Default operating system stack size increased on x64 platforms</li> <li>Control groups v2 support</li> <li>Support for OpenSSL 3.0.x</li> <li>EC key agreement algorithm support for OpenSSL</li> </ul>"},{"location":"version0.33/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.33/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.33.x supports OpenJDK 8, 11, 17, and 18.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 8 are now compiled with Microsoft\u00ae Visual Studio 2017. The Visual Studio redistributable files included with the build are updated to match.</p> <p> Note: Binaries that are labeled 0.33.1 include additional bug fixes. For more information, see the release notes.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.33/#jitserver-technology-feature-updated","title":"JITServer technology feature updated","text":"<p>The JITServer technology feature is updated to provide the following new capabilities, which are disabled by default:</p> <ul> <li>The caching of AOT-compiled methods on the server. The AOT cache improves CPU usage when clients request the compilation of methods that were previously cached. Use the <code>-XX:+JITServerUseAOTCache</code> command line option to enable this feature. Use the <code>-XX:JITServerAOTCacheName</code> option to specify the name of the AOT cache to be used at the JITServer server.</li> <li>The provision of metrics to a monitoring tool that follows the OpenMetrics standard. The following metrics are available for a JITServer server: CPU usage, available memory, number of clients connected, and number of active compilation threads. Use the <code>-XX:+JITServerMetrics</code> command line option to enable this feature.</li> </ul>"},{"location":"version0.33/#xl-c-runtime-required-on-aix","title":"XL C++ Runtime required on AIX","text":"<p>AIX OpenJ9 builds now require version 16.1 of the IBM XL C++ Runtime. This was already required for OpenJDK 17 and is now also required from 11.0.16 to accommodate a security update to the HarfBuzz text shaping library.</p>"},{"location":"version0.33/#linux-reference-compiler-updated-to-gcc-103","title":"Linux reference compiler updated to gcc 10.3","text":"<p>Linux\u00ae builds for all platforms now use gcc 10.3 instead of gcc 7.5. See the list of build environments.</p>"},{"location":"version0.33/#the-maximum-number-of-jit-compilation-threads-is-increased","title":"The maximum number of JIT compilation threads is increased","text":"<p>The maximum number of JIT compilation threads is increased from 7 to 15. If the JITServer feature is enabled, the maximum number of JIT compilation threads is increased further on the server, to 999. You can set the number of compilation threads to be used by specifying the <code>-XcompilationThreads</code> command line option.</p>"},{"location":"version0.33/#default-operating-system-stack-size-increased-on-x64-platforms","title":"Default operating system stack size increased on x64 platforms","text":"<p>The default operating system stack size on Windows x64, macOS\u00ae x64, and Linux x64 platforms is increased from 256 KB to 512 KB to accommodate vector support. You can change the operating system stack size by using the -Xmso option.</p>"},{"location":"version0.33/#control-groups-v2-support","title":"Control groups v2 support","text":"<p>The Linux kernel has two variants of control groups (cgroups): v1 and v2. Many Linux operating systems are gradually transitioning from cgroups v1 to v2 as their default choice. Now, OpenJ9 has added cgroups v2 support, which is identical to the support for cgroups v1.</p>"},{"location":"version0.33/#support-for-openssl-30x","title":"Support for OpenSSL 3.0.x","text":"<p>The JITServer technology feature now supports OpenSSL 3.0.x. For more information about OpenSSL support, see <code>Cryptographic operations</code>.</p>"},{"location":"version0.33/#ec-key-agreement-algorithm-support-for-openssl","title":"EC key agreement algorithm support for OpenSSL","text":"<p>The EC key agreement algorithm can now use the native OpenSSL library. For more information, see <code>-Djdk.nativeEC</code>.</p>"},{"location":"version0.33/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.32.0 and v0.33.x, see the Release notes.</p>"},{"location":"version0.35/","title":"Version 0.35.0","text":""},{"location":"version0.35/#whats-new-in-version-0350","title":"What's new in version 0.35.0","text":"<p>The following new features and notable changes since version 0.33.1 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Java\u2122 dump files contain more information about waiting threads</li> <li>New <code>-XX:[+|-]ShowNativeStackSymbols</code> option added</li> <li>New <code>user2</code> event added for the <code>-Xdump</code> option</li> <li>New <code>-XX:[+|-]PerfTool</code> option added</li> <li>New default options added in the <code>options.default</code> file</li> <li>New options added to encrypt the JITServer exported metrics</li> <li> XL C++ Runtime 16.1.0.7 or later required on AIX</li> <li><code>-XX:[+|-]JITServerLocalSyncCompiles</code> enabled by default</li> <li> Support for changes to the maintenance specifications of JSR 337 in Java 8</li> </ul>"},{"location":"version0.35/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.35/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.35.0 supports OpenJDK 8, 11, and 17.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 11 are now compiled with Microsoft\u00ae Visual Studio 2019. The Visual Studio redistributable files included with the build are updated to match.</p> <p>Apple silicon macOS\u00ae is now a fully supported, production-ready target for OpenJDK 11 and later.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.35/#java-dump-files-contain-more-information-about-waiting-threads","title":"Java dump files contain more information about waiting threads","text":"<p>For threads that are waiting for a class initialization lock, the Java dump output now shows the thread that is currently working to progress the initialization of the class. This thread is indicated by the new <code>Initializing thread: &lt;thread_name&gt;</code> string in the existing <code>3XMTHREADBLOCK</code> line in the Java dump output. For example:</p> <p><code>3XMTHREADBLOCK Waiting on: java/lang/J9VMInternals$ClassInitializationLock@0x00000000FFF5DC90 Owned by: &lt;unowned&gt; Initializing thread: \"Class Initialization Thread 1\"</code></p> <p>For more information, see Threads.</p>"},{"location":"version0.35/#new-xx-shownativestacksymbols-option-added","title":"New <code>-XX:[+|-]ShowNativeStackSymbols</code> option added","text":"<p>This option controls whether Java dumps show the names of functions in native call stacks.</p> <p>For more information, see <code>-XX:[+|-]ShowNativeStackSymbols</code>.</p>"},{"location":"version0.35/#new-user2-event-added-for-the-xdump-option","title":"New <code>user2</code> event added for the <code>-Xdump</code> option","text":"<p>On operating systems other than Windows\u2122, you can now use the <code>user2</code> event for the <code>-Xdump</code> option. This event is triggered when the VM receives the <code>SIGUSR2</code> signal.</p> <p>There is a change in the <code>SIGUSR2</code> signal behavior as well whereby, the process does not exit in response to this signal.</p> <p>For more information, see <code>-Xdump</code> and Signal handling.</p>"},{"location":"version0.35/#new-xx-perftool-option-added","title":"New <code>-XX:[+|-]PerfTool</code> option added","text":"<p>This option enables or disables the JIT support for the <code>perf</code> tool without affecting the existing <code>Xjit</code> options.</p> <p>Since this option creates a file that is used by the Linux\u00ae system profiler, <code>perf</code>, it applies only to Linux.</p> <p>For more information, see <code>-XX:[+|-]PerfTool</code>.</p>"},{"location":"version0.35/#new-default-options-added-in-the-optionsdefault-file","title":"New default options added in the <code>options.default</code> file","text":"<p><code>-XX:+EnsureHashed:java/lang/Class,java/lang/Thread</code> is added to the list of default options in the <code>options.default</code> file to improve performance.</p> <p>For more information, see <code>XX:[+|-]EnsureHashed</code>.</p>"},{"location":"version0.35/#new-options-added-to-encrypt-the-jitserver-exported-metrics","title":"New options added to encrypt the JITServer exported metrics","text":"<p>You can use the <code>-XX:JITServerMetricsSSLKey</code> and <code>-XX:JITServerMetricsSSLCert</code> options to encrypt the custom metrics with TLS or SSL.</p>"},{"location":"version0.35/#xl-c-runtime-16107-or-later-required-on-aix","title":"XL C++ Runtime 16.1.0.7 or later required on AIX","text":"<p>AIX OpenJ9 builds now require version 16.1.0.7 or later of the IBM XL C++ Runtime.</p>"},{"location":"version0.35/#-xx-jitserverlocalsynccompiles-enabled-by-default","title":"<code>-XX:[+|-]JITServerLocalSyncCompiles</code> enabled by default","text":"<p>The <code>-XX:[+|-]JITServerLocalSyncCompiles</code> option is now enabled in most cases. For more information, see <code>-XX:[+|-]JITServerLocalSyncCompiles</code>.</p>"},{"location":"version0.35/#support-for-changes-to-the-maintenance-specifications-of-jsr-337-in-java-8","title":"Support for changes to the maintenance specifications of JSR 337 in Java 8","text":"<p>OpenJ9 now supports changes to the maintenance specifications in Java 8 as listed in the JSR 337 Maintenance Release 4 document.</p> <p>These changes include the change in the garbage collector behavior for handling the phantom references in Java 8. The garbage collector handles both the phantom as well as the weak references similarly, which is the current behavior in Java 11 and later. For more information, see Weak reference processing.</p>"},{"location":"version0.35/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.33.1 and v0.35.0 releases, see the Release notes.</p>"},{"location":"version0.36/","title":"Version 0.36.x","text":""},{"location":"version0.36/#whats-new-in-version-036x","title":"What's new in version 0.36.x","text":"<p>The following new features and notable changes since version 0.35.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Changes to the location of the default directory for the shared cache and snapshot</li> <li>New <code>-XX:[+|-]MergeCompilerOptions</code> option added</li> <li>Default JITServer AOT cache name changed</li> <li>New <code>-XX:JITServerAOTmx</code> option added</li> <li>New <code>-XX:[+|-]JITServerAOTCachePersistence</code> option added</li> <li>New <code>-XX:JITServerAOTCacheDir</code> option added</li> </ul>"},{"location":"version0.36/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.36/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.36.0 supports OpenJDK 8 and 17.</p> <p>Release 0.36.1 supports OpenJDK 11.</p> <p>Support for running OpenJ9 with OpenJDK 8 or OpenJDK 11 on CentOS 6.10 is deprecated and might be removed in a future release. OpenJ9 will not be tested with OpenJDK 11 on CentOS 6.10 after the 0.36.1 release.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.36/#changes-to-the-location-of-the-default-directory-for-the-shared-cache-and-snapshot","title":"Changes to the location of the default directory for the shared cache and snapshot","text":"<p>On operating systems other than Windows\u2122 and z/OS\u00ae, the default shared classes cache directory in the user's home directory is changed from <code>javasharedresources</code> to <code>.cache/javasharedresources</code>. This change is to avoid cluttering of the home directory. If you specify <code>-Xshareclasses:groupAccess</code>, the default directory remains <code>/tmp/javasharedresources/</code>.</p> <p>If the <code>javasharedresources</code> directory in the user's home directory is empty, the <code>javasharedresources</code> directory can be deleted.</p> <p>You can find and remove caches or snapshots in the old default directory by using the following command-line options:</p> <p>For persistent caches:</p> <ul> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,listAllCaches</code> to find the caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,name=&lt;cacheName&gt;,destroy</code> to remove a particular cache</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,destroyAll</code> to remove all caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,destroyAllLayers</code> to remove multi-layer caches</li> </ul> <p>For nonpersistent caches or snapshots:</p> <ul> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,listAllCaches</code> to find the cache or snapshot</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,name=&lt;cacheName&gt;,destroy</code> to remove a particular shared cache</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,destroyAll</code> to remove all caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,destroyAllLayers</code> to remove multi-layer caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,name=&lt;snapshotName&gt;,destroySnapshot</code> to remove a particular snapshot</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,destroyAllSnapshots</code> to remove all snapshots</li> </ul>"},{"location":"version0.36/#new-xx-mergecompileroptions-option-added","title":"New <code>-XX:[+|-]MergeCompilerOptions</code> option added","text":"<p>This option enables or disables the merging of multiple <code>-Xjit</code> or <code>-Xaot</code> options into a single <code>-Xjit</code> or <code>-Xaot</code> option.</p> <p>For more information, see <code>-XX:[+|-]MergeCompilerOptions</code>.</p>"},{"location":"version0.36/#default-jitserver-aot-cache-name-changed","title":"Default JITServer AOT cache name changed","text":"<p>A JITServer instance can have several AOT caches, each with its own name and containing different versions of compiled methods. Client JVMs with different profiles of execution can connect to the same JITServer instance, but access the cache with compiled methods optimized for their own profile with the <code>-XX:JITServerAOTCacheName</code> option. Earlier, if the cache name was not specified in this option, the default was to use a nameless cache. The default AOT cache name is now changed to <code>default</code>.</p> <p>This change is to allow AOT cache persistence, whereby JITServer can periodically save its AOT caches to files with names that include the name of the cache. JITServer can then load caches from such files when a client requests a particular cache.</p> <p>For more information, see <code>-XX:JITServerAOTCacheName</code> and <code>-XX:[+|-]JITServerAOTCachePersistence</code>.</p>"},{"location":"version0.36/#new-xxjitserveraotmx-option-added","title":"New <code>-XX:JITServerAOTmx</code> option added","text":"<p>This option specifies the maximum amount of memory that can be used by the JITServer AOT cache. Instead of unlimited memory consumption, the maximum amount of memory that all AOT cache instances combined can use at the server is now limited to 300 MB, by default.</p> <p>For more information, see <code>-XX:JITServerAOTmx</code>.</p>"},{"location":"version0.36/#new-xx-jitserveraotcachepersistence-option-added","title":"New <code>-XX:[+|-]JITServerAOTCachePersistence</code> option added","text":"<p>The JITServer AOT cache was a non-persistent in-memory cache. If the JITServer instance terminated, the cache content was lost. Now, with the <code>-XX:+JITServerAOTCachePersistence</code> option, the JITServer server periodically saves its AOT caches to files. Other JITServer instances can then load these caches from files the first time a client requests a particular cache.</p> <p>For more information, see <code>-XX:[+|-]JITServerAOTCachePersistence</code>.</p>"},{"location":"version0.36/#new-xxjitserveraotcachedir-option-added","title":"New <code>-XX:JITServerAOTCacheDir</code> option added","text":"<p>You can specify the directory for saving or loading the JITServer AOT cache files with the <code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code> option. If the option is not used, AOT cache files are saved to (or loaded from) the current working directory of the JITServer server.</p> <p>For more information, see <code>-XX:JITServerAOTCacheDir</code>.</p>"},{"location":"version0.36/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.35.0 and v0.36.x releases, see the Release notes.</p>"},{"location":"version0.37/","title":"Version 0.37.0","text":""},{"location":"version0.37/#whats-new-in-version-0370","title":"What's new in version 0.37.0","text":"<p>The following new features and notable changes since version 0.36.x are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>AIX is now built on AIX 7.2 TL5</li> <li> Linux\u00ae reference compiler updated to gcc 11.2</li> <li>Support added for the <code>com.sun.management.ThreadMXBean</code> interface</li> <li> Support for PKCS#11 token labels added on Linux on IBM Z\u00ae</li> <li>New message added to help find system dumps on Linux</li> <li> New JDK 19 features</li> </ul>"},{"location":"version0.37/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.37/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.37.0 works with OpenJDK 19. OpenJDK 19 is out of support at the time of the 0.37.0 release. Builds of 0.37.0 should not be used in production and might contain known security vulnerabilities as of 18 April 2023.</p> <p>RHEL 8.2 is out of support. RHEL 8.4 is the new minimum operating system level.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 19 and later are now compiled with Microsoft\u00ae Visual Studio 2022. The Visual Studio redistributable files included with the build are updated to match.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.37/#aix-is-now-built-on-aix-72-tl5","title":"AIX is now built on AIX 7.2 TL5","text":"<p>All AIX compiles are now moved from AIX 7.1 TL5 to AIX 7.2 TL5.</p> <p>For more information, see Supported environments.</p>"},{"location":"version0.37/#linux-reference-compiler-updated-to-gcc-112","title":"Linux reference compiler updated to gcc 11.2","text":"<p>Linux builds for platforms Linux x86 64-bit, Linux on POWER LE 64-bit, and Linux on IBM Z 64-bit now use gcc 11.2 instead of gcc 10.3. Linux AArch64 64-bit continues to use the gcc 10.3 compiler. See the list of build environments.</p>"},{"location":"version0.37/#support-added-for-the-comsunmanagementthreadmxbean-interface","title":"Support added for the <code>com.sun.management.ThreadMXBean</code> interface","text":"<p>The OpenJ9 <code>ThreadMXbean</code> interface (<code>com.ibm.lang.management.ThreadMXBean</code>) was extending the <code>java.lang.management.ThreadMXBean</code> interface. With this release, the OpenJ9 <code>ThreadMXBean</code> interface extends the <code>com.sun.management.ThreadMXBean</code> interface, whereby it now contains all the methods of the <code>java.lang.management.ThreadMXBean</code> interface with additional methods from the <code>com.sun.management.ThreadMXBean</code> interface.</p> <p>The OpenJ9 VM implementation does not support thread memory allocation measurement (<code>isThreadAllocatedMemorySupported</code> method returns false).</p>"},{"location":"version0.37/#support-for-pkcs11-token-labels-added-on-linux-on-ibm-z","title":"Support for PKCS#11 token labels added on Linux on IBM Z","text":"<p>On restarting an application, or creating or removing of tokens, the token might move to a different slot. An application that uses the <code>slot</code> or <code>slotListIndex</code> attributes might fail if it doesn\u2019t first check which slot the token is in.</p> <p>OpenJ9 now supports the use of an extra attribute, <code>tokenlabel</code>, in the SunPKCS11 configuration file on Linux on IBM Z, which helps to avoid this issue.</p> <p>For more information, see Support for PKCS#11 token labels.</p>"},{"location":"version0.37/#new-message-added-to-help-find-system-dumps-on-linux","title":"New message added to help find system dumps on Linux","text":"<p>A new message, <code>JVMPORT049I</code>, is added to help find the system dump files for <code>kernel.core_pattern</code> piped programs on Linux.</p> <p>For more information about system dumps and piped system dumps, see System dumps on Linux.</p>"},{"location":"version0.37/#new-jdk-19-features","title":"New JDK 19 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 424: Foreign Function &amp; Memory API (Preview)</li> <li>JEP 425: Virtual Threads (Preview)</li> <li>JEP 426: Vector API (Fourth Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 19 with OpenJ9:</p> <ul> <li>JEP 405: Record Patterns (Preview)</li> <li>JEP 427: Pattern Matching for switch (Third Preview)</li> </ul> <p>You can find the full list of features for JDK 19 at the OpenJDK project. Any remaining features that are listed are not implemented and hence not applicable to OpenJ9 in this release.</p>"},{"location":"version0.37/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.36.x and v0.37.0 releases, see the Release notes.</p>"},{"location":"version0.38/","title":"Version 0.38.0","text":""},{"location":"version0.38/#whats-new-in-version-0380","title":"What's new in version 0.38.0","text":"<p>The following new features and notable changes since version 0.37.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New <code>-XX:[+|-]HandleSIGUSR2</code> option added</li> <li>Technical preview of CRIU support</li> </ul>"},{"location":"version0.38/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.38/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.38.0 supports OpenJDK 8, 11 and 17.</p> <p>Support for running OpenJ9 with OpenJDK 8 or OpenJDK 11 on CentOS 6.10 is deprecated and might be removed in a future release. Since release 0.37, OpenJ9 is no longer tested with OpenJDK 11 on CentOS 6.10. Testing of OpenJ9 with OpenJDK 8 on CentOS 6.10 is likely to end in a future release.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 8 are now compiled with Microsoft\u00ae Visual Studio 2019. The Visual Studio redistributable files included with the build are updated to match.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.38/#new-xx-handlesigusr2-option-added","title":"New <code>-XX:[+|-]HandleSIGUSR2</code> option added","text":"<p>This option controls the handling of the <code>SIGUSR2</code> signal by the VM signal handler. The VM signal handler is installed only if this option is enabled.</p> <p>For more information, see <code>-XX:[+|-]HandleSIGUSR2</code>.</p>"},{"location":"version0.38/#technical-preview-of-criu-support","title":"Technical preview of CRIU support","text":"<p>This release supports, as a technical preview, the Checkpoint/Restore In Userspace (CRIU) tool that is included with many Linux distributions. This tool is available for OpenJDK 11 and later running on Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), and Linux on IBM Z\u00ae only.</p> <p>You can use the CRIU feature to stop the VM at a checkpoint, save its state, then run the VM from the point where it was stopped. You can restore the checkpoint image in multiple other environments with improved start-up time. This capability means that the CRIU support is particularly useful in container environments. For more information, see CRIU support.</p>"},{"location":"version0.38/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.37.0 and v0.38.0 releases, see the Release notes.</p>"},{"location":"version0.39/","title":"Version 0.39.0","text":""},{"location":"version0.39/#whats-new-in-version-0390","title":"What's new in version 0.39.0","text":"<p>The following new features and notable changes since version 0.38.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>EC key generation algorithm support for OpenSSL</li> <li>New JDK 20 features</li> </ul>"},{"location":"version0.39/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.39/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.39.0 supports OpenJDK 20.</p> <p>OpenJDK 20 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>RHEL 8.4 is out of support. RHEL 8.6 is the new minimum operating system level.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.39/#ec-key-generation-algorithm-support-for-openssl","title":"EC key generation algorithm support for OpenSSL","text":"<p>The EC key generation algorithm can now use the native OpenSSL library for OpenJDK 20. For more information, see <code>-Djdk.nativeECKeyGen</code>.</p>"},{"location":"version0.39/#new-jdk-20-features","title":"New JDK 20 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 434: Foreign Function &amp; Memory API (Second Preview)</li> <li>JEP 436: Virtual Threads (Second Preview)</li> <li>JEP 437: Structured Concurrency (Second Incubator)</li> <li>JEP 438: Vector API (Fifth Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 20 with OpenJ9:</p> <ul> <li>JEP 432: Record Patterns (Second Preview)</li> <li>JEP 433: Pattern Matching for switch (Fourth Preview)</li> </ul> <p>You can find the full list of features for JDK 20 at the OpenJDK project. Any remaining features that are listed either do not apply to OpenJ9 or are not implemented and hence not applicable to OpenJ9 in this release.</p>"},{"location":"version0.39/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.38.0 and v0.39.0 releases, see the Release notes.</p>"},{"location":"version0.40/","title":"Version 0.40.0","text":""},{"location":"version0.40/#whats-new-in-version-0400","title":"What's new in version 0.40.0","text":"<p>The following new features and notable changes since version 0.39.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New <code>-XX:codecachetotalMaxRAMPercentage</code> option added</li> <li>VM starts with a warning message after the container detection fails</li> <li>Support for persistent shared classes cache added on z/OS</li> <li>EC key generation algorithm and XDH key agreement and generation algorithms support for OpenSSL</li> </ul>"},{"location":"version0.40/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.40/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.40.0 supports OpenJDK 8, 11, 17 and 20.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.40/#new-xxcodecachetotalmaxrampercentage-option-added","title":"New <code>-XX:codecachetotalMaxRAMPercentage</code> option added","text":"<p>In environments with low physical memory availability, the VM might use too much memory for JIT code caches, leaving little memory for critical operations. With the <code>-XX:codecachetotalMaxRAMPercentage</code> option, you can set an upper limit for the total code cache size, where the upper limit is specified as a percentage of the physical memory the VM process is allowed to use.</p> <p>For more information, see <code>-XX:codecachetotalMaxRAMPercentage</code>.</p>"},{"location":"version0.40/#vm-starts-with-a-warning-message-after-the-container-detection-fails","title":"VM starts with a warning message after the container detection fails","text":"<p>If you mount the <code>/proc</code> file system with the <code>hidepid=2</code> option on Linux\u00ae systems and the VM does not have root privileges, it cannot access the <code>/proc</code> file system. In previous releases, the VM exits when it encounters this scenario. From this release, the VM starts with a warning message after the container detection fails.</p> <p>For more information, see the Cloud optimizations topic.</p>"},{"location":"version0.40/#support-for-persistent-shared-classes-cache-added-on-zos","title":"Support for persistent shared classes cache added on z/OS","text":"<p>Persistent shared caches are now supported on z/OS systems. The default cache type on z/OS is still non-persistent. You can use the <code>-Xshareclasses:persistent</code> option to switch to persistent shared cache.</p>"},{"location":"version0.40/#ec-key-generation-algorithm-and-xdh-key-agreement-and-generation-algorithms-support-for-openssl","title":"EC key generation algorithm and XDH key agreement and generation algorithms support for OpenSSL","text":"<p>The EC key generation algorithm can now use the native OpenSSL library for all OpenJDK versions. The XDH key agreement and generation algorithms can also use the native OpenSSL library. For more information, see <code>-Djdk.nativeECKeyGen</code>, <code>-Djdk.nativeXDHKeyAgreement</code>, and <code>-Djdk.nativeXDHKeyGen</code>.</p>"},{"location":"version0.40/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.39.0 and v0.40.0 releases, see the Release notes.</p>"},{"location":"version0.41/","title":"Version 0.41.0","text":""},{"location":"version0.41/#whats-new-in-version-0410","title":"What's new in version 0.41.0","text":"<p>The following new features and notable changes since version 0.40.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> New <code>-XX:[+|-]ShowCarrierFrames</code> option added </li> <li> New <code>-XX:ContinuationCache</code> option added </li> <li> <code>-XX:+CompactStrings</code> option enabled by default </li> <li>Change in behavior of <code>-Xshareclasses:readonly</code></li> <li>New <code>-XX:[+|-]EnableDynamicAgentLoading</code> option added</li> <li>New <code>-XX:[+|-]UseZlibNX</code> option added</li> <li>Support for OpenSSL 3.x</li> </ul>"},{"location":"version0.41/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.41/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.41.0 supports OpenJDK 8, 11, and 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.41/#new-xx-showcarrierframes-option-added","title":"New <code>-XX:[+|-]ShowCarrierFrames</code> option added","text":"<p>A VM maintains multiple platform threads that are used as carrier threads to run the virtual threads. Although the virtual thread runs on a carrier thread, the stack trace of the virtual thread and its carrier thread are separate. You can use the <code>-XX:+ShowCarrierFrames</code> option to add the stack trace of the carrier thread in addition to the virtual thread stack trace to the <code>Throwable.getStackTrace()</code> method, if an exception occurs.</p> <p>For more information, see <code>-XX:[+|-]ShowCarrierFrames</code>. </p>"},{"location":"version0.41/#new-xxcontinuationcache-option-added","title":"New <code>-XX:ContinuationCache</code> option added","text":"<p>When a virtual thread is created, it is associated with a continuation, which holds the target task of the virtual thread. The VM saves the current thread state in an internal data structure that is linked with the continuation and allocates the memory for that structure. The VM stores the internal data structure in a continuation cache. New continuations can reuse the cached structure instead of allocating new memory for it.</p> <p>You can optimize the virtual thread performance by tuning the continuation tier 1 and 2 cache size with the <code>-XX:ContinuationCache</code> option. </p>"},{"location":"version0.41/#-xxcompactstrings-option-enabled-by-default","title":"<code>-XX:+CompactStrings</code> option enabled by default","text":"<p>Like HotSpot, the<code>-XX:+CompactStrings</code> option is now enabled by default on Java\u2122 11 and later. In the earlier versions, this option is disabled by default.</p> <p>For more information, see <code>-XX:[+|-]CompactStrings</code>. </p>"},{"location":"version0.41/#change-in-behavior-of-xshareclassesreadonly","title":"Change in behavior of <code>-Xshareclasses:readonly</code>","text":"<p>In the earlier releases, if the <code>-Xshareclasses:readonly</code> option and the JITServer AOT cache feature were both enabled at the same time at a JITServer client, the client could not use the JITServer AOT cache because the cache for storing data that the JITServer AOT cache needed was read-only.</p> <p>Now, with the change in behavior of the <code>-Xshareclasses:readonly</code> option, the shared class cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p>"},{"location":"version0.41/#new-xx-enabledynamicagentloading-option-added","title":"New <code>-XX:[+|-]EnableDynamicAgentLoading</code> option added","text":"<p>This option enables or disables the dynamic loading of agents into a running VM. The <code>-XX:+EnableDynamicAgentLoading</code> option is the default setting.</p> <p> For Java 21 and later, warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the <code>-XX:+EnableDynamicAgentLoading</code> option and the same agents were not loaded before. </p> <p>For more information, see <code>-XX:[+|-]EnableDynamicAgentLoading</code>.</p>"},{"location":"version0.41/#new-xx-usezlibnx-option-added","title":"New <code>-XX:[+|-]UseZlibNX</code> option added","text":"<p>AIX\u00ae system adds the <code>zlibnx</code> library directory path in the <code>LIBPATH</code> environment variable by default, if it is available in the system. You can control the loading of the <code>zlibnx</code> library by using the <code>-XX:[+|-]UseZlibNX</code> option.</p>"},{"location":"version0.41/#support-for-openssl-3x","title":"Support for OpenSSL 3.x","text":"<p>OpenSSL 3.x is now supported on all operating systems. For more information about OpenSSL support, see <code>Cryptographic operations</code>.</p>"},{"location":"version0.41/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.40.0 and v0.41.0 releases, see the Release notes.</p>"},{"location":"version0.42/","title":"Version 0.42.0","text":""},{"location":"version0.42/#whats-new-in-version-0420","title":"What's new in version 0.42.0","text":"<p>The following new features and notable changes since version 0.41.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> OpenJ9 <code>jextract</code> removed </li> </ul>"},{"location":"version0.42/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.42/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.42.0 supports OpenJDK 21.</p> <p>OpenJDK 21 with Eclipse OpenJ9 is a long term support (LTS) release and supersedes OpenJDK 20 with Eclipse OpenJ9.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.42/#openj9-jextract-removed","title":"OpenJ9 <code>jextract</code> removed","text":"<p>The dump extractor tool, OpenJ9 <code>jextract</code>, that was deprecated since the 0.26.0 release is now removed from Java 21 and later. The <code>jpackcore</code> tool replaced the OpenJ9 <code>jextract</code> tool after its deprecation. </p>"},{"location":"version0.42/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.41.0 and v0.42.0 releases, see the Release notes.</p>"},{"location":"version0.8/","title":"Version 0.8.0","text":""},{"location":"version0.8/#release-notes-version-080","title":"Release notes - version 0.8.0","text":"<p>Version 0.8.0 is the first release of Eclipse OpenJ9\u2122, as defined in the release plan.</p> <p>This release supports OpenJDK Version 8 binaries at AdoptOpenJDK.net that contain the Eclipse OpenJ9 virtual machine.</p> <p>For more information about supported platforms, and any issues and limitations, read the OpenJ9 GitHub release notes.</p>"},{"location":"version0.9/","title":"Version 0.9.0","text":""},{"location":"version0.9/#whats-new-in-version-090","title":"What's new in version 0.9.0","text":"<p>The following new features and notable changes from v.0.8.0 are included in this release:</p> <ul> <li>New binaries and supported environments.</li> <li>The idle tuning feature is now supported on Linux running on Power\u00ae Systems and IBM Z\u00ae Systems.</li> <li>A new Garbage Collection (GC) policy is available that performs no housekeeping.</li> <li>A command line option is provided to automatically set a larger Java heap size for applications that run in containers.</li> <li>You can now specify the maximum Java heap size as a percentage value.</li> <li>The shared classes feature now supports nested jar files.</li> <li>System dump data can now be read to help diagnose problems on Linux and Windows platforms.</li> <li>There are notable changes to the <code>java.lang.String</code> class.</li> <li>There are notable changes to the <code>com.ibm.oti.shared.SharedClassCacheInfo</code> class.</li> <li> New JDK 9 features</li> <li> New JDK 10 features</li> </ul>"},{"location":"version0.9/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.9/#binaries-and-supported-platforms","title":"Binaries and supported platforms","text":"<p>The following additional OpenJDK binaries that contain the Eclipse OpenJ9\u2122 VM are now available from the AdoptOpenJDK community:</p> <ul> <li>OpenJDK version 10</li> <li>OpenJDK version 8 for 32-bit Windows</li> <li>OpenJDK version 8 for x86 64-bit Linux (Large Heap) for Java heaps &gt;57 GB.</li> </ul> <p>Complete platform support information for OpenJ9 can be found in Supported environments</p>"},{"location":"version0.9/#idle-tuning-feature","title":"Idle tuning feature","text":"<p>The idle tuning feature in OpenJ9 keeps your memory footprint small by releasing unused memory back to the operating system. Prior to Eclipse version 0.9.0 this feature was available only on Linux x86 architectures with the <code>gencon</code> garbage collection policy. From version 0.9.0, this feature is now available on Linux for IBM POWER\u00ae and IBM Z\u00ae architectures. For more information about this feature, see the following command line options, which control this behavior:</p> <ul> <li>-XX:[+|-]IdleTuningCompactOnIdle</li> <li>-XX:[+|-]IdleTuningGcOnIdle</li> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> </ul> <p>The following blog post describes the benefits of using this feature: Are you still paying for unused memory when your Java app is idle?</p>"},{"location":"version0.9/#new-gc-policy","title":"New GC policy","text":"<p>A new GC policy is introduced for JEP 318: Epsilon: A No-Op Garbage Collector.</p> <p>When this policy is enabled, the Java object heap is expanded in the normal way until the limit is reached, but memory is not reclaimed through garbage collection. When the limit is reached the VM shuts down.</p> <p>This JEP has a number of use cases including short-lived applications and certain test scenarios.</p> <p>To enable this policy you can use one of the following options:</p> <ul> <li>-Xgcpolicy:nogc</li> <li>-XX:+UseNoGC</li> </ul>"},{"location":"version0.9/#modifying-the-default-java-heap-size-for-applications-that-run-in-containers","title":"Modifying the default Java heap size for applications that run in containers","text":"<p>When using container technology, applications are typically run on their own and do not need to compete for memory. In this release, changes are introduced to detect when OpenJ9 is running inside a container. If your application is running in a container and you want the VM to allocate a larger fraction of memory to the Java heap, set the <code>-XX:+UseContainerSupport</code> option on the command line.</p> <p>The following table shows the maximum Java heap size that gets set, depending on the memory available:</p> Physical memory <code>&lt;size&gt;</code> Maximum Java heap size Less than 1 GB 50% <code>&lt;size&gt;</code> 1 GB - 2 GB <code>&lt;size&gt;</code> - 512M Greater than 2 GB 75% <code>&lt;size&gt;</code> <p>The default heap size for containers only takes affect when running in a container environment and when <code>-XX:+UseContainerSupport</code> is specified, which is expected to be the default in a future release.</p>"},{"location":"version0.9/#specifying-the-maximum-java-heap-size-as-a-percentage-value","title":"Specifying the maximum Java heap size as a percentage value","text":"<p>OpenJ9 now supports setting the heap size as a percentage of the physical memory. The following OpenJDK options are recognized and can be set for the VM:</p> <ul> <li><code>-XX:MaxRAMPercentage</code></li> <li><code>-XX:InitialRAMPercentage</code></li> </ul> <p>To understand how to set these options, see -XX:InitialRAMPercentage / -XX:MaxRAMPercentage.</p> <p>If your application is running in a container and you have specified <code>-XX:+UseContainerSupport</code>, as described in Modifying the default Java heap size for applications that run in containers, both the default heap size for containers and the <code>-XX:MaxRAMPercentage</code> and <code>-XX:InitialRAMPercentage</code> options are based on the available container memory.</p>"},{"location":"version0.9/#shared-classes-support-for-nested-jar-files","title":"Shared classes support for nested jar files","text":"<p>Changes are made to the <code>com.ibm.oti.shared</code> API to support nested jar files.</p>"},{"location":"version0.9/#direct-dump-reader-enabled-on-linux-and-windows","title":"Direct Dump Reader enabled on Linux and Windows","text":"<p>Direct Dump Reader (DDR) support is now enabled for the OpenJ9 VM on all Linux architectures and on Windows. The DDR code enables the VM to read system dump data by using the OpenJ9 Diagnostic Tool Framework for Java (DTFJ) API or the <code>jdmpview</code> tool. If you use the Eclipse Memory Analyzer\u2122 tool (MAT), you can also analyze OpenJ9 or IBM VMs by installing the DTFJ plugin. (Install from the Eclipse Help menu; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and  Diagnostic Tools &gt; Diagnostic Tool Framework for Java)</p> <p>You must use a 32-bit VM to look at a 32-bit core, and a 64-bit VM to look at a 64-bit core. This restriction will be fixed in a later version of OpenJ9.</p>"},{"location":"version0.9/#changes-to-the-javalangstring-class","title":"Changes to the <code>java.lang.String</code> class","text":"<p> To match the behavior of OpenJDK, <code>java.lang.String</code> no longer has a count field, which changes the way that <code>String.subString()</code> works compared to Java 8. <code>String.subString()</code> now copies the value array. Similarly, <code>StringBuffer</code> and <code>StringBuilder</code> do not share the value array with any <code>String</code> created by <code>toString()</code>.</p> <p>For performance and compatibility with the new String object layout, the OpenJ9 implementations of <code>StringBuffer</code> and <code>StringBuilder</code> have been deprecated in favor of the OpenJDK implementations. </p>"},{"location":"version0.9/#changes-to-the-sharedclasscacheinfo-class","title":"Changes to the <code>SharedClassCacheInfo</code> class","text":"<p> <code>SharedClassCacheInfo.getCacheJVMLevel()</code> used to return the JVMLEVEL constant that maps to a Java version number, for example JVMLEVEL_JAVA8. This call now returns only the Java version number, for example 10 for Java 10. </p>"},{"location":"version0.9/#new-jdk-9-features","title":"New JDK 9 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 102: Process API Updates</li> <li>JEP 110: HTTP 2 Client</li> <li>JEP 143: Improve Contended Locking</li> <li>JEP 193: Variable Handles</li> <li>JEP 199: Smart Java Compilation, Phase Two</li> <li>JEP 200: The Modular JDK</li> <li>JEP 201: Modular Source Code</li> <li>JEP 211: Elide Deprecation Warnings on Import Statements</li> <li>JEP 213: Milling Project Coin</li> <li>JEP 215: Tiered Attribution for javac</li> <li>JEP 216: Process Import Statements Correctly</li> <li>JEP 217: Annotations Pipeline 2.0</li> <li>JEP 219: Datagram Transport Layer Security (DTLS)</li> <li>JEP 220: Modular Run-Time Images</li> <li>JEP 221: Simplified Doclet API</li> <li>JEP 222: jshell: The Java Shell (Read-Eval-Print Loop)</li> <li>JEP 223: New Version-String Scheme</li> <li>JEP 224: HTML5 Javadoc</li> <li>JEP 225: Javadoc Search</li> <li>JEP 226: UTF-8 Property Files</li> <li>JEP 227: Unicode 7.0</li> <li>JEP 229: Create PKCS12 Keystores by Default</li> <li>JEP 232: Improve Secure Application Performance</li> <li>JEP 235: Test Class-File Attributes Generated by javac</li> <li>JEP 236: Parser API for Nashorn</li> <li>JEP 238: Multi-Release JAR Files</li> <li>JEP 240: Remove the JVM TI hprof Agent</li> <li>JEP 241: Remove the jhat Tool</li> <li>JEP 244: TLS Application-Layer Protocol Negotiation Extension</li> <li>JEP 247: Compile for Older Platform Versions</li> <li>JEP 249: OCSP Stapling for TLS</li> <li>JEP 251: Multi-Resolution Images</li> <li>JEP 252: Use CLDR Locale Data by Default</li> <li>JEP 253: Prepare JavaFX UI Controls and CSS APIs for Modularization</li> <li>JEP 254: Compact Strings (not enabled by default)</li> <li>JEP 255: Merge Selected Xerces 2.11.0 Updates into JAXP</li> <li>JEP 256: BeanInfo Annotations</li> <li>JEP 257: Update JavaFX/Media to Newer Version of GStreamer</li> <li>JEP 258: HarfBuzz Font-Layout Engine</li> <li>JEP 259: Stack-Walking API</li> <li>JEP 260: Encapsulate Most Internal APIs</li> <li>JEP 261: Module System</li> <li>JEP 262: TIFF Image I/O</li> <li>JEP 263: HiDPI Graphics on Windows and Linux\u00ae</li> <li>JEP 264: Platform Logging API and Service</li> <li>JEP 265: Marlin Graphics Renderer</li> <li>JEP 266: More Concurrency Updates</li> <li>JEP 267: Unicode 8.0</li> <li>JEP 268: XML Catalogs</li> <li>JEP 269: Convenience Factory Methods for Collections</li> <li>JEP 272: Platform-Specific Desktop Features</li> <li>JEP 273: DRBG-Based SecureRandom Implementations</li> <li>JEP 274: Enhanced Method Handles</li> <li>JEP 275: Modular Java Application Packaging</li> <li>JEP 276: Dynamic Linking of Language-Defined Object Models</li> <li>JEP 277: Enhanced Deprecation</li> <li>JEP 280: Indify String Concatenation</li> <li>JEP 282: jlink: The Java Linker</li> <li>JEP 283: Enable GTK 3 on Linux</li> <li>JEP 285: Spin-Wait Hints</li> <li>JEP 287: SHA-3 Hash Algorithms</li> <li>JEP 288: Disable SHA-1 Certificates</li> <li>JEP 289: Deprecate the Applet API</li> <li>JEP 290: Filter Incoming Serialization Data</li> <li>JEP 292: Implement Selected ECMAScript 6 Features in Nashorn</li> <li>JEP 298: Remove Demos and Samples</li> <li>JEP 299: Reorganize Documentation</li> </ul> <p>You can find the full list of features for JDK 9 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.9/#new-jdk-10-features","title":"New JDK 10 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 286: Local-Variable Type Inference</li> <li>JEP 313: Remove the Native-Header Generation Tool (javah)</li> <li>JEP 314: Additional Unicode Language-Tag Extensions</li> <li>JEP 319: Root Certificates</li> <li>JEP 322: Time-Based Release Versioning</li> </ul> <p>You can find the full list of features for JDK 10 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.9/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.8.0 and version 0.9.0 releases, see the Release notes.</p>"},{"location":"vgclog/","title":"Verbose GC logs","text":""},{"location":"vgclog/#verbose-garbage-collection-logs","title":"Verbose garbage collection logs","text":"<p>Garbage collection (GC) reclaims used memory in the Java\u2122 object heap for reuse. During cleanup of the heap, the verbose GC logs, when enabled, capture information about the different GC operations that are involved in the GC cycles. GC operations aim to reorganize or reclaim memory.</p> <p>Verbose GC logs contain information about GC operations to assist with the following actions:  </p> <ul> <li>Tuning GC and improving application performance.</li> <li>Troubleshooting GC operations and policies. For example, analyzing long pauses, or determining how free memory is divided in the Java object heap before and after a GC cycle.  </li> </ul> <p>Verbose GC logs, when enabled, begin capturing information as soon as GC is initialized.</p> <p>To help you visualize and analyze the GC, you can feed verbose GC log files into various diagnostic tools and interfaces. Examples include tools such as Garbage Collection and Memory Visualizer (GCMV) and online services such as GCEasy.  </p> <p>For examples of log output, including guidance on how to analyze the logs, see Log examples.</p> <p>A further diagnostic step is to run one or more traces on GC activity by using the <code>-Xtgc</code> option. Trace output provides more granular information to help diagnose GC problems or perform finer tuning.</p>"},{"location":"vgclog/#how-to-generate-a-verbose-gc-log","title":"How to generate a verbose GC log","text":"<p>You can enable verbose GC logs by specifying the <code>-verbose:gc</code> standard option when you start your application. For more information, see standard command-line options.</p> <p>The output of <code>-verbose:gc</code> is printed to STDERR by default. To print the log output to a file, append the <code>-Xverbosegclog</code> option. You can also use this option to print to a succession of files, where each file logs a specified number of GC cycles.</p>"},{"location":"vgclog/#verbose-gc-log-contents-and-structure","title":"Verbose GC log contents and structure","text":"<p>The verbose GC logs are printed in XML format and consist of the following sections:  </p> <ul> <li> <p>A summary of your GC configuration, which is captured in the <code>&lt;initialized&gt;</code> XML element.</p> </li> <li> <p>Information about the GC cycles that ran, including GC operations and GC increments.  </p> </li> </ul> <p>For definitions of GC cycles and operations, see Garbage collection. For definitions of GC increments, see GC increments and interleaving.</p> <p>The logs record when GC cycles and their increments start and end, and list the GC operations that run within these increments to manage or reclaim memory. You can also determine which type of event triggered the cycle or increment, and the amount of memory available to your application before and after processing.  </p>"},{"location":"vgclog/#initialization","title":"Initialization","text":"<p>The log begins by recording the configuration of the Eclipse OpenJ9\u2122 runtime virtual environment (VM) and details of the GC configuration(GC). The configuration is recorded by using child elements of the <code>&lt;initialized&gt;</code> element, for example:</p> <pre><code>\n&lt;initialized id=\"1\" timestamp=\"2020-10-18T13:27:07.691\"&gt;\n  &lt;attribute name=\"gcPolicy\" value=\"-Xgcpolicy:gencon\" /&gt;\n  &lt;attribute name=\"maxHeapSize\" value=\"0x40000000\" /&gt;\n  &lt;attribute name=\"initialHeapSize\" value=\"0x40000000\" /&gt;\n  &lt;attribute name=\"compressedRefs\" value=\"true\" /&gt;\n  &lt;attribute name=\"compressedRefsDisplacement\" value=\"0x0\" /&gt;\n  &lt;attribute name=\"compressedRefsShift\" value=\"0x0\" /&gt;\n  &lt;attribute name=\"pageSize\" value=\"0x1000\" /&gt;\n  &lt;attribute name=\"pageType\" value=\"not used\" /&gt;\n  &lt;attribute name=\"requestedPageSize\" value=\"0x1000\" /&gt;\n  &lt;attribute name=\"requestedPageType\" value=\"not used\" /&gt;\n  &lt;attribute name=\"gcthreads\" value=\"4\" /&gt;\n  &lt;attribute name=\"gcthreads Concurrent Mark\" value=\"1\" /&gt;\n  &lt;attribute name=\"packetListSplit\" value=\"1\" /&gt;\n  &lt;attribute name=\"cacheListSplit\" value=\"1\" /&gt;\n  &lt;attribute name=\"splitFreeListSplitAmount\" value=\"1\" /&gt;\n  &lt;attribute name=\"numaNodes\" value=\"0\" /&gt;\n  &lt;system&gt;\n    &lt;attribute name=\"physicalMemory\" value=\"100335456256\" /&gt;\n    &lt;attribute name=\"numCPUs\" value=\"28\" /&gt;\n    &lt;attribute name=\"architecture\" value=\"amd64\" /&gt;\n    &lt;attribute name=\"os\" value=\"Linux\" /&gt;\n    &lt;attribute name=\"osVersion\" value=\"3.10.0-1160.el7.x86_64\" /&gt;\n  &lt;/system&gt;\n  &lt;vmargs&gt;\n    &lt;vmarg name=\"-Dfile.encoding=bestfit936\" /&gt;\n    ...\n    &lt;vmarg name=\"-Xms1024m\" /&gt;\n    &lt;vmarg name=\"-Xmx1024m\" /&gt;\n    ...\n    &lt;vmarg name=\"-Xverbosegclog:verbosegc.xml\" /&gt;\n    ...\n  &lt;/vmargs&gt;\n&lt;/initialized&gt;\n</code></pre> <p>The first set of <code>&lt;attribute&gt;</code> elements records the configuration of the garbage collector, such as the GC policy type, configuration of the Java object heap, and the number of threads that are used for garbage collection. For example, the <code>GCThreads</code> attribute records that the garbage collector is configured to use four threads.</p> <p>The <code>&lt;system&gt;</code> section records information about the operating system and available hardware, such as the physical memory, number of CPUs, and operating system type and version. In the example, the VM is running on Linux\u00ae amd64 V3.10 and has access to 28 CPUs and over 100 GB.</p> <p>The <code>&lt;vmargs&gt;</code> section records any VM configuration command-line options (VM arguments) that are specified. The following types of options are recorded:</p> <ul> <li>non-standard JVM <code>-X</code> options and JVM <code>-XX</code> options. In the example output, the log records the location of the file that contains VM options and definitions as <code>java/perffarm/sdks/O11_j9_x64_linux-20201014/sdk/lib/options.default</code>. The verbose GC log option is set to <code>-Xverbosegclog:verbosegc.xml</code> to write the verbose GC log output to an XML file. The initial and maximum Java object heap sizes are both set to 1024 KB by using the <code>-Xms</code> and <code>-Xmx</code> options.</li> <li>system property options. In the example output, the system property <code>file.encoding</code> is set to <code>bestfit936</code> to force the GBK converter to follow unicode 2.0 rather than 3.0 standards.</li> </ul> <p>These command-line options can be set by using the command line, or by passing a manifest file, options file, or environment variable to the VM.</p> <p>After the configurations are recorded in the Initialization section, the verbose GC log begins recording GC activities and details.</p>"},{"location":"vgclog/#gc-cycles","title":"GC cycles","text":"<p>The start of a GC cycle is recorded by the <code>&lt;cycle-start&gt;</code> XML element. The trigger for the start of a GC cycle is captured in a preceding element to the <code>&lt;cycle-start&gt;</code> element. A GC cycle or GC increment is triggered for one of the following reasons:</p> <ul> <li>an allocation failure occurs. Allocation failures occur when a request for memory fails because the Java object heap does not have enough memory available. The element <code>&lt;af-start&gt;</code> logs an allocation failure trigger.</li> <li>a memory threshold is reached. Memory threshold values, which set the conditions for triggering certain types of GC cycles or increments, are defined by the policy type and configuration options. For more information about the particular elements or attributes that are used to record a memory threshold trigger, see specific policies and cycles in Log examples.</li> </ul> <p>The following XML structure is an example of the verbose GC logs that are generated from the Generational Concurrent GC policy (<code>-Xgcpolicy:gencon</code>). In this example, the lines are indented to help illustrate the flow and attributes and some child elements are omitted for clarity:</p> <pre><code>    &lt;exclusive-start/&gt;\n\n      &lt;af-start/&gt;\n\n        &lt;cycle-start/&gt;\n\n          &lt;gc-start&gt;\n\n            &lt;mem-info&gt;\n\n              &lt;mem/&gt;\n\n            &lt;/mem-info&gt;\n\n          &lt;/gc-start&gt;\n\n          &lt;allocation-stats/&gt;\n\n              &lt;gc-op/&gt;\n\n          &lt;gc-end&gt;\n\n            &lt;mem-info&gt;\n\n              &lt;mem/&gt;\n\n            &lt;/mem-info&gt;\n\n          &lt;/gc-end&gt;\n\n        &lt;cycle-end/&gt;\n\n        &lt;allocation-satisfied/&gt;\n\n      &lt;af-end/&gt;\n\n    &lt;exclusive-end/&gt;\n</code></pre> <p>Some elements serve as markers for starting and ending parts of the GC cycle and do not contain child elements, while other elements do contain child elements. In this example, the <code>&lt;af-start/&gt;</code>, <code>&lt;cycle-start/&gt;</code>, <code>&lt;cycle-end/&gt;</code>, <code>&lt;allocation-satisfied/&gt;</code>, and <code>&lt;af-end/&gt;</code> XML elements are empty and contain only attributes. All other XML elements contain child XML elements, which are omitted from this simplified example. For detailed examples of log output for a specific cycle, see Log examples).</p>"},{"location":"vgclog/#gc-increments-and-interleaving","title":"GC increments and interleaving","text":"<p>Some GC cycle types are run in piecemeal blocks of operations called GC increments. Using GC increments reduces pause times by enabling blocks of operations or operation steps to interleave with operations or operation steps from other types of cycle.</p> <p>For example, consider the garbage collector for the <code>gencon</code> policy, which uses partial cycles and global cycles. The partial cycle consists of just 1 GC operation, scavenge, that runs on the nursery area during a stop-the-world (STW) pause. However, the <code>gencon</code> global cycle, which runs when the tenure area is close to full, is split into three increments. The initial and final global cycle increments run during a relatively short STW pause. The intermediate global cycle increment, which consists of the majority of the GC cycle's work, runs its GC operations concurrently.</p> <p>Splitting the global cycle operations into these increments reduces pause times by running most of the GC operations concurrently with application threads. The <code>gencon</code> global cycle's concurrent increment is paused when a <code>gencon</code> partial GC cycle is triggered and resumes when the partial cycle, or multiple partial cycles, complete. In this way, a global cycle can progress while other types of cycle are run by pausing and resuming the concurrent work. In some policies, concurrent operations are split further into multiple concurrent increments for better control of progress of the concurrent operation.</p> <p>You can see this interleaving of the increments in the verbose GC log. The following table illustrates how the interleaving of the <code>gencon</code> policy's partial scavenge and global cycles appears in the logs. Line numbers of an example <code>gencon</code> policy's verbose GC log are displayed, alongside columns that show the status of each cycle that is recorded in the logs. (for clarity, not all GC activities are listed):</p> Table showing how the `gencon` policy's global and partial scavenge cycles, which interleave with each other, are recorded in an example log.  Example log line number `gencon` global GC cycle status recorded in log `gencon` partial GC cycle status recorded in log 1-87 Initialization section of the logs  87-51676  -   series of partial scavenge cycles start and finish   51677  global cycle's trigger and target logged - 51680  STW pause starts - 51683  global cycle starts - 51684  STW pause ends - 518685  blank line in logs. (Concurrent increment runs)  - 51686  (concurrent increment paused) STW pause starts 51690  (concurrent increment paused) partial scavenge cycle starts 51691  (concurrent increment paused)  partial scavenge increment runs 51730  (concurrent increment paused) partial cycle ends 51733  (concurrent increment resumes) STW pause ends 51734  blank line in logs. (Concurrent increment resumes) - 51735  STW pause starts - 51741  final global increment logged  - 51793  global cycle ends  - 51795  STW pause ends - <p> Note: Zero, one, or multiple GC cycles might run between the start and end of a <code>gencon</code> global GC cycle.</p> <p>The XML elements and attribute values that define operations and increments of a particular cycle are specific to the policy and type of cycle. To follow how the different cycle's increments interleave in a log, you can locate the elements and attributes that record the increments and operations that belong to a particular type of cycle. For example, for the <code>gencon</code> policy, you can locate the start of the intermediate, concurrent increment of the global cycle by searching for the <code>&lt;concurrent-kickoff&gt;</code> element.</p> <p>For more information about the XML elements and attribute values that are used for a particular type of cycle for a particular policy, and examples of log output, see Log examples.</p> <p>You can determine the GC increments and operations that are associated with a particular instance of a cycle by using the <code>contextid</code> and <code>id</code> attributes:</p> <ol> <li>Determine the ID of the GC cycle: find the value of the <code>id</code> attribute of the <code>&lt;cycle-start&gt;</code> element that denotes the start of the GC cycle.  Note: the <code>id</code> attribute increases incrementally with each GC event.  </li> <li>Search for the <code>contextid</code> attribute values that match the GC cycle's ID. All GC increments, operations, and concurrent events that are associated with a particular cycle have a <code>contextid</code> attribute whose value matches the GC cycle's ID.</li> </ol>"},{"location":"vgclog_examples/","title":"Log examples","text":""},{"location":"vgclog_examples/#log-examples","title":"Log examples","text":"<p>To help you understand how garbage collection (GC) processes memory for your application and how these processes are recorded, a number of annotated log examples are provided from different GC policies. Each example covers a particular type of cycle from a particular policy. By following the examples, you can learn how to interpret the XML elements in a log.</p>"},{"location":"vgclog_examples/#gencon-examples","title":"<code>gencon</code> examples","text":"<p>The <code>gencon</code> policy uses two types of cycle; a partial GC cycle and a global GC cycle. By default, the partial GC cycle runs a stop-the-world (STW) scavenge operation. On specific platforms, <code>gencon</code> can run a concurrent scavenge operation (-Xgc:concurrentScavenge) instead, if enabled at run time.</p> <p>The start of a <code>gencon</code> cycle is recorded in the log by the following elements and attributes:</p> Table showing types of <code>gencon</code> cycle along with the corresponding trigger reason and XML elements for each type.  GC cycle Value of <code>type</code> attribute of the <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code>elements Element that logs the cycle trigger Trigger reason  Global <code>global</code> <code>&lt;concurrent-kickoff&gt;</code> Low free memory tenure area threshold reached. Cycle trigger element is located before the <code>&lt;cycle-start&gt;</code> element.  Partial <code>scavenge</code> <code>&lt;af-start&gt;</code> Allocation failure. Cycle trigger element is located before the <code>&lt;cycle-start&gt;</code> element. <p>You can use the <code>type</code> attribute of the <code>&lt;gc-start&gt;</code> and <code>&lt;gc-end&gt;</code> elements to locate a particular cycle. You can also locate a particular type of cycle by searching for the element that records the cycle trigger, which is located before the <code>&lt;cycle-start&gt;</code> element.</p> <p>You can analyze the increments and operations that are associated with a particular type of cycle by locating and interpreting the elements in the following table:</p> Table showing increments and operations that are associated with the <code>gencon</code> partial scavenge and global cycles. GC process Elements that log the start and end of the event Details  GC cycle <code>&lt;cycle-start&gt;</code>, <code>&lt;cycle-end&gt;</code> The start and end of a GC cycle.  GC STW increment <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> The start and end of a GC increment that begins with a pause.  GC STW increment <code>&lt;concurrent-kickoff&gt;</code> The start of the initial GC increment of the global concurrent cycle that begins the initial mark operation.  GC STW increment <code>&lt;concurrent-global-final&gt;</code> The start of the final GC increment of the global concurrent cycle that executes the final collection.  GC operations and suboperations <code>&lt;gc-op&gt;</code> A GC operation such as mark or sweep, or a suboperation such as class unload. <p> Note: For more information about the XML structure of GC cycles, see GC cycles. For more information about GC cycle increments, see GC increments and interleaving.</p> <p>The following examples use log excerpts to show how the different types of <code>gencon</code> cycle are logged.</p>"},{"location":"vgclog_examples/#scavenge-partial-gc-cycle","title":"Scavenge partial GC cycle","text":"<p>The following example is taken from a <code>gencon</code> log. The output is broken down into sections with supporting text to explain the GC processing that is taking place.</p> <p>To search for a scavenge partial GC cycle, you can search for the <code>type</code> attribute value <code>scavenge</code> in <code>cycle-start</code> and <code>cycle-end</code> elements, or search for the <code>&lt;af&gt;</code> element that logs the allocation failure trigger.</p> <p>By default, the <code>gencon</code> partial GC cycle runs by using a single STW pause. The cycle performs only one operation, a scavenge operation, which runs only on the nursery area. The cycle consists of a single GC increment, which is labeled by using the elements that are shown in the following table:</p> Table showing the <code>gencon</code> default partial scavenge cycle's GC increment and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment Details  scavenge single  STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> Contains detailed information about copied objects and the weak roots processing operation <p>The scavenge partial GC cycle follows a general structure in the verbose GC log as shown. Some elements are omitted for clarity:</p> <pre><code>\n&lt;exclusive-start/&gt;          (STW Pause starts)\n\n&lt;af-start/&gt;                 (allocation failure trigger recorded)\n\n&lt;cycle-start/&gt;              (scavenge cycle starts)\n\n&lt;gc-start&gt;                  (scavenge cycle increment starts)\n\n&lt;mem-info&gt;                  (memory status before operation)\n\n&lt;mem&gt;&lt;/mem&gt;                 (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-start&gt;\n\n&lt;allocation-stats/&gt;         (Snapshot of how memory was divided up between\n                            ... application threads before current cycle started)\n\n&lt;gc-op&gt; \u201cscavenge\"&lt;/gc-op&gt;  (scavenge operation completed)\n\n&lt;gc-end&gt;                    (scavenge cycle increment ends)\n\n&lt;mem-info&gt;                  (memory status after operation)\n\n&lt;mem&gt;&lt;/mem&gt;                 (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-end&gt;\n\n&lt;/cycle-end&gt;                (scavenge cycle ends)\n\n&lt;allocation-satisfied/&gt;     (required allocation has been achieved)\n\n&lt;af-end/&gt;\n\n&lt;exclusive-end&gt;             (STW for scavenge cycle ends)\n...\n\n</code></pre> <p>The first activity in the cycle is recorded by an <code>&lt;exclusive-start&gt;</code> element, which indicates the start of the STW pause. Application (or mutator) threads are halted to give the garbage collector exclusive access to the Java\u2122 object heap:</p> <pre><code>&lt;!-- Start of gencon scavenge partial GC cycle example --&gt;\n\n&lt;exclusive-start id=\"12392\" timestamp=\"2020-10-18T13:35:45.000\" intervalms=\"406.180\"&gt;\n  &lt;response-info timems=\"0.070\" idlems=\"0.070\" threads=\"0\" lastid=\"00000000013D6900\" lastname=\"LargeThreadPool-thread-68\" /&gt;\n&lt;/exclusive-start&gt;\n</code></pre> <p>The <code>&lt;af-start&gt;</code> element indicates that the cycle was triggered by an allocation failure in the nursery (<code>type=\"nursery\"</code>) area of the heap:</p> <pre><code>&lt;af-start id=\"12393\" threadId=\"00000000013D7280\" totalBytesRequested=\"8200\" timestamp=\"2020-10-18T13:35:45.000\" intervalms=\"418.233\" type=\"nursery\" /&gt;\n</code></pre> <p>The <code>&lt;cycle-start&gt;</code> element marks the start of the cycle. The attribute <code>type=\"scavenge\"</code> confirms that this activity is a scavenge partial GC cycle:</p> <pre><code>&lt;cycle-start id=\"12394\" type=\"scavenge\" contextid=\"0\" timestamp=\"2020-10-18T13:35:45.000\" intervalms=\"418.231\" /&gt;\n</code></pre> <p>Most elements are labeled with an <code>id</code> attribute that increases in value incrementally, a<code>timestamp</code> attribute, and a <code>contextid</code> attribute. All elements that record GC increments and operations that are associated with a particular cycle have a <code>contextid</code> value that matches the <code>id</code> value of the cycle. The <code>&lt;cycle-start&gt;</code> element of this example cycle has an <code>id=\"12394\"</code>, so all subsequent elements that have a <code>contextid=\"4\"</code>, such as the <code>&lt;gc-start&gt;</code> increment element and the <code>&lt;gc-op&gt;</code> operation element, are associated with this particular example cycle.  </p> <p>The <code>&lt;gc-start&gt;</code> element records the first GC increment. In this <code>&lt;gc-start&gt;</code> section, you can find information about the amount of memory available (<code>&lt;mem-info&gt;</code>) and where it is located in the Java object heap.</p> <p>The memory snapshot within the <code>&lt;gc-start&gt;</code> element is taken before the scavenge operation and can be compared with a similar snapshot that is taken afterward to understand the effect on the heap.</p> <pre><code>&lt;gc-start id=\"12395\" type=\"scavenge\" contextid=\"12394\" timestamp=\"2020-10-18T13:35:45.000\"&gt;\n  &lt;mem-info id=\"12396\" free=\"414960320\" total=\"1073741824\" percent=\"38\"&gt;\n    &lt;mem type=\"nursery\" free=\"0\" total=\"268435456\" percent=\"0\"&gt;\n      &lt;mem type=\"allocate\" free=\"0\" total=\"241565696\" percent=\"0\" /&gt;\n      &lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n    &lt;/mem&gt;\n    &lt;mem type=\"tenure\" free=\"414960320\" total=\"805306368\" percent=\"51\"&gt;\n      &lt;mem type=\"soa\" free=\"374694592\" total=\"765040640\" percent=\"48\" /&gt;\n      &lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n    &lt;/mem&gt;\n    &lt;remembered-set count=\"21474\" /&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The following statements describe the object heap memory allocation at the start of the increment:</p> <ul> <li>The allocate space of the nursery area is full, or close to full. The allocation failure was triggered by the lack of available memory in this space.</li> <li>The survivor space of the nursery area is reported as 'full' to reflect that no available memory is available to allocate to the mutator threads. The entire survivor space is reserved for GC operations during the GC increment.</li> <li>The tenure area has 395.7 MB (414,960,320B) of free memory available.</li> </ul> <p>The next element <code>&lt;allocation-stats&gt;</code> shows a snapshot, which was taken before the cycle started, of how memory was divided up between application threads. In this example, the thread that used the most memory was <code>LargeThreadPool-thread-79</code>.</p> <pre><code>&lt;allocation-stats totalBytes=\"235362176\" &gt;\n  &lt;allocated-bytes non-tlh=\"32880\" tlh=\"235329296\" /&gt;\n  &lt;largest-consumer threadName=\"LargeThreadPool-thread-79\" threadId=\"00000000013F0C00\" bytes=\"6288544\" /&gt;\n&lt;/allocation-stats&gt;\n</code></pre> <p>The scavenge GC operation is recorded by the <code>&lt;gc-op&gt;</code> element; child elements record details about the operation. For example,</p> <pre><code>&lt;gc-op id=\"12397\" type=\"scavenge\" timems=\"11.649\" contextid=\"12394\" timestamp=\"2020-10-18T13:35:45.012\"&gt;\n  &lt;scavenger-info tenureage=\"7\" tenuremask=\"4080\" tiltratio=\"89\" /&gt;\n  &lt;memory-copied type=\"nursery\" objects=\"154910\" bytes=\"6027440\" bytesdiscarded=\"394832\" /&gt;\n  &lt;memory-copied type=\"tenure\" objects=\"16171\" bytes=\"562848\" bytesdiscarded=\"3064\" /&gt;\n  &lt;ownableSynchronizers candidates=\"10838\" cleared=\"10824\" /&gt;\n  &lt;references type=\"soft\" candidates=\"24\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"16\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"390\" cleared=\"269\" enqueued=\"269\" /&gt;\n  &lt;references type=\"phantom\" candidates=\"1\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;object-monitors candidates=\"132\" cleared=\"0\"  /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The <code>&lt;memory-copied&gt;</code> element indicates that 5.75 MB (6,027,440B) of reachable objects were moved by the scavenge operation from the allocate space to the survivor space in the nursery area, and 0.54 MB(562,848 B) were moved to the tenure area.</p> <p>The <code>&lt;scavenger-info&gt;</code> element shows that the tenure age is set to <code>7</code>. Any object in the allocate space with an age less than or equal to <code>7</code> is copied to the survivor space during this <code>scavenge</code>operation. Any object that is copied between the allocate and survivor areas more than <code>7</code> times is moved to the tenure area.</p> <p>For more information about how the scavenge operation acts on the Java object heap, see GC processing.</p> <p>The end of the increment is recorded with <code>&lt;gc-end&gt;</code> and provides another snapshot of memory allocation on the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"12398\" type=\"scavenge\" contextid=\"12394\" durationms=\"11.785\" usertimems=\"46.278\" systemtimems=\"0.036\" stalltimems=\"0.145\" timestamp=\"2020-10-18T13:35:45.012\" activeThreads=\"4\"&gt;\n  &lt;mem-info id=\"12399\" free=\"649473560\" total=\"1073741824\" percent=\"60\"&gt;\n    &lt;mem type=\"nursery\" free=\"235142120\" total=\"268435456\" percent=\"87\"&gt;\n      &lt;mem type=\"allocate\" free=\"235142120\" total=\"241565696\" percent=\"97\" /&gt;\n      &lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n    &lt;/mem&gt;\n    &lt;mem type=\"tenure\" free=\"414331440\" total=\"805306368\" percent=\"51\" macro-fragmented=\"0\"&gt;\n      &lt;mem type=\"soa\" free=\"374065712\" total=\"765040640\" percent=\"48\" /&gt;\n      &lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n    &lt;/mem&gt;\n    &lt;pending-finalizers system=\"0\" default=\"0\" reference=\"269\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"13792\" /&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The Java object heap memory allocation at the end of the increment is as follows:</p> <ul> <li>97% of the allocate space of the nursery area is now available as free memory.</li> <li>The survivor space of the nursery area is still reported as 'full' to reflect that the entire survivor space is reserved for GC operations during the next GC increment.</li> <li>The tenure area has 395 MB (414,331,440B) of free memory available. The scavenge operation copied 562 KB from the nursery area to the tenure area so less memory is now available in the tenure area.</li> </ul> <p>The scavenge operation successfully reclaimed memory in the allocate space of the nursery area by copying objects from the allocate space into the survivor space of the nursery area, and copying objects from the survivor space into the tenure area.</p> <p>The cycle ends (<code>&lt;cycle-end&gt;</code>). The following <code>&lt;allocation-satisfied&gt;</code> element indicates that the allocation request that caused the allocation failure can now complete successfully. The STW pause ends with the <code>&lt;exclusive-end&gt;</code> element:</p> <pre><code>&lt;cycle-end id=\"12400\" type=\"scavenge\" contextid=\"12394\" timestamp=\"2020-10-18T13:35:45.012\" /&gt;\n&lt;allocation-satisfied id=\"12401\" threadId=\"00000000013D6900\" bytesRequested=\"8200\" /&gt;\n&lt;af-end id=\"12402\" timestamp=\"2020-10-18T13:35:45.012\" threadId=\"00000000013D7280\" success=\"true\" from=\"nursery\"/&gt;\n&lt;exclusive-end id=\"12403\" timestamp=\"2020-10-18T13:35:45.012\" durationms=\"12.319\" /&gt;\n\n&lt;!-- End of gencon partial GC cycle example --&gt;\n</code></pre>"},{"location":"vgclog_examples/#summary","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example global cycle has the following characteristics:</p> <ul> <li> <p>The GC cycle begins with an STW pause due to an allocation failure.</p> </li> <li> <p>All GC operations and suboperations that are associated with this cycle occur during the STW pause</p> </li> <li> <p>The cycle consists of only 1 GC increment, which runs a single scavenge operation.</p> </li> <li> <p>The GC cycle reclaims memory in the allocate area of the nursery area by coping objects from the allocate area to the survivor area and also to the tenure area.</p> </li> </ul>"},{"location":"vgclog_examples/#concurrent-scavenge-partial-gc-cycle-non-default","title":"Concurrent scavenge partial GC cycle (non-default)","text":"<p>When concurrent scavenge mode is enabled, the partial GC cycle is run as a Concurrent Scavenge cycle. This partial GC cycle is divided into increments to enable the majority of the scavenge operation to run concurrently with running application (or mutator) threads. The concurrent increment can run while application threads run, and also while the intermediate concurrent increment of the global GC cycle runs. The interleaving of the concurrent scavenge partial GC cycle with the global cycle can be seen in the logs.</p> <p>The following elements log the GC increments and operations of the concurrent scavenge partial GC cycle:</p> Table showing the <code>gencon</code> concurrent (non-default) partial scavenge cycle's GC increment and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment Details  scavenge initial  STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> Root scanning, reported as a single scavenge operation.  scavenge intermediate  concurrent <code>&lt;concurrent-start&gt;</code>, <code>&lt;concurrent-end&gt;</code> Live objects are traversed and evacuated (*copy forward*). Operation is reported as a <code>scavenge</code> operation.  scavenge final STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> weak roots scanning, reported as a complex scavenge operation. <code>&lt;gc-op&gt;</code> contains specific details for each of the weak root groups. <p>To search for a concurrent scavenge partial GC cycle, you can search for the <code>type</code> attribute value <code>scavenge</code> in <code>cycle-start</code> and <code>cycle-end</code> elements, or search for the <code>&lt;af&gt;</code> element that logs the allocation failure trigger.</p> <p>You can locate the concurrent scavenge partial cycle's concurrent increment by searching for <code>&lt;concurrent-start&gt;</code> and <code>&lt;concurrent-end&gt;</code>. The global cycle's intermediate concurrent increment, which can run at the same time, is not logged by an element, but begins immediately after application threads are restarted following the <code>&lt;cycle-start type=\"global\"/&gt;</code> element. For more information about the global cycle's intermediate concurrent increment, see <code>gencon</code> global GC cycle. For more information about GC increments, see GC increments and interleaving.</p>"},{"location":"vgclog_examples/#gencon-global-gc-cycle","title":"<code>gencon</code> global GC cycle","text":"<p>The following example shows how a global GC cycle is recorded in a <code>gencon</code> policy verbose GC log. The output is broken down into sections with supporting text to explain the GC processing that is taking place.</p> <p>The global GC cycle runs when the tenure area is close to full, which typically occurs after many partial cycles. As such, the output can be found part way down a full log. For more information about the GC initialization section, see Initialization . For an example log output for a <code>gencon</code> partial cycle, see Scavenge partial GC cycle.</p> <p>The global GC cycle is split into three increments, as shown in GC increments and interleaving. Splitting the cycle operations into the following increments reduces pause times by running the majority of the GC work concurrently. The concurrent increment pauses when a partial GC cycle is triggered and resumes after the partial cycle, or multiple cycles, finish. The interleaving of partial GC cycles with the global cycle's intermediate concurrent increment can be seen in the following <code>gencon</code> global GC cycle log output. A single partial GC cycle is logged between the initial and final increments of the global cycle.</p> <p>To search for a global cycle, you can search for the <code>type</code> attribute value <code>global</code> in <code>cycle-start</code> and <code>cycle-end</code> elements, or search for the element that logs the initial concurrent increment, <code>&lt;concurrent-kickoff&gt;</code>.</p> <p>The following elements log the GC increments and operations of the global GC cycle:</p> Table showing the <code>gencon</code> global cycle's GC increment and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment Details  n/a - initiates cycle initial STW <code>&lt;concurrent-kickoff&gt;</code> No <code>&lt;gc-op&gt;</code> is logged. This increment just initiates the concurrent mark increment.  concurrent mark intermediate  concurrent none <code>&lt;concurrent-trace-info&gt;</code> records the progress of the concurrent mark increment.  final collection final STW  <code>&lt;concurrent-global-final&gt;</code> The increment is typically triggered when a card cleaning threshold is reached. The completion of a tracing phase can also trigger the increment. Operations include a final concurrent mark, a sweep, and an optional class unload and compact. <p>The global GC cycle follows a general structure in the verbose GC log. Some child elements are omitted for clarity. Multiple partial GC cycles can start and finish between the start and end of a global GC cycle. In the following example, the structure includes a single partial GC cycle within the global cycle:</p> <pre><code>\n&lt;concurrent-kickoff/&gt;       (global cycle 1st increment recorded)\n\n&lt;exclusive-start/&gt;          (STW pause starts)\n\n&lt;cycle-start/&gt;              (global cycle starts)\n\n&lt;exclusive-end/&gt;            (STW pause ends)\n\n(mutator threads running, global cycle concurrent increment running concurrently)\n\n\n&lt;exclusive-start/&gt;          (STW for partial GC cycle starts)\n\n\n...                         (partial GC cycle starts and completes)\n\n\n&lt;exclusive-end/&gt;            (STW for partial GC cycle ends)\n\n(mutator threads running, global cycle concurrent increment running concurrently)\n\n&lt;exclusive-start/&gt;          (STW pause starts)\n\n&lt;concurrent-global-final/&gt;  (global cycle final increment recorded)\n\n&lt;gc-start/&gt;                 (global cycle final increment starts)\n\n&lt;allocation-stats/&gt;         (Snapshot of how memory was divided up between\n                            ... application threads before current cycle started)\n\n&lt;mem-info&gt;                  (memory status before operations)\n\n&lt;mem&gt;&lt;/mem&gt;                 (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-start&gt;\n\n&lt;gc-op&gt; \u201ctype=rs-scan\"&lt;/gc-op&gt;        (remembered set scan completed)\n\n&lt;gc-op&gt;\u201dtype=card-cleaning\" &lt;/gc-op&gt;  (card cleaning completed)\n\n&lt;gc-op&gt; \u201ctype=mark\u201d&lt;/gc-op&gt;           (final mark operation and weak roots processing completed)\n\n&lt;gc-op&gt; \u201ctype=classunload\u201d&lt;/gc-op&gt;    (class unload operation completed)\n\n&lt;gc-op \u201dtype=sweep\u201d /&gt;                (sweep operation completed)\n\n&lt;gc-end&gt;                     (global cycle final increment ends)\n\n&lt;mem-info&gt;                   (memory status after operations)\n\n&lt;mem&gt;&lt;/mem&gt;                  (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-end&gt;\n\n&lt;/cycle-end&gt;                 (global cycle ends)\n\n&lt;exclusive-end&gt;              (STW pause ends)\n\n&lt;exclusive-start&gt;            (STW pause starts)\n...\n\n</code></pre> <p>The first activity in the cycle is recorded by a <code>&lt;concurrent-kickoff&gt;</code> element, which records the start of the first of three increments that make up a <code>gencon</code> global GC cycle. The <code>&lt;concurrent-kickoff&gt;</code> element records the following information:</p> <ul> <li>The reason why the GC cycle was triggered. For a <code>gencon</code> global cycle, the cycle is triggered when the amount of free memory decreases to a threshold value, the <code>thresholdFreeBytes</code> value.</li> <li>The target number of bytes, <code>targetBytes</code>, that the cycle aims to mark concurrently.</li> <li>The current available memory in the different parts of the heap.</li> </ul> <pre><code>&lt;concurrent-kickoff id=\"12362\" timestamp=\"2020-10-18T13:35:44.341\"&gt;\n\n&lt;kickoff reason=\"threshold reached\" targetBytes=\"239014924\" thresholdFreeBytes=\"33024922\" remainingFree=\"32933776\" tenureFreeBytes=\"42439200\" nurseryFreeBytes=\"32933776\" /&gt;\n\n&lt;/concurrent-kickoff&gt;\n</code></pre> <p>For this example, the <code>remainingFree</code> bytes value of 31.4 MB (32,933,776B) is approaching the <code>thresholdFreeBytes</code> value of 31.5 MB (33,024,922B) so a global cycle is triggered.  </p> <p>This cycle aims to trace 228 MB (239,014,924B) during the concurrent increment. If the concurrent increment is interrupted by a card cleaning threshold value before it traces all 228 MB, the final STW increment completes the tracing during the STW pause.</p> <p> Note: To analyze specific parts of a cycle, you can search for the elements that mark a specific increment of the cycle. For example, you can search for the  element to locate the final increment of the <code>gencon</code> global cycle. See the details of a particular cycle, such as the <code>gencon</code> global GC cycle, to determine the element names for particular STW or concurrent GC increments or operations. <p>The next element recorded in the log, the <code>&lt;exclusive-start&gt;</code>element, records the start of an STW pause:</p> <pre><code>&lt;exclusive-start id=\"12363\" timestamp=\"2020-10-18T13:35:44.344\" intervalms=\"342.152\"&gt;\n\n&lt;response-info timems=\"0.135\" idlems=\"0.068\" threads=\"3\" lastid=\"00000000015DE600\" lastname=\"LargeThreadPool-thread-24\" /&gt;\n\n&lt;/exclusive-start&gt;\n</code></pre> <p>The following <code>&lt;gc-start&gt;</code> element records details of the start of a new cycle.</p> <pre><code>&lt;cycle-start id=\"12364\" type=\"global\" contextid=\"0\" timestamp=\"2020-10-18T13:35:44.344\" intervalms=\"516655.052\" /&gt;\n</code></pre> <p>The <code>type</code> attribute records the cycle as a global cycle. The <code>contextid</code> of the cycle is, which indicates that all GC events that are associated with this cycle are tagged in relation to the <code>id</code> of this cycle. In particular, all subsequent elements that are associated with this particular example cycle have a <code>contextid</code> value equal to the <code>&lt;cycle-start&gt;</code> <code>id</code> attribute value of <code>\u201c12634\u201d</code>.</p> <p>The next element in the log is <code>&lt;exclusive-end&gt;</code>, which records the end of the STW pause:</p> <pre><code>&lt;exclusive-end id=\"12365\" timestamp=\"2020-10-18T13:35:44.344\" durationms=\"0.048\" /&gt;\n</code></pre> <p>The operations and suboperations of the second increment of the <code>gencon</code> global cycle are now running concurrently.</p> <p>The next section of the logs records an STW pause that is associated with an allocation failure. The <code>&lt;cycle-start&gt;</code> element that follows this STW pause indicates that the cycle is a <code>scavenge</code> cycle, which is the partial GC cycle that is used by the <code>gencon</code> GC:</p> <pre><code>...\n&lt;cycle-start id=\"12368\" type=\"scavenge\" contextid=\"0\" timestamp=\"2020-10-18T13:35:44.582\" intervalms=\"580.047\" /&gt;\n...\n</code></pre> <p>Subsequent elements have a <code>contextid=\u201c12368\u201d</code>, which matches the <code>id</code> of this new <code>scavenge</code>cycle. For more information about how this cycle is recorded in the logs, see Scavenge partial GC cycle.</p> <p>The operations and suboperations of the second, concurrent increment of the <code>gencon</code> global cycle are paused while the STW <code>scavenge</code> operation is running, and resume when the STW pause finishes.</p> <p>After the partial GC cycle completes and the STW pause finishes, the log records a new STW pause, which is triggered to enable the final <code>gencon</code> global GC increment to run. This final increment finishes marking the nursery area and completes the global cycle. The <code>&lt;exclusive-start&gt;</code> element is followed by a <code>&lt;concurrent-global-final&gt;</code> element, which logs the beginning of this final increment (and by implication, the end of the second increment).</p> <pre><code>&lt;exclusive-start id=\"12378\" timestamp=\"2020-10-18T13:35:44.594\" intervalms=\"12.075\"&gt;\n\n&lt;response-info timems=\"0.108\" idlems=\"0.040\" threads=\"3\" lastid=\"00000000018D3800\" lastname=\"LargeThreadPool-thread-33\" /&gt;\n\n&lt;/exclusive-start&gt;\n\n&lt;concurrent-global-final id=\"12379\" timestamp=\"2020-10-18T13:35:44.594\" intervalms=\"516905.029\" &gt;\n\n&lt;concurrent-trace-info reason=\"card cleaning threshold reached\" tracedByMutators=\"200087048\" tracedByHelpers=\"12164180\" cardsCleaned=\"4966\" workStackOverflowCount=\"0\" /&gt;\n\n&lt;/concurrent-global-final&gt;\n</code></pre> <p>The <code>reason</code> attribute of the <code>&lt;concurrent-trace-info&gt;</code> child element indicates that this final STW increment of the global cycle was triggered because a card-cleaning threshold was reached. The concurrent tracing was stopped prematurely and the <code>targetBytes</code> concurrent tracing target, recorded at the cycle start by <code>&lt;concurrent-kickoff&gt;</code>, was not achieved concurrently. If the concurrent tracing completes without interruption, the <code>&lt;concurrent-trace-info</code> element logs <code>reason=tracing completed</code>.  </p> <p>In the next section that begins with the <code>gc-start</code> element, you can find information about the amount of memory available (<code>&lt;mem-info&gt;</code>) and where it is located in the java object heap. This snapshot is taken before the final increment's operations and suboperations are run and can be compared with a similar snapshot that is taken afterward to understand the effect on the heap. The child element attribute values of the<code>&lt;mem&gt;</code> and <code>&lt;mem-info&gt;</code> elements indicate the status of the memory.</p> <p> Note: You can double check that the increment is associated with the GC global cycle in the example by checking the <code>contextid</code> attribute value matches the <code>id=12364</code> attribute value of the cycle's  element. <pre><code>&lt;gc-start id=\"12380\" type=\"global\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.594\"&gt;\n\n&lt;mem-info id=\"12381\" free=\"277048640\" total=\"1073741824\" percent=\"25\"&gt;\n\n&lt;mem type=\"nursery\" free=\"234609440\" total=\"268435456\" percent=\"87\"&gt;\n\n&lt;mem type=\"allocate\" free=\"234609440\" total=\"241565696\" percent=\"97\" /&gt;\n\n&lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;mem type=\"tenure\" free=\"42439200\" total=\"805306368\" percent=\"5\"&gt;\n\n&lt;mem type=\"soa\" free=\"2173472\" total=\"765040640\" percent=\"0\" /&gt;\n\n&lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;pending-finalizers system=\"0\" default=\"0\" reference=\"405\" classloader=\"0\" /&gt;\n\n&lt;remembered-set count=\"17388\" /&gt;\n\n&lt;/mem-info&gt;\n\n&lt;/gc-start&gt;\n\n&lt;allocation-stats totalBytes=\"827488\" &gt;\n\n&lt;allocated-bytes non-tlh=\"96\" tlh=\"827392\" /&gt;\n\n&lt;largest-consumer threadName=\"LargeThreadPool-thread-68\" threadId=\"00000000013D6900\" bytes=\"65632\" /&gt;\n\n&lt;/allocation-stats&gt;\n</code></pre> <p>The next element <code>&lt;allocation-stats&gt;</code> shows a snapshot of how memory was divided up between application threads before the current cycle started. In this example, the thread that used the most memory was <code>LargeThreadPool-thread-68</code>.</p> <p>For this example, at the start of this GC increment, the tenure area is low on free memory, as expected. 25% of the total heap is available as free memory, which is split between the following areas of the heap:</p> <ul> <li>The nursery area, which has 223.7 MB (234,609,440B) of free memory available. The free memory is only available in the allocate space of the nursery area. The survivor space of the nursery area is reported as 'full' to reflect that no available memory is available to allocate to the mutator threads. The entire survivor space is reserved for GC operations during the GC increment.</li> <li>The tenure area, which has 40.5 MB (42,439,200B) available as free memory, which is only 5% of its total memory. Most of this free memory is in the large object area (LOA). Almost no free memory is available in the small object area (SOA).</li> </ul> <p>The <code>&lt;gc-op&gt;</code> elements and their child elements contain information about the operations and suboperations in the increment. The final increment of the <code>gencon</code> global cycle consists of multiple operations, each logged with a <code>&lt;gc-op&gt;</code> element. The type of operation is shown by the <code>&lt;gc-op&gt;</code> <code>type</code> attribute. The final increment of the example log runs five types of operation:</p> <ol> <li><code>rs-scan</code></li> <li><code>card-cleaning</code></li> <li><code>mark</code></li> <li><code>classunload</code></li> <li><code>sweep</code></li> </ol> <p> Note: The final increment of a <code>gencon</code> global cycle can include an optional <code>compact</code> suboperation.</p> <p>For more information about the different types of GC operation, see GC operations.</p> <pre><code>&lt;gc-op id=\"12382\" type=\"rs-scan\" timems=\"3.525\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.598\"&gt;\n\n&lt;scan objectsFound=\"11895\" bytesTraced=\"5537600\" workStackOverflowCount=\"0\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12383\" type=\"card-cleaning\" timems=\"2.910\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.601\"&gt;\n\n&lt;card-cleaning cardsCleaned=\"3603\" bytesTraced=\"5808348\" workStackOverflowCount=\"0\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12384\" type=\"mark\" timems=\"6.495\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.607\"&gt;\n\n&lt;trace-info objectcount=\"1936\" scancount=\"1698\" scanbytes=\"61200\" /&gt;\n\n&lt;finalization candidates=\"389\" enqueued=\"1\" /&gt;\n\n&lt;ownableSynchronizers candidates=\"5076\" cleared=\"523\" /&gt;\n\n&lt;references type=\"soft\" candidates=\"18420\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"32\" maxThreshold=\"32\" /&gt;\n\n&lt;references type=\"weak\" candidates=\"19920\" cleared=\"114\" enqueued=\"60\" /&gt;\n\n&lt;references type=\"phantom\" candidates=\"671\" cleared=\"50\" enqueued=\"50\" /&gt;\n\n&lt;stringconstants candidates=\"40956\" cleared=\"109\" /&gt;\n\n&lt;object-monitors candidates=\"182\" cleared=\"51\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12385\" type=\"classunload\" timems=\"1.607\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.609\"&gt;\n\n&lt;classunload-info classloadercandidates=\"425\" classloadersunloaded=\"6\" classesunloaded=\"2\" anonymousclassesunloaded=\"1\" quiescems=\"0.000\" setupms=\"1.581\" scanms=\"0.019\" postms=\"0.007\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12386\" type=\"sweep\" timems=\"9.464\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.618\" /&gt;\n</code></pre> <p>The end of the increment is recorded with <code>&lt;gc-end&gt;</code> and provides another snapshot of memory in the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"12387\" type=\"global\" contextid=\"12364\" durationms=\"24.220\" usertimems=\"86.465\" systemtimems=\"0.000\" stalltimems=\"2.846\" timestamp=\"2020-10-18T13:35:44.618\" activeThreads=\"4\"&gt;\n\n&lt;mem-info id=\"12388\" free=\"650476504\" total=\"1073741824\" percent=\"60\"&gt;\n\n&lt;mem type=\"nursery\" free=\"235516088\" total=\"268435456\" percent=\"87\"&gt;\n\n&lt;mem type=\"allocate\" free=\"235516088\" total=\"241565696\" percent=\"97\" /&gt;\n\n&lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;mem type=\"tenure\" free=\"414960416\" total=\"805306368\" percent=\"51\" micro-fragmented=\"98245682\" macro-fragmented=\"0\"&gt;\n\n&lt;mem type=\"soa\" free=\"374694688\" total=\"765040640\" percent=\"48\" /&gt;\n\n&lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;pending-finalizers system=\"1\" default=\"0\" reference=\"515\" classloader=\"0\" /&gt;\n\n&lt;remembered-set count=\"13554\" /&gt;\n\n&lt;/mem-info&gt;\n\n&lt;/gc-end&gt;\n</code></pre> <p>60% of the heap now contains free memory as a result of the final global cycle increment, which is split between the following areas of the heap:</p> <ul> <li>The nursery area, which gained 0.9 MB of free memory. The nursery area now has 224.6 MB (235,516,088B) available as free memory. At the start of the final increment, the nursery area had 223.7 MB (234,609,440B) of free memory available.</li> <li>The tenure area, which gained 355.2 MB (372,521,216B) of free memory. (the tenure area now has 395.7 MB (414,960,416B) available as free memory. At the start of the final increment, the tenure area had 40.5 MB (42,439,200B) of free memory available).</li> </ul> <p> Note: The global GC cycle runs to reclaim memory in the tenure area. The freeing up of memory in the nursery area is achieved by using the partial GC cycle. For more information, see <code>gencon</code> policy (default).</p> <p>After the final increment of the global cycle completes, the global cycle ends and the STW pause ends, as shown in the following output:</p> <pre><code>&lt;cycle-end id=\"12389\" type=\"global\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.619\" /&gt;\n\n&lt;exclusive-end id=\"12391\" timestamp=\"2020-10-18T13:35:44.619\" durationms=\"24.679\" /&gt;\n</code></pre>"},{"location":"vgclog_examples/#summary_1","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example global cycle has the following characteristics:</p> <ul> <li> <p>The GC global cycle is triggered when a memory threshold is reached and begins with an STW pause.</p> </li> <li> <p>After the first increment of the GC global cycle completes, the STW pause ends and the second increment runs concurrently.</p> </li> <li> <p>A single partial GC cycle starts and finishes between the start and end of the concurrent increment.</p> </li> <li> <p>An STW pause begins after the concurrent increments completes, during which the third and final increment of the global cycle, which consists of five operations, runs.</p> </li> <li> <p>The global GC cycle reclaims memory in the tenure area and a small amount of memory in the nursery area.</p> </li> </ul>"},{"location":"vgclog_examples/#balanced-examples","title":"<code>balanced</code> examples","text":"<p>The <code>balanced</code> policy (<code>-Xgcpolicy:balanced</code>) uses two types of cycle to perform GC; a partial GC cycle and a global GC mark cycle. The policy might also run a third type of cycle, which is a global cycle, to reclaim memory after an allocation failure that results from tight memory conditions.</p> <p>For more information about the cycles used in a particular policy, see GC policies.</p> <p>The start of a <code>balanced</code> cycle is recorded in the log by the following elements and attributes:</p> Table showing types of <code>balanced</code> cycle, the corresponding trigger, and XML elements for each `type`.  GC cycle or increment Value of <code>type</code> attribute of the cycle or increment elements Element that logs the cycle trigger Trigger reason  partial cycle <code>partial gc</code> <code>&lt;allocation-taxation&gt;</code> Allocation taxation threshold reached. global mark cycle <code>global mark phase</code> <code>&lt;allocation-taxation&gt;</code> Allocation taxation threshold reached. global mark STW subincrement of global mark cycle <code>mark increment</code> n/a Allocation taxation threshold reached global mark concurrent subincrement of global mark cycle <code>GMP work packet processing</code> n/a Allocation taxation threshold reached global cycle <code>global garbage collect</code> <code>&lt;af-start&gt;</code> (or <code>&lt;sys-start reason=\"explicit\"&gt;</code> if triggered explicitly) Allocation failure. Occurs under tight memory conditions. Cycle runs rarely. <p>To locate a particular type of cycle, you can search for the <code>type</code> attribute of the <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code> elements.</p> <p>When memory in the Java object heap reaches a memory threshold, called an allocation taxation threshold, a <code>balanced</code> partial GC cycle, <code>balanced</code> global mark cycle, or <code>balanced</code> global mark cycle increment, is triggered. If the available memory in the heap is low, the GC triggers a <code>balanced</code> global mark cycle, or a global mark cycle increment if the global mark cycle is in progress. Otherwise, the GC triggers a partial cycle.</p> <p>Partial GC cycles, global mark cycles, and global GC cycles set the allocation taxation threshold at the end of their cycle or increment to schedule the next cycle or increment. For <code>balanced</code> cycles, the taxation on the mutator threads refers to pausing the mutator threads while GC work is run.</p> <p>When a partial cycle ends, if the cycle is not run between global mark phase increments of a global mark cycle, and a global mark cycle is not scheduled as the next cycle, the allocation taxation threshold is set to trigger the next partial cycle when the eden space is full. Specifically, the allocation threshold is set to be equal to the size of the eden space.</p> <p>If a partial cycle runs within a global mark cycle, or if a global mark cycle is scheduled as the next cycle, the allocation taxation threshold, set at the end of the partial cycle, is set to be smaller than the size of the eden space.  Specifically, the allocation taxation threshold is set to be half the size of the eden space so that the next global mark cycle or global mark cycle increment has enough memory available in the eden space to run.</p> <p>For more information about GC increments, see GC increments and interleaving.</p> <p>You can analyze the increments and operations that are associated with a particular type of cycle by locating and interpreting the elements in the following table:</p> Table showing increments and operations that are associated with the <code>balanced</code> partial and global mark cycles GC process Elements that log the start and end of the event&gt; Details  GC cycle <code>&lt;cycle-start&gt;</code>,<code>&lt;cycle-end&gt;</code> The start and end of a GC cycle  GC STW increment <code>&lt;gc-start&gt;</code><code>&lt;gc-end&gt;</code> The start and end of a GC increment or subincrement that begins with a STW pause. For example, a <code>global mark phase</code> global mark GC cycle increment or a partial GC cycle increment  GC concurrent increment <code>&lt;concurrent-start&gt;</code>, <code>&lt;concurrent-end&gt;</code> The start of the concurrent global mark phase work packet processing subincrements of the global mark cycle  GC operations and phases <code>&lt;gc-op&gt;</code> A GC operation such as mark or sweep, or a suboperation such as class unload. <p>For more information about the XML structure of GC cycles, see GC cycles.</p> <p>The following sections use log excerpts to show how the different GC processes are logged.</p>"},{"location":"vgclog_examples/#balanced-partial-gc-cycle","title":"<code>balanced</code> partial GC cycle","text":"<p>The following example is taken from a <code>balanced</code> policy verbose GC log. The output is broken down into sections to explain the GC processing that is taking place.</p> <p>To search for a <code>balanced</code> partial GC cycle, you can search for the <code>type</code> attribute value <code>partial gc</code> in <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code> elements.</p> <p>The partial GC cycle reclaims memory in the heap for the allocation of new objects by reducing the number of used regions. The partial GC cycle always reduces used regions in the eden space and might also reclaim memory from older regions. Multiple partial GC cycles often run in between global mark phase increments of the <code>balanced</code> global mark GC cycle.  </p> <p>All the operations in a partial GC cycle run during a single STW pause, as shown in the following table:</p> Table showing the <code>balanced</code> partial GC cycle operation and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment  copy forward, and optionally class unload, sweep, and compact single  STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> <p>The following general structure shows a <code>balanced</code> partial GC cycle. Some child elements are omitted for clarity:</p> <pre><code>&lt;exclusive-start/&gt;                       (STW pause starts)\n\n&lt;allocation-taxation/&gt;                   (memory threshold trigger recorded)\n\n&lt;cycle-start/&gt;                            (partial cycle starts)\n\n&lt;gc-start/&gt;                             (partial  cycle increment starts)\n\n&lt;mem-info&gt;                            (memory status before operations)\n\n  &lt;mem&gt;&lt;/mem&gt;                         (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-start&gt;\n\n&lt;allocation-stats/&gt;                  (Snapshot of how memory was divided up between\n                                     ... application threads before current cycle started)\n\n&lt;gc-op&gt; type=\"copy forward\" &lt;/gc-op&gt;    (copy forward operation completed)\n\n&lt;gc-op&gt; type=\"class unload\" &lt;/gc-op&gt;    (class unload operation completed)\n\n&lt;gc-op&gt; type=\"sweep\" &lt;/gc-op&gt;           (sweep operation completed)\n\n&lt;gc-op&gt; type=\"compact\" &lt;/gc-op&gt;         (compact operation completed)\n\n&lt;gc-end&gt;                                (partial cycle increment ends)\n\n&lt;mem-info&gt;                            (memory status after operations)\n\n  &lt;mem&gt;&lt;/mem&gt;                         (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-end&gt;\n\n&lt;cycle-end&gt;                               (partial cycle ends)\n\n&lt;exclusive-end&gt;                           (STW pause ends)\n</code></pre> <p>When the <code>balanced</code> partial GC cycle is triggered, the GC runs an STW pause. Application (or mutator) threads are halted to give the garbage collector exclusive access to the heap. The STW pause is recorded in the logs by the <code>&lt;exclusive-start&gt;</code> element.</p> <pre><code>&lt;exclusive-start id=\"184\" timestamp=\"2021-02-26T11:11:42.310\" intervalms=\"3745.790\"&gt;\n  &lt;response-info timems=\"3.138\" idlems=\"1.056\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n</code></pre> <p>An allocation taxation threshold triggers a <code>balanced</code> partial GC cycle. The logs record this trigger reason by using the<code>&lt;allocation-taxation&gt;</code> element.</p> <pre><code>&lt;allocation-taxation id=\"185\" taxation-threshold=\"2147483648\" timestamp=\"2021-02-26T11:11:42.311\" intervalms=\"3745.785\" /&gt;\n</code></pre> <p>Details about the start of the cycle are recorded by the <code>&lt;cycle-start&gt;</code> element. The cycle is recorded as a <code>partial gc</code> with an <code>id=336</code>. Any subsequent elements that are associated with this cycle have a <code>contextid=186</code> to match the cycle <code>id</code>. You can use this <code>contextid</code> value to distinguish the partial GC cycle increment and operations from interleaving increments and operations of other <code>balanced</code> cycles, such as global mark cycles.</p> <pre><code>&lt;cycle-start id=\"186\" type=\"partial gc\" contextid=\"0\" timestamp=\"2021-02-26T11:11:42.311\" intervalms=\"3745.805\" /&gt;\n\n</code></pre> <p>The partial cycle begins its only GC increment, recorded by using the <code>&lt;gc-start&gt;</code> element. You can understand the effect that the increment operations have on the heap by comparing snapshots of the memory that are taken at the start and the end of the increment.  The child elements <code>&lt;mem-info&gt;</code> and <code>&lt;mem&gt;</code> of the <code>&lt;gc-start&gt;</code> and <code>&lt;gc-end&gt;</code> elements record the amount of memory available and where it is located in the heap.</p> <pre><code>&lt;gc-start id=\"187\" type=\"partial gc\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.311\"&gt;\n  &lt;mem-info id=\"188\" free=\"897581056\" total=\"4294967296\" percent=\"20\"&gt;\n    &lt;mem type=\"eden\" free=\"0\" total=\"2147483648\" percent=\"0\" /&gt;\n    &lt;arraylet-primitive objects=\"1\" leaves=\"4\" largest=\"4\" /&gt;\n    &lt;remembered-set count=\"2749664\" freebytes=\"160705664\" totalbytes=\"171704320\" percent=\"93\" regionsoverflowed=\"1\" regionsstable=\"12\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>As expected, at the start of this increment, the eden regions are full. 856 MB (897,581,056 B) of the total 4096 MB (4294,967,296 B) heap, equivalent to 20% of the heap, is available as free memory.</p> <p>The status of the remembered set, a metastructure specific to Eclipse OpenJ9\u2122 generational garbage collectors, is reported by the <code>&lt;remembered-set&gt;</code> element. The remembered set metastructure keeps a record of any object references that cross different regions. Each region corresponds to a single remembered set.</p> <p>The partial GC cycle uses and prunes the remembered set. The <code>regionsoverflowed</code> value records the number of regions that exceeded the non-object heap memory allocation that is reserved for the remembered set. The partial GC cycle cannot reclaim memory from these overflow regions. The partial GC cycle also cannot reclaim memory from any regions whose remembered set is being rebuilt by an increment of a global mark cycle that is in progress.</p> <p>At the start of the partial GC cycle, the remembered set is using 93% of its available memory capacity, with 153.26 MB (160705664 B) available. The set consists of 2,749,664 cards and has one overflow region.</p> <p>The following element, <code>&lt;allocation-stats&gt;</code>, records information about how memory was divided between application (or mutator) threads before the start of the current cycle. For this example, the thread <code>Group1.Backend.CompositeBackend{Tier1}.7</code> was the largest consumer of memory.</p> <pre><code>&lt;allocation-stats totalBytes=\"2146431360\" &gt;\n  &lt;allocated-bytes non-tlh=\"96417448\" tlh=\"2050013912\" arrayletleaf=\"0\"/&gt;\n  &lt;largest-consumer threadName=\"Group1.Backend.CompositeBackend{Tier1}.7\" threadId=\"00000000007E9300\" bytes=\"275750048\" /&gt;\n&lt;/allocation-stats&gt;\n</code></pre> <p>The operations of the GC increment are run and details are recorded in the <code>&lt;gc-op&gt;</code> elements. The logs show that this increment begins with a copy forward operation followed by a class unload. Other <code>balanced</code> partial GC cycles can also include sweep and compact operations. For more information about the operations involved in <code>balanced</code> partial GC cycles, see GC Processing.</p> <pre><code>&lt;gc-op id=\"189\" type=\"copy forward\" timems=\"400.637\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.713\"&gt;\n  &lt;memory-copied type=\"eden\" objects=\"4434622\" bytes=\"119281928\" bytesdiscarded=\"1382272\" /&gt;\n  &lt;memory-copied type=\"other\" objects=\"8847813\" bytes=\"244414264\" bytesdiscarded=\"6243176\" /&gt;\n  &lt;memory-cardclean objects=\"1446970\" bytes=\"64143048\" /&gt;\n  &lt;regions eden=\"512\" other=\"80\" /&gt;\n  &lt;remembered-set-cleared processed=\"2435794\" cleared=\"887129\" durationms=\"8.667\" /&gt;\n  &lt;finalization candidates=\"66\" enqueued=\"56\" /&gt;\n  &lt;ownableSynchronizers candidates=\"256500\" cleared=\"78012\" /&gt;\n  &lt;references type=\"soft\" candidates=\"153648\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"22\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"1266\" cleared=\"610\" enqueued=\"430\" /&gt;\n  &lt;stringconstants candidates=\"9479\" cleared=\"0\"  /&gt;\n  &lt;object-monitors candidates=\"13576\" cleared=\"13505\"  /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"190\" type=\"classunload\" timems=\"0.010\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.713\"&gt;\n  &lt;classunload-info classloadercandidates=\"179\" classloadersunloaded=\"0\" classesunloaded=\"0\" anonymousclassesunloaded=\"0\" quiescems=\"0.000\" setupms=\"0.010\" scanms=\"0.000\" postms=\"0.000\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The logs show that the copy forward operation acts on the entire eden space (512 regions), recorded as <code>type=eden</code>, and 80 older regions, which are recorded as <code>type=other</code>. 113.76 MB (119281928 B) of memory was copied from the eden space to 1st generation regions and 233.10 MB (244414264 B) of memory in non-eden regions was copied to the next generation of regions. The copy forward operation is followed by a class unload operation.</p> <p>In some cases, a copy forward operation moves some regions by copying forward the objects in those regions, but only marks the objects in other regions. For example, the following log excerpt is taken from a different partial cycle, which corresponds to a <code>contextid</code> of <code>2049</code>. The copy forward operation in the following example involves marking some regions and copying forward other regions.</p> <pre><code>&lt;gc-op id=\"2052\" type=\"copy forward\" timems=\"649.059\" contextid=\"2049\" timestamp=\"2021-02-26T11:22:34.901\"&gt;\n  &lt;memory-copied type=\"eden\" objects=\"95989\" bytes=\"7882704\" bytesdiscarded=\"501088\" /&gt;\n  &lt;memory-copied type=\"other\" objects=\"2955854\" bytes=\"86854064\" bytesdiscarded=\"626024\" /&gt;\n  &lt;memory-cardclean objects=\"1304\" bytes=\"56840\" /&gt;\n  &lt;memory-traced type=\"eden\" objects=\"23392785\" bytes=\"553756840\" /&gt;\n  &lt;memory-traced type=\"other\" objects=\"5461302\" bytes=\"131394216\" /&gt;\n  &lt;regions eden=\"488\" other=\"138\" /&gt;\n  &lt;remembered-set-cleared processed=\"156775\" cleared=\"4897\" durationms=\"1.759\" /&gt;\n  &lt;finalization candidates=\"31\" enqueued=\"12\" /&gt;\n  &lt;ownableSynchronizers candidates=\"1992467\" cleared=\"1600904\" /&gt;\n  &lt;references type=\"soft\" candidates=\"329190\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"8\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"697\" cleared=\"105\" enqueued=\"6\" /&gt;\n  &lt;stringconstants candidates=\"9848\" cleared=\"0\"  /&gt;\n  &lt;object-monitors candidates=\"1437\" cleared=\"1353\"  /&gt;\n  &lt;heap-resize type=\"expand\" space=\"default\" amount=\"0\" count=\"1\" timems=\"0.000\" reason=\"continue current collection\" /&gt;\n  &lt;warning details=\"operation aborted due to insufficient free space\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The logs record these two concurrent parts of a copy forward operation in the <code>&lt;gc-op type=\"copy forward\"&gt;</code> section by using a <code>&lt;memory-traced&gt;</code> child element. In addition,<code>evacuated</code> and <code>marked</code> attributes for the <code>&lt;regions&gt;</code> child element are used to distinguish between the number of regions that were copied-forward (recorded as <code>evacuated</code>) and the number of regions that were only marked and not copied-forward. For example, <code>&lt;regions eden=\"256\" other=\"308\" evacuated=\"308\" marked=\"256\" /&gt;</code>.</p> <p>Returning to the <code>contextid=186</code> partial cycle example, the next element in the logs, <code>&lt;gc-end&gt;</code>, records the end of the increment and provides another snapshot of memory allocation on the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"191\" type=\"partial gc\" contextid=\"186\" durationms=\"402.645\" usertimems=\"3157.520\" systemtimems=\"4.000\" stalltimems=\"47.689\" timestamp=\"2021-02-26T11:11:42.714\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"192\" free=\"3003121664\" total=\"4294967296\" percent=\"69\"&gt;\n    &lt;mem type=\"eden\" free=\"2147483648\" total=\"2147483648\" percent=\"100\" /&gt;\n    &lt;arraylet-primitive objects=\"1\" leaves=\"4\" largest=\"4\" /&gt;\n    &lt;pending-finalizers system=\"56\" default=\"0\" reference=\"430\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"2922048\" freebytes=\"160016128\" totalbytes=\"171704320\" percent=\"93\" regionsoverflowed=\"1\" regionsstable=\"12\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The following information describes the heap memory allocation at the end of the increment:</p> <ul> <li> <p>The heap now has 2864 MB (3,003,121,664 bytes) of memory available compared to the 856 MB available at the start of the increment. The increment reclaimed 2,008 MB of memory in the heap, which is slightly less than the size of the eden space, as is typically the case.</p> </li> <li> <p>The eden space is recorded to have 100% memory available as free memory. The eden space, which consists of regions containing the youngest objects, was fully re-created by reclaiming almost all of the eden regions and assigning some other empty regions of the heap to the eden space. Note that some objects from eden regions always survive.</p> </li> <li> <p>The remembered set count increased by 172,384 cards, and the number of free bytes in the remembered set decreased by 0.66 MB (689,536 B).</p> </li> </ul> <p>The cycle completes and the GC restarts application threads.</p> <pre><code>&lt;cycle-end id=\"193\" type=\"partial gc\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.714\" /&gt;\n&lt;exclusive-end id=\"194\" timestamp=\"2021-02-26T11:11:42.714\" durationms=\"404.145\" /&gt;\n</code></pre> <p>The next cycle that is recorded in the logs is another partial GC cycle. The <code>&lt;gc-start&gt;</code>element records the following information:</p> <pre><code>&lt;gc-start id=\"198\" type=\"partial gc\" contextid=\"197\" timestamp=\"2021-02-26T11:11:46.072\"&gt;\n  &lt;mem-info id=\"199\" free=\"855638016\" total=\"4294967296\" percent=\"19\"&gt;\n    &lt;mem type=\"eden\" free=\"0\" total=\"2147483648\" percent=\"0\" /&gt;\n    &lt;arraylet-primitive objects=\"1\" leaves=\"4\" largest=\"4\" /&gt;\n    &lt;remembered-set count=\"2922048\" freebytes=\"160016128\" totalbytes=\"171704320\" percent=\"93\" regionsoverflowed=\"1\" regionsstable=\"12\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The <code>&lt;mem-info&gt;</code> element shows that the following events occurred in between the end of the last (partial) GC cycle and the start of this cycle:</p> <ul> <li>All available memory in the eden area was allocated to application threads.</li> <li>Application threads also used some memory from non-eden heap areas. The total available memory in the heap reduced from 69% to 19%.</li> <li>The remembered set status is unchanged, as shown by the <code>&lt;remembered-set&gt;</code> element. When mutator threads run, they build data about object references that cross boundaries by using a card table. However, the processing of card table data into the remembered set, and the reporting of the remembered set counts, are run during other cycle operations.</li> </ul>"},{"location":"vgclog_examples/#summary_2","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example <code>balanced</code> partial GC cycle has the following characteristics:</p> <ul> <li>The partial GC cycle is triggered when the eden space is full by an allocation taxation threshold.</li> <li>All GC operations that are associated with this cycle occur during the STW pause.</li> <li>The partial GC cycle consists of only one increment, which runs a copy forward operation on 512 eden regions and 80 other regions, followed by a class-unload operation.</li> <li>The partial GC cycle re-creates a free eden space by reclaiming all possible regions from the eden space (some objects always survive) and assigning other free regions to the eden space. The GC cycle also reclaims memory from some other regions.</li> <li>2864 MB of the total 4096 MB heap was reclaimed. 100% of the eden space is available as free memory, and some older regions were also reclaimed.</li> <li>Between the start and end of the partial GC cycle, the remembered set count increases by 172,384 cards and the number of free bytes decreases by 0.66 MB (689,536 B). After performing a copy forward operation on objects to move them to older regions, the partial GC cycle rebuilds the remembered set of any regions that received these moved objects. During a partial cycle, the remembered set is also pruned. Overall, the rebuilding and pruning can lead to either an increase or a decrease in the remembered set count and free memory available.</li> <li>The remembered set metastructure remains unchanged between GC cycles, even though the mutator threads build new data about object references when the threads run. The remembered set count is identical at the end of one partial GC cycle and the beginning of the next because the remembered set consumes this data and reports to the verbose GC logs only during a cycle's operation.</li> </ul>"},{"location":"vgclog_examples/#balanced-global-mark-gc-cycle","title":"<code>balanced</code> global mark GC cycle","text":"<p>The global mark GC cycle uses a mixture of STW and concurrent operations to build a new record of object liveness across the heap for use by the <code>balanced</code> partial GC cycle. The <code>balanced</code> GC runs a <code>balanced global mark cycle</code>, or a <code>balanced</code> global mark cycle increment if the global mark cycle is in progress, if the heap satisfies a low memory condition when the allocation taxation threshold is reached.</p> <p>The global mark cycle runs a global mark phase and also triggers an associated sweep phase within the partial GC cycle that immediately follows the end of the global mark cycle.</p> <p>To search for a <code>balanced</code> global mark cycle, you can search for the <code>type</code> attribute value <code>global mark phase</code> in <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code> elements.</p> <p>The global cycle is split into multiple increments, each recorded as <code>type=\"global mark phase\"</code>. A global mark phase increment involves an STW subincrement, which runs a global mark operation during an STW pause, followed by a global mark phase (GMP) work packet subincrement. The GMP work packet subincrement involves a processing operation that runs concurrently. The GMP work packet subincrement might also use an STW pause to complete if the subincrement is interrupted by a partial or global cycle trigger.</p> <p>Splitting the global mark phase into these increments and subincrements reduces pause times by running the majority of the GC work concurrently and interleaving global mark phase increments with partial GC cycles, and, rarely a <code>balanced</code> global GC cycles.</p> <p>The following elements log the GC increments, subincrements, and operations of the global mark GC cycle:</p> Table showing the global mark cycle GC increments and corresponding XML elements GC increment GC operations&gt; STW or concurrent XML element of GC increment Details <code>global mark phase</code> subincrement mark STW <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> The global mark phase operations start at the beginning of the cycle and run through all regions until the final region <code>GMP work packet processing</code> subincrement Work packet processing (WPP) operations concurrent and sometimes final operations during an STW to complete the subincrement <code>&lt;concurrent-start&gt;</code>, <code>&lt;concurrent-end&gt;</code> The <code>GMP work packet processing subincrement</code> runs immediately after the <code>global mark phase</code>  final global mark phase increment final global mark phase operations including class unload STW <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> Final increment. Runs the final global mark phase operations, including weak roots processing, followed by operations to finish the cycle <p>The following structure shows a <code>balanced</code> global mark GC cycle. The lines are indented to help illustrate the flow and some child elements are omitted for clarity:</p> <pre><code>&lt;exclusive-start/&gt;                        (STW pause starts)\n\n&lt;allocation-taxation/&gt;                    (memory threshold trigger recorded)\n\n&lt;cycle-start type=\"global mark phase\"/&gt;   (global mark cycle starts)\n\n&lt;gc-start type=\"global mark phase\"/&gt;      (1st GMP STW subincrement starts)\n\n    &lt;mem-info&gt;                            (memory status before operations)\n\n    &lt;remembered-set&gt;\n\n    &lt;/mem-info&gt;         \n\n&lt;/gc-start&gt;\n\n&lt;gc-op type=\"mark increment\" /&gt;           (STW copy forward operation completed)\n\n&lt;gc-end&gt;                                  (1st GMP STW subincrement ends)\n\n    &lt;mem-info&gt;                            (memory status after operations)\n\n    &lt;remembered-set&gt;\n\n    &lt;/mem-info&gt;\n\n&lt;gc-end&gt;\n\n&lt;concurrent-start type=\"GMP work packet processing\"/&gt; (1st GMP concurrent subincrement starts)\n\n&lt;exclusive-end/&gt;                                      (STW pause ends and application threads resume)\n\n&lt;concurrent-end type=\"GMP work packet processing\"/&gt;   (1st GMP concurrent subincrement ends)\n\n&lt;gc-op type=\"mark increment\"/&gt;                        (marking operation runs concurrently)\n\n&lt;/concurrent-end type=\"GMP work packet processing\"/&gt;\n\n...                                       (application threads run. STW pauses stop    \n                                          and start application threads to run\n                                          partial GC cycles.)\n\n&lt;exclusive-start/&gt;                        (STW pause starts)\n\n&lt;gc-start type=\"global mark phase\"/&gt;      (2nd STW GMP subincrement starts)\n\n...   \n\n&lt;concurrent-start type=\"GMP work packet processing\"/&gt; (2nd concurrent GMP subincrement starts)\n\n...\n\n&lt;exclusive-end/&gt;\n\n...                                       (application threads run. Partial GC cycles may run)\n\n&lt;concurrent-end type=\"GMP work packet processing\" /&gt;  (2nd concurrent GMP subincrement ends)\n...\n\n&lt;/concurrent-end&gt;\n\n...                                       (application threads run. Partial cycles\n                                          and GMP increments interleave)\n\n&lt;exclusive-start/&gt;                        (STW pause starts)\n\n...\n\n&lt;gc-start type=\"global mark phase\"/&gt;      (final STW GMP subincrement starts.)\n\n&lt;gc-op type=\"mark increment\" /&gt;           (STW copy forward operation completed)\n\n&lt;gc-op  type=\"class unload\" /&gt;            (STW class unload operation completed)\n\n&lt;gc-end&gt;                                  (1st GMP STW subincrement ends)\n...   \n&lt;gc-end type=\"global mark phase\"/&gt;        (final STW GMP subincrement ends. No concurrent subincrement runs)\n\n&lt;cycle-end type=\"global mark phase\"/&gt;     (end of global mark cycle)\n\n&lt;exclusive-end/&gt;                          (STW pause ends)    \n\n&lt;exclusive-start/&gt;                        (STW pause starts)\n\n&lt;cycle-start type=\"partial gc\" /&gt;         (partial cycle starts)\n\n...\n\n&lt;gc-op type=\"sweep\" /&gt;                    (Sweep operation associated with global mark cycle runs)\n\n...\n\n&lt;cycle-end type=\"partial gc\"/&gt;            (partial GC cycle ends)\n\n&lt;exclusive-end/&gt;                          (STw pause ends)\n</code></pre>"},{"location":"vgclog_examples/#global-mark-phase","title":"Global mark phase","text":"<p>The first activity of the global mark cycle is an STW pause, recorded by an <code>&lt;exclusive-start&gt;</code> element that precedes the <code>&lt;cycle-start type=\"global mark phase\"/&gt;</code> element. The garbage collector pauses application threads to run the initial operations.</p> <pre><code>&lt;exclusive-start id=\"1152\" timestamp=\"2021-02-26T11:17:25.033\" intervalms=\"1931.263\"&gt;\n  &lt;response-info timems=\"3.082\" idlems=\"1.041\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n</code></pre> <p>The <code>&lt;allocation-taxation&gt;</code> element indicates that an allocation taxation threshold triggered the cycle. The  <code>taxation threshold</code> is recorded as 1024 MB (1,073,741,824), which is half the total memory of the eden space (2048 MB), as expected for threshold triggers of global mark cycles and increments. For more information about taxation thresholds for the <code>balanced</code> policy, see <code>balanced</code> examples.</p> <pre><code>&lt;allocation-taxation id=\"1153\" taxation-threshold=\"1073741824\" timestamp=\"2021-02-26T11:17:25.034\" intervalms=\"1931.251\" /&gt;\n</code></pre> <p>Details about the start of the global mark GC cycle are recorded by the <code>&lt;cycle-start&gt;</code> element. The cycle is recorded as type <code>global mark phase</code> with <code>id=1154</code>. Any subsequent elements that are associated with this cycle have a <code>contextid=1154</code> to match the global mark GC cycle <code>id</code>. You can use the <code>contextid</code> value to distinguish increments and operations of the global mark GC cycle from the partial cycles that interleave with it.</p> <pre><code>&lt;cycle-start id=\"1154\" type=\"global mark phase\" contextid=\"0\" timestamp=\"2021-02-26T11:17:25.034\" intervalms=\"374365.075\" /&gt;\n</code></pre> <p>The cycle begins with the STW subincrement of a global mark phase increment. The STW subincrement is recorded by using the <code>&lt;gc-start&gt;</code> element of type <code>global mark phase</code>.</p> <pre><code>&lt;gc-start id=\"1155\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.034\"&gt;\n  &lt;mem-info id=\"1156\" free=\"1442840576\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"2197888\" freebytes=\"162912768\" totalbytes=\"171704320\" percent=\"94\" regionsoverflowed=\"3\" regionsstable=\"130\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The <code>&lt;gc-start&gt;</code> element provides a snapshot of the free memory available in the heap and the status of the remembered set. At the start of the increment, the heap is 33% free; 1376 MB (1442840576 B) of the total 4096 MB (4294967296 B).</p> <p>The <code>&lt;remembered-set&gt;</code> element records the status of the remembered set metastructure, a structure that records object references that cross different regions. During the rebuilding of the remembered set metastructure, any regions that cannot be rebuilt into a remembered set due to a lack of memory resource in the metastructure are marked as overflow regions. Partial GC cycles cannot reclaim memory from overflow regions.</p> <p>The aim of the global mark cycle is to create a new record of object liveness by populating the remembered set. The global mark cycle also attempts to rebuild the remembered set information for the overflowed regions, which can be seen in the remembered set statistics. After the global mark cycle completes, the remembered set reflects a closer snapshot of the current liveness of the heap. This more accurate snapshot of object liveness optimizes the pruning of the set, which is run by the partial GC cycle when it consumes the object liveness snapshot.</p> <p>The logs show that at the start of this STW subincrement, the remembered set count is 2,197,888 cards, the metastructure is using 94% of its total available memory, and three overflow regions need to be rebuilt.</p> <p>The <code>&lt;gc-op&gt;</code> element records that the STW subincrement runs a mark operation. This operation begins the process of building a record of object liveness across the heap.</p> <pre><code>&lt;gc-op id=\"1157\" type=\"mark increment\" timems=\"122.825\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.157\"&gt;\n  &lt;trace-info objectcount=\"7726701\" scancount=\"7584109\" scanbytes=\"213445656\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The <code>&lt;trace-info&gt;</code> element records information about the marking and scanning stages of the mark increment operation. <code>objectcount</code> records the number of objects that were marked, ready for tracing. After marking live objects, a scan is run to trace objects and references. The following values are recorded:</p> <ul> <li><code>scancount</code> records the number of marked objects that were scanned.</li> <li><code>scanbytes</code> records the total memory of all marked objects that were scanned.</li> </ul> <p>In the example, the mark increment operation marked 7,726,701 objects and scanned 7,584,109 of these marked objects. The 7,584,109 of scanned objects take up 203.5 MB (213445656 B) of memory. The number of scanned objects is less than the number of marked objects because only objects that have children require scanning. Also, the scanning part of the marking operation might be interrupted by the garbage collector if a trigger threshold for a partial cycle or global cycle is reached during the marking operation.</p> <p>The STW <code>global mark phase</code> subincrement ends, as recorded by <code>&lt;gc-end&gt;</code>, which records a snapshot of the memory status in the heap in a similar way to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"1158\" type=\"global mark phase\" contextid=\"1154\" durationms=\"123.139\" usertimems=\"977.851\" systemtimems=\"0.000\" stalltimems=\"1.453\" timestamp=\"2021-02-26T11:17:25.157\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"1159\" free=\"1442840576\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3263968\" freebytes=\"158648448\" totalbytes=\"171704320\" percent=\"92\" regionsoverflowed=\"0\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The following comparison can be made between the snapshot at the beginning and end of this STW <code>global mark phase</code> subincrement:</p> <ul> <li>The marking operation has increased the <code>count</code> value of the <code>&lt;remembered-set&gt;</code> by 1,066,080 cards (from 2,197,888 to 3,263,968). As regions are rebuilt, the new cards record the new remembered set data that is associated with these regions.</li> <li>The number of overflow regions went from three to zero.</li> <li>As expected with a global mark cycle, there is no change in the amount of free memory available, which is 1376 MB.</li> </ul> <p>The beginning of the second part of the global mark phase increment, the GMP work packet processing subincrememt, is recorded by <code>&lt;concurrent-start&gt;</code>. The child element <code>&lt;concurrent-mark-start&gt;</code> records the scan target of this subincrement as 242.74 MB (254,532,672 B).</p> <pre><code>&lt;concurrent-start id=\"1160\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.157\"&gt;\n  &lt;concurrent-mark-start scanTarget=\"254532672\" /&gt;\n&lt;/concurrent-start&gt;\n</code></pre> <p>Now that the STW global mark phase subincrement is complete, application threads are restarted.</p> <pre><code>&lt;exclusive-end id=\"1161\" timestamp=\"2021-02-26T11:17:25.157\" durationms=\"123.936\" /&gt;\n</code></pre> <p>The <code>GMP work packet processing</code> subincrement continues to run concurrently. The end of this operation is recorded by using the <code>&lt;concurrent-end&gt;</code> element.</p> <pre><code>&lt;concurrent-end id=\"1162\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.469\" terminationReason=\"Work target met\"&gt;\n&lt;gc-op id=\"1163\" type=\"mark increment\" timems=\"311.867\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.469\"&gt;\n  &lt;trace-info scanbytes=\"254708852\" /&gt;\n&lt;/gc-op&gt;\n&lt;/concurrent-end&gt;\n</code></pre> <p>The child element <code>&lt;trace-info&gt;</code> shows that the processing scanned 242.91 MB (254,708,852 B), which slightly exceeds the 108.25 MB scan target.</p> <p>Application threads continue to run and allocate memory. The garbage collector stops and starts the application threads to run partial GC cycles that reclaim free space in the eden space and some older regions. To see an example of how a <code>balanced</code> partial GC cycle appears in the logs, see the <code>balanced</code> partial GC cycle.</p> <p>Following some partial GC cycles, an allocation taxation threshold is reached that triggers an STW pause followed by another global mark phase increment. The element <code>&lt;gc-start&gt;</code> in the following log excerpt has a <code>contextid=1154</code> and type <code>global mark phase</code>, which indicates that this is a global mark phase subincrement associated with the global mark cycle example.</p> <pre><code>&lt;exclusive-start id=\"1175\" timestamp=\"2021-02-26T11:17:28.993\" intervalms=\"1978.886\"&gt;\n  &lt;response-info timems=\"5.111\" idlems=\"1.714\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n&lt;allocation-taxation id=\"1176\" taxation-threshold=\"1073741824\" timestamp=\"2021-02-26T11:17:28.994\" intervalms=\"1978.879\" /&gt;\n&lt;gc-start id=\"1177\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:28.994\"&gt;\n  &lt;mem-info id=\"1178\" free=\"1451229184\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3325824\" freebytes=\"158401024\" totalbytes=\"171704320\" percent=\"92\" regionsoverflowed=\"2\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The <code>&lt;allocation-taxation&gt;</code> element shows that the allocation taxation threshold, which triggers this global mark phase increment, is set to 1024 MB, half of the size of the eden space, as expected.</p> <p><code>&lt;gc-start&gt;</code> records that the heap has 1384 MB (1,451,229,184 B) of free memory available at the beginning of this global mark phase increment. This value compares to the 1376 MB (1,442,840,576 B) of free memory available at the end of the previous global mark phase increment. Although free memory was reclaimed by the partial GC cycles that ran between these global mark phase increments, free memory was allocated to objects when application threads ran, resulting in a net reduction of free memory available.</p> <p>The status of the heap at the beginning and end of STW subincrements are automatically recorded. For this STW subincrement, there are no <code>&lt;gc-op&gt;</code> elements recorded; <code>&lt;gc-end&gt;</code> immediately follows <code>&lt;gc-start&gt;</code> in the logs. For some STW subincrements, a mark operation is run.</p> <pre><code>&lt;gc-end id=\"1179\" type=\"global mark phase\" contextid=\"1154\" durationms=\"0.289\" usertimems=\"1.000\" systemtimems=\"0.000\" stalltimems=\"0.000\" timestamp=\"2021-02-26T11:17:28.994\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"1180\" free=\"1451229184\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3325824\" freebytes=\"158401024\" totalbytes=\"171704320\" percent=\"92\" regionsoverflowed=\"2\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The second part of the increment, the <code>GMP work packet processing</code> subincrement, is recorded by using the <code>&lt;concurrent-start&gt;</code> and <code>&lt;concurrent-end&gt;</code> elements.</p> <pre><code>&lt;concurrent-start id=\"1181\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:28.994\"&gt;\n  &lt;concurrent-mark-start scanTarget=\"258671414\" /&gt;\n&lt;/concurrent-start&gt;\n&lt;exclusive-end id=\"1182\" timestamp=\"2021-02-26T11:17:28.994\" durationms=\"0.816\" /&gt;\n\n&lt;concurrent-end id=\"1183\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:29.273\" terminationReason=\"Work target met\"&gt;\n&lt;gc-op id=\"1184\" type=\"mark increment\" timems=\"279.311\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:29.274\"&gt;\n  &lt;trace-info scanbytes=\"258767612\" /&gt;\n&lt;/gc-op&gt;\n&lt;/concurrent-end&gt;\n</code></pre> <p>The log excerpt shows the concurrent <code>GMP work packet processing</code> subincrement achieved the scan target of 246.69 MB (258671414 B). 246.78 MB (258767612 B) were scanned.</p> <p>More partial cycles run. This pattern of interleaving of global mark increments with partial GC cycles repeats until a final global mark increment completes the global mark cycle. The final global mark phase increment consists of an STW <code>global mark phase</code> subincrement that includes <code>mark increment</code> and <code>class unload</code> operations.</p> <pre><code>&lt;exclusive-start id=\"1217\" timestamp=\"2021-02-26T11:17:36.864\" intervalms=\"1986.124\"&gt;\n  &lt;response-info timems=\"0.287\" idlems=\"0.104\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n&lt;allocation-taxation id=\"1218\" taxation-threshold=\"1073741824\" timestamp=\"2021-02-26T11:17:36.865\" intervalms=\"1986.101\" /&gt;\n&lt;gc-start id=\"1219\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:36.865\"&gt;\n  &lt;mem-info id=\"1220\" free=\"1438646272\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3514496\" freebytes=\"157646336\" totalbytes=\"171704320\" percent=\"91\" regionsoverflowed=\"3\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n&lt;gc-op id=\"1221\" type=\"mark increment\" timems=\"164.843\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:37.030\"&gt;\n  &lt;trace-info objectcount=\"7715572\" scancount=\"7665293\" scanbytes=\"214739196\" /&gt;\n  &lt;cardclean-info objects=\"3962203\" bytes=\"117924792\" /&gt;\n  &lt;finalization candidates=\"206\" enqueued=\"30\" /&gt;\n  &lt;ownableSynchronizers candidates=\"601780\" cleared=\"16925\" /&gt;\n  &lt;references type=\"soft\" candidates=\"718240\" cleared=\"2858\" enqueued=\"2832\" dynamicThreshold=\"18\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"2321\" cleared=\"142\" enqueued=\"0\" /&gt;\n  &lt;references type=\"phantom\" candidates=\"8\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;stringconstants candidates=\"9522\" cleared=\"0\"  /&gt;\n  &lt;object-monitors candidates=\"7142\" cleared=\"7066\"  /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"1222\" type=\"classunload\" timems=\"0.704\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:37.030\"&gt;\n  &lt;classunload-info classloadercandidates=\"185\" classloadersunloaded=\"13\" classesunloaded=\"13\" anonymousclassesunloaded=\"0\" quiescems=\"0.000\" setupms=\"0.644\" scanms=\"0.043\" postms=\"0.016\" /&gt;\n&lt;/gc-op&gt;\n&lt;gc-end id=\"1223\" type=\"global mark phase\" contextid=\"1154\" durationms=\"169.521\" usertimems=\"1244.810\" systemtimems=\"3.000\" stalltimems=\"27.792\" timestamp=\"2021-02-26T11:17:37.034\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"1224\" free=\"1438646272\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;pending-finalizers system=\"30\" default=\"0\" reference=\"2832\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"2241440\" freebytes=\"162738560\" totalbytes=\"171704320\" percent=\"94\" regionsoverflowed=\"3\" regionsstable=\"127\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>Comparing the memory at the start and end of this final <code>global mark phase</code> increment shows the following status:</p> <ul> <li>As expected, the final global mark phase increment does not reclaim any free memory.</li> <li>The remembered set metastructure was marginally rebuilt. The card count has increased slightly, and the number of stable regions dropped from 130 to 127. </li> <li>The number of overflow regions remains unchanged. The final global mark phase increment did not manage to rebuild any overflow regions.</li> </ul> <p>Following the final global mark increment, the global mark cycle completes and the GC ends the STW pause.</p> <pre><code>&lt;cycle-end id=\"1225\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:37.034\" /&gt;\n&lt;exclusive-end id=\"1226\" timestamp=\"2021-02-26T11:17:37.034\" durationms=\"170.186\" /&gt;\n</code></pre> <p>The operations to create a record of object liveness across the heap, which began with the global mark cycle, is followed by a sweep phase. The sweep phase is triggered by the end of the global mark cycle to be included in the next partial GC cycle that runs.</p>"},{"location":"vgclog_examples/#sweep-phase","title":"Sweep phase","text":"<p>The sweep operation has the following two objectives:</p> <ul> <li>To directly reclaim some memory by creating empty regions.</li> <li>To build information about occupancy and fragmentation for regions that still contain live objects. The next partial GC cycle uses this information to defragment older regions.</li> </ul> <p>While the global sweep operation is logically associated with the global mark phase, it does not run in the same global mark cycle. Instead, the sweep operation runs in the same STW increment as the first partial GC cycle that runs after the completion of the global mark cycle. This can be seen in the following log excerpt.  After the log records the end of the global mark cycle, it records an STW pause followed by a <code>partial gc</code> cycle of <code>id=1229</code>. The global sweep operation that runs after the global mark phase is recorded in the <code>&lt;gc-op&gt;</code> element that is tagged as <code>id=1229</code>.</p> <pre><code>&lt;exclusive-start id=\"1227\" timestamp=\"2021-02-26T11:17:38.804\" intervalms=\"1940.125\"&gt;\n...\n&lt;cycle-start id=\"1229\" type=\"partial gc\" contextid=\"0\" timestamp=\"2021-02-26T11:17:38.805\" intervalms=\"3926.202\" /&gt;\n...\n&lt;/gc-start&gt;\n...\n&lt;/gc-start&gt;\n&lt;gc-op id=\"1232\" type=\"sweep\" timems=\"9.472\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:38.815\" /&gt;\n&lt;gc-op id=\"1233\" type=\"copy forward\" timems=\"308.258\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:39.124\"&gt;\n...\n&lt;gc-op id=\"1234\" type=\"classunload\" timems=\"0.012\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:39.125\"&gt;\n...\n&lt;gc-end&gt;\n...\n&lt;/gc-end&gt;\n&lt;cycle-end id=\"1237\" type=\"partial gc\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:39.125\" /&gt;\n&lt;exclusive-end id=\"1238\" timestamp=\"2021-02-26T11:17:39.125\" durationms=\"320.792\" /&gt;\n</code></pre> <p>A record of object liveness is now complete.</p>"},{"location":"vgclog_examples/#summary_3","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example <code>balanced</code> global mark GC cycle has the following characteristics:</p> <ul> <li>If the total free memory is low when the taxation allocation threshold is reached, the GC triggers a global mark cycle. The allocation taxation threshold is set by the previous cycle to trigger a new cycle when the eden space is half full. This threshold value frees up eden space to enable a global mark cycle to interleave with the GC operations of partial GC cycles.</li> <li>Each global mark phase increment is triggered by an allocation taxation threshold value that is set to half of the eden space.</li> <li>Global mark GC cycle and global mark cycle increments begin with an STW pause.</li> <li>The global mark cycle does not reclaim memory. The cycle creates an updated record of object liveness by rebuilding the mark map, and also attempts to rebuild the remembered set for overflowed and stable regions. The change in status of the remembered set metastructure can be seen in the logs by inspecting the <code>&lt;remembered-set&gt;</code> attributes.</li> <li>Partial cycles run in between global mark phase increments.</li> <li>The final global mark phase increment includes a class unload. The final increment also triggers a sweep phase to run in the next partial cycle.</li> </ul>"},{"location":"vgclog_examples/#balanced-global-gc-cycle","title":"<code>balanced</code> global GC cycle","text":"<p>The following global GC cycle example is taken from a <code>balanced</code> verbose GC log. The output is broken down into sections to explain the GC processing that is taking place.</p> <p>A <code>balanced</code> global cycle is triggered if the VM is close to throwing an out of memory exception. This situation occurs only under tight memory conditions when the garbage collector cannot reclaim enough memory by using only partial and global mark cycles.</p> <p>To search for a <code>balanced</code> global cycle or increment, you can search for the <code>type</code> attribute value <code>global garbage collect</code> of the cycle or increment element.</p> <p>If the <code>balanced</code> global cycle is triggered during a <code>balanced</code> global mark GC cycle, a new <code>global</code> cycle is not recorded. Instead, the global mark cycle's global mark phase increment switches to a global garbage collect increment that is run as an STW increment. This switch is recorded in the logs by using a <code>&lt;cycle-continue&gt;</code> element, which precedes the <code>gc-start</code> element that records the new global garbage collect increment.</p> <p>If the <code>balanced</code> global cycle is not triggered during a <code>balanced</code> global mark cycle, the global cycle is recorded as a new cycle by using the <code>&lt;cycle-start&gt;</code> element.</p> <p>The element <code>&lt;sys-start reason=\"explicit\"&gt;</code> is used in the logs to record a cycle that was triggered explicitly rather than by the garbage collector. For example, the trigger reason is recorded as <code>explicit</code> if a cycle is triggered by an application calling <code>System.gc()</code>. For more information about explicitly or implicitly triggering a GC cycle, see Garbage collection.</p> <p>The global cycle operations run as a single GC increment during an STW pause.</p> Table showing the <code>balanced</code> global cycle's GC increment and corresponding XML elements. GC increment  GC operations STW or concurrent XML element of GC increment Details single STW mark-sweep operations, optionally followed by a compact operation STW <code>&lt;cycle-start&gt;</code>, <code>&lt;gc-end&gt;</code> Contains detailed information about where free memory is located and remembered set statistics <p>If the global cycle is triggered during a global mark cycle, the global cycle follows a general structure in the verbose GC log as shown. Some child elements are omitted for clarity:</p> <pre><code>...                                        (global mark cycle increment runs)\n\n&lt;af-start/&gt;                                (allocation failure trigger recorded)\n\n&lt;concurrent-end/&gt;                          (global mark cycle concurrent subincrement finishes )\n\n&lt;allocation-taxation/&gt;                     (memory threshold trigger recorded)\n\n&lt;cycle-continue/&gt;                          (change of cycle type from global mark to global)\n\n&lt;/gc-start type=\"global garbage collect\"/&gt; (global cycle STW increment starts)\n\n&lt;mem-info&gt;                                 (memory status before operations)\n\n &lt;mem&gt;&lt;/mem&gt;                               (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-start type=\"global garbage collect\"/&gt;\n\n&lt;allocation-stats/&gt;                        (Snapshot of how memory was divided up between\n                                           ... application threads before current cycle started)\n&lt;gc-op&gt; type=\"mark\" &lt;/gc-op&gt;                (mark operation completed)\n\n&lt;gc-op&gt; type=\"class unload\" &lt;/gc-op&gt;        (class unload operation completed)\n\n&lt;gc-op&gt; type=\"sweep\" &lt;/gc-op&gt;               (sweep operation completed)\n\n&lt;gc-op&gt; type=\"compact\" &lt;/gc-op&gt;             (compact operation completed)\n\n&lt;gc-end type=\"global garbage collect\"&gt;      (global cycle STW increment ends)\n\n&lt;mem-info&gt;                                  (memory status after operations)\n\n&lt;mem&gt;&lt;/mem&gt;                                 (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-end type=\"global garbage collect\"&gt;\n\n&lt;cycle-end type = \"global garbage collect\"/&gt; (cycle ends)\n\n&lt;allocation-satisfed/&gt;                      (required allocation has been achieved)\n\n&lt;exclusive-end&gt;                             (STW pause ends)\n</code></pre> <p>The following example shows a <code>balanced</code> global cycle that is triggered during a global mark cycle.</p> <p>The start of the GMP work processing subincrement of the global mark cycle, which runs concurrently with application threads, is recorded by using the <code>&lt;concurrent-start&gt;</code> element.</p> <pre><code>&lt;concurrent-start id=\"2009\" type=\"GMP work packet processing\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.109\"&gt;\n  &lt;concurrent-mark-start scanTarget=\"18446744073709551615\" /&gt;\n&lt;/concurrent-start&gt;\n</code></pre> <p>After the start of the concurrent subincrement, the logs record an allocation failure by using <code>&lt;af-start&gt;</code>. The <code>&lt;concurrent-end&gt;</code> element attribute <code>terminationReason</code> shows that a termination of the concurrent increment was requested by the garbage collector.</p> <pre><code>&lt;af-start id=\"2010\" threadId=\"00000000008AA780\" totalBytesRequested=\"24\" timestamp=\"2021-03-05T12:16:43.109\" intervalms=\"1212.727\" /&gt;\n&lt;concurrent-end id=\"2011\" type=\"GMP work packet processing\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\" terminationReason=\"Termination requested\"&gt;\n&lt;gc-op id=\"2012\" type=\"mark increment\" timems=\"0.893\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\"&gt;\n  &lt;trace-info scanbytes=\"584612\" /&gt;\n&lt;/gc-op&gt;\n&lt;/concurrent-end&gt;\n</code></pre> <p>The next element, the <code>&lt;cycle-continue&gt;</code> element, records information about the switch of cycle type from a global mark cycle, recorded as type <code>global mark phase</code>, to a global cycle, recorded as type <code>global garbage collect</code>.</p> <pre><code>&lt;cycle-continue id=\"2013\" oldtype=\"global mark phase\" newtype=\"global garbage collect\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\" /&gt;\n</code></pre> <p>A global cycle increment is recorded by <code>&lt;gc-start&gt;</code> and has the same <code>contextid</code> as the global mark cycle's elements. The global cycle operations are run during an STW pause and as a modification to the global mark cycle rather than a new cycle. The memory snapshot within the <code>&lt;gc-start&gt;</code> element is taken before the global increment's operations run and can be compared with a similar snapshot that is taken afterward to understand the effect on the heap.</p> <pre><code>&lt;gc-start id=\"2014\" type=\"global garbage collect\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\"&gt;\n  &lt;mem-info id=\"2015\" free=\"0\" total=\"838860800\" percent=\"0\"&gt;\n    &lt;mem type=\"eden\" free=\"0\" total=\"524288\" percent=\"0\" /&gt;\n    &lt;remembered-set count=\"12832\" freebytes=\"33331072\" totalbytes=\"33382400\" percent=\"99\" regionsoverflowed=\"0\" regionsstable=\"0\" regionsrebuilding=\"1593\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>At the start of the global cycle's increment, the amount of memory available in the heap is zero. In some cases, the heap is close to full, and in other cases, the memory is full.</p> <p>The next element <code>&lt;allocation-stats&gt;</code> shows a snapshot of how memory was divided up between application threads before the current cycle started.</p> <pre><code>&lt;allocation-stats totalBytes=\"524200\" &gt;\n  &lt;allocated-bytes non-tlh=\"0\" tlh=\"524200\" arrayletleaf=\"0\"/&gt;\n&lt;/allocation-stats&gt;\n</code></pre> <p>The <code>&lt;allocation-stats&gt;</code> element shows that very little allocation took place. Global cycles are triggered due to an allocation failure, so the low memory allocation values are expected.</p> <p>The following operations, each recorded by a <code>&lt;gc-op&gt;</code> element, run as part of the global cycle's increment:</p> <ul> <li><code>global mark</code></li> <li><code>class unload</code></li> <li><code>sweep</code></li> <li><code>compact</code></li> </ul> <pre><code>&lt;gc-op id=\"2016\" type=\"global mark\" timems=\"357.859\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.468\"&gt;\n  &lt;trace-info objectcount=\"37461962\" scancount=\"37447916\" scanbytes=\"828311396\" /&gt;\n  &lt;cardclean-info objects=\"311\" bytes=\"22632\" /&gt;\n  &lt;finalization candidates=\"195\" enqueued=\"2\" /&gt;\n  &lt;ownableSynchronizers candidates=\"2089\" cleared=\"0\" /&gt;\n  &lt;references type=\"soft\" candidates=\"3059\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"0\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"10797\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;references type=\"phantom\" candidates=\"6\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;stringconstants candidates=\"10031\" cleared=\"0\"  /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"2017\" type=\"classunload\" timems=\"0.123\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.468\"&gt;\n  &lt;classunload-info classloadercandidates=\"25\" classloadersunloaded=\"0\" classesunloaded=\"0\" anonymousclassesunloaded=\"0\" quiescems=\"0.000\" setupms=\"0.123\" scanms=\"0.000\" postms=\"0.000\" /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"2018\" type=\"sweep\" timems=\"5.120\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.474\" /&gt;\n&lt;gc-op id=\"2019\" type=\"compact\" timems=\"762.323\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:44.236\"&gt;\n  &lt;compact-info movecount=\"8024461\" movebytes=\"163375400\" /&gt;\n  &lt;remembered-set-cleared processed=\"777104\" cleared=\"777104\" durationms=\"2.188\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The global cycle's increment ends. The end of the increment is recorded with <code>&lt;gc-end&gt;</code> and provides another snapshot of memory allocation on the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"2020\" type=\"global garbage collect\" contextid=\"2003\" durationms=\"1126.788\" usertimems=\"7971.788\" systemtimems=\"1.000\" stalltimems=\"1016.256\" timestamp=\"2021-03-05T12:16:44.237\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"2021\" free=\"1572864\" total=\"838860800\" percent=\"0\"&gt;\n    &lt;mem type=\"eden\" free=\"1572864\" total=\"1572864\" percent=\"100\" /&gt;\n    &lt;pending-finalizers system=\"2\" default=\"0\" reference=\"0\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"874496\" freebytes=\"29884416\" totalbytes=\"33382400\" percent=\"89\" regionsoverflowed=\"0\" regionsstable=\"0\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>Comparing the snapshot at the beginning and end of this STW <code>global mark phase</code> subincrement shows that memory was reclaimed and regions reassigned to create an empty eden space, equal to 1.5 MB (1,572,864 B). Because global cycles are triggered when memory conditions are tight, the global cycle is able to reclaim only a small amount of memory.</p> <p>The cycle ends (<code>&lt;cycle-end&gt;</code>). The following <code>&lt;allocation-satisfied&gt;</code> element indicates that the allocation request that caused the allocation failure can now complete successfully.</p> <pre><code>&lt;cycle-end id=\"2022\" type=\"global garbage collect\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:44.237\" /&gt;\n&lt;allocation-satisfied id=\"2023\" threadId=\"00000000008A9E00\" bytesRequested=\"24\" /&gt;\n&lt;af-end id=\"2024\" timestamp=\"2021-03-05T12:16:44.237\" threadId=\"00000000008AA780\" success=\"true\" /&gt;\n</code></pre> <p>The STW pause ends with the <code>&lt;exclusive-end&gt;</code> element.</p> <pre><code>&lt;exclusive-end id=\"2025\" timestamp=\"2021-03-05T12:16:44.237\" durationms=\"1130.358\" /&gt;\n</code></pre>"},{"location":"vgclog_examples/#summary_4","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this global cycle has the following characteristics:</p> <ul> <li> <p>The global GC cycle was triggered during a global mark GC cycle when the heap was very low in memory. The memory could not be reclaimed by just using partial GC cycles and global mark cycles.</p> </li> <li> <p>The concurrent subincrement of the global mark GC cycle was interrupted by an allocation failure that triggered the concurrent subincrement to end and the <code>global mark</code> cycle type to change to a <code>global</code> type.</p> </li> <li> <p>The global GC cycle consists of only 1 GC increment, which runs mark, sweep, and compact operations during an STW pause.</p> </li> <li> <p>The global GC cycle reclaimed the eden space (1.5 MB of memory). When global GC cycle's are triggered, which occurs when memory conditions are tight, the amount of memory that the global GC cycle reclaims is often small.</p> </li> </ul>"},{"location":"x/","title":"-X","text":""},{"location":"x/#-x","title":"-X","text":"<p>Displays help on nonstandard options.</p>"},{"location":"x/#syntax","title":"Syntax","text":"<pre><code>    -X\n</code></pre>"},{"location":"x_jvm_commands/","title":"Using -X options","text":""},{"location":"x_jvm_commands/#using-x-command-line-options","title":"Using -X command-line options","text":"<p>Use these options to configure the Eclipse OpenJ9\u2122 virtual machine (VM). Unlike standard options, options prefixed with <code>-X</code> are nonstandard and are typically unique to a Java\u2122 virtual machine implementation. However, in some cases, <code>-X</code> option names are common to different VM implementations and might have the same function.</p> <p>For options that take a <code>&lt;size&gt;</code> parameter, add a suffix to the size value: \"k\" or \"K\" to indicate kilobytes, \"m\" or \"M\" to indicate megabytes, \"g\" or \"G\" to indicate gigabytes, or \"t\" or \"T\" to indicate terabytes.</p> <p>For example, to set the <code>-Xmx</code> value to 16 MB, you can specify <code>-Xmx16M</code>, <code>-Xmx16m</code>, <code>-Xmx16384K</code>, <code>-Xmx16384k</code>, or <code>-Xmx16777216</code> on the command line.</p>"},{"location":"xaggressive/","title":"-Xaggressive","text":""},{"location":"xaggressive/#-xaggressive","title":"-Xaggressive","text":"<p>Enables performance optimizations and new platform exploitation that are expected to be the default in future releases.</p>"},{"location":"xaggressive/#syntax","title":"Syntax","text":"<pre><code>    -Xaggressive\n</code></pre>"},{"location":"xalwaysclassgc/","title":"-Xalwaysclassgc","text":""},{"location":"xalwaysclassgc/#-xalwaysclassgc","title":"-Xalwaysclassgc","text":"<p>Always perform dynamic class unloading during global garbage collection.</p>"},{"location":"xalwaysclassgc/#syntax","title":"Syntax","text":"<pre><code>    -Xalwaysclassgc\n</code></pre>"},{"location":"xalwaysclassgc/#default-behavior","title":"Default behavior","text":"<p>If you don't set this option, the default behavior is defined by <code>-Xclassgc</code>.</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xalwaysclassgc/#see-also","title":"See also","text":"<ul> <li><code>-Xclassgc</code>/<code>-Xnoclassgc</code></li> </ul>"},{"location":"xaot/","title":"-Xnoaot","text":""},{"location":"xaot/#-xaot-xnoaot","title":"-Xaot / -Xnoaot","text":"<p>Use this option to control the behavior of the ahead-of-time (AOT) compiler. When the AOT compiler is active, the compiler selects the methods to be AOT compiled with the primary goal of improving startup time.</p> <p>AOT compilation allows the compilation of Java\u2122 classes into native code for subsequent executions of the same program. The AOT compiler works with the class data sharing framework.</p> <p>The AOT compiler generates native code dynamically while an application runs and caches any generated AOT code in the shared data cache. Subsequent VMs that execute the method can load and use the AOT code from the shared data cache without incurring the performance decrease experienced with JIT-compiled native code.</p>"},{"location":"xaot/#performance","title":"Performance","text":"<p>Because AOT code must persist over different program executions, AOT-generated code does not perform as well as JIT-generated code. AOT code usually performs better than interpreted code.</p> <p>In a VM without an AOT compiler or with the AOT compiler disabled, the JIT compiler selectively compiles frequently used methods into optimized native code. There is a time cost associated with compiling methods because the JIT compiler operates while the application is running. Because methods begin by being interpreted and most JIT compilations occur during startup, startup times can be increased.</p> <p>Startup performance can be improved by using the shared AOT code to provide native code without compiling. There is a small time cost to load the AOT code for a method from the shared data cache and bind it into a running program. The time cost is low compared to the time it takes the JIT compiler to compile that method.</p>"},{"location":"xaot/#default-behavior","title":"Default behavior","text":"<p>The AOT compiler is enabled by default, but is only active for classes that are found in the shared classes cache. See Introduction to class data sharing for information about the shared classes cache, how class sharing is enabled, and what options are available to modify class sharing behavior.</p>"},{"location":"xaot/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xaot</code> Enable AOT yes <code>-Xaot:&lt;parameter&gt;[=&lt;value&gt;]</code> (See Note) Enable AOT with modifications <code>-Xnoaot</code> Disable AOT <p> Note: You can concatenate several parameters in a comma-separated list, for example: <code>-Xaot:&lt;parameter1&gt;[=&lt;value1&gt;], &lt;parameter2&gt;[=&lt;value2&gt;]</code>.</p> <p>Specify the <code>-Xaot</code> option only once. By default, if you specify this option multiple times, only the last option takes effect. You can use the <code>-XX:+MergeCompilerOptions</code> option to merge all the existing instances of the <code>-Xaot</code> options logically.</p>"},{"location":"xaot/#parameters-for-xaot","title":"Parameters for <code>-Xaot</code>","text":"Parameter Effect <code>verbose</code> Reports information about the AOT and JIT compiler configuration and method compilation. <code>count</code> Specifies the number of times a method is called before it is compiled. <code>exclude</code> Excludes specified methods when AOT code is compiled. <code>limit</code> Includes specified methods when AOT code is compiled. <code>limitFile</code> Compiles only the methods listed in the specified limit file. <code>loadExclude</code> Excludes specified methods when AOT code is loaded. <code>loadLimit</code> Includes specified methods when AOT code is loaded. <code>loadLimitFile</code> Loads only the methods listed in the specified limit file."},{"location":"xaot/#verbose","title":"<code>verbose</code>","text":"<pre><code>    -Xaot:verbose\n</code></pre> Reports information about the AOT and JIT compiler configuration and method compilation."},{"location":"xaot/#count","title":"<code>count</code>","text":"<pre><code>    -Xaot:count=&lt;n&gt;\n</code></pre> Specifies the number of times, <code>&lt;n&gt;</code>, a method is called before it is compiled or loaded from an existing shared classes cache. Setting <code>-Xaot:count=0</code> forces the AOT compiler to compile everything on first execution, which is useful for problem determination."},{"location":"xaot/#exclude","title":"<code>exclude</code>","text":"<pre><code>    -Xaot:exclude={&lt;method_name&gt;}\n</code></pre> <p>Excludes a Java method when AOT code is compiled from the shared classes cache. Use this option if the method causes the program to fail.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be excluded; the wildcard <code>*</code> may be used. Specify as much of the full package, class and method as necessary.</p> <p>For example, <code>-Xaot:exclude={test/sample/MyClass.testMethod()V}</code> excludes the single method specified. However, <code>-Xaot:exclude={test/sample/MyClass.testMethod()*}</code> excludes the method regardless of return type. Similarly, <code>-Xaot:exclude={*}</code> excludes all methods.</p> <p> Note: <code>exclude</code> has the same effect regardless of whether it's specified on <code>-Xjit</code> or <code>-Xaot</code>. In consequence, if you specify <code>-Xaot:exclude</code>, JIT compilation is also prevented and the methods specified are always interpreted.</p>"},{"location":"xaot/#limit","title":"<code>limit</code>","text":"<pre><code>    -Xaot:limit={&lt;method_name&gt;}\n</code></pre> <p>Only the Java methods specified are included when AOT code is compiled from the shared classes cache. <code>&lt;method_name&gt;</code> is the method or methods that are to be included (the wildcard <code>*</code> may be used, see <code>-Xaot:exclude</code> for details).</p> <p> Note: <code>limit</code> has the same effect regardless of whether it's specified on <code>-Xjit</code> or <code>-Xaot</code>. In consequence, if you specify <code>-Xaot:limit</code>, JIT compilation is also restricted to those methods specified; other methods are always interpreted.</p>"},{"location":"xaot/#limitfile","title":"<code>limitFile</code>","text":"<pre><code>    -Xaot:limitFile=(&lt;filename&gt;,&lt;m&gt;,&lt;n&gt;)\n</code></pre> <p>Compiles or loads only the methods listed on lines <code>&lt;m&gt;</code> to, and including, <code>&lt;n&gt;</code> in the specified limit file, <code>&lt;filename&gt;</code>. Methods not listed in the limit file and methods listed on lines outside the range are not compiled or loaded.</p> <p> Note: <code>limitFile</code> has the same effect regardless of whether it's specified on <code>-Xjit</code> or <code>-Xaot</code>. In consequence, if you specify <code>-Xaot:limitFile</code>, JIT compilation is also restricted to those methods specified; other methods are always interpreted.</p>"},{"location":"xaot/#loadexclude","title":"<code>loadExclude</code>","text":"<pre><code>    -Xaot:loadExclude={&lt;method_name&gt;}\n</code></pre> <p>Excludes the specified Java methods when AOT code is loaded from the shared classes cache. In consequence, the compiler does a JIT compilation on those methods instead.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be excluded (the wildcard <code>*</code> may be used, see <code>-Xaot:exclude</code> for details). This option does not prevent the method from being compiled.</p> <p> Note: <code>loadExclude</code> can only be specified on <code>-Xaot</code>; it does not have an equivalent on <code>-Xjit</code>.</p>"},{"location":"xaot/#loadlimit","title":"<code>loadLimit</code>","text":"<pre><code>    -Xaot:loadLimit={&lt;method_name&gt;}\n</code></pre> <p>Only the Java methods specified are included when AOT code is loaded from the shared classes cache. In consequence, the compiler does a JIT compilation on other methods instead.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be included (the wildcard <code>*</code> may be used; see <code>-Xaot:exclude</code> for details).</p> <p> Note: <code>loadLimit</code> can only be specified on <code>-Xaot</code>; it does not have an equivalent on <code>-Xjit</code>. This option filters what AOT code the compiler is allowed to load from the shared classes cache.</p>"},{"location":"xaot/#loadlimitfile","title":"<code>loadLimitFile</code>","text":"<pre><code>    -Xaot:loadLimitFile=(&lt;filename&gt;,&lt;m&gt;,&lt;n&gt;)\n</code></pre> <p>Loads only the methods listed on lines <code>&lt;m&gt;</code> to, and including, <code>&lt;n&gt;</code> in the specified limit file. In consequence, the compiler does a JIT compilation on other methods instead.</p> <p><code>&lt;filename&gt;</code>. Methods not listed in the limit file and methods listed on lines outside the range are not loaded.</p> <p> Note: <code>loadLimitFile</code> can only be specified on <code>-Xaot</code>; it does not have an equivalent on <code>-Xjit</code>.</p>"},{"location":"xaot/#see-also","title":"See also","text":"<ul> <li>Introduction to class data sharing</li> <li><code>-Xquickstart</code></li> <li><code>-Xshareclasses</code></li> <li><code>-Xjit</code></li> </ul>"},{"location":"xargencoding/","title":"-Xargencoding","text":""},{"location":"xargencoding/#-xargencoding","title":"-Xargencoding","text":"<p>The <code>java</code> and <code>javaw</code> launchers accept arguments and class names containing any character that is in the character set of the current locale. You can also specify any Unicode character in the class name and arguments by using Java\u2122 escape sequences.</p> <p>To do this, use the <code>-Xargencoding</code> command-line option.</p>"},{"location":"xargencoding/#syntax","title":"Syntax","text":"<pre><code>    -Xargencoding:&lt;parameter&gt;\n</code></pre>"},{"location":"xargencoding/#parameters","title":"Parameters","text":""},{"location":"xargencoding/#no-parameter","title":"No parameter","text":"<pre><code>    -Xargencoding\n</code></pre> You can use Unicode escape sequences in the argument list that you pass to this option. To specify a Unicode character, use escape sequences in the form <code>\\u####</code>, where <code>#</code> is a hexadecimal digit (0-9, A-F). For example, to specify a class that is called <code>HelloWorld</code> and use Unicode encoding for both capital letters, use this command:<pre><code>java -Xargencoding \\u0048ello\\u0057orld\n</code></pre>"},{"location":"xargencoding/#utf8","title":"<code>utf8</code>","text":"<pre><code>    -Xargencoding:utf8\n</code></pre> Use utf8 encoding."},{"location":"xargencoding/#latin","title":"<code>latin</code>","text":"<pre><code>    -Xargencoding:latin\n</code></pre> Use ISO8859_1 encoding."},{"location":"xbootclasspath/","title":"-Xbootclasspath","text":""},{"location":"xbootclasspath/#-xbootclasspath","title":"-Xbootclasspath","text":"<p>This Oracle\u00ae HotSpot\u2122 option specifies the search path for bootstrap classes and resources. The default is to search for bootstrap classes and resources in the internal VM directories and <code>.jar</code> files. The option is recognized by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xbootclasspath/#syntax","title":"Syntax","text":"Limited to... Setting Effect <code>-Xbootclasspath:&lt;path&gt;</code> Sets the search path for bootstrap classes and resources. <code>-Xbootclasspath/p:&lt;path&gt;</code> Prepends the specified resources to the front of the bootstrap class path. <code>-Xbootclasspath/a:&lt;path&gt;</code> Appends the specified resources to the end of the bootstrap class path. where <code>&lt;path&gt;</code> represents directories and compressed or Java\u2122 archive files separated with colons (:). On Windows\u2122 systems, use a semicolon (;) as a separator. <p> Oracle advise that you should \"not deploy applications that use this option to override a class in <code>rt.jar</code>, because this violates the JRE binary code license.\"</p>"},{"location":"xceehdlr/","title":"-XCEEHDLR","text":""},{"location":"xceehdlr/#-xceehdlr","title":"-XCEEHDLR","text":"<p>(31-bit z/OS\u00ae only)</p> <p>Controls Eclipse OpenJ9\u2122 VM Language Environment\u00ae condition handling.</p>"},{"location":"xceehdlr/#syntax","title":"Syntax","text":"<pre><code>    -XCEEHDLR\n</code></pre>"},{"location":"xceehdlr/#explanation","title":"Explanation","text":"<p>Use the <code>-XCEEHDLR</code> option if you want the new behavior for the Java\u2122 and COBOL interoperability batch mode environment, because this option makes signal and condition handling behavior more predictable in a mixed Java and COBOL environment.</p> <p>When the <code>-XCEEHDLR</code> option is enabled, a condition triggered by an arithmetic operation while executing a Java Native Interface (JNI) component causes the VM to convert the Language Environment condition into a Java <code>ConditionException</code>.</p> <p>When the <code>-XCEEHDLR</code> option is used the VM does not install POSIX signal handlers for the following signals:</p> <ul> <li><code>SIGBUS</code></li> <li><code>SIGFPE</code></li> <li><code>SIGILL</code></li> <li><code>SIGSEGV</code></li> <li><code>SIGTRAP</code></li> </ul> <p>Instead, user condition handlers are registered by the VM, using the <code>CEEHDLR()</code> method. These condition handlers are registered every time a thread calls into the VM. Threads call into the VM using the Java Native Interface and including the invocation interfaces, for example <code>JNI\\_CreateJavaVM</code>.</p> <p>The Java runtime continues to register POSIX signal handlers for the following signals:</p> <ul> <li><code>SIGABRT</code></li> <li><code>SIGINT</code></li> <li><code>SIGQUIT</code></li> <li><code>SIGTERM</code></li> </ul> <p>Signal chaining using the <code>libjsig.so</code> library is not supported.</p> <p>When the <code>-XCEEHDLR</code> option is used, condition handler actions take place in the following sequence:</p> <ol> <li>All severity 0 and severity 1 conditions are percolated.</li> <li>If a Language Environment condition is triggered in JNI code as a result of an arithmetic operation, the VM condition handler resumes executing Java code as if the JNI native code had thrown a <code>com.ibm.le.conditionhandling.ConditionException</code> exception. This exception class is a subclass of <code>java.lang.RuntimeException</code>. Note: The Language Environment conditions that correspond to arithmetic operations are <code>CEE3208S</code> through <code>CEE3234S</code>. However, the Language Environment does not deliver conditions <code>CEE3208S</code>, <code>CEE3213S</code>, or <code>CEE3234S</code> to C applications, so the VM condition handler will not receive them.</li> <li>If the condition handling reaches this step, the condition is considered to be unrecoverable. RAS diagnostic information is generated, and the VM ends by calling the <code>CEE3AB2()</code> service with abend code 3565, reason code 0, and cleanup code 0.</li> </ol> <p> Restriction: You cannot use <code>-Xsignal:userConditionHandler=percolate</code> and <code>-XCEEHDLR</code> together.</p>"},{"location":"xceehdlr/#see-also","title":"See also","text":"<ul> <li> <p>-Xsignal:userConditionHandler=percolate</p> </li> <li> <p>Signal handling</p> </li> </ul>"},{"location":"xcheck/","title":"-Xcheck","text":""},{"location":"xcheck/#-xcheck","title":"-Xcheck","text":"<p>You can use the <code>-Xcheck</code> option to run checks during Eclipse OpenJ9\u2122 virtual machine (VM) startup, such as memory checks or checks on JNI functions.</p>"},{"location":"xcheck/#syntax","title":"Syntax","text":"<pre><code>    -Xcheck:&lt;parameter&gt;\n</code></pre>"},{"location":"xcheck/#parameters","title":"Parameters","text":"Parameter Effect <code>classpath</code> Checks the classpath and reports errors such as a missing directory or JAR file. <code>dump</code> Checks the operating system for settings that might truncate system dumps. (AIX\u00ae and Linux\u00ae only) <code>gc</code> Runs additional checks on garbage collection. <code>jni</code> Runs additional checks for JNI functions. <code>memory</code> Identifies memory leaks inside the VM using strict checks that cause the VM to exit on failure. <code>vm</code> Performs additional checks on the VM."},{"location":"xcheck/#classpath","title":"<code>classpath</code>","text":"<pre><code>    -Xcheck:classpath\n</code></pre> Checks the classpath and reports errors such as a missing directory or JAR file."},{"location":"xcheck/#dump","title":"<code>dump</code>","text":"<p>AIX and Linux only</p> <pre><code>    -Xcheck:dump\n</code></pre> <p>Checks operating system settings during VM startup. Messages are issued if the operating system has settings that might truncate system dumps.</p> <p>On AIX systems, the following messages are possible:</p> <ul> <li><code>JVMJ9VM133W The system core size hard ulimit is set to &lt;value&gt;, system dumps may be truncated</code></li> </ul> This message indicates that the AIX operating system user limit is set to restrict the size of system dumps to the value indicated. If a system dump is produced by the VM it might be truncated, and therefore of greatly reduced value in investigating the cause of crashes and other issues. For more information about how to set user limits on AIX, see Setting system resource limits on AIX and Linux systems. <ul> <li><code>JVMJ9VM134W The system fullcore option is set to FALSE, system dumps may be truncated</code></li> </ul> This message indicates that the AIX operating system <code>Enable full CORE dump</code>option is set to FALSE. This setting might result in truncated system dumps. For more information about how to set this option correctly on AIX, see Setting system resource limits on AIX and Linux systems. <p>On Linux systems, the following messages are possible:</p> <ul> <li><code>JVMJ9VM133W The system core size hard ulimit is set to &lt;value&gt;, system dumps may be truncated.</code></li> </ul> This message indicates that the Linux operating system user limit is set to restrict the size of system dumps to the value indicated. If a system dump is produced by the VM, it might be truncated and therefore of greatly reduced value in investigating the cause of crashes and other issues. Review the documentation that is provided for your operating system to correctly configure the value for <code>ulimits</code>. For further information, see Setting system resource limits on AIX and Linux systems. <ul> <li><code>JVMJ9VM135W /proc/sys/kernel/core_pattern setting \"|/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t e\" specifies that core dumps are to be piped to an external program. The JVM may be unable to locate core dumps and rename them.</code></li> </ul> This message means that an external program, abrt-hook-ccpp, is configured in the operating system to intercept any system dump files that are generated. This program is part of the Automatic Bug Reporting Tool (ABRT). For more information, see Automatic Bug Reporting Tool. This tool might interfere with the VM's system dump file processing by renaming or truncating system dumps. Review the configuration of the ABRT tool and messages that are written by the tool in<code>/var/log/messages</code>. If problems occur when generating system dumps from the VM, consider disabling ABRT. <ul> <li><code>JVMJ9VM135W /proc/sys/kernel/core_pattern setting \"|/usr/share/apport/apport %p %s %c\" specifies that core dumps are to be piped to an external program. The JVM may be unable to locate core dumps and rename them.</code></li> </ul> This message means that an external program, apport, is configured in the operating system to intercept any system dump files that are generated. For more information about this tool, see: Apport The tool might interfere with the VM's system dump file processing by renaming or truncating system dumps. Review the configuration of the Apport tool and messages that are written by the tool in <code>/var/log/apport.log</code>. If problems occur when generating system dumps from the VM, consider disabling the Apport tool. <ul> <li><code>JVMJ9VM136W \"/proc/sys/kernel/core_pattern setting \"/tmp/cores/core.%e.%p.%h.%t \" specifies a format string for renaming core dumps. The JVM may be unable to locate core dumps and rename them.</code></li> </ul> This message indicates that the Linux <code>/proc/sys/kernel/core_pattern</code> option is set to rename system dumps. The tokens that are used in the operating system dump name might interfere with the VM's system dump file processing, in particular with file names specified in the VM <code>-Xdump</code> options. If problems occur when generating system dumps from the VM, consider changing the <code>/proc/sys/kernel/core_pattern</code> setting to the default value of <code>core</code>."},{"location":"xcheck/#gc","title":"<code>gc</code>","text":"<pre><code>    -Xcheck:gc[:help][:&lt;scan options&gt;][:&lt;verify options&gt;][:&lt;misc options&gt;]\n</code></pre> Runs additional checks on garbage collection. By default, no checks are made. There are many scan, verify, and miscellaneous suboptions available. If you do not specify any, all possible scan and verify suboptions are run, plus the miscellaneous verbose and check suboptions. For more information, see the output of <code>-Xcheck:gc:help</code>."},{"location":"xcheck/#jni","title":"<code>jni</code>","text":"<pre><code>    -Xcheck:jni[:help][:&lt;option&gt;]\n</code></pre> Runs additional checks for JNI functions. By default, no checks are made. For more information, see the output of <code>-Xcheck:jni:help</code>."},{"location":"xcheck/#memory","title":"<code>memory</code>","text":"<pre><code>    -Xcheck:memory[:&lt;option&gt;]\n</code></pre> Identifies memory leaks inside the VM by using strict checks that cause the VM to exit on failure. Restriction: You cannot include <code>-Xcheck:memory</code> in the options file (see <code>-Xoptionsfile</code>). <p>The available parameters are as follows:</p> <code>:all</code> (Default if no options specified) Enables checking of all allocated and freed blocks on every free and allocate call. This check of the heap is the most thorough. It typically causes the VM to exit on nearly all memory-related problems soon after they are caused. This option has the greatest affect on performance. <code>:callsite=&lt;number_of_allocations&gt;</code> <p>Displays callsite information every <code>&lt;number_of_allocations&gt;</code>. De-allocations are not counted. Callsite information is presented in a table with separate information for each callsite. Statistics include:</p> <ul> <li>The number and size of allocation and free requests since the last report.</li> <li>The number of the allocation request responsible for the largest allocation from each site.</li> </ul> <p>Callsites are presented as <code>sourcefile:linenumber</code> for C code and assembly function name for assembler code.</p> <p>Callsites that do not provide callsite information are accumulated into an \"unknown\" entry.</p> <code>:failat=&lt;number_of_allocations&gt;</code> <p>Causes memory allocation to fail (return NULL) after <code>&lt;number_of_allocations&gt;</code>. For example, setting <code>&lt;number_of_allocations&gt;</code> to 13 causes the 14th allocation to return NULL. De-allocations are not counted. Use this option to ensure that VM code reliably handles allocation failures. This option is useful for checking allocation site behavior rather than setting a specific allocation limit.</p> <code>:ignoreUnknownBlocks</code> Ignores attempts to free memory that was not allocated using the <code>-Xcheck:memory</code> tool. Instead, the -Xcheck:memory statistics that are printed out at the end of a run indicates the number of \"unknown\" blocks that were freed. <code>:mprotect=[top|bottom]</code> Locks pages of memory on supported platforms, causing the program to stop if padding before or after the allocated block is accessed for reads or writes. An extra page is locked on each side of the block returned to the user. If you do not request an exact multiple of one page of memory, a region on one side of your memory is not locked. The <code>top</code> and <code>bottom</code> options control which side of the memory area is locked. <code>top</code> aligns your memory blocks to the top of the page (lower address), so buffer underruns result in an application failure. <code>bottom</code> aligns your memory blocks to the bottom of the page (higher address) so buffer overruns result in an application failure. Standard padding scans detect buffer underruns when using <code>top</code> and buffer overruns when using <code>bottom</code>. <code>:nofree</code> Keeps a list of blocks that are already used instead of freeing memory. This list, and the list of currently allocated blocks, is checked for memory corruption on every allocation and deallocation. Use this option to detect a dangling pointer (a pointer that is \"dereferenced\" after its target memory is freed). This option cannot be reliably used with long-running applications (such as WebSphere\u00ae Application Server), because \"freed\" memory is never reused or released by the VM. <code>:noscan</code> Checks for blocks that are not freed. This option has little effect on performance, but memory corruption is not detected. This option is compatible only with <code>subAllocator</code>, <code>callsite</code>, and <code>callsitesmall</code>. <code>:quick</code> Enables block padding only and is used to detect basic heap corruption. Every allocated block is padded with sentinel bytes, which are verified on every allocate and free. Block padding is faster than the default of checking every block, but is not as effective. <code>:skipto=&lt;number_of_allocations&gt;</code> Causes the program to check only on allocations that occur after <code>&lt;number_of_allocations&gt;</code>. De-allocations are not counted. Use this option to speed up VM startup when early allocations are not causing the memory problem. The VM performs approximately 250+ allocations during startup. <code>:subAllocator[=&lt;size_in_MB&gt;]</code> Allocates a dedicated and contiguous region of memory for all VM allocations. This option helps to determine if user JNI code or the VM is responsible for memory corruption. Corruption in the VM <code>subAllocator</code> heap suggests that the VM is causing the problem; corruption in the user-allocated memory suggests that user code is corrupting memory. Typically, user and VM allocated memory are interleaved. <code>:zero</code> Newly allocated blocks are set to 0 instead of being filled with the <code>0xE7E7xxxxxxxxE7E7</code> pattern. Setting these blocks to 0 helps you to determine whether a callsite is expecting zeroed memory, in which case the allocation request is followed by <code>memset(pointer, 0, size)</code>."},{"location":"xcheck/#vm","title":"<code>vm</code>","text":"<pre><code>    -Xcheck:vm[:&lt;option&gt;]\n</code></pre> Performs additional checks on the VM. By default, no checking is performed. For more information, run <code>-Xcheck:vm:help</code>."},{"location":"xclassgc/","title":"-Xnoclassgc","text":""},{"location":"xclassgc/#-xclassgc-xnoclassgc","title":"-Xclassgc / -Xnoclassgc","text":"<p>Enables and disables the garbage collection (GC) of storage that is associated with Java classes that are no longer being used by the Eclipse OpenJ9\u2122 VM.</p> <p>When enabled, GC occurs only on class loader changes. To always enable dynamic class unloading regardless of class loader changes, set <code>-Xalwaysclassgc</code>.</p> <p> Note: Disabling class GC is not recommended because unlimited native memory growth can occur, which can lead to out-of-memory errors.</p>"},{"location":"xclassgc/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xclassgc</code> Enables dynamic class unloading on demand yes <code>-Xnoclassgc</code> Disables dynamic class unloading <p>These options can be used with all OpenJ9 GC policies.</p>"},{"location":"xclassgc/#see-also","title":"See also","text":"<ul> <li><code>-Xalwaysclassgc</code></li> </ul>"},{"location":"xcodecache/","title":"-Xcodecache","text":""},{"location":"xcodecache/#-xcodecache","title":"-Xcodecache","text":"<p>Use this option to tune performance.</p> <p>This option sets the size of each block of memory that is allocated to store the native code of compiled Java\u2122 methods. By default, this size is selected internally according to the processor architecture and the capability of your system. The maximum value you can specify is 32 MB. If you set a value larger than 32 MB, the JIT ignores the input and sets the value to 32 MB.</p> <p> Note: The JIT compiler might allocate more than one code cache for an application. Use the <code>-Xcodecachetotal</code> option to set the maximum amount of memory that is used by all code caches.</p>"},{"location":"xcodecache/#syntax","title":"Syntax","text":"<pre><code>    -Xcodecache&lt;size&gt;\n</code></pre> See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter."},{"location":"xcodecachetotal/","title":"-Xcodecachetotal","text":""},{"location":"xcodecachetotal/#-xcodecachetotal","title":"-Xcodecachetotal","text":"<p>Use this option to set the maximum size limit for the JIT code cache. This option also affects the size of the JIT data cache.</p>"},{"location":"xcodecachetotal/#syntax","title":"Syntax","text":"<pre><code>    -Xcodecachetotal&lt;size&gt;\n</code></pre> <p>The default size is 256 MB for a 64-bit VM and 64 MB for a 31/32-bit VM.</p> <p>See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xcodecachetotal/#explanation","title":"Explanation","text":"<p>By default, the total JIT code cache size is 256 MB for a 64-bit VM and 64 MB for a 31/32-bit VM or 25% of the physical memory available to the VM process, whichever is lesser. Long-running, complex, server-type applications can fill the JIT code cache, which can cause performance problems because not all of the important methods can be JIT-compiled. Use the <code>-Xcodecachetotal</code> option to increase or decrease the maximum code cache size to a setting that suits your application. The minimum size of the code cache is restricted to 2 MB.</p> <p>The value that you specify is rounded up to a multiple of the code cache block size, as specified by the -Xcodecache option. If you specify a value for the <code>-Xcodecachetotal</code> option that is smaller than the default setting, that value is ignored.</p> <p>When you use this option, the maximum size limit for the JIT data cache, which holds metadata about compiled methods, is increased or decreased proportionally to support the JIT compilations.</p> <p>The maximum size limits, for both the JIT code and data caches, that are in use by the VM are shown in Javadump output. Look for lines that begin with <code>1STSEGLIMIT</code>. Use this information together with verbose JIT tracing to determine suitable values for this option on your system. For example Javadump output, see Java dump: Storage Management (MEMINFO).</p>"},{"location":"xcodecachetotal/#see-also","title":"See also","text":"<ul> <li><code>-XX:codecachetotalMaxRAMPercentage</code></li> <li>-Xjit</li> </ul>"},{"location":"xcomp/","title":"-Xcomp","text":""},{"location":"xcomp/#-xcomp","title":"-Xcomp","text":"<p>The use of this option is deprecated; use <code>-Xjit:count=0</code> instead.</p>"},{"location":"xcomp/#syntax","title":"Syntax","text":"<pre><code>    -Xcomp\n</code></pre>"},{"location":"xcompactexplicitgc/","title":"-Xnocompactexplicitgc","text":""},{"location":"xcompactexplicitgc/#xcompactexplicitgc-xnocompactexplicitgc","title":"\u2011Xcompactexplicitgc / \u2011Xnocompactexplicitgc","text":"<p>Enables or disables full compaction each time <code>System.gc()</code> is called. </p> <p>Compaction takes place on global garbage collections if you specify <code>-Xcompactgc</code> or if compaction triggers are met. </p>"},{"location":"xcompactexplicitgc/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xcompactexplicitgc</code> Enable compaction yes <code>-Xnocompactexplicitgc</code> Disable compaction"},{"location":"xcompactexplicitgc/#see-also","title":"See also","text":"<ul> <li>Global garbage collection: Compaction phase</li> </ul>"},{"location":"xcompactgc/","title":"-Xnocompactgc","text":""},{"location":"xcompactgc/#-xcompactgc-xnocompactgc","title":"-Xcompactgc / -Xnocompactgc","text":"<p>Enables or disables full compaction on system and global garbage collection (GC) activities.</p>"},{"location":"xcompactgc/#syntax","title":"Syntax","text":"Setting Action <code>-Xcompactgc</code> Enable full compaction <code>-Xnocompactgc</code> Disable full compaction"},{"location":"xcompactgc/#default-behavior","title":"Default behavior","text":"<p>If a compaction option is not specified, the garbage collector compacts based on a series of triggers. These triggers attempt to compact only when it is beneficial to the future performance of the VM.</p> <p>These options are not applicable to the following GC policies:</p> <ul> <li>balanced GC policy (<code>-Xgcpolicy:balanced</code>): compaction is always enabled.</li> <li>metronome GC policy (<code>-Xgcpolicy:metronome</code>): compaction is not supported.</li> </ul>"},{"location":"xcompactgc/#see-also","title":"See also","text":"<ul> <li>GC compact operation</li> </ul>"},{"location":"xcompilationthreads/","title":"-XcompilationThreads","text":""},{"location":"xcompilationthreads/#-xcompilationthreads","title":"-XcompilationThreads","text":"<p>Use this option to specify the number of compilation threads that are used by the JIT compiler.</p>"},{"location":"xcompilationthreads/#syntax","title":"Syntax","text":"<pre><code>    -XcompilationThreads&lt;n&gt;\n</code></pre> Where &lt;n&gt; is the number of threads. The minimum value is 1. The default and maximum values depend on whether the VM is running with the JITServer feature enabled and if so, whether the VM is running as a JITServer server, as shown in the following table: JIT compiler scenario Default value Maximum value JIT and JITServer client Determined by internal JIT heuristics that consider the number of CPUs that the VM is allowed to use 15 JITServer server 63 999 Any number outside this range is ignored. Setting the compilation threads to zero does not disable the JIT compiler. If you want to disable the JIT, use the <code>-Xint</code> option."},{"location":"xcompilationthreads/#explanation","title":"Explanation","text":"<p>When multiple compilation threads are used, the JIT might generate several diagnostic log files. A log file is generated for each compilation thread. The naming convention for the log file generated by the first compilation thread uses the following pattern:</p> <pre><code>&lt;specified_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;pid&gt;\n</code></pre> <p>The first compilation thread has ID 0. Log files generated by the second and subsequent compilation threads append the ID of the corresponding compilation thread as a suffix to the log file name. The pattern for these log file names is as follows:</p> <pre><code>&lt;specified_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;pid&gt;.&lt;compilation_thread_ID&gt;\n</code></pre> <p>For example, the second compilation thread has ID 1. The result is that the corresponding log file name has the form:</p> <pre><code>&lt;specified_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;pid&gt;.1\n</code></pre>"},{"location":"xcompilationthreads/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xcompressedrefs/","title":"-Xnocompressedrefs","text":""},{"location":"xcompressedrefs/#-xcompressedrefs-xnocompressedrefs","title":"-Xcompressedrefs / -Xnocompressedrefs","text":"<p>(64-bit only)</p> <p>Enables or disables the use of compressed references.</p> <p> Restriction: You cannot include <code>-Xcompressedrefs</code> in the options file (see <code>-Xoptionsfile</code>).</p>"},{"location":"xcompressedrefs/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xcompressedrefs</code> Enable compression yes (see Default behavior) <code>-Xnocompressedrefs</code> Disable compression"},{"location":"xcompressedrefs/#default-behavior","title":"Default behavior","text":"<p>Compressed references are enabled by default when <code>-Xmx</code> \u2264 57 GB.</p> <p>z/OS\u00ae: This threshold value assumes that you have APAR OA49416 installed. If you do not have the APAR installed, the threshold value is 25 GB.</p> <p>AIX\u00ae and Linux\u00ae: For the metronome garbage collection policy, the threshold is 25 GB.</p>"},{"location":"xcompressedrefs/#see-also","title":"See also","text":"<ul> <li>Compressed references</li> </ul>"},{"location":"xconcurrentbackground/","title":"-Xconcurrentbackground","text":""},{"location":"xconcurrentbackground/#-xconcurrentbackground","title":"-Xconcurrentbackground","text":"<p>Specifies the number of low-priority background threads that are attached to assist the mutator threads in concurrent mark operations. This option maps directly to the HotSpot <code>-XX:ParallelCMSThreads=N</code> and <code>-XX:ConcGCThreads=N</code> options.</p>"},{"location":"xconcurrentbackground/#syntax","title":"Syntax","text":"<pre><code>    -Xconcurrentbackground&lt;n&gt;\n</code></pre>"},{"location":"xconcurrentbackground/#default-behavior","title":"Default behavior","text":"<p>The default value is <code>1</code>.</p> <p> Note: This value is reported in the header section of a verbose GC log with the entry <code>&lt;attribute name=\"gcthreads Concurrent Mark\" value=\"1\" /&gt;</code>.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xconcurrentbackground/#see-also","title":"See also","text":"<ul> <li><code>-XX:ParallelCMSThreads</code></li> <li><code>-XX:ConcGCThreads</code></li> </ul>"},{"location":"xconcurrentlevel/","title":"-Xconcurrentlevel","text":""},{"location":"xconcurrentlevel/#-xconcurrentlevel","title":"-Xconcurrentlevel","text":"<p>This option indicates the ratio between the amount of heap allocated and the amount of heap marked, which is known as the allocation tax rate.</p>"},{"location":"xconcurrentlevel/#syntax","title":"Syntax","text":"<pre><code>    -Xconcurrentlevel&lt;number&gt;\n</code></pre>"},{"location":"xconcurrentlevel/#default-behavior","title":"Default behavior","text":"<p>The default is 8.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xconcurrentslack/","title":"-Xconcurrentslack","text":""},{"location":"xconcurrentslack/#-xconcurrentslack","title":"-Xconcurrentslack","text":"<p>Attempts to keep the specified amount of the heap space free in concurrent collectors by starting the concurrent operations earlier.</p> <p>Using this option can sometimes alleviate pause time problems in concurrent collectors at the cost of longer concurrent cycles, affecting total throughput.</p>"},{"location":"xconcurrentslack/#syntax","title":"Syntax","text":"<pre><code>    -Xconcurrentslack&lt;size&gt;\n</code></pre> See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter."},{"location":"xconcurrentslack/#default-behavior","title":"Default behavior","text":"<p>The default value is 0, which is optimal for most applications.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>), the optimize for throughput policy (<code>-Xgcpolicy:optthruput</code>), or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xconmeter/","title":"-Xconmeter","text":""},{"location":"xconmeter/#-xconmeter","title":"-Xconmeter","text":"<p>This option determines the usage of which area, LOA (large object area) or SOA (small object area), is metered and therefore which allocations are taxed during concurrent mark operations.</p>"},{"location":"xconmeter/#syntax","title":"Syntax","text":"<pre><code>    -Xconmeter:&lt;parameter&gt;\n</code></pre>"},{"location":"xconmeter/#parameters","title":"Parameters","text":""},{"location":"xconmeter/#soa","title":"<code>soa</code>","text":"<pre><code>    -Xconmeter:soa\n</code></pre> (Default) Applies the allocation tax to allocations from the small object area (SOA)."},{"location":"xconmeter/#loa","title":"<code>loa</code>","text":"<pre><code>    -Xconmeter:loa\n</code></pre> Applies the allocation tax to allocations from the large object area (LOA)."},{"location":"xconmeter/#dynamic","title":"<code>dynamic</code>","text":"<pre><code>    -Xconmeter:dynamic\n</code></pre> The collector dynamically determines which area to meter based on which area is exhausted first, whether it is the SOA or the LOA."},{"location":"xconmeter/#default-behavior","title":"Default behavior","text":"<p>By default, allocation tax is applied to the SOA.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xdisablejavadump/","title":"-Xdisablejavadump","text":""},{"location":"xdisablejavadump/#-xdisablejavadump","title":"-Xdisablejavadump","text":"<p>Turns off Java dump generation on errors and signals.</p>"},{"location":"xdisablejavadump/#syntax","title":"Syntax","text":"<pre><code>    -Xdisablejavadump\n</code></pre>"},{"location":"xdisablejavadump/#default-behavior","title":"Default behavior","text":"<p>By default, Javadump generation is enabled.</p>"},{"location":"xdisablejavadump/#see-also","title":"See also","text":"<ul> <li><code>-Xdump</code></li> </ul>"},{"location":"xdump/","title":"-Xdump","text":""},{"location":"xdump/#-xdump","title":"-Xdump","text":"<p>OpenJ9 produces various types of diagnostic information for analysis when different events occur, such as a general protection fault. The dumps produced are controlled by dump agents, which are initialized when the OpenJ9 virtual machine (VM) starts. The default settings for the dump agents are sufficient for most cases. However, you can use the <code>-Xdump</code> option on the command line to fine tune the dump agent settings. For example, you can use the <code>-Xdump</code> option to add and remove dump agents for various VM events, update default dump settings, and limit the number of dumps that are produced.</p> <p>A large set of options and suboptions are available for controlling dumps, which provides a lot of flexibility.</p>"},{"location":"xdump/#xdump-option-builder","title":"Xdump Option Builder","text":"<p>Use the Xdump Option Builder tool to help you specify the correct options and avoid incompatibilities.</p>"},{"location":"xdump/#syntax","title":"Syntax","text":"<pre><code>    -Xdump:&lt;parameter&gt;\n</code></pre> <p>The following table lists the help options for <code>-Xdump</code>, which provide usage and configuration information:</p> Command Result <code>-Xdump:help</code> Displays general dump help. <code>-Xdump:events</code> Lists available trigger events. <code>-Xdump:request</code> Lists additional VM requests. <code>-Xdump:tokens</code> Lists recognized label tokens. <code>-Xdump:what</code> Shows registered agents on startup. <code>-Xdump:&lt;agent&gt;:help</code> Displays dump agent usage information. <p>The following options can be used to control the production of diagnostic data:  </p> Parameter Result <code>-Xdump:none</code> Removes all default dump agents and any preceding dump options. <code>-Xdump:dynamic</code> Enable support for pluggable agents <code>-Xdump:nofailover</code> Discards dumps when the default or specified dump location is full. <code>-Xdump:directory=&lt;path&gt;</code> Specifies a directory for all dump types to be written to. This directory path is prefixed to the path of all non-absolute dump file names, including the file names for the default dump agents. <code>-Xdump:suspendwith=&lt;offset&gt;</code> Modifies the signal that is used to suspend VM threads while a dump file is being written. Use <code>&lt;offset&gt;</code> to change the default signal number. (Linux\u00ae only) <code>-Xdump:&lt;agent&gt;:&lt;suboptions&gt;</code> Provides detailed suboptions per dump agent that provide more granular control. <p>Dump agents can be configured at a very granular level by specifying suboptions. The <code>&lt;events&gt;</code> suboption is the prime trigger mechanism. If no events are specified explicitly, then the default settings for the corresponding agent are added. For more information, see Default dump agents. You can update the default dump settings by using the <code>defaults</code> suboption. The full set of suboptions are listed in the following table:</p> Dump agent suboptions Result <code>-Xdump:&lt;agent&gt;:none</code> Removes the dump agent. <code>-Xdump:&lt;agent&gt;:defaults</code> Prints the default options for the dump agent. <code>-Xdump:&lt;agent&gt;:events=&lt;events&gt;</code> Triggers a dump agent when a specific event occurs. <code>-Xdump:&lt;agent&gt;:exec=&lt;command&gt;</code> Starts an external application for the dump agent. <code>-Xdump:&lt;agent&gt;:file=&lt;filename&gt;</code> Specifies where to write the dump for the dump agent. <code>-Xdump:&lt;agent&gt;:filter=&lt;filter&gt;</code> Filters dumps by wildcards or events. <code>-Xdump:&lt;agent&gt;:msg_filter=&lt;filter&gt;</code> Filters on text strings within an exception message. <code>-Xdump:&lt;agent&gt;:opts=&lt;options&gt;</code> Used by specific dump agents to select the type of dump file to produce. <code>-Xdump:&lt;agent&gt;:priority=&lt;0-999&gt;</code> Specifies the priority that the dump agents run in. <code>-Xdump:&lt;agent&gt;:range=&lt;ranges&gt;</code> Starts and stops a dump agent on a particular occurrence of a VM. <code>-Xdump:&lt;agent&gt;:request=&lt;requests&gt;</code> Asks the VM to prepare the state before starting the dump agent. <p>You can have multiple <code>-Xdump</code> options on the command line. You can also have multiple dump types triggered by multiple events. For example, the following command turns off the creation of heap dump files, and creates a dump agent that produces a heap dump file and a Java\u2122 dump file when either a vmstart or vmstop event occurs:</p> <pre><code>java -Xdump:heap:none -Xdump:heap+java:events=vmstart+vmstop -mp . -m &lt;class&gt; [args...]\n</code></pre> <p> Note: Multiple suboptions that follow an <code>Xdump</code> suboption must be split with a comma (,), for example:</p> <pre><code>java -Xdump:java:events=vmstart,file=/STDERR/ -version\n</code></pre> <p>For more detailed information on these parameters and suboptions, including examples, see Parameters.</p>"},{"location":"xdump/#dump-agents","title":"Dump agents","text":"<p>A dump agent performs diagnostic tasks when triggered. Most dump agents save information on the state of the VM in some form of dump or trace file for later analysis. An exception is the \"tool\" agent, which can be used to trigger external processes when specific events occur.</p> Dump agent Description stack Stack dumps are very basic dumps in which the status and Java stack of the thread is written to stderr. console Console dumps are very basic dumps, in which the status of every Java thread is written to stderr. system System dumps capture the raw process image or address space of an application. tool The tool option allows external processes to be started when an event occurs. java Java dumps are an internally generated and formatted analysis of the VM, giving information that includes the Java threads present, the classes loaded, and heap statistics. heap Heap dumps capture all object instances in the heap, including each object address, type or class name, size, and references to other objects. snap Take a snap of the trace buffers, which contain tracepoint data. ceedump LE CEEDUMP dumps are z/OS\u00ae formatted summary system dumps that show stack traces for each thread that is in the VM process, together with register information and a short dump of storage for each register. jit JIT compiler dumps contain diagnostic data in a binary format. exit Shut down the VM."},{"location":"xdump/#default-dump-agents","title":"Default dump agents","text":"<p>During VM initialization a set of dump agents are added by default. You can override this set of dump agents using <code>-Xdump</code> on the command line. To show the registered dump agents, user the <code>Xdump:what</code> option on the command line. The following sample output shows the default dump agents that are in place on a Linux system:</p> <pre><code>java -Xdump:what\n\nRegistered dump agents\n----------------------\n-Xdump:system:\n    events=gpf+abort+traceassert+corruptcache,\n    file=/home/user/core.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..0,\n    priority=999,\n    request=serial\n----------------------\n-Xdump:system:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/core.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..1,\n    priority=999,\n    request=exclusive+compact+prepwalk\n----------------------\n-Xdump:heap:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/heapdump.%Y%m%d.%H%M%S.%pid.%seq.phd,\n    range=1..4,\n    priority=500,\n    request=exclusive+compact+prepwalk,\n    opts=PHD\n----------------------\n-Xdump:java:\n    events=gpf+user+abort+traceassert+corruptcache,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n-Xdump:java:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..4,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n-Xdump:snap:\n    events=gpf+abort+traceassert+corruptcache,\n    file=/home/user/Snap.%Y%m%d.%H%M%S.%pid.%seq.trc,\n    range=1..0,\n    priority=300,\n    request=serial\n----------------------\n-Xdump:snap:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/Snap.%Y%m%d.%H%M%S.%pid.%seq.trc,\n    range=1..4,\n    priority=300,\n    request=serial\n----------------------\n-Xdump:jit:\n    events=gpf+abort,\n    file=/home/user/jitdump.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..0,\n    priority=200,\n    request=serial\n----------------------\n</code></pre>"},{"location":"xdump/#dump-agent-tokens","title":"Dump agent tokens","text":"<p>You can use tokens to add context to dump file names and directories, and to pass command-line arguments to the tool agent. The tokens available are listed in the following tables:</p> Token Description %Y Year (4 digits) %y Year (2 digits) %m Month (2 digits) %d Day of the month (2 digits) %H Hour (2 digits) %M Minute (2 digits) %S Second (2 digits) %home Java home directory %last Last dump %pid Process ID %seq Dump counter %tick msec counter %uid User name <p>The following tokens are applicable only to z/OS:</p> Token Description %asid Address space ID %job Job name %jobid Job ID %sysname SYSNAME sysparm &amp;DS Dump Section. An incrementing sequence number used for splitting TDUMP files to be less than 2 GB in size. (64-bit only)"},{"location":"xdump/#merging-dump-agents","title":"Merging dump agents","text":"<p>If you configure more than one dump agent, each responds to events according to its configuration. However, the internal structures representing the dump agent configuration might not match the command line because dump agents are merged for efficiency. Two sets of options can be merged as long as none of the agent settings conflict. This means that the list of installed dump agents and their parameters produced by <code>-Xdump:what</code> might not be grouped in the same way as the original <code>-Xdump</code> options that configured them.</p> <p>For example, you can use the following command to specify that a dump agent creates a Java dump file on class unload:</p> <pre><code>java -Xdump:java:events=unload -Xdump:what\n</code></pre> <p>This command does not create a new agent, as can be seen in the results from the <code>-Xdump:what</code> option.</p> <pre><code>...\n----------------------\n-Xdump:java:\n    events=gpf+user+abort+unload+traceassert+corruptcache,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n</code></pre> <p>The configuration is merged with the existing Java dump agent for events gpf, user, abort, traceassert, and corruptcache, because none of the specified options for the new unload agent conflict with those for the existing agent.</p> <p>In the previous example, if one of the parameters for the unload agent is changed so that it conflicts with the existing agent, then it cannot be merged. For example, the following command specifies a different priority, forcing a separate agent to be created:</p> <pre><code>java -Xdump:java:events=unload,priority=100 -Xdump:what\n</code></pre> <p>The results of the <code>-Xdump:what</code> option in the command are as follows.</p> <pre><code>...\n----------------------\n-Xdump:java:\n    events=unload,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=100,\n    request=exclusive+preempt\n----------------------\n-Xdump:java:\n    events=gpf+user+abort+traceassert+corruptcache,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n</code></pre> <p>To merge dump agents, the request, filter, opts, file, and range parameters must match exactly. If you specify multiple agents that filter on the same string, but keep all other parameters the same, the agents are merged. For example:</p> <pre><code>java -Xdump:none -Xdump:java:events=uncaught,filter=java/lang/NullPointerException -Xdump:java:events=unload,filter=java/lang/NullPointerException -Xdump:what\n</code></pre> <p>The results of this command are as follows:</p> <pre><code>Registered dump agents\n----------------------\n-Xdump:java:\n    events=unload+uncaught,\n    filter=java/lang/NullPointerException,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n</code></pre>"},{"location":"xdump/#dump-events","title":"Dump events","text":"<p>Dump agents are triggered by events occurring during operation of the OpenJ9 VM. Some events can be filtered to improve the relevance of the output.</p> <p>The following table shows the events that are available as dump agent triggers:</p> Event Triggered when.... Filters on.... gpf A General Protection Fault (GPF) occurs. Not applicable user The VM receives the SIGQUIT (Linux, macOS\u00ae, AIX\u00ae, z/OS) or SIGBREAK (Windows\u2122) signal from the operating system. Not applicable user2 The VM receives the SIGUSR2 (Linux, AIX, z/OS, and macOS) signal from the operating system. Not applicable abort The VM receives the SIGABRT signal from the operating system. Not applicable vmstart The virtual machine is started. Not applicable vmstop The virtual machine stops. Exit code; for example, <code>filter=#129..#192#-42#255</code> load A class is loaded. Class name; for example, <code>filter=java/lang/String</code> unload A class is unloaded. Not applicable throw An exception is thrown explicitly in Java code. Use 'systhrow' for unexpected VM exceptions. Exception class name; for example, <code>filter=java/lang/OutOfMem*</code> catch An exception is caught. Exception class name; for example, <code>filter=*Memory*</code> uncaught A Java exception is not caught by the application. Exception class name; for example, <code>filter=*MemoryError</code> systhrow A Java exception is about to be thrown by the VM. This is different from the 'throw' event because it is only triggered for error conditions detected internally in the VM. Exception class name; for example, <code>filter=java/lang/OutOfMem*</code>. thrstart A new thread is started. Not applicable blocked A thread becomes blocked. Not applicable thrstop A thread stops. Not applicable fullgc A garbage collection cycle is started. Not applicable slow A thread takes longer than 50 ms to respond to an internal VM request. Time taken; for example, filter=#300ms will trigger when a thread takes longer than 300 ms to respond to an internal VM request. allocation A Java object is allocated with a size matching the given filter specification. Object size; a filter must be supplied. For example, filter=#5m will trigger on objects larger than 5 Mb. Ranges are also supported; for example, filter=#256k..512k will trigger on objects 256 - 512 Kb in size. traceassert An internal error occurs in the VM. Not applicable corruptcache The VM finds that the shared classes cache is corrupt. Not applicable excessivegc An excessive amount of time is being spent in the garbage collector. Not applicable <p> Notes:</p> <ul> <li>The gpf, traceassert, and abort events cannot trigger a heap dump, prepare the heap (request=prepwalk), or compact the heap (request=compact).</li> <li>The Java dump agent behaves differently when triggered by the <code>user</code> and <code>user2</code> events. For more information, see <code>request=&lt;requests&gt;</code>.</li> <li>The <code>user2</code> event is commonly used for taking system dump files with exclusive access without overriding the <code>user</code> event, which is generally left for taking Java dump files for performance investigations. For example:</li> </ul> <pre><code>-Xdump:system:events=user2,request=exclusive+prepwalk\n</code></pre>"},{"location":"xdump/#parameters","title":"Parameters","text":"<p><code>-Xdump:&lt;agent&gt;:&lt;suboptions&gt;</code> descriptions and examples.</p>"},{"location":"xdump/#help","title":"<code>help</code>","text":"<p>To print usage information for a specific dump agent, use <code>-Xdump:&lt;agent&gt;:help</code></p>"},{"location":"xdump/#noneoptions","title":"<code>none:&lt;options&gt;</code>","text":"<p>Use the <code>-Xdump:none</code> option to add and remove dump agents for various VM events, update default dump settings (such as the dump name), and limit the number of dumps that are produced.</p> <p>The option can be used to affect all agents by specifying <code>-Xdump:none:&lt;options&gt;</code> or specific agents by specifying <code>-Xdump:&lt;agent&gt;:none:&lt;suboptions&gt;</code></p> <p>where <code>&lt;suboptions&gt;</code> is one of the following control types:</p> <ul> <li><code>events=&lt;event&gt;</code></li> <li><code>exec=&lt;command&gt;</code></li> <li><code>file=&lt;filename&gt;</code></li> <li><code>filter=&lt;filter&gt;</code></li> <li><code>opts=&lt;options&gt;</code></li> <li><code>priority=&lt;0-999&gt;</code></li> <li><code>range=&lt;ranges&gt;</code></li> <li><code>request=&lt;requests&gt;</code></li> </ul> <p>Explanations for these suboptions are provided elsewhere in this topic.</p> <p>To remove all default dump agents and any preceding dump options, use <code>-Xdump:none</code>. Use this option so that you can subsequently specify a completely new dump configuration.</p> <p>You can also remove dump agents of a particular type. Here are some examples:</p> <p>To turn off all heap dumps (including default agents) but leave Java dumps enabled, use the following option:</p> <pre><code>-Xdump:java+heap:events=vmstop -Xdump:heap:none\n</code></pre> <p>To turn off all dump agents for corruptcache events:</p> <pre><code>-Xdump:none:events=corruptcache\n</code></pre> <p>To turn off just system dumps for corruptcache events:</p> <pre><code>-Xdump:system:none:events=corruptcache\n</code></pre> <p>To turn off all dumps when a <code>java/lang/OutOfMemory</code> error is thrown:</p> <pre><code>-Xdump:none:events=systhrow,filter=java/lang/OutOfMemoryError\n</code></pre> <p>To turn off just system dumps when a <code>java/lang/OutOfMemory</code> error is thrown:</p> <pre><code>-Xdump:system:none:events=systhrow,filter=java/lang/OutOfMemoryError\n</code></pre> <p>If you remove all dump agents by using <code>-Xdump:none</code> with no further <code>-Xdump</code> options, the VM still provides these basic diagnostic outputs:</p> <ul> <li>If a user signal (kill -QUIT) is sent to the VM, a brief listing of the Java threads including their stacks, status, and monitor information is written to stderr.</li> <li>If a crash occurs, information about the location of the crash, VM options, and native and Java stack traces are written to stderr. A system dump file is also written to the user's home directory.</li> </ul> <p> Note: Removing dump agents and specifying a new dump configuration can require a long set of command-line options. To reuse command-line options, save the new dump configuration in a file and use the <code>-Xoptionsfile</code> option. For more information, see -Xoptionsfile.</p>"},{"location":"xdump/#defaults","title":"<code>defaults</code>","text":"<p>Each dump type has default options. To view the default options for a particular dump type, use <code>-Xdump:&lt;agent&gt;:defaults</code>.</p> <p>You can change the default options at run time. For example, you can direct Java dump files into a separate directory for each process, and guarantee unique files by adding a sequence number to the file name using:</p> <pre><code>-Xdump:java:defaults:file=dumps/%pid/javacore-%seq.txt\n</code></pre> <p>Or, for example, on z/OS, you can add the jobname to the Java dump file name using:</p> <pre><code>-Xdump:java:defaults:file=javacore.%job.%H%M%S.txt\n</code></pre> <p>This option does not add a Java dump agent; it updates the default settings for Java dump agents. Further Java dump agents will then create dump files using this specification for filenames, unless overridden.</p> <p> Note: Changing the defaults for a dump type will also affect the default agents for that dump type added by the VM during initialization. For example, if you change the default file name for Java dump files, that will change the file name used by the default Java dump agents. However, changing the default range option will not change the range used by the default Java dump agents, because those agents override the range option with specific values.</p>"},{"location":"xdump/#eventsevent","title":"<code>events=&lt;event&gt;</code>","text":"<p>To trigger a dump as a result of an event, use the <code>-Xdump:&lt;agent&gt;:events=&lt;event&gt;</code> suboption. For a list of possible events, see Dump events.</p> <p>For example, the following command instructs the VM to create a dump agent at startup that produces a Heap dump whenever the vmstop event happens:</p> <pre><code>-Xdump:heap:events=vmstop\n</code></pre>"},{"location":"xdump/#execcommand","title":"<code>exec=&lt;command&gt;</code>","text":"<p>The exec suboption is used by the tool dump agent to specify an external application to start. You can set a specific command to run for a particular dump agent with the following command:</p> <pre><code>-Xdump:&lt;agent&gt;:exec=&lt;command&gt;\n</code></pre>"},{"location":"xdump/#filefilename","title":"<code>file=&lt;filename&gt;</code>","text":"<p>The file suboption specifies where the diagnostics information is written for the specified dump type. The syntax is <code>-Xdump:&lt;agent&gt;:file=&lt;filename&gt;</code>.</p> <p>For example, to create a Heap dump called <code>my.dmp</code> when a vmstop event is received, use:</p> <pre><code>java -Xdump:heap:events=vmstop,file=my.dmp\n</code></pre> <p>When producing system dump files on z/OS platforms, use the <code>dsn</code> option instead of the <code>file</code> option. For example:</p> <pre><code>java -Xdump:system:events=vmstop,dsn=%uid.MYDUMP\n</code></pre>"},{"location":"xdump/#writing-to-stdoutstderr","title":"Writing to <code>STDOUT</code>/<code>STDERR</code>","text":"<p>Add one of the following options to write a Java dump file to STDOUT or STDERR respectively:</p> <pre><code>-Xdump:java:file=/STDOUT/\n-Xdump:java:file=/STDERR/\n</code></pre> <ul> <li>The keywords <code>/STDOUT/</code> and <code>/STDERR/</code> are not case sensitive; <code>/stdout/</code> and <code>/stderr/</code> are equivalent.</li> <li>By common convention, you can use a dash (<code>-</code>) to refer to STDOUT:<pre><code>-Xdump:java:file=-\n</code></pre> </li> </ul>"},{"location":"xdump/#tokens","title":"Tokens","text":"<p>You can use tokens to add context to dump file names. For a list of tokens, see Dump agent tokens.</p>"},{"location":"xdump/#file-location","title":"File location","text":"<p>The location for the dump file is selected from the following options, in this order:</p> <ol> <li>The location specified by the <code>-Xdump:&lt;agent&gt;:file</code> suboption on the command line (if that location includes a path). This location applies to the specified dump agent type only.</li> <li>The location specified by the <code>-Xdump:directory</code> option on the command line. This location applies to all dump agent types.</li> <li> <p>The location specified by the relevant environment variable:</p> Dump agent type z/OS operating systems Other operating systems Java dumps <code>_CEE_DMPTARG</code> <code>IBM_JAVACOREDIR</code> Heap dumps <code>_CEE_DMPTARG</code> <code>IBM_HEAPDUMPDIR</code> System dumps <code>JAVA_DUMP_TDUMP_PATTERN</code> <code>IBM_COREDIR</code> JIT dumps <code>_CEE_DMPTARG</code> <code>IBM_COREDIR</code> Snap traces <code>_CEE_DMPTARG</code> <code>IBM_COREDIR</code> </li> <li> <p>The current working directory of the OpenJ9 VM process.</p> </li> </ol> <p>If the directory does not exist, it is created.</p> <p>If the dump file cannot be written to the selected location, the VM reverts to using the following locations, in this order:</p> <ol> <li>On Windows platforms only, the system default location is <code>C:\\WINDOWS</code>.</li> <li>The location specified by the <code>TMPDIR</code> environment variable.</li> <li>The <code>C:\\Temp</code> on Windows operating systems, or the <code>/tmp</code> directory on other operating systems.</li> </ol> <p>This VM action does not apply to system dumps on z/OS operating systems that use the <code>dsn</code> option. You can prevent the VM reverting to different dump locations by using the <code>-Xdump:nofailover</code> option.</p>"},{"location":"xdump/#filterfilter","title":"<code>filter=&lt;filter&gt;</code>","text":"<p>Some VM events occur thousands of times during the lifetime of an application. Dump agents can use filters and ranges to avoid producing an excessive number of dump files. The following syntax must be used:</p> <pre><code>-Xdump:&lt;agent&gt;:filter=&lt;filter&gt;\n</code></pre>"},{"location":"xdump/#wildcards","title":"Wildcards","text":"<p>You can use a wildcard in your exception event filter by placing an asterisk only at the beginning or end of the filter. The following command does not work because the second asterisk is not at the end:</p> <pre><code>-Xdump:java:events=throw,filter=*InvalidArgumentException#*.myVirtualMethod\n</code></pre> <p>To fix the problem, change this filter to the following string:</p> <pre><code>-Xdump:java:events=throw,filter=*InvalidArgumentException#MyApplication.*\n</code></pre>"},{"location":"xdump/#class-loading-and-exception-events","title":"Class loading and exception events","text":"<p>You can filter class loading (load) and exception (throw, catch, uncaught, systhrow) events by the name of the class that is being loaded, thrown or caught. For example:</p> <pre><code>-Xdump:java:events=load,filter=java/lang/String\n-Xdump:java:events=throw,filter=java/lang/ArrayStoreException\n-Xdump:java:events=catch,filter=java/lang/NullPointerException\n</code></pre> <p>In addition, you can filter throw, uncaught, and systhrow exception events by the name of the method that throws the exception. The name of the parent class must include the full package name, using the forward slash (/) as a separator. Use a dot (.) to separate the method name from the class name. You can use an asterisk (*) as a wildcard character, to include all methods (optional portions are shown in brackets). For example:</p> <pre><code>-Xdump:java:events=throw,filter=ExceptionClassName[#com/ibm/ThrowingClassName.throwingMethodName[#stackFrameOffset]]\n</code></pre> <p>For example, to trigger a Java dump when method <code>MyApplication.myMethod()</code> throws a <code>NullPointerException</code> exception, use the following syntax:</p> <pre><code>-Xdump:java:events=throw,filter=java/lang/NullPointerException#com/ibm/MyApplication.myMethod\n</code></pre> <p>The stack frame offset allows you to filter on the name of a method that calls the throwing method. This option is useful if the exception is being thrown from a general purpose or utility class. For example, to trigger a Java dump when a method called by <code>MyApplication.main()</code> throws a <code>NullPointerException</code>, use the following syntax:</p> <pre><code>-Xdump:java:events=throw,filter=java/lang/NullPointerException#com/ibm/MyApplication.main#1\n</code></pre> <p>The default value of the stack frame offset is zero.</p> <p>You can filter the catch exception events by Java method name (optional portions are shown in brackets). For example:</p> <pre><code>-Xdump:java:events=catch,filter=ExceptionClassName[#com/ibm/CatchingClassName.catchingMethodName]\n</code></pre> <p>You can filter throw, uncaught, and systhrowexception events by Java method name (optional portions are shown in brackets):</p> <pre><code>-Xdump:java:events=throw,filter=ExceptionClassName[#com/ibm/ThrowingClassName.throwingMethodName[#stackFrameOffset]]\n</code></pre> <p>You can filter the catch exception events by Java method name (optional portions are shown in brackets):</p> <pre><code>-Xdump:java:events=catch,filter=ExceptionClassName[#com/ibm/CatchingClassName.catchingMethodName]\n</code></pre> <p> Note: The filters apply to the stacktrace and fire every time the same exception is rethrown, which might result in multiple Java core files.</p>"},{"location":"xdump/#vmstop-event","title":"vmstop event","text":"<p>You can filter the VM shut down event (vmstop) by using one or more exit codes:</p> <pre><code>-Xdump:java:events=vmstop,filter=#129..192#-42#255\n</code></pre>"},{"location":"xdump/#slow-event","title":"slow event","text":"<p>You can filter the slow event to change the time threshold from the default of 50 ms:</p> <pre><code>-Xdump:java:events=slow,filter=#300ms\n</code></pre>"},{"location":"xdump/#allocation-event","title":"allocation event","text":"<p>You must filter the allocation event to specify the size of objects that cause a trigger. You can set the filter size from zero up to the maximum value of a 32-bit pointer on 32-bit platforms, or the maximum value of a 64-bit pointer on 64-bit platforms. Setting the lower filter value to zero triggers a dump on all allocations.</p> <p>For example, to trigger dumps on allocations greater than 5 Mb in size, use:</p> <pre><code>-Xdump:stack:events=allocation,filter=#5m\n</code></pre> <p>To trigger dumps on allocations between 256 Kb and 512 Kb in size, use:</p> <pre><code>-Xdump:stack:events=allocation,filter=#256k..512k\n</code></pre>"},{"location":"xdump/#other-events","title":"Other events","text":"<p>If you apply a filter to an event that does not support filtering, the filter is ignored.</p>"},{"location":"xdump/#msg_filterfilter","title":"<code>msg_filter=&lt;filter&gt;</code>","text":"<p>You can use the msg_filter suboption to filter on text strings within an exception message, allowing you to reduce the number of dump files produced. This option is supported only for the following events: throw, catch, systhrow, and uncaught.</p> <p>Use the following syntax to include message filtering in your dump output:</p> <pre><code>-Xdump:&lt;agent&gt;:events=&lt;event&gt;,msg_filter=&lt;filter&gt;`\n</code></pre> <p>where <code>&lt;filter&gt;</code> is a text string from the exceptions that you want to include in the dump file. This suboption supports asterisks as wild cards.</p> <p>The following example filters <code>java/lang/VerifyError</code> exceptions that contain the text string class format:</p> <pre><code>-Xdump:java:events=throw,filter=java/lang/VerifyError,msg_filter=*class format*\n</code></pre>"},{"location":"xdump/#optsoptions","title":"<code>opts=&lt;options&gt;</code>","text":"<p>The full syntax is <code>-Xdump:&lt;agent&gt;:opts=&lt;options&gt;</code>.</p> <p>The heap dump agent uses this suboption to specify the type of file to produce. On z/OS, the system dump agent uses this suboption to specify the type of dump to produce.</p>"},{"location":"xdump/#heap-dumps","title":"Heap dumps","text":"<p>You can specify a PHD heap dump file (PHD), a classic text heap dump file (CLASSIC), or both. The default is a PHD file. For example:</p> <pre><code>-Xdump:heap:opts=PHD  \n-Xdump:heap:opts=CLASSIC\n-Xdump:heap:opts=PHD+CLASSIC\n</code></pre>"},{"location":"xdump/#zos-system-dumps","title":"z/OS system dumps","text":"<p>You can specify a system transaction dump (IEATDUMP), an LE dump (CEEDUMP), or both. The default is an IEADUMP file. For example:</p> <pre><code>-Xdump:system:opts=IEATDUMP\n-Xdump:system:opts=CEEDUMP\n-Xdump:system:opts=IEATDUMP+CEEDUMP\n</code></pre> <p>The ceedump agent is the preferred way to specify LE dumps, for example:</p> <pre><code>-Xdump:ceedump:events=gpf\n</code></pre>"},{"location":"xdump/#tool-dumps","title":"Tool dumps","text":"<p>The tool dump agent supports two suboptions that can be specified using the <code>opts</code> subption. You can run the external process asynchronously with opts=ASYNC. You can also specify a delay in milliseconds that produces a pause after starting the command. These two options can be used independently or together. The following examples show different options for starting a new process that runs <code>myProgram</code>:</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram\n</code></pre> <p>Without the <code>opts</code> suboption, the tool dump agent starts the process, and waits for the process to end before continuing.</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram,opts=ASYNC\n</code></pre> <p>When <code>opts=ASYNC</code> is specified, the tool dump agent starts the process, and continues without waiting for the new process to end.</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram,opts=WAIT1000\n</code></pre> <p>This option starts the process, waits for the process to end, and then waits a further 1 second (1000 milliseconds) before continuing.</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram,opts=ASYNC+WAIT10000\n</code></pre> <p>Finally, the last example starts the process and waits for 10 seconds before continuing, whether the process is still running or not. This last form is useful if you are starting a process that does not end, but requires time to initialize properly.</p>"},{"location":"xdump/#priority0-999","title":"<code>priority=&lt;0-999&gt;</code>","text":"<p>One event can generate multiple dump files. The agents that produce each dump file run sequentially and their order is determined by the priority keyword set for each agent. The full syntax for this command is <code>-Xdump:&lt;agent&gt;:priority=&lt;0-999&gt;</code>.</p> <p>Examination of the output from <code>-Xdump:what</code> shows that a gpf event produces a snap trace, a Java dump file, and a system dump file. In this example, the system dump runs first, with priority 999. The snap dump runs second, with priority 500. The Java dump runs last, with priority 10:</p> <pre><code>-Xdump:heap:events=vmstop,priority=123\n</code></pre> <p>The maximum value allowed for priority is 999. Higher priority dump agents are started first.</p> <p>If you do not specifically set a priority, default values are taken based on the dump type. The default priority and the other default values for a particular type of dump, can be displayed by using <code>-Xdump:&lt;type&gt;:defaults</code>. For example:</p> <pre><code>java -Xdump:heap:defaults -version\n</code></pre> <p>Default <code>-Xdump:heap</code> settings:</p> <pre><code>  events=gpf+user\n  filter=\n  file=/home/user/heapdump.%Y%m%d.%H%M%S.%pid.phd\n  range=1..0\n  priority=500\n  request=exclusive+compact+prepwalk\n  opts=PHD\n</code></pre>"},{"location":"xdump/#rangeranges","title":"<code>range=&lt;ranges&gt;</code>","text":"<p>You can start and stop dump agents on a particular occurrence of a VM event by using the <code>range</code> suboption: <code>-Xdump:&lt;agent&gt;:range=&lt;ranges&gt;</code></p> <p>For example:</p> <pre><code>-Xdump:java:events=fullgc,range=100..200\n</code></pre> <p> Note: range=1..0 against an event means \"on every occurrence\".</p> <p>The VM default dump agents have the range suboption set to 1..0 for all events except systhrow. Most systhrow events with <code>filter=java/lang/OutOfMemoryError</code> have the range suboption set to 1..4, which limits the number of dump files produced on <code>OutOfMemory</code> conditions to a maximum of 4. For more information, see Default dump agents.</p> <p>If you add a new dump agent and do not specify the range, a default of 1..0 is used.</p>"},{"location":"xdump/#requestrequests","title":"<code>request=&lt;requests&gt;</code>","text":"<p>Use the request suboption to ask the VM to prepare the state before starting the dump agent: <code>-Xdump:&lt;agent&gt;:request=&lt;requests&gt;</code></p> <p>The available suboptions are listed in the following table:</p> suboption value Description exclusive Request exclusive access to the VM. compact Run garbage collection. This option removes all unreachable objects from the heap before the dump file is generated. prepwalk Prepare the heap for walking. You must also specify exclusive when you use this option. serial Suspend other dumps until this dump is finished. preempt Applies to the Java dump agent and controls whether native threads in the process are forcibly pre-empted in order to collect stack traces. If this option is not specified, only Java stack traces are collected in the Java dump. <p>You can specify more than one request option by using +. For example:</p> <pre><code>-Xdump:heap:request=exclusive+compact+prepwalk\n</code></pre> <p>The VM exclusive access mechanism allows a VM thread to halt the activity of other VM threads in a controlled way by using internal VM locks. When the <code>request=exclusive</code> option is specified for a dump agent, the VM thread that is producing the dump waits for threads that are running Java code to halt, and for garbage collection operations to complete, before the dump file is written. This process helps ensure that the dump has consistent data. When the dump is complete, the mechanism allows the other threads to resume.</p> <p>By default, only system dumps for <code>OutOfMemoryError</code> exceptions request exclusive access. Other system dump events typically result from a crash. In these cases, exclusive access is not requested because acquiring locks during a crash can be problematic.</p> <p>If system dumps are requested by using the <code>com.ibm.jvm.Dump.SystemDump()</code> API, the default system dump agent settings are used, and exclusive access is not requested. However, if you intend to use the system dump file for Java heap memory analysis, use the following option to request exclusive access when the dump is taken:</p> <pre><code>-Xdump:system:defaults:request=exclusive+compact+prepwalk\n</code></pre> <p>These settings avoid capturing a dump file with in-flight data during garbage collection. As an alternative, you can use the <code>com.ibm.jvm.Dump.triggerDump()</code> API and specify <code>request=exclusive+compact+prepwalk</code> on the API call.</p> <p>For more information about the <code>com.ibm.jvm.Dump API</code>, see the API reference information.</p> <p>The default setting of the <code>request</code> suboption for Java dump files is <code>request=exclusive+preempt</code>. To change the settings so that Java dump files are produced without pre-empting threads to collect native stack traces, use the following option:</p> <pre><code>-Xdump:java:request=exclusive\n</code></pre> <p>The Java dump agent ignores the <code>request=exclusive</code> setting if a <code>user</code> event occurs and another event already has exclusive access. In this scenario, the Java dump agent shares the access instead. This behavior is useful because it allows you to obtain a Java dump file during a deadlock situation, when exclusive access is not released. However, the resulting Java dump file, even in other situations, might omit thread stacks and contain inconsistent thread information, as indicated by the following line in the file:</p> <pre><code>1TIPREPINFO    Exclusive VM access not taken: data may not be consistent across javacore sections\n</code></pre> <p>On operating systems other than Windows, you can enforce exclusive access and obtain a complete dump file by specifying that the <code>user2</code> event triggers the Java dump agent instead of the <code>user</code> event. For example:</p> <pre><code>-Xdump:java:events=user2,request=exclusive+preempt\n</code></pre> <p>When a <code>user2</code> event occurs, for example, when you enter <code>kill -USR2 &lt;pid&gt;</code> on the command line, the Java dump agent accepts the <code>request=exclusive</code> setting and waits for exclusive access before creating the Java dump file.</p> <p>For more information about events, see Dump events.</p> <p>In general, the default request options are sufficient.</p>"},{"location":"xdump/#dump-output","title":"Dump output","text":"<p>Dump output is written to different files, depending on the type of dump and the platform. File names include a time stamp.</p> Dump type File name  (AIX, Linux, macOS, Windows) File name (z/OS) System dump core.%Y%m%d.%H%M%S.%pid.dmp %uid.JVM.TDUMP.%job.D%Y%m%d.T%H%M%S (31-bit),  %uid.JVM.%job.D%y%m%d.T%H%M%S.X&amp;DS (64-bit) See Note Java dump javacore.%Y%m%d.%H%M%S.%pid.%seq.txt javacore.%Y%m%d.%H%M%S.%pid.%seq.txt Heap dump heapdump.%Y%m%d.%H%M%S.%pid.phd heapdump.%Y%m%d.T%H%M%S.phd JIT dump jitdump%Y%m%d.%H%M%S.%pid.%seq.dmp jitdump%Y%m%d.%H%M%S.%pid.%seq.dmp LE CEEDUMP - CEEDUMP.%Y%m%d.%H%M%S.%pid See Note <p>The tokens used in this table, for example <code>%Y</code>, are described in Dump agent tokens.</p> <p> Note: On z/OS, the system dump file name can be set with the <code>JAVA_DUMP_TDUMP_PATTERN</code> environment variable. The CEEDUMP, which is not produced by default, is stored in the directory specified by <code>_CEE_DMPTARG</code> or the current directory if <code>_CEE_DMPTARG</code> is not specified.</p>"},{"location":"xdump/#system-dumps-on-linux","title":"System dumps on Linux","text":"<p>Linux does not provide an operating system API for generating a system dump from a running process. The VM produces system dumps on Linux by using the fork() API to start an identical process to the parent VM process. The VM then generates a SIGSEGV signal in the child process. The SIGSEGV signal causes Linux to create a system dump for the child process. The parent VM processes and renames the system dump, as required, by the <code>-Xdump</code> options, and might add additional data into the dump file.</p> <p>The system dump file for the child process contains an exact copy of the memory areas used in the parent. The dump viewer can obtain information about the Java threads, classes, and heap from the system dump. However, the dump viewer, and other system dump debuggers show only the single native thread that was running in the child process.</p> <p>You can use the Linux <code>kernel.core_pattern</code> setting to specify the name and path for system dumps. The VM dump agents override the Linux system dump name and path by renaming the dump as specified in the <code>-Xdump</code> options. If the <code>kernel.core_pattern</code> setting specifies a different file system to the <code>-Xdump</code> options, the VM dump agents might be unable to change the file path. In this case the VM renames the dump file, but leaves the file path unchanged. You can find the dump file name and location in the <code>JVMDUMP010I</code> message.</p> <p> Note: If you use the <code>%t</code> specifier in the <code>kernel.core_pattern</code> setting, the VM does not rename the dump. The VM cannot determine the exact time that Linux generated the core file, and therefore cannot be certain which Linux dump file is the correct one to rename.</p>"},{"location":"xdump/#piped-system-dumps","title":"Piped system dumps","text":"<p>The Linux option, <code>kernel.core_pattern=|&lt;program&gt;</code>, might be set to pipe system dumps to a system dump processing program (specified by <code>&lt;program&gt;</code>). If such a program is specified and the VM cannot find the system dump, you will see the following messages:</p> <ul> <li><code>JVMPORT030W</code></li> <li><code>JVMDUMP012E</code></li> <li><code>JVMPORT049I</code></li> </ul> <p>These messages do not necessarily indicate a problem with the system dump. Review the documentation for the program listed in the <code>kernel.core_pattern</code> property to find the location of the system dump and how to configure the program to ensure that the dump file is not truncated.</p> <p>You can find the current setting of <code>kernel.core_pattern</code> by running one of the following commands. For example,</p> <pre><code>$ cat /proc/sys/kernel/core_pattern\n|/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %h\n</code></pre> <pre><code>$ sysctl kernel.core_pattern\nkernel.core_pattern = |/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %h\n</code></pre> <p>The <code>kernel.core_pattern</code> setting is also available in a Java dump. For example:</p> <pre><code>2CISYSINFO     /proc/sys/kernel/core_pattern = |/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %h\n</code></pre> <p>Here are some of the most common system dump processing programs and their default system dump locations:</p> <ul> <li> <p>systemd-coredump:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/usr/lib/systemd/systemd-coredump</code></li> <li>By default, dump files go to <code>/var/lib/systemd/coredump/</code>.</li> <li>Versions before v251 truncate 64-bit Java dumps at 2 GB. To avoid this, consider updating the configuration file, <code>/etc/systemd/coredump.conf</code> to increase the values of the <code>ProcessSizeMax</code> and <code>ExternalSizeMax</code> properties and load the updated configuration by running the <code>systemctl daemon-reload</code> command. For v251 and later versions, similar changes are needed if the dump files are greater than 32 GB.</li> </ul> </li> <li> <p>apport:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/usr/share/apport/apport</code></li> <li>By default, dump files go to <code>/var/crash/</code> or <code>/var/lib/apport/coredump/</code>.</li> <li>Default settings do not truncate the dump files.</li> </ul> </li> <li> <p>abrt-hook-ccpp:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/usr/libexec/abrt-hook-ccpp</code></li> <li>By default, dump files go to <code>/var/spool/abrt</code>.</li> <li>Default settings might truncate the dump files. Consider updating <code>/etc/abrt/abrt.conf</code> to set <code>MaxCrashReportsSize=0</code> and restart <code>abrtd</code>.</li> </ul> </li> <li> <p>Dynatrace rdp:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/opt/dynatrace/oneagent/agent/rdp</code></li> <li>The program passes the dump files to the underlying system dump processing program specified in <code>/opt/dynatrace/oneagent/agent/conf/original_core_pattern</code>.</li> </ul> </li> </ul> <p>In container environments, such as OpenShift, piped system dump files are stored in the worker node rather than in the container. Here is one example method for retrieving a dump file that was piped to the <code>systemd-coredump</code> program:</p> <ol> <li>To access the system dump files, you must have access to the cluster as a user that has the <code>cluster-admin</code> role.</li> <li> <p>Find the worker node of the pod. For example:</p> <p><code>oc get pod --namespace MyNamespace --output \"jsonpath={.spec.nodeName}{'\\n'}\" MyPodname</code></p> <p>Where, MyNamespace and MyPodname are names of your namespace and pod.</p> </li> <li> <p>Start a debug pod on the worker node. For example:</p> <p><code>oc debug node/MyNode -t</code></p> <p>Where, MyNode is the worker node retrieved in step 2.</p> </li> <li> <p>List the available system dump files. For example:</p> </li> </ol> <pre><code>#chroot /host coredumpctl\n\nTIME                             PID        UID   GID SIG COREFILE  EXE\n\nWed 2022-08-03 18:52:29 UTC  2923161 1000650000     0  11 present   /opt/java/semeru/jre/bin/java\n</code></pre> <ol> <li>Find the line for the system dump that you want to download, copy the PID number from that row, and then pass it to the <code>info</code> sub-command to search for the dump location. For example:</li> </ol> <pre><code># chroot /host coredumpctl info 2923161 | grep Storage:\nStorage: /var/lib/systemd/coredump/core.kernel-command-.1000650000.08b9e28f46b348f3aabdffc6896838e0.2923161.1659552745000000.lz4\n</code></pre> <ol> <li> <p>Run a command to print output on a loop so that the debug pod doesn't timeout:</p> <p><code>while true; do echo 'Sleeping'; sleep 8; done</code></p> </li> <li> <p>Open a new terminal and then find the debug pod and namespace. For example:</p> </li> </ol> <pre><code>$ oc get pods --field-selector=status.phase==Running --all-namespaces | grep debug\nopenshift-debug-node-pwcn42r47f       worker3-debug       1/1     Running            0                  3m38s\n</code></pre> <ol> <li>Use the namespace (first column) and pod name (second column) that you retrieved in step 7 to download the system dump file from the <code>Storage</code> location that was listed in the output of step 5 on the worker node. Ensure that you prefix the <code>Storage</code> location with <code>/host/</code>. For example:</li> </ol> <pre><code>oc cp --namespace openshift-debug-node-pwcn42r47f worker3-debug:/host/var/lib/systemd/coredump/core.kernel-command-.1000650000.08b9e28f46b348f3aabdffc6896838e0.2923161.1659552745000000.lz4 core.dmp.lz4\n</code></pre> <p>This example stores the system dump locally in a compressed file, <code>core.dmp.lz4</code>.</p> <ol> <li>After the download completes, in the first terminal window, exit the loop by pressing <code>Ctrl+C</code> and end the debug pod by typing <code>exit</code>.</li> </ol>"},{"location":"xdump/#see-also","title":"See also","text":"<ul> <li><code>-Xtrace</code></li> <li><code>-Xdisablejavadump</code></li> <li><code>-XX[+|-]HandleSIGUSR2</code></li> </ul>"},{"location":"xenableexcessivegc/","title":"-Xenableexcessivegc","text":""},{"location":"xenableexcessivegc/#xenableexcessivegc-xdisableexcessivegc","title":"\u2011Xenableexcessivegc / \u2011Xdisableexcessivegc","text":"<p>Enables or disables the throwing of an <code>OutOfMemory</code> exception if excessive time is spent in the GC.</p> <p>If excessive time is spent in the GC, the option returns <code>null</code> for an allocate request and thus causes an <code>OutOfMemory</code> exception to be thrown.</p> <p> Note: The <code>OutOfMemory</code> exception is thrown only when the heap has been fully expanded and the percentage of application run time that is spent in garbage collection is at least 95%. This percentage is the default value that triggers an excessive GC event. You can control this value with the <code>-Xgc:excessiveGCratio</code> option.</p>"},{"location":"xenableexcessivegc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xenableexcessivegc</code> Enable exception yes <code>-Xdisableexcessivegc</code> Disable exception <p>These options can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xenableexplicitgc/","title":"-Xenableexplicitgc","text":""},{"location":"xenableexplicitgc/#xenableexplicitgc-xdisableexplicitgc","title":"\u2011Xenableexplicitgc / \u2011Xdisableexplicitgc","text":"<p>Enables and disables garbage collection (GC) when calls are made to <code>System.gc()</code>.</p>"},{"location":"xenableexplicitgc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xenableexplicitgc</code> Enable explicit GC calls yes <code>-Xdisableexplicitgc</code> Disable explicit GC calls"},{"location":"xenableexplicitgc/#explanation","title":"Explanation","text":"<p>Although it is possible to programmatically trigger a global GC by calling <code>System.gc()</code>, performance can be adversely affected by halting the application before it is really necessary. Use this option to prevent the VM responding to application requests for a GC cycle.</p> <p>The default for all Eclipse OpenJ9\u2122 GC policies is <code>-Xenableexplicitgc</code> except for <code>-Xgcpolicy:nogc</code>, where the default is <code>-Xdisableexplicitgc</code>.</p> <p>These options can be used with all OpenJ9 GC policies.</p>"},{"location":"xenablestringconstantgc/","title":"-Xenablestringconstantgc","text":""},{"location":"xenablestringconstantgc/#xenablestringconstantgc-xdisablestringconstantgc","title":"\u2011Xenablestringconstantgc / \u2011Xdisablestringconstantgc","text":"<p>Enables or disables the collection of strings from the string intern table.</p>"},{"location":"xenablestringconstantgc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xenablestringconstantgc</code> Enable collection yes <code>-Xdisablestringconstantgc</code> Disable collection <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>).</p>"},{"location":"xfastresolve/","title":"-Xfastresolve","text":""},{"location":"xfastresolve/#-xfastresolve","title":"-Xfastresolve","text":"<p>Tune performance by improving the resolution time for classes when the field count exceeds the specified threshold.</p> <p>If profiling tools show significant costs in field resolution, change the threshold until the costs are reduced. If you enable this option, additional memory is used when the threshold is exceeded.</p> <p> Note: The use of this option is deprecated.</p>"},{"location":"xfastresolve/#syntax","title":"Syntax","text":"<pre><code>    -Xfastresolve&lt;n&gt;\n</code></pre> where <code>&lt;n&gt;</code> is the required threshold."},{"location":"xfuture/","title":"-Xfuture","text":""},{"location":"xfuture/#-xfuture","title":"-Xfuture","text":"<p>As described in the Oracle \"Non-Standard Options\" documentation, this HotSpot option turns on strict class-file format checks. For compatibility, this option is also supported by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xfuture/#syntax","title":"Syntax","text":"<pre><code>    -Xfuture\n</code></pre>"},{"location":"xfuture/#explanation","title":"Explanation","text":"<p>Oracle recommend that you use this flag when you are developing new code because stricter checks will become the default in future releases.</p> <p> Note: You cannot use this setting in conjunction with -XX:+ClassRelationshipVerifier.</p>"},{"location":"xfuture/#default-behavior","title":"Default behavior","text":"<p>By default, strict format checks are disabled.</p>"},{"location":"xgc/","title":"-Xgc","text":""},{"location":"xgc/#-xgc","title":"-Xgc","text":"<p>Options that change the behavior of the garbage collector.</p>"},{"location":"xgc/#syntax","title":"Syntax","text":"<pre><code>    -Xgc:&lt;parameter&gt;\n</code></pre>"},{"location":"xgc/#parameters","title":"Parameters","text":"Parameter Effect <code>breadthFirstScanOrdering</code> Sets the scan mode to breadth first. <code>classUnloadingKickoffThreshold</code> Sets a threshold to start an early concurrent global garbage collection (GC) cycle due to recent, heavy class loading activity <code>classUnloadingThreshold</code> Sets a threshold to trigger a class unloading operation in a global GC cycle <code>concurrentScavenge</code> Enables a GC mode with less pause times. <code>dnssExpectedTimeRatioMaximum</code> Sets the maximum percentage of time to spend on local GC pauses <code>dnssExpectedTimeRatioMinimum</code> Sets the minimum percentage of time to spend on local GC pauses <code>dynamicBreadthFirstScanOrdering</code> Sets scan mode to dynamic breadth first. <code>excessiveGCratio</code> Sets a boundary value beyond which GC is deemed to be excessive. <code>hierarchicalScanOrdering</code> Sets scan mode to hierarchical. <code>minContractPercent</code> Sets the minimum percentage of the heap that can be contracted at any given time. <code>maxContractPercent</code> Sets the maximum percentage of the heap that can be contracted at any given time. <code>noConcurrentScavenge</code> Disables concurrent scavenge. <code>noSynchronousGCOnOOM</code> Prevents an application stopping to allow GC activity. <code>overrideHiresTimerCheck</code> Overrides GC operating system checks for timer resolution. <code>preferredHeapBase</code> Sets a memory range for the Java\u2122 heap. (AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122 only) <code>scvNoAdaptiveTenure</code> Turns off the adaptive tenure age in the generational concurrent GC policy. <code>scvTenureAge</code> Sets the initial scavenger tenure age in the generational concurrent GC policy. <code>stdGlobalCompactToSatisfyAllocate</code> Prevents the GC from performing a compaction unless absolutely required. <code>synchronousGCOnOOM</code> Stops an application to allow GC activity. <code>targetPausetime</code> Sets the target GC pause time for the <code>metronome</code> and <code>balanced</code> GC policies. <code>targetUtilization</code> Sets application utilization for the <code>metronome</code> GC policy. <code>tlhIncrementSize</code> Sets the size of the thread local heap (TLH) increment. <code>tlhInitialSize</code> Sets the initial size of the thread local heap. <code>tlhMaximumSize</code> Sets the maximum size of the thread local heap. <code>verboseFormat</code> Sets the verbose GC format. <code>verbosegcCycleTime</code> Sets the criteria for verbose GC logging."},{"location":"xgc/#breadthfirstscanordering","title":"<code>breadthFirstScanOrdering</code>","text":"<pre><code>     -Xgc:breadthFirstScanOrdering\n</code></pre> This option sets the scan mode for GC operations that evacuate objects in the heap (scavenge operations (<code>gencon</code>) and copy forward operations (<code>balanced</code>)) to breadth first mode. The scan mode reflects the method for traversing the object graph and is also known as Cheney's algorithm."},{"location":"xgc/#classunloadingkickoffthreshold","title":"<code>classUnloadingKickoffThreshold</code>","text":"<pre><code>     -Xgc:classUnloadingKickoffThreshold=&lt;value&gt;\n</code></pre> Where <code>&lt;value&gt;</code> is equal to the number of class loaders plus the number of anonymous classes that are loaded since the previous class unloading operation. This option sets a threshold that is used to start an early concurrent global GC cycle due to recent class loading activity. The default value is 80000. This option is applicable to the following GC policies: <code>gencon</code> and <code>optavgpause</code>."},{"location":"xgc/#classunloadingthreshold","title":"<code>classUnloadingThreshold</code>","text":"<pre><code>     -Xgc:classUnloadingThreshold=&lt;value&gt;\n</code></pre> Where <code>&lt;value&gt;</code> is equal to the number of class loaders plus the number of anonymous classes that are loaded since the previous class unloading operation. This option sets a threshold that is used to trigger an optional GC class unloading operation in a global GC cycle, irrespective of how the global GC cycle is triggered. The default value is 6. This option is applicable to the following GC policies: <code>gencon</code>, <code>optavgpause</code>, and <code>optthruput</code>."},{"location":"xgc/#concurrentscavenge","title":"<code>concurrentScavenge</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xgc:concurrentScavenge\n</code></pre> <p>This option supports pause-less garbage collection mode when you use the Generational Concurrent (<code>gencon</code>) garbage collection policy (the default policy). This option cannot be used with any other GC policies.</p> <p>If you set this option, the VM attempts to reduce GC pause times for response-time sensitive, large-heap applications. This mode can be enabled with hardware-based support (Linux on IBM Z\u00ae and z/OS\u00ae) and software-based support (64-bit: Linux on (x86-64, POWER\u00ae, IBM Z\u00ae) AIX\u00ae, macOS\u00ae, and z/OS).</p> <p> Note: Linux on IBM Z and z/OS</p> <p>This option is supported by all generations of IBM Z hardware to enable pause-less GC with two modes of operation: hardware-based and software-based operations. IBM z13\u2122 and earlier hardware operates in software-based pause-less GC mode; IBM z14\u2122 and later hardware (with supported software) operates in hardware-based mode.</p> <p>Hardware-based pause-less GC is supported on IBM z14 and later hardware running the following software:</p> <p>Operating systems:</p> <ul> <li>z/OS V2R3</li> <li>z/OS V2R2 and APAR OA51643.</li> <li>RHEL 7.5 (minimum kernel level 4.14)</li> <li>Ubuntu 18.04 (minimum kernel level 4.15)</li> </ul> <p>Hypervisors:</p> <ul> <li>IBM z/VM 6.4 with APAR VM65987</li> <li>IBM z/VM 7.1</li> <li>KVM solutions with QEMU 2.10 or later and minimum host kernel level 4.12 (for example, RHEL 7.5 with kernel level 4.14)</li> </ul> <p>If these requirements are not met, the option is ignored.</p> <p> Note: On z/OS, the virtual storage used might exceed the Java maximum heap size. Set the z/OS memory limit, specified by <code>ulimit -M</code>, to a larger value than the maximum heap size.</p>"},{"location":"xgc/#dnssexpectedtimeratiomaximum","title":"<code>dnssExpectedTimeRatioMaximum</code>","text":"<pre><code>    -Xgc:dnssExpectedTimeRatioMaximum=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [percentage] 5 for gencon, 5 for balanced <p>The maximum percentage of time spent in local garbage collection pauses. For the <code>gencon</code> policy, this refers to the amount of time spent on the nursery area of the heap (scavenge operation). For the <code>balanced</code> policy, this refers to the amount of time spent on the eden regions of the heap (PGC operation).</p> <p>This option applies only to the <code>gencon</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgc/#dnssexpectedtimeratiominimum","title":"<code>dnssExpectedTimeRatioMinimum</code>","text":"<pre><code>    -Xgc:dnssExpectedTimeRatioMinimum=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [percentage] 1 for gencon, 2 for balanced <p>The minimum percentage of time spent in local garbage collection pauses. For the <code>gencon</code> policy, this refers to the amount of time spent in Scavenge operation (on the nursery area of the heap). For the <code>balanced</code> policy, this refers to the amount of time spent in PGC operations (mostly on the eden and young regions, but also some other regions for de-fragmentation purposes). </p> <p>This option applies only to the <code>gencon</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgc/#dynamicbreadthfirstscanordering","title":"<code>dynamicBreadthFirstScanOrdering</code>","text":"<pre><code>     -Xgc:dynamicBreadthFirstScanOrdering\n</code></pre> This option sets the scan mode for GC operations that evacuate objects in the heap (scavenge operations (<code>gencon</code>) and copy forward operations (<code>balanced</code>)) to dynamic breadth first mode. This scan mode reflects the method for traversing the object graph and is a variant that adds partial depth first traversal on top of the breadth first scan mode. The aim of dynamic breadth first mode is driven by object field hotness. This mode is the default for the <code>balanced</code> GC policy."},{"location":"xgc/#excessivegcratio","title":"<code>excessiveGCratio</code>","text":"<pre><code>    -Xgc:excessiveGCratio=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [percentage] 95 <p>where <code>&lt;value&gt;</code> is a percentage of total application run time that is spent in GC.</p> <p>The default value is 95, which means that anything over 95% of total application run time spent on GC is deemed excessive. This option can be used only when <code>-Xenableexcessivegc</code> is set (enabled by default).</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xgc/#hierarchicalscanordering","title":"<code>hierarchicalScanOrdering</code>","text":"<pre><code>    -Xgc:hierarchicalScanOrdering\n</code></pre> This option sets the scan mode for the scavenge operation (<code>gencon</code> GC policy) to hierarchical mode. This mode reflects the method for traversing the object graph and adds partial depth first traversal on top of breadth first scan mode. The aim of hierarchical mode is to minimize object distances. This option is the default for the <code>gencon</code> GC policy."},{"location":"xgc/#mincontractpercent","title":"<code>minContractPercent</code>","text":"<pre><code>    -Xgc:minContractPercent=&lt;n&gt;\n</code></pre> Setting Value Default <code>&lt;n&gt;</code> [percentage] - <p>The minimum percentage of the heap that can be contracted at any given time.</p> <p>This option can be used with all OpenJ9 GC policies.</p>"},{"location":"xgc/#maxcontractpercent","title":"<code>maxContractPercent</code>","text":"<pre><code>    -Xgc:maxContractPercent=&lt;n&gt;\n</code></pre> Setting Value Default <code>&lt;n&gt;</code> [percentage] - <p>The maximum percentage of the heap that can be contracted at any given time. For example, <code>-Xgc:maxContractPercent=20</code> causes the heap to contract by as much as 20%.</p> <p>This option can be used with all OpenJ9 GC policies.</p>"},{"location":"xgc/#noconcurrentscavenge","title":"<code>noConcurrentScavenge</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xgc:noConcurrentScavenge\n</code></pre> <p>This option disables pause-less garbage collection that you might have enabled with the <code>-Xgc:concurrentScavenge</code> option when using the default <code>gencon</code> GC policy. This option applies only to the <code>gencon</code> GC policy.</p> <p> Note: No concurrent scavenge is the default state, but the <code>noConcurrentScavenge</code> option is useful as it will disable concurrent scavenge even if it has been enabled by a previous option; the right-most option always takes precedence.</p>"},{"location":"xgc/#nosynchronousgconoom","title":"<code>nosynchronousGCOnOOM</code>","text":"<pre><code>    -Xgc:nosynchronousGCOnOOM\n</code></pre> Setting <code>-Xgc:nosynchronousGCOnOOM</code> implies that when heap memory is full your application stops and issues an out-of-memory message. The default is <code>-Xgc:synchronousGCOnOOM</code>. This option applies only to the <code>metronome</code> GC policy."},{"location":"xgc/#overridehirestimercheck","title":"<code>overrideHiresTimerCheck</code>","text":"<pre><code>    -Xgc:overrideHiresTimerCheck\n</code></pre> <p>When the VM starts, the GC checks that the operating system can meet the timer resolution requirements for the requested target pause time. Typically, this check correctly identifies operating systems that can deliver adequate time resolution. However, in some cases the operating system provides a more conservative answer than strictly necessary for GC pause time management, which prevents startup. Specifying this parameter causes the GC to ignore the answer returned by the operating system. The VM starts, but GC pause time management remains subject to operating system performance, which might not provide adequate timer resolution.</p> <p> Note: Use this option with caution, and only when you are unable to use a supported operating system.</p> <p>This option applies only to the <code>metronome</code> GC policy.</p>"},{"location":"xgc/#preferredheapbase","title":"<code>preferredHeapBase</code>","text":"<p>(AIX, Linux, macOS, and Windows only)</p> <pre><code>    -Xgc:preferredHeapBase=&lt;address&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [hexadecimal] - <p>where, <code>&lt;address&gt;</code> is the base memory address for the heap. Use this option with the <code>-Xcompressedrefs</code> option to allocate the heap you specify with the <code>-Xmx</code> option, in a memory range of your choice. If <code>-Xcompressedrefs</code> is not specified, this option has no effect. In the following example, the heap is located at the 4 GB mark, leaving the lowest 4 GB of address space for use by other processes.</p> <pre><code>-Xgc:preferredHeapBase=0x100000000\n</code></pre> <p>If the heap cannot be allocated in a contiguous block at the <code>preferredHeapBase</code> address you specified, an error occurs detailing a Garbage Collection (GC) allocation failure startup. When the <code>preferredHeapBase</code> option is used with the <code>-Xlp</code> option, the <code>preferredHeapBase</code> address must be a multiple of the large page size. If you specify an inaccurate heap base address, the heap is allocated with the default page size.</p> <p>This option can be used with all OpenJ9 GC policies.</p>"},{"location":"xgc/#scvnoadaptivetenure","title":"<code>scvNoAdaptiveTenure</code>","text":"<pre><code>    -Xgc:scvNoAdaptiveTenure\n</code></pre> Turns off the adaptive tenure age in the <code>gencon</code> GC policy. The initial age that is set is maintained throughout the run time of the VM. See <code>scvTenureAge</code>. This option applies only to the <code>gencon</code> GC policy."},{"location":"xgc/#scvtenureage","title":"<code>scvTenureAge</code>","text":"<pre><code>    -Xgc:scvTenureAge=&lt;n&gt;\n</code></pre> Setting Value Default <code>&lt;n&gt;</code> [1 - 14] 10 <p>Sets the initial scavenger tenure age in the <code>gencon</code> GC policy. For more information, see <code>gencon</code> policy (default).</p> <p>This option applies only to the <code>gencon</code> GC policy.</p>"},{"location":"xgc/#stdglobalcompacttosatisfyallocate","title":"<code>stdGlobalCompactToSatisfyAllocate</code>","text":"<pre><code>    -Xgc:stdGlobalCompactToSatisfyAllocate\n</code></pre> Prevents the GC from performing a compaction unless absolutely required to satisfy the current allocation failure by removing the dynamic compaction triggers that look at heap occupancy. This option works only with the following GC policies: <ul> <li><code>gencon</code></li> <li><code>optthruput</code></li> <li><code>optavgpause</code></li> </ul> This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>)."},{"location":"xgc/#synchronousgconoom","title":"<code>synchronousGCOnOOM</code>","text":"<pre><code>    -Xgc:synchronousGCOnOOM\n</code></pre> GC cycles can occur when the Java heap runs out of memory. If there is no more free space in the heap, using <code>-Xgc:synchronousGCOnOOM</code> stops your application while GC operations remove unused objects. If free space runs out again, consider decreasing the target utilization to allow GC operations more time to complete. Setting <code>-Xgc:nosynchronousGCOnOOM</code> implies that when heap memory is full your application stops and issues an out-of-memory message. The default is <code>-Xgc:synchronousGCOnOOM</code>. This option applies only to the <code>metronome</code> GC policy."},{"location":"xgc/#targetpausetime","title":"<code>targetPausetime</code>","text":"<pre><code>    -Xgc:targetPausetime=N\n</code></pre> Sets the target GC pause time, where <code>N</code> is the time in milliseconds. When this option is specified with the <code>metronome</code> policy, the garbage collector operates with pauses that do not exceed the value specified. If this option is not specified when using the <code>metronome</code> policy, the default pause time target is set to 3 milliseconds. For example, running with <code>-Xgc:targetPausetime=20</code> causes the garbage collector to pause for no longer than 20 milliseconds during GC operations. <p>When this option is specified with the <code>balanced</code> policy, the GC will use the specified pause time as a soft pause time target. If this option is not specified when using the <code>balanced</code> policy, the default pause time target is set to 200 milliseconds. If the GC pauses are longer than the specified target, then the GC may shrink the amount of eden regions in order to satisfy the target pause time. If the percentage of time spent in PGC pauses is higher than <code>dnssExpectedTimeRatioMaximum</code> and the GC pauses are longer than the specified pause time target, then the target pause time may not be satisfied, in order to balance reaching the target pause time goal and percentage of time in GC pause goal.</p> <p> Note: Specifying an ultra low <code>targetPausetime</code> with the Balanced GC policy may cause the percentage of time spent in GC pauses to noticeably increase.</p> <p>This option applies only to the <code>metronome</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgc/#targetutilization","title":"<code>targetUtilization</code>","text":"<pre><code>    -Xgc:targetUtilization=N\n</code></pre> <p>Sets the application utilization to <code>N%</code>; the garbage collector attempts to use at most (100-N)% of each time interval. Reasonable values are in the range of 50-80%. Applications with low allocation rates might be able to run at 90%. The default is 70%.</p> <p>In the following example, the maximum size of the heap is set to 30 MB. The garbage collector attempts to use 25% of each time interval because the target utilization for the application is set to 75%.</p> <pre><code>java -Xgcpolicy:metronome -Xmx30m -Xgc:targetUtilization=75 Test\n</code></pre> <p>This option applies only to the <code>metronome</code> GC policy.</p>"},{"location":"xgc/#tlhincrementsize","title":"<code>tlhIncrementSize</code>","text":"<pre><code>    -Xgc:tlhIncrementSize=&lt;bytes&gt;\n</code></pre> Sets the increment size of the thread local heap (TLH), which plays a key role in cache allocation. Threads start creating TLHs with a predefined initial size (default 2 KB). On every TLH refresh, the requested size for that thread is increased by an increment (default 4 KB). Use this option to control the increment size. This option can be used with all OpenJ9 GC policies."},{"location":"xgc/#tlhinitialsize","title":"<code>tlhInitialSize</code>","text":"<pre><code>    -Xgc:tlhInitialSize=&lt;bytes&gt;\n</code></pre> Sets the initial size of the TLH. The default size is 2 KB. This option can be used with all OpenJ9 GC policies."},{"location":"xgc/#tlhmaximumsize","title":"<code>tlhMaximumSize</code>","text":"<pre><code>    -Xgc:tlhMaximumSize=&lt;bytes&gt;\n</code></pre> Sets the maximum size of the TLH. The size of the TLH varies from 512 bytes (768 on 64-bit JVMs) to 128 KB, depending on the allocation rate of the thread. Larger TLHs can help reduce heap lock contention, but might also reduce heap utilisation and increase heap fragmentation. Typically, when the maximum TLH size is increased, you should also increase the increment size (<code>-XtlhIncrementSize</code>) proportionally, so that active threads can reach the maximum requested TLH size more quickly. This option can be used with all OpenJ9 GC policies."},{"location":"xgc/#verboseformat","title":"<code>verboseFormat</code>","text":"<pre><code>    -Xgc:verboseFormat=&lt;format&gt;\n</code></pre> Setting Value Default <code>&lt;format&gt;</code> <code>default</code> yes <code>deprecated</code> <ul> <li><code>default</code>: The default verbose garbage collection format for OpenJ9. For more information, see Verbose garbage collection logs.</li> <li><code>deprecated</code>: The verbose garbage collection format available in the IBM J9 VM V2.4 and earlier.</li> </ul> <p>This option does not apply to the <code>metronome</code> GC policy. The verbose log format for the <code>metronome</code> GC policy is equivalent to <code>-Xgc:verboseFormat=deprecated</code>.</p>"},{"location":"xgc/#verbosegccycletime","title":"<code>verbosegcCycleTime</code>","text":"<pre><code>    -Xgc:verbosegcCycleTime=N\n</code></pre> <p><code>N</code> is the time in milliseconds that the summary information should be logged.</p> <p> Note: The cycle time does not mean that the summary information is logged precisely at that time, but when the last GC event that meets this time criterion passes.</p> <p>This option applies only to the <code>metronome</code> GC policy.</p>"},{"location":"xgcmaxthreads/","title":"-Xgcmaxthreads","text":""},{"location":"xgcmaxthreads/#-xgcmaxthreads","title":"-Xgcmaxthreads","text":"<p>Specifies the maximum number of threads that the garbage collector can use for parallel operations. This option behaves in the same way as <code>-Xgcthreads</code> but does not enforce a fixed thread count, which allows the garbage collector to adjust the thread count when used with the <code>-XX:+AdaptiveGCThreading</code> option.</p>"},{"location":"xgcmaxthreads/#syntax","title":"Syntax","text":"<pre><code>    -Xgcmaxthreads&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the maximum number of threads that can be used for parallel operations.</p>"},{"location":"xgcpolicy/","title":"-Xgcpolicy","text":""},{"location":"xgcpolicy/#-xgcpolicy","title":"-Xgcpolicy","text":"<p>Controls which garbage collection (GC) policy is used for your Java\u2122 application.</p>"},{"location":"xgcpolicy/#syntax","title":"Syntax","text":"<pre><code>    -Xgcpolicy:&lt;parameter&gt;\n</code></pre>"},{"location":"xgcpolicy/#parameters","title":"Parameters","text":"Parameter Default <code>gencon</code> yes <code>balanced</code> (64-bit only) <code>metronome</code> (AIX\u00ae, Linux\u00ae x86 only) <code>optavgpause</code> <code>optthruput</code> <code>nogc</code> <p>For a detailed description of the policies, when to use them, and how they work, see Garbage Collection policies. The following GC policies are available:</p>"},{"location":"xgcpolicy/#gencon","title":"<code>gencon</code>","text":"<pre><code>    -Xgcpolicy:gencon\n</code></pre> The generational concurrent policy (default) requires a heap that is divided into two main areas (nursery and tenure) to manage two generation groups (new and older). The policy uses a global GC cycle of concurrent mark-sweep operations, optionally followed by compact operations. The policy also uses a partial GC cycle to run scavenge operations on the nursery area. The partial cycle helps reduce the frequency and duration of the global GC cycle. Note that scavenge is a stop-the-world operation, unless <code>-Xgcpolicy:gencon</code> is specified with the <code>-Xgc:concurrentScavenge</code> option. To learn more about this policy, when to use it, and how it works, see Garbage collection: <code>gencon</code> policy."},{"location":"xgcpolicy/#balanced-64-bit-only","title":"<code>balanced</code> (64-bit only)","text":"<pre><code>    -Xgcpolicy:balanced\n</code></pre> The Balanced policy requires a multi-region heap to manage multiple generations of objects. The policy uses a global GC cycle that involves an incremental concurrent mark operation (global mark phase), followed by stop-the-world (STW) sweep operation. The policy also uses a partial GC cycle to run copy forward or mark-compact operations. Regions are individually managed to reduce the maximum pause time on large heaps and increase the efficiency of garbage collection. The policy tries to avoid global collections by matching object allocation and survival rates. With the <code>balanced</code> policy, the global mark and partial GC cycles interleave. The global STW sweep operation runs within the same GC increment as the first partial GC cycle that follows the global mark phase. The <code>balanced</code> policy also exploits large systems that have Non-Uniform Memory Architecture (NUMA) characteristics (x86 and POWER\u2122 platforms only), which might further improve application throughput. Note: If you are using this GC policy in a Docker container that uses the default <code>seccomp</code> Docker profile, you must start the container with <code>--security-opt seccomp=unconfined</code> to exploit NUMA characteristics. These options are not required if you are running in Kubernetes because <code>unconfined</code> is set by default (see Seccomp). To learn more about this policy, how it works, and when to use it, see Garbage collection: <code>balanced</code> policy."},{"location":"xgcpolicy/#balanced-defaults-and-options","title":"<code>balanced</code> defaults and options","text":"<p>The initial heap size is Xmx/1024, rounded down to the nearest power of 2, where Xmx is the maximum heap size available. You can override this value by specifying the <code>-Xms</code> option on the command line.</p> <p>The following options can also be specified on the command line with <code>-Xgcpolicy:balanced</code>:</p> <ul> <li><code>-Xdisableexcessivegc</code></li> <li><code>-Xdisableexplicitgc</code></li> <li><code>-Xenableexcessivegc</code></li> <li><code>-Xgcthreads&lt;number&gt;</code></li> <li><code>-Xgcworkpackets&lt;number&gt;</code></li> <li><code>-Xmaxe&lt;size&gt;</code></li> <li><code>-Xmaxf&lt;percentage&gt;</code></li> <li><code>-Xmaxt&lt;percentage&gt;</code></li> <li><code>-Xmca&lt;size&gt;</code></li> <li><code>-Xmco&lt;size&gt;</code></li> <li><code>-Xmine&lt;size&gt;</code></li> <li><code>-Xminf&lt;percentage&gt;</code></li> <li><code>-Xmint&lt;percentage&gt;</code></li> <li><code>-Xmn&lt;size&gt;</code></li> <li><code>-Xmns&lt;size&gt;</code></li> <li><code>-Xmnx&lt;size&gt;</code></li> <li><code>-Xms&lt;size&gt;</code></li> <li><code>-Xmx&lt;size&gt;</code></li> <li><code>-Xnuma:none</code></li> <li><code>-Xsoftmx&lt;size&gt;</code></li> <li><code>-Xsoftrefthreshold&lt;number&gt;</code></li> <li><code>-Xverbosegclog[:&lt;file&gt; [, &lt;X&gt;,&lt;Y&gt;]]</code></li> </ul> <p>The behavior of the following options is different when specified with <code>-Xgcpolicy:balanced</code>:</p> <code>-Xcompactgc</code> (default) Forces compaction in each Global GC cycle. <code>-Xnocompactgc</code> Disables internal compaction heuristics in Global GC cycles. <code>-Xcompactexplicitgc</code> (default) Forces compaction in explicit Global GC cycles, such as those invoked by <code>System.gc()</code>. Compaction in implicit Global GC remains optional, triggered by internal heuristics. <code>-Xnocompactexplicitgc</code> Disables compaction in explicit Global GC cycles. Compaction in implicit Global GC remains optional, triggered by internal heuristics. <code>-Xgc:targetPausetime</code> Uses the specified GC pause time as a soft GC pause time target. <p>The following options are ignored when specified with <code>-Xgcpolicy:balanced</code>:</p> <ul> <li><code>-Xconcurrentbackground&lt;number&gt;</code></li> <li><code>-Xconcurrentlevel&lt;number&gt;</code></li> <li><code>-Xconcurrentslack&lt;size&gt;</code></li> <li><code>-Xconmeter:&lt;soa | loa | dynamic&gt;</code></li> <li><code>-Xdisablestringconstantgc</code></li> <li><code>-Xenablestringconstantgc</code></li> <li><code>-Xloa</code></li> <li><code>-Xloainitial&lt;percentage&gt;</code></li> <li><code>-Xloamaximum&lt;percentage&gt;</code></li> <li><code>-Xloaminimum&lt;percentage&gt;</code></li> <li><code>-Xmo&lt;size&gt;</code></li> <li><code>-Xmoi&lt;size&gt;</code></li> <li><code>-Xmos&lt;size&gt;</code></li> <li><code>-Xmr&lt;size&gt;</code></li> <li><code>-Xmrx&lt;size&gt;</code></li> <li><code>-Xnoloa</code></li> </ul>"},{"location":"xgcpolicy/#optavgpause","title":"<code>optavgpause</code>","text":"<pre><code>    -Xgcpolicy:optavgpause\n</code></pre> <p>The optimize for pause time policy requires a flat heap and uses a global GC cycle to run concurrent mark-sweep operations, optionally followed by compact operations. Pause times are shorter than with <code>optthruput</code>, but application throughput is reduced. The impact on throughput occurs because some garbage collection work is taking place in the context of mutator (application) threads, and because GC frequency is increased.</p> <p>To learn more about this policy and when to use it, see Garbage collection: <code>optavgpause</code> policy.</p>"},{"location":"xgcpolicy/#optthruput","title":"<code>optthruput</code>","text":"<pre><code>    -Xgcpolicy:optthruput\n</code></pre> <p>The optimize for throughput policy requires a flat heap and uses a global GC cycle to run mark-sweep operations, optionally followed by compact operations. Because the application stops during a global GC cycle, long pauses can occur.</p> <p>To learn more about this policy, how it works, and when to use it, see Garbage collection: <code>optthruput</code> policy.</p>"},{"location":"xgcpolicy/#metronome-aix-linux-x86-only","title":"<code>metronome</code> (AIX, Linux x86 only)","text":"<pre><code>    -Xgcpolicy:metronome\n</code></pre> <p>The metronome policy is an incremental, deterministic garbage collector with short pause times. Applications that are dependent on precise response times can take advantage of this technology by avoiding potentially long delays from GC activity. The <code>metronome</code> policy is supported on specific hardware and operating system configurations.</p> <p>To learn more about this policy, how it works, and when to use it, see Garbage collection: <code>metronome</code> policy.</p>"},{"location":"xgcpolicy/#metronome-options","title":"<code>metronome</code> options","text":"<p>The following options are specific to the <code>metronome</code> GC policy:</p> <ul> <li><code>-Xgc:nosynchronousGCOnOOM</code></li> <li><code>-Xgc:overrideHiresTimerCheck</code></li> <li><code>-Xgc:synchronousGCOnOOM</code></li> <li><code>-Xgc:targetUtilization</code></li> <li><code>-Xgc:verbosegcCycleTime</code></li> </ul> <p><code>-Xgc:targetPausetime</code> option also applies to the <code>metronome</code> GC policy. This option applies only to the <code>metronome</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgcpolicy/#nogc","title":"<code>nogc</code>","text":"<pre><code>    -Xgcpolicy:nogc\n</code></pre> <p>This policy handles only memory allocation and heap expansion, but doesn't reclaim any memory. If the available Java heap becomes exhausted, an <code>OutOfMemoryError</code> exception is triggered and the VM stops.</p> <p>You should be especially careful when using any of the following techniques with <code>nogc</code> because memory is never released under this policy: - Finalization - Direct memory access - Weak, soft, and phantom references</p> <p>To learn when to use this policy, see Garbage collection: <code>nogc</code> policy.</p> <p>This policy can also be enabled with the <code>-XX:+UseNoGC</code> option.</p> <p>Further details are available at JEP 318: Epsilon: A No-Op Garbage Collector.</p>"},{"location":"xgcsplitheap/","title":"-Xgc:splitheap","text":""},{"location":"xgcsplitheap/#-xgcsplitheap","title":"-Xgc:splitheap","text":"<p>(Windows\u2122 32-bit only)</p> <p>By default, the VM uses a contiguous Java\u2122 heap to store Java objects. However, on Windows 32-bit systems, there are restrictions in the 32-bit memory space that prevents a process accessing more than 2GB of memory, even if there is more memory available. To increase the maximum allocatable heap size, Eclipse OpenJ9\u2122 can split the heap, allowing memory use up to the 4GB limit.</p> <p> Restrictions:</p> <ul> <li>A split heap forces the garbage collector to use the <code>gencon</code> policy and allocates the new and old areas of the generational Java heap in separate areas of memory. Resizing of the new and old memory areas is disabled.</li> <li> This option can be used only with Java SE version 8 runtime environments.  This option is deprecated in Version 8 and will be removed from future versions.</li> </ul>"},{"location":"xgcsplitheap/#syntax","title":"Syntax","text":"<pre><code>    -Xgc:splitheap\n</code></pre>"},{"location":"xgcsplitheap/#explanation","title":"Explanation","text":"<p>Use <code>-Xgc:splitheap</code> for applications that must run on the 32-bit VM because of 32-bit JNI libraries, a 32-bit operating system, or 32-bit hardware, but need large Java heaps. By using a larger heap, you can allocate more objects before incurring a garbage collection (GC) and you can increase the number of live objects that you can use before an <code>OutOfMemoryError</code> exception occurs.</p> <p>With a split heap, the old area is committed to its maximum size (set with <code>-Xmox</code>) in a lower region of memory and the new area is committed to its maximum size (set with <code>-Xmnx</code>) in a higher region of memory.</p> <p>This option is not recommended if your application works in the any of the following ways:</p> <ul> <li>Performs poorly under the <code>gencon</code> GC policy.</li> <li>Loads a very large number of classes.</li> <li>Uses large amounts of native system memory in JNI libraries; the increased size Java heap might reserve too much of the application's address space.</li> </ul>"},{"location":"xgcthreads/","title":"-Xgcthreads","text":""},{"location":"xgcthreads/#-xgcthreads","title":"-Xgcthreads","text":"<p>Sets the number of threads that the garbage collector uses for parallel operations.</p> <p> Notes:</p> <p>This option enforces a fixed thread count and cannot be used with the <code>-XX:+AdaptiveGCThreading</code> option, which enables the garbage collector to adjust the number of parallel threads based on heuristics. If you want to use <code>-XX:+AdaptiveGCThreading</code>, use <code>-Xgcmaxthreads</code> instead of <code>-Xgcthreads</code>.</p>"},{"location":"xgcthreads/#syntax","title":"Syntax","text":"<pre><code>    -Xgcthreads&lt;number&gt;\n</code></pre>"},{"location":"xgcthreads/#explanation","title":"Explanation","text":"<p>The total number of GC threads is composed of one application thread with the remainder being dedicated GC threads. By default, the number is set to <code>n-1</code>, where <code>n</code> is the number of reported CPUs, up to a maximum of 64. Where SMT or hyperthreading is in place, the number of reported CPUs is larger than the number of physical CPUs. Likewise, where virtualization is in place, the number of reported CPUs is the number of virtual CPUs assigned to the operating system. To set it to a different number, for example 4, use <code>-Xgcthreads4</code>. The minimum valid value is 1, which disables parallel operations, at the cost of performance. No advantage is gained if you increase the number of threads to more than the default setting.</p> <p>On systems running multiple VMs or in LPAR environments where multiple VMs can share the same physical CPUs, you might want to restrict the number of GC threads used by each VM. The restriction helps prevent the total number of parallel operation GC threads for all VMs exceeding the number of physical CPUs present, when multiple VMs perform garbage collection at the same time.</p> <p>This option is directly mapped to the HotSpot option <code>-XX:ParallelGCThreads</code> and can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xgcworkpackets/","title":"-Xgcworkpackets","text":""},{"location":"xgcworkpackets/#-xgcworkpackets","title":"-Xgcworkpackets","text":"<p>Specifies the total number of work packets available in the global collector.</p>"},{"location":"xgcworkpackets/#syntax","title":"Syntax","text":"<pre><code>    -Xgcworkpackets&lt;number&gt;\n</code></pre>"},{"location":"xgcworkpackets/#explanation","title":"Explanation","text":"<p>If you do not specify a value, the collector allocates a number of packets based on the maximum heap size.</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xint/","title":"-Xint","text":""},{"location":"xint/#-xint","title":"-Xint","text":"<p>As described in the Oracle \"Non-Standard Options\" documentation, this VM option runs an application in interpreted-only mode. For compatibility, this option is also supported by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xint/#syntax","title":"Syntax","text":"<pre><code>    -Xint\n</code></pre>"},{"location":"xint/#explanation","title":"Explanation","text":"<p>If you use this option, the OpenJ9 VM uses only the interpreter, disabling the OpenJ9 just-in-time (JIT) and ahead-of-time (AOT) compilers. By default, both these compilers are enabled, although the AOT compiler is not used by the VM unless shared classes are also enabled.</p>"},{"location":"xjit/","title":"-Xnojit","text":""},{"location":"xjit/#-xjit-xnojit","title":"-Xjit / -Xnojit","text":"<p>Use this option to control the behavior of the JIT compiler.</p> <p>Specifying <code>-Xjit</code> with no parameters has no effect because the JIT compiler is enabled by default.</p> <p>Specifying <code>-Xnojit</code> turns off the JIT compiler but does not affect the AOT compiler.</p> <p>Specify the <code>-Xjit</code> option only once. By default, if you specify this option multiple times, only the last option takes effect. You can use the <code>-XX:+MergeCompilerOptions</code> option to merge all the existing instances of the <code>-Xjit</code> options logically.</p> <p>You can specify multiple parameters for the <code>-Xjit</code> option by using commas to separate the parameters. For example: </p> <p><code>-Xjit:enableGPU,exclude={ilog/rules/engine/sequential/generated/*}</code> </p> <p>Parameters such as <code>exclude</code> are additive so you can specify them multiple times within the same <code>-Xjit</code> option.</p>"},{"location":"xjit/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xjit</code> Enable JIT yes <code>-Xjit[:&lt;parameter&gt;=&lt;value&gt;{,&lt;parameter&gt;=&lt;value&gt;}]</code> Enable JIT with options <code>-Xnojit</code> Disable JIT"},{"location":"xjit/#parameters","title":"Parameters","text":"<p>These parameters can be used to modify the behavior of <code>-Xjit</code>:</p> Parameter Effect <code>count</code> Specifies the number of times a method is called before it is compiled. <code>disableRMODE64</code> Allows the JIT to allocate executable code caches above the 2 GB memory bar. <code>enableGPU</code> Allows the JIT to offload certain processing tasks to a graphics processing unit (GPU) <code>exclude</code> Excludes the specified method from compilation. <code>limit</code> Includes the specified method in compilation. <code>limitFile</code> Compile methods that are listed in the limit file. <code>optlevel</code> Forces the JIT compiler to compile all methods at a specific optimization level. <code>verbose</code> Reports information about the JIT and AOT compiler configuration and method compilation. <code>vlog</code> Sends verbose output to a file. <code>perfTool</code> Facilitates JIT-compiled code symbol resolution when profiling the VM on Linux."},{"location":"xjit/#count","title":"<code>count</code>","text":"<pre><code>    -Xjit:count=&lt;n&gt;\n</code></pre> Specifies the number of times, <code>&lt;n&gt;</code>, a method is called before it is compiled. For example, setting <code>count=0</code> forces the JIT compiler to compile everything on first execution, which is useful for problem determination."},{"location":"xjit/#disablermode64","title":"<code>disableRMODE64</code>","text":"<p>(z/OS\u00ae only)</p> <pre><code>    -Xjit:disableRMODE64\n</code></pre> From z/OS V2R3, residency mode for 64-bit applications (RMODE64) is enabled by default. This feature allows the JIT to allocate executable code caches above the 2 GB memory bar, which is the default behavior. Use this option to turn off this JIT behavior."},{"location":"xjit/#enablegpu","title":"<code>enableGPU</code>","text":"<p>(Windows (x86-64) or Linux (x86-64 and IBM POWER LE))</p> <pre><code>    -Xjit:enableGPU\n</code></pre> Enables the JIT compiler to offload certain processing tasks to a graphics processing unit (GPU). The JIT determines which functions to offload based on performance heuristics. Systems must support NVIDIA Compute Unified Device Architecture (CUDA). The JIT requires the CUDA Toolkit 7.5 and your GPU device must have a minimum compute capability of 3.0. To troubleshoot operations between the JIT compiler and the GPU, use <code>-Xjit:enableGPU={verbose}</code>, which provides output showing the processing tasks that are offloaded and their status. To send this output to a file (<code>output.txt</code>), run <code>-Xjit:enableGPU={verbose},vlog=output.txt</code> when you start your application."},{"location":"xjit/#exclude","title":"<code>exclude</code>","text":"<pre><code>    -Xjit:exclude={&lt;method&gt;}\n</code></pre> <p>Excludes the specified method from compilation.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be excluded; the wildcard <code>*</code> may be used. Specify as much of the full package, class and method as necessary. </p> <p>For example, <code>-Xjit:exclude={test/sample/MyClass.testMethod()V}</code> excludes the single method specified. However, <code>-Xjit:exclude={test/sample/MyClass.testMethod()*}</code> excludes the method regardless of return type. Similarly, <code>-Xjit:exclude={*}</code> excludes all methods.</p> <p> Note: <code>exclude</code> has the same effect regardless of whether it is specified on <code>-Xaot</code> or <code>-Xjit</code>. In consequence, if you specify <code>-Xjit:exclude</code>, AOT compilation is also prevented and the methods specified are always interpreted.</p>"},{"location":"xjit/#limit","title":"<code>limit</code>","text":"<pre><code>    -Xjit:limit={&lt;method_name&gt;}\n</code></pre> Only the Java\u2122 methods specified are included when code is compiled or loaded from the shared classes cache. <code>&lt;method_name&gt;</code> is the method or methods that are to be included (the wildcard <code>*</code> can be used, see <code>-Xjit:exclude</code> for details). Note: <code>limit</code> has the same effect regardless of whether it is specified on <code>-Xaot</code> or <code>-Xjit</code>. In consequence, if you specify <code>-Xjit:limit</code>, AOT compilation is also restricted to those methods specified; other methods are always interpreted."},{"location":"xjit/#limitfile","title":"<code>limitFile</code>","text":"<pre><code>    -Xjit:limitFile=(&lt;vlog_filename&gt;, &lt;m&gt;, &lt;n&gt;)\n</code></pre> Compile only the methods that are listed on lines <code>&lt;m&gt;</code> to <code>&lt;n&gt;</code> in the specified limit file, where the limit file is a verbose log that you generated with the <code>-Xjit:verbose,vlog=&lt;vlog_filename&gt;</code> option. Methods that are not listed in the limit file and methods that are listed on lines outside the range are not compiled. Note: <code>limitFile</code> has the same effect regardless of whether it is specified on <code>-Xaot</code> or <code>-Xjit</code>. In consequence, if you specify <code>-Xjit:limitFile</code>, AOT compilation is also restricted to those methods specified; other methods are always interpreted."},{"location":"xjit/#optlevel","title":"<code>optlevel</code>","text":"<pre><code>    -Xjit:optlevel=[noOpt|cold|warm|hot|veryHot|scorching]\n</code></pre> Forces the JIT compiler to compile all methods at a specific optimization level. Specifying <code>optlevel</code> might have an unexpected effect on performance, including reduced overall performance."},{"location":"xjit/#verbose","title":"<code>verbose</code>","text":"<pre><code>    -Xjit:verbose\n</code></pre> Generates a JIT verbose log. The log provides a summary of which methods were compiled by the JIT and some of the compilation heuristic decisions that were taken while the JIT operates inside the Eclipse OpenJ9\u2122 VM.<pre><code>-Xjit:verbose={compileStart}\n</code></pre> <p>Prints a line when the JIT is about to start compiling a method.</p> <pre><code>-Xjit:verbose={compileEnd}\n</code></pre> <p>Prints a line when the JIT stops compiling a method.</p> <pre><code>-Xjit:verbose={compilePerformance}\n</code></pre> <p>Adds the values <code>time</code> (time taken to do the compilation) and <code>mem</code> (the amount of memory that was allocated during the compilation) into each line. This option includes the <code>compileStart</code> and <code>compileEnd</code> suboptions by default.</p> <pre><code>-Xjit:verbose={disableInlining}\n</code></pre> <p>Turns off inlining operations.</p> <pre><code>-Xjit:verbose={inlining}\n</code></pre> <p>Shows the methods that are inlined.</p> <p> Note: Suboptions can be chained together by using a pipe (<code>|</code>) symbol. When used, you must enclose the full option name in single quotation marks (<code>'</code>) to avoid the shell misinterpreting these characters as pipe commands. For example:</p> <pre><code>java '-Xjit:verbose={compileStart|compileEnd|inlining}' -version\n</code></pre>"},{"location":"xjit/#vlog","title":"<code>vlog</code>","text":"<pre><code>    -Xjit:vlog=&lt;vlog_filename&gt;\n</code></pre> Sends verbose output to a file, of the format <code>&lt;vlog_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;JVM_process_ID&gt;</code>, which is created in your current directory. Running the command multiple times produces multiple distinct versions of this file. If you do not specify this parameter, the output is sent to the standard error output stream (STDERR). This type of log file can be used with the <code>limitFile</code> suboption to target the compilation of specific methods."},{"location":"xjit/#perftool","title":"<code>perfTool</code>","text":"<pre><code>    -Xjit:perfTool\n</code></pre> generates a <code>/tmp/perf-&lt;pid&gt;.map</code> file for the JIT-compiled code. This file is used by the Linux\u00ae system profiler, <code>perf</code>, to map the samples in the JIT-compiled code to the corresponding Java method names for profiling the VM. <p>For more information, see <code>-XX:[+|-]PerfTool</code>.</p>"},{"location":"xjit/#examples","title":"Examples","text":""},{"location":"xjit/#generating-a-jit-verbose-log","title":"Generating a JIT verbose log","text":"<p>The following example requests a JIT verbose log of the <code>java -version</code> command:</p> <pre><code>java -Xjit:verbose,vlog=vlogfile -version\n</code></pre>"},{"location":"xjit/#analyzing-jit-performance","title":"Analyzing JIT performance","text":"<p>The following example requests information about the performance of JIT compiler threads, with output written to <code>vlogfile</code>.</p> <pre><code>java -Xjit:verbose={compilePerformance},vlog=vlogfile -version\n</code></pre> <p>The output generated by using this command adds the following information to compilation entry:</p> <ul> <li>the amount of time taken to do the compilation.</li> <li>the amount of memory that was allocated during the compilation.</li> </ul>"},{"location":"xjit/#analyzing-inlining-operations","title":"Analyzing inlining operations","text":"<p>The following example generates output that contains performance data and inlining operations. The suboptions <code>count</code> and <code>-XcompilationThreads1</code> are used only to simplify the output. These options are not recommended for production because performance will be affected.</p> <pre><code>java '-Xjit:verbose={compileStart|compileEnd|inlining},count=5,vlog=vlogfile' -XcompilationThreads1 -version\n</code></pre>"},{"location":"xjit/#see-also","title":"See also","text":"<ul> <li>Diagnosing a JIT or AOT problem</li> <li>-Xaot</li> </ul>"},{"location":"xjni/","title":"-Xjni","text":""},{"location":"xjni/#-xjni","title":"-Xjni","text":"<p>Sets JNI options.</p>"},{"location":"xjni/#syntax","title":"Syntax","text":"<pre><code>    -Xjni:&lt;parameter&gt;\n</code></pre>"},{"location":"xjni/#parameters","title":"Parameters","text":""},{"location":"xjni/#arraycachemax","title":"<code>arrayCacheMax</code>","text":"<pre><code>    -Xjni:arrayCacheMax=&lt;size in bytes&gt;\n    -Xjni:arrayCacheMax=unlimited\n</code></pre> Sets the maximum size of the array cache. The default size is 128 KB (<code>-Xjni:arrayCacheMax=131072</code>)."},{"location":"xlinenumbers/","title":"-Xnolinenumbers","text":""},{"location":"xlinenumbers/#-xlinenumbers-xnolinenumbers","title":"-Xlinenumbers / -Xnolinenumbers","text":"<p>Enables or disables line numbers in stack traces for debugging.</p>"},{"location":"xlinenumbers/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xlinenumbers</code> Enable yes <code>-Xnolinenumbers</code> Disable"},{"location":"xlinenumbers/#explanation","title":"Explanation","text":"<p>If you start the Eclipse OpenJ9\u2122 VM with <code>-Xnolinenumbers</code> when creating a new shared classes cache, the Class Debug Area is not created. The option <code>-Xnolinenumbers</code> advises the VM not to load any class debug information, so there is no need for this region. If <code>-Xscdmx</code> is also used on the command line to specify a non zero debug area size, then a debug area is created despite the use of <code>-Xnolinenumbers</code>.</p>"},{"location":"xloa/","title":"-Xnoloa","text":""},{"location":"xloa/#-xloa-xnoloa","title":"-Xloa / -Xnoloa","text":"<p>This option enables or prevents the allocation of a large object area (LOA) during garbage collection (GC).</p>"},{"location":"xloa/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xloa</code> Enable LOA yes (see Default behavior) <code>-Xnoloa</code> Disable LOA"},{"location":"xloa/#default-behavior","title":"Default behavior","text":"<p>By default, allocations are made in the small object area (SOA). If there is no room in the SOA, and an object is larger than 64KB, the object is allocated in the LOA.</p> <p>If the LOA is not used, it is shrunk to zero after a few collections. You can disable it explicitly by specifying the <code>-Xnoloa</code> option.</p>"},{"location":"xloa/#explanation","title":"Explanation","text":"<p>The LOA is an area of the tenure area of the heap set used solely to satisfy allocations for large objects. The LOA is used when the allocation request cannot be satisfied in the main area (the SOA of the tenure heap.</p> <p>As objects are allocated and freed, the heap can become fragmented in such a way that allocation can be met only by time-consuming compactions. This problem is more pronounced if an application allocates large objects. In an attempt to alleviate this problem, the LOA is allocated. A large object in this context is considered to be any object 64 KB or greater in size. Allocations for new TLH objects are not considered to be large objects.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>), which do not use an LOA. Any LOA options passed on the command line are ignored. These policies address the issues that are solved by an LOA by reorganizing object layout with the VM to reduce heap fragmentation and compaction requirements.</p>"},{"location":"xloa/#see-also","title":"See also","text":"<ul> <li>-Xloainitial / -Xloaminimum / -Xloamaximum</li> </ul>"},{"location":"xloaminimum/","title":"-Xloaminimum","text":""},{"location":"xloaminimum/#-xloainitial-xloaminimum-xloamaximum","title":"-Xloainitial / -Xloaminimum / -Xloamaximum","text":"<p>Specifies the initial, minimum, and maximum proportion of the current tenure space allocated to the large object area (LOA).</p> <p>The LOA does not shrink to less than the minimum value.</p>"},{"location":"xloaminimum/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xloainitial&lt;value&gt;</code> Set initial space <code>0.05</code> <code>-Xloaminimum&lt;value&gt;</code> Set minimum space <code>0.01</code> <code>-Xloamaximum&lt;value&gt;</code> Set minimum space <code>0.5</code>"},{"location":"xloaminimum/#see-also","title":"See also","text":"<ul> <li>-Xloa / Xnoloa</li> </ul> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>), which do not use an LOA.</p>"},{"location":"xlockreservation/","title":"-XlockReservation","text":""},{"location":"xlockreservation/#-xlockreservation","title":"-XlockReservation","text":"<p>Enables an optimization that presumes a monitor is owned by the thread that last acquired it.</p> <p>This optimization minimizes the runtime cost of acquiring and releasing a monitor for a single thread if the monitor is rarely acquired by multiple threads.</p>"},{"location":"xlockreservation/#syntax","title":"Syntax","text":"<pre><code>    -XlockReservation\n</code></pre>"},{"location":"xlockword/","title":"-Xlockword","text":""},{"location":"xlockword/#-xlockword","title":"-Xlockword","text":"<p>Test whether performance optimizations are negatively impacting an application.</p>"},{"location":"xlockword/#syntax","title":"Syntax","text":"<pre><code>    -Xlockword:&lt;parameters&gt;\n</code></pre>"},{"location":"xlockword/#parameters","title":"Parameters","text":""},{"location":"xlockword/#mode","title":"<code>mode</code>","text":"<pre><code>    -Xlockword:mode=all\n    -Xlockword:mode=default\n</code></pre> <p>Locking optimizations typically reduce memory usage and improve performance. However, there might be some situations where a smaller heap size is achieved for an application, but overall application performance decreases.</p> <p>For example, if your application synchronizes on objects that are not typically synchronized on, such as <code>Java.lang.String</code>, run the following test: Use the following command-line option to revert to behavior that is closer to earlier versions and monitor application performance:</p> <pre><code>-Xlockword:mode=all\n</code></pre> <p>If performance does not improve, remove the previous command-line options or use the following command-line option to reestablish the new behavior:</p> <pre><code>-Xlockword:mode=default\n</code></pre>"},{"location":"xlockword/#nolockword","title":"<code>nolockword</code>","text":"<pre><code>    -Xlockword:nolockword=&lt;class_name&gt;\n</code></pre> <p>Removes the lockword from object instances of the class <code>&lt;class_name&gt;</code>, reducing the space required for these objects. However, this action might have an adverse effect on synchronization for those objects.</p> <p>You should only use this option for troubleshooting.</p>"},{"location":"xlockword/#what","title":"<code>what</code>","text":"<pre><code>    -Xlockword:what\n</code></pre> Shows the current lockword configuration."},{"location":"xlog/","title":"-Xlog","text":""},{"location":"xlog/#-xlog","title":"-Xlog","text":"<p>This option is supported for better compatibility with the reference implementation. However, only forms of <code>-Xlog</code> that enable garbage collection (GC) logging are recognized. Note that the behavior of this option changed in Eclipse OpenJ9\u2122 0.24.0.</p>"},{"location":"xlog/#syntax","title":"Syntax","text":"<pre><code>    -Xlog[:&lt;parameters&gt;]\n</code></pre> <p>Note: In Eclipse OpenJ9 version 0.24.0, the <code>-Xsyslog</code> option replaced the existing OpenJ9 <code>-Xlog</code> option for message logging to avoid conflicts with the reference implementation. For backward compatibility, you can control the behavior of the <code>-Xlog</code> option with the <code>-XX:[+|-]LegacyXlogOption</code> option.</p>"},{"location":"xlog/#explanation","title":"Explanation","text":"<p>Use of the <code>-Xlog</code> option is supported for GC logging only. The following table describes the behavior of the option depending on what you specify on the command line.</p> <code>-Xlog</code> option type Behavior An option that returns GC data. For example <code>-Xlog:gc</code> An equivalent OpenJ9 GC logging option is enabled. See the next table for more details. An option that, in the reference implementation, returns GC data and also other data. For example: <code>-Xlog</code>, <code>-Xlog:all</code>, <code>-Xlog:gc+&lt;other_tag&gt;</code>, or  <code>-Xlog:gc:stdout</code> An equivalent OpenJ9 GC logging option is enabled as before but because non-GC data is not supported, the following error message is also produced:  <code>JVMJ9VM007W Command-line option unrecognised: &lt;option&gt;</code> An option that, in the reference implementation, returns only non-GC data Non-GC data is not supported, so the following error message is produced:  <code>JVMJ9VM007W Command-line option unrecognised: &lt;option&gt;</code> <p>The following table shows some examples of the mapping between <code>-Xlog</code> parameters and the equivalent OpenJ9 GC parameters:</p> <code>-Xlog</code> parameter OpenJ9 GC equivalent <code>-Xlog:gc</code> <code>-Xlog:gc:stderr</code> <code>-verbose:gc</code> <code>-Xlog:gc:&lt;filename&gt;</code> <code>-Xlog:gc:file=&lt;filename&gt;</code> <code>-Xverbosegclog:&lt;updated_filename&gt;</code> <p>In the table, the value of <code>&lt;filename&gt;</code> can contain the following tokens, which are processed and passed to the <code>-Xverbosegclog</code> option as <code>&lt;updated_filename&gt;</code>:</p> <ul> <li><code>%p</code> is replaced with the process ID (equivalent to dump agent token <code>%pid</code>)</li> <li><code>%t</code> is replaced with the dump agent tokens <code>%Y-%m-%d_%H-%M-%S</code>.</li> </ul>"},{"location":"xlog/#see-also","title":"See also","text":"<ul> <li><code>-Xsyslog</code></li> <li><code>-Xverbosegclog</code></li> <li><code>-XX:[+|-]LegacyXlogOption</code></li> </ul>"},{"location":"xlp/","title":"-Xlp","text":""},{"location":"xlp/#-xlp","title":"-Xlp","text":"<p>Requests the Eclipse OpenJ9\u2122 VM to allocate the Java\u2122 object heap and JIT code cache memory with large pages.</p> <p> Note: This option is deprecated in all versions later than Java 8. Use the <code>-Xlp:codecache</code> and <code>-Xlp:objectheap</code> options instead.</p> <p> Restriction: This option does not work on macOS\u00ae.</p> <p>If you use the <code>-Xgc:preferredHeapBase</code> option with <code>-Xlp</code>, the preferredHeapBase address must be a multiple of the large page size. If you specify an inaccurate heap base address, the heap is allocated with the default page size.</p> <p>To find out the large page sizes available and the current setting, use the <code>-verbose:sizes</code> option. Note that the current settings are the requested sizes and not the sizes obtained. For object heap size information, check the <code>-verbose:gc</code> output.</p>"},{"location":"xlp/#syntax","title":"Syntax","text":"<pre><code>    -Xlp[&lt;size&gt;]\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xlp/#explanation","title":"Explanation","text":""},{"location":"xlp/#aix","title":"AIX\u00ae","text":"<p>If <code>&lt;size&gt;</code> is specified, the VM attempts to allocate the JIT code cache memory by using pages of that size. Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 32-bit VM.</p> <p>If a size is not specified, this option requests the VM to allocate the Java object heap (the heap from which Java objects are allocated) with large (16 MB) pages.</p> <p>If large pages are not available, the Java object heap is allocated with the next smaller page size that is supported by the system. AIX requires special configuration to enable large pages.</p> <p>The VM supports the use of large pages only to back the Java object heap shared memory segments. The VM uses <code>shmget()</code> with the SHM_LGPG and SHM_PIN flags to allocate large pages. The <code>-Xlp</code> option replaces the environment variable <code>IBM_JAVA_LARGE_PAGE_SIZE</code>, which is now ignored if set.</p> <p>For more information about configuring AIX support for large pages, see Large pages in the AIX product documentation.</p>"},{"location":"xlp/#linux","title":"Linux\u00ae","text":"<p>If <code>&lt;size&gt;</code> is specified, the VM attempts to allocate the JIT code cache memory by using pages of that size. Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 32-bit VM.</p> <p>If large pages are not available, the VM does not start and produces an error message. The VM uses <code>shmget()</code> to allocate large pages for the heap. Large pages are supported by systems that have Linux kernels v2.6 or higher.</p> <p> Note: Linux for IBM Z\u00ae supports only a large page size of 1 M.</p> <p>Depending on the architecture, 1 MB or 2 MB large pages, when available, are the default size for the object heap and the code cache. The options that control these sizes are <code>Xlp:codecache</code> and <code>-Xlp:objectheap</code>.</p>"},{"location":"xlp/#windows","title":"Windows\u2122","text":"<p>If <code>&lt;size&gt;</code> is specified, the VM attempts to allocate the JIT code cache memory by using pages of that size.</p> <p>Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 32-bit VM.</p>"},{"location":"xlp/#zos","title":"z/OS\u00ae","text":"<p>If <code>&lt;size&gt;</code> is specified but unsuccessful, or if executable pages of that size are not supported, 1 M pageable is attempted. If 1 M pageable is not available, the JIT code cache memory is allocated by using the default or smallest available executable page size.</p> <p>If <code>&lt;size&gt;</code> is not specified, the 1 M nonpageable size is used. If large pages are not supported by the hardware, or enabled in RACF\u00ae, the VM does not start and produces an error message.</p> <p>Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 31-bit VM. The <code>-Xlp[&lt;size&gt;]</code> option supports only a large page size of 2 G and 1 M (nonpageable).</p> <p>1 M pageable pages, when available, are the default size for the object heap and the code cache. The options that control these sizes are <code>Xlp:codecache</code> and <code>-Xlp:objectheap</code>.</p> <p>Specifying <code>-Xlp1M</code> uses a 1 M pageable size for the code cache, when available. Specifying <code>-Xlp2G</code> sets the object heap size, but generates a warning that 2 G nonpageable pages cannot be used for the code cache. Use the <code>-Xlp:objectheap:pagesize=2G,nonpageable</code> option to avoid the warning.</p>"},{"location":"xlp/#limitation-and-workaround","title":"Limitation and workaround","text":"<p>The VM ends if insufficient operating system resources are available to satisfy the request. However, an error message is not issued. There are a number of reasons why the VM cannot honor a large page request. For example, there might be insufficient large pages available on the system at the time of the request. To check whether the <code>-Xlp</code> request was honored, you can review the output from <code>-verbose:gc</code>. Look for the attributes <code>requestedPageSize</code> and <code>pageSize</code> in the <code>-verbose:gc</code> log file. The attribute <code>requestedPageSize</code> contains the value specified by <code>-Xlp</code>. The attribute <code>pageSize</code> is the actual page size used by the VM.</p>"},{"location":"xlp/#see-also","title":"See also","text":"<ul> <li>Configuring large page memory allocation.</li> </ul>"},{"location":"xlpcodecache/","title":"-Xlp:codecache","text":""},{"location":"xlpcodecache/#-xlpcodecache","title":"-Xlp:codecache","text":"<p>Requests the Eclipse OpenJ9\u2122 VM to allocate the JIT code cache by using large page sizes.</p> <p>If the requested large page size is not available, the VM starts, but the JIT code cache is allocated by using a platform-defined size. A warning is displayed when the requested page size is not available.</p> <p>To find out the large page sizes available and the current setting, use the <code>-verbose:sizes</code> option. Note that the current settings are the requested sizes and not the sizes obtained. For object heap size information, check the <code>-verbose:gc</code> output.</p>"},{"location":"xlpcodecache/#syntax","title":"Syntax","text":"<p>AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122:</p> <pre><code>    -Xlp:codecache:pagesize=&lt;size&gt;\n</code></pre> <p>z/OS\u00ae:</p> <pre><code>    -Xlp:codecache:pagesize=&lt;size&gt;,pageable\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xlpcodecache/#default-values","title":"Default values","text":""},{"location":"xlpcodecache/#aix","title":"AIX","text":"<p>The code cache page size is controlled by the <code>DATAPSIZE</code> setting of the <code>LDR_CNTRL</code> environment variable. The page size cannot be controlled by the <code>-Xlp:codecache:pagesize=&lt;size&gt;</code> option. Specifying any other page size results in a warning that the page size is not available. The <code>-verbose:sizes</code> output reflects the current operating system setting.</p> <p>For more information about the <code>LDR_CNTRL</code> environment variable, see Configuring large page memory allocation: AIX systems.</p>"},{"location":"xlpcodecache/#linux","title":"Linux","text":"<p>The default size for the code cache depends on the architecture:</p> <ul> <li>Linux on x86 and AMD64/EM64T systems: 2 MB large pages</li> <li>Linux on IBM Z\u00ae: 1 MB large pages</li> <li>Linux on Power Systems\u2122: The code cache page size cannot be controlled by the <code>-Xlp:codecache:pagesize=&lt;size&gt;</code> option. Specifying any other page size results in a warning that the page size is not available. The <code>-verbose:sizes</code> output reflects the current operating system setting.</li> <li>On other architectures, the VM uses the default operating system page size.</li> </ul>"},{"location":"xlpcodecache/#macos","title":"macOS","text":"The default size for the code cache is 4 KB large pages."},{"location":"xlpcodecache/#zos","title":"z/OS","text":"<p>1 MB pageable pages, when available, are the default size for the code cache.</p> <p>The <code>-Xlp:codecache:pagesize=&lt;size&gt;,pageable</code> option supports only a large page size of 1 MB pageable large pages. The use of 1 MB pageable large pages for the JIT code cache can improve the runtime performance of some Java\u2122 applications. A page size of 4 KB can also be used.</p>"},{"location":"xlpcodecache/#see-also","title":"See also","text":"<ul> <li>Configuring large page memory allocation.</li> </ul>"},{"location":"xlpobjectheap/","title":"-Xlp:objectheap","text":""},{"location":"xlpobjectheap/#-xlpobjectheap","title":"-Xlp:objectheap","text":"<p>Requests the Eclipse OpenJ9\u2122 VM to allocate the Java\u2122 object heap by using large page sizes.</p> <p>To find out the large page sizes available and the current setting, use the <code>-verbose:sizes</code> option. Note that the current settings are the requested sizes and not the sizes obtained. For object heap size information, check the <code>-verbose:gc</code> output.</p>"},{"location":"xlpobjectheap/#syntax","title":"Syntax","text":"<p>AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122:</p> <pre><code>    -Xlp:objectheap:pagesize=&lt;size&gt;[,strict|warn]\n</code></pre> <p>z/OS\u00ae:</p> <pre><code>    -Xlp:objectheap:pagesize=&lt;size&gt;[,strict|warn][,pageable|nonpageable]\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xlpobjectheap/#parameters","title":"Parameters","text":""},{"location":"xlpobjectheap/#pagesize","title":"<code>pagesize</code>","text":"<pre><code>    -Xlp:objectheap:pagesize=&lt;size&gt;\n</code></pre> <p>The large page size that you require.</p> <p>If the operating system does not have sufficient resources to satisfy the request, the page size you requested might not be available when the VM starts up. By default, the VM starts and the Java object heap is allocated by using a different platform-defined page size. Alternatively, you can use the <code>strict</code> or <code>warn</code> suboptions to customize behavior.</p>"},{"location":"xlpobjectheap/#default-page-sizes","title":"Default page sizes","text":"<p>On Linux systems, the default size for the object heap depends on the architecture:</p> <ul> <li>Linux on x86 and AMD64/EM64T systems: 2 MB large pages</li> <li>Linux on IBM Z\u00ae: 1 MB large pages</li> <li>On other architectures, the VM uses the default operating system page size.</li> </ul> <p>On macOS, the default page size is 4 KB.</p> <p>On z/OS systems, the default page size is 1 MB pageable large pages. For more information, see <code>pageable</code>|<code>nonpageable</code>.</p>"},{"location":"xlpobjectheap/#strict-warn","title":"<code>strict</code> | <code>warn</code>","text":"<pre><code>    -Xlp:objectheap:strict\n    -Xlp:objectheap:warn\n</code></pre> <ul> <li><code>strict</code> causes an error message to be generated if large pages are requested but cannot be obtained. This option causes the VM to end.</li> <li><code>warn</code> causes a warning message to be generated if large pages are requested but cannot be obtained. This option allows the VM to continue.</li> </ul> <p> Note: If both <code>strict</code> and <code>warn</code> are specified, <code>strict</code> takes precedence.</p>"},{"location":"xlpobjectheap/#pageablenonpageable","title":"<code>pageable</code>|<code>nonpageable</code>","text":"<pre><code>    -Xlp:objectheap:pageable\n    -Xlp:objectheap:nonpageable\n</code></pre> <p>On z/OS systems, defines the type of memory to allocate for the Java object heap.</p> <p>1 MB pageable large pages, when available, are the default size for the object heap.  </p> <p>64-bit VMs support large page sizes of 1 MB nonpageable and 2 GB nonpageable with the following requirements:</p> <ul> <li>2 GB nonpageable sizes are supported only on IBM zEnterprise EC12 processors or later.</li> <li>A system programmer must configure z/OS for nonpageable large pages.</li> <li>Users who require large pages must be authorized to the IARRSM.LRGPAGES resource in the RACF FACILITY class with read authority.</li> </ul> <p>31-bit VMs support a large page size of only 1 MB pageable.</p> <p>A page size of 4 KB can also be used.</p>"},{"location":"xlpobjectheap/#examples","title":"Examples","text":"<ol> <li>z/OS: To allocate 1 GB of real memory by using 1 MB nonpageable pages when the VM starts, set the following options:</li> </ol> <pre><code>-Xmx1023m -Xms512m -Xlp:objectheap:pagesize=1M,nonpageable\n</code></pre> <ol> <li>z/OS: To allocate 1 GB of real memory by using 2 GB nonpageable pages, set the following options:</li> </ol> <pre><code>-Xmx1023m -Xms512m -Xlp:objectheap:pagesize=2G,nonpageable\n</code></pre> <p>In this example the heap is allocated on a 2 GB large page. Even though the object heap is only 1 GB, 2 GB of memory are consumed and the large page is never paged out while the VM is running.</p>"},{"location":"xlpobjectheap/#see-also","title":"See also","text":"<ul> <li>Configuring large page memory allocation.</li> </ul>"},{"location":"xmca/","title":"-Xmco","text":""},{"location":"xmca/#-xmca-xmco","title":"-Xmca / -Xmco","text":"<p>Sets the expansion step for the memory allocated to store the RAM (<code>-Xmca</code>) and ROM (<code>-Xmco</code>) portions of loaded classes.</p> <p>Each time more memory is required to store classes in RAM or ROM, the allocated memory is increased by the amount set.</p> <p>If the expansion step size you choose is too large, <code>OutOfMemoryError</code> is reported. The exact value of a \"too large\" expansion step size varies according to the platform and the specific machine configuration.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the value that is being used by the VM.</p>"},{"location":"xmca/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmca&lt;size&gt;</code> Set expansion step for RAM 32 KB <code>-Xmco&lt;size&gt;</code> Set expansion step for ROM 128 KB <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>This option cannot be used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</p>"},{"location":"xmca/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> </ul>"},{"location":"xmcrs/","title":"-Xmcrs","text":""},{"location":"xmcrs/#-xmcrs","title":"-Xmcrs","text":"<p>Sets an initial size for an area in memory that is reserved for any native classes, monitors, and threads that are used by compressed references within the lowest 4 GB memory area.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the value that is being used by the VM.</p> <p> Notes:</p> <ul> <li>Native memory <code>OutOfMemoryError</code> exceptions might occur when using compressed references if the lowest 4 GB of address space becomes full, particularly when loading classes, starting threads, or using monitors. </li> <li>If you are not using compressed references and this option is set, the option is ignored and the output of <code>-verbose:sizes</code> shows <code>-Xmcrs0</code>.</li> </ul>"},{"location":"xmcrs/#syntax","title":"Syntax","text":"<pre><code>    -Xmcrs&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xmine/","title":"-Xmine","text":""},{"location":"xmine/#-xmine-xmaxe","title":"-Xmine / -Xmaxe","text":"<p>Set the minimum and maximum amounts by which the garbage collector expands the heap.</p>"},{"location":"xmine/#syntax","title":"Syntax","text":"Setting Default <code>-Xmine&lt;size&gt;</code> 1 MB <code>-Xmaxe&lt;size&gt;</code> 0 (unlimited expansion) <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xmine/#explanation","title":"Explanation","text":"<p>Typically, the garbage collector expands the heap by the amount required to restore the free space to 30% (or the amount specified by <code>-Xminf</code>).</p> <p>If heap expansion is required:</p> <ul> <li><code>-Xmine</code> forces the expansion to be at least the specified value. For example, <code>-Xmine10M</code> sets the expansion size to a minimum of 10 MB.  </li> <li><code>-Xmaxe</code> limits the expansion to the specified value. For example <code>-Xmaxe50M</code> prevents expansion by more than 50 MB. (<code>-Xmaxe0</code> allows unlimited expansion.)</li> </ul> <p>For the <code>gencon</code> GC policy, the values apply only to the tenure part of the heap. For the <code>balanced</code>, <code>optthruput</code>, and <code>optavgpause</code> GC policies, these values apply to the whole heap. This option cannot be used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</p>"},{"location":"xmine/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> </ul>"},{"location":"xminf/","title":"-Xminf","text":""},{"location":"xminf/#-xminf-xmaxf","title":"<code>-Xminf</code> / <code>-Xmaxf</code>","text":"<p>Specifies the minimum and maximum proportion of the heap that must remain free after a global garbage collection (GC) cycle.</p> <p>If the free space is above or below these limits, the Eclipse OpenJ9\u2122 VM attempts to adjust the heap size so that: <code>-Xminf</code> \u2264 free space \u2264 <code>-Xmaxf</code>.</p>"},{"location":"xminf/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xminf&lt;value&gt;</code> Set minimum free space 0.3 <code>-Xmaxf&lt;value&gt;</code> Set maximum free space 0.6 <p>The value range is 0.0 - 1.0.</p> <ul> <li>For the <code>balanced</code> GC policy, these values apply only to the non-eden space part of the heap. The non-eden heap resizing decision is made by observing both <code>-Xmint</code>/<code>-Xmaxt</code> and <code>-Xminf</code>/<code>-Xmaxf</code>. Free memory in eden space is not considered for <code>-Xminf</code>/<code>-Xmaxf</code> purposes.</li> <li>For the <code>gencon</code> GC policy, the values apply only to the tenure part of the heap and only at global GC points.</li> <li>For the <code>optthruput</code> and <code>optavgpause</code> GC policies, these values apply to the whole heap at every GC point.</li> <li>This option cannot be used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</li> </ul>"},{"location":"xminf/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> <li>Garbage collection policies</li> </ul>"},{"location":"xmint/","title":"-Xmint","text":""},{"location":"xmint/#-xmint-xmaxt","title":"-Xmint / -Xmaxt","text":"<p>Sets the minimum and maximum proportion of time to spend in the garbage collection (GC) process as a percentage of the overall running time that included the last three GC runs. Therefore, the time spent in the GC process includes time spent in global mark phase and global GC operations but excludes partial garbage collection pauses because the latter apply only to the eden space.</p> <ul> <li>If the percentage of time drops to less than the minimum, the Eclipse OpenJ9\u2122 VM tries to shrink the heap.</li> <li>If the percentage of time exceeds the maximum, the VM tries to expand the heap.</li> </ul> <p> Restrictions:</p> <ul> <li>This option applies only to GC policies that include stop-the-world (STW) operations, such as <code>-Xgcpolicy:optthruput</code>.  </li> </ul>"},{"location":"xmint/#syntax","title":"Syntax","text":"Setting Effect Default for balanced policy Default for other policies <code>-Xmint&lt;value&gt;</code> Set minimum time in GC 0.02 0.05 <code>-Xmaxt&lt;value&gt;</code> Set maximum time in GC 0.05 0.13 <ul> <li>For the <code>balanced</code> GC policy, the values apply only to the non-eden space part of the heap. The non-eden heap resizing decision is made by observing both <code>-Xmint</code>/<code>-Xmaxt</code> and <code>-Xminf</code>/<code>-Xmaxf</code>.</li> <li>For the <code>gencon</code> GC policy, the values apply only to the tenure part of the heap.</li> <li>For the <code>optthruput</code>, and <code>optavgpause</code> GC policies, these values apply to the whole heap.</li> <li>This option cannot be used with the <code>metronome</code> GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</li> </ul>"},{"location":"xmint/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> <li>Garbage collection policies</li> </ul>"},{"location":"xmn/","title":"-Xmnx","text":""},{"location":"xmn/#-xmn-xmns-xmnx","title":"-Xmn / -Xmns / -Xmnx","text":"<p>Sets the initial and maximum size of the nursery area when using the <code>gencon</code> garbage collection (GC) policy (<code>-Xgcpolicy:gencon</code>), and sets the size of eden when using the <code>balanced</code> garbage collection (GC) policy (<code>-Xgcpolicy:balanced</code>). These options are ignored if they are used with any other GC policy.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the value that is being used by the VM.</p>"},{"location":"xmn/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmn&lt;size&gt;</code> Equivalent to setting both <code>-Xmns</code> and <code>-Xmnx</code> Not set <code>-Xmns&lt;size&gt;</code> Set initial size 25% of <code>-Xms</code> when using <code>gencon</code> and <code>balanced</code> policies <code>-Xmnx&lt;size&gt;</code> Set maximum size 25% of <code>-Xmx</code> when using <code>gencon</code>, and 75% of <code>-Xmx</code> when using <code>balanced</code> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p> Restriction: If you try to set <code>-Xmn</code> with either <code>-Xmns</code> or <code>-Xmnx</code>, the VM does not start, returning an error.</p> <p> Notes:</p> <ul> <li>When using the <code>balanced</code> GC policy without specifying <code>-Xmn</code> or <code>-Xmns</code>, the GC may decide to shrink eden size below its initial size (25% of <code>-Xms</code>) if it determines that doing so will improve GC performance.</li> <li>When using the <code>balanced</code> GC policy, specifying <code>-Xmn</code>/<code>-Xmns</code>/<code>-Xmnx</code> may affect <code>balanced</code> GC's ability to satisfy <code>-Xgc:targetPausetime</code></li> <li>Specifying <code>-Xmn</code>/<code>-Xmns</code>/<code>-Xmnx</code> may affect both <code>gencon</code> and <code>balanced</code> GC's ability to satisfy <code>-Xgc:dnssexpectedtimeratiomaximum</code> and <code>-Xgc:dnssexpectedtimeratiominimum</code></li> </ul> <p>To set the size of the tenure area of the heap when using <code>gencon</code> GC policy, see <code>-Xmo/-Xmos/-Xmox</code>.</p>"},{"location":"xmn/#see-also","title":"See also","text":"<ul> <li><code>gencon</code> GC policy (default)</li> <li><code>balanced</code> GC policy</li> <li><code>-Xmo/-Xmos/-Xmox</code></li> <li><code>-Xms</code>/<code>-Xmx</code></li> </ul>"},{"location":"xmo/","title":"-Xmox","text":""},{"location":"xmo/#-xmo-xmos-xmox","title":"-Xmo / -Xmos / -Xmox","text":"<p>Sets the size of the tenure area of the heap for the <code>gencon</code> garbage collection (GC) policy.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p>"},{"location":"xmo/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmo&lt;size&gt;</code> Equivalent to setting both <code>-Xmos</code> and <code>-Xmox</code> not set <code>-Xmos&lt;size&gt;</code> Set initial size of the tenure area of the heap 75% of <code>-Xms</code> <code>-Xmox&lt;size&gt;</code> Set maximum size of the tenure area of the heap Same as <code>-Xmx</code> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p> Restriction: If you try to set <code>-Xmo</code> with either <code>-Xmos</code> or <code>-Xmox</code>, the VM does not start, returning an error.</p> <p>To set the size of the nursery area of the heap, see <code>-Xmn/-Xmns/-Xmnx</code>.</p>"},{"location":"xmo/#see-also","title":"See also","text":"<ul> <li><code>gencon</code> policy (default)</li> <li><code>-Xmn/-Xmns/-Xmnx</code></li> <li><code>-Xms</code>/<code>-Xmx</code></li> </ul>"},{"location":"xmoi/","title":"-Xmoi","text":""},{"location":"xmoi/#-xmoi","title":"-Xmoi","text":"<p>Sets the heap expansion allocation increment.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p>"},{"location":"xmoi/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmoi&lt;size&gt;</code> Sets the heap expansion allocation increment See Notes <p> Notes:</p> <ul> <li>By default, the increment size (<code>-Xmoi</code>) is calculated on the expansion size, set by <code>-Xmine</code> and <code>-Xminf</code>.  If you set <code>-Xmoi</code> to zero, no expansion is allowed.</li> <li>For the <code>gencon</code> GC policy, the expansion increment applies to the tenure area of the heap.  </li> </ul> <p>This option is not supported for the <code>metronome</code> GC policy, because the heap is always fully expanded.</p> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xmoi/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> </ul>"},{"location":"xmr/","title":"-Xmrx","text":""},{"location":"xmr/#-xmr-xmrx","title":"-Xmr / \u00a0 -Xmrx","text":"<p>Sets the initial and maximum size of the the garbage collection (GC) remembered set in the <code>gencon</code> GC policy. The remembered set is a list of objects in the tenure area of the heap that have references to objects in the new area.</p>"},{"location":"xmr/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmr&lt;size&gt;</code> Set initial size 16 K <code>-Xmrx&lt;size&gt;</code> Set maximium size <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>This option applies only to the <code>gencon</code> GC policy.</p>"},{"location":"xms/","title":"-Xmx","text":""},{"location":"xms/#-xms-xmx","title":"-Xms / -Xmx","text":"<p>These Oracle\u00ae HotSpot\u2122 options set the initial/minimum Java\u2122 heap size, and the maximum heap size respectively. These options are recognized by the Eclipse OpenJ9\u2122 VM.</p> <p> Notes:</p> <ul> <li>If you set <code>-Xms</code> &gt; <code>-Xmx</code>, the VM fails with the message <code>-Xms too large for -Xmx</code>.</li> <li>If you exceed the limit set by the <code>-Xmx</code> option, the VM generates an <code>OutofMemoryError</code>.</li> <li>If you set a value for <code>-Xms</code>, the <code>-XX:InitialRAMPercentage</code> option is ignored.</li> <li>If you set a value for <code>-Xmx</code>, the <code>-XX:MaxRAMPercentage</code> option is ignored.</li> </ul> <p>For the <code>gencon</code> GC policy, you can also use the <code>-Xmo</code> option:</p> <ul> <li>If the scavenger is enabled, <code>-Xms</code> \u2265 <code>-Xmn</code> + <code>-Xmo</code> </li> <li>If the scavenger is disabled, <code>-Xms</code> \u2265 <code>-Xmo</code> </li> </ul>"},{"location":"xms/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xms&lt;size&gt;</code> Set initial heap size 8 MB <code>-Xmx&lt;size&gt;</code> Set maximum heap size 25% of available memory (25 GB maximum) <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter. See Default settings for the OpenJ9 VM for more about default values.</p> <p>The <code>-Xmx</code> option can be used with all OpenJ9 GC policies. However, the <code>-Xms</code> option can be used with all GC policies except for the <code>metronome</code> GC policy because the heap is always fully expanded.</p>"},{"location":"xms/#examples","title":"Examples","text":"<code>-Xms2m -Xmx64m</code> Heap starts at 2 MB and grows to a maximum of 64 MB. <code>-Xms100m -Xmx100m</code> Heap starts at 100 MB and never grows. <code>-Xms50m</code> Heap starts at 50 MB and grows to the default maximum. <code>-Xmx256m</code> Heap starts at default initial value and grows to a maximum of 256 MB."},{"location":"xms/#see-also","title":"See also","text":"<ul> <li>-Xsoftmx (Set \"soft\" maximum Java heap size)</li> </ul>"},{"location":"xmso/","title":"-Xmso","text":""},{"location":"xmso/#-xmso","title":"-Xmso","text":"<p>Sets the native stack size for operating system threads.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p> <p>When a native method makes a call into the VM, the VM calculates whether the memory required for the call will exceed the <code>-Xmso</code> value. If so, a <code>java/lang/StackOverflowError</code> error is thrown.</p> <p> Note: Java methods and native methods run on two different stacks and the VM handles switching between them for JNI calls. Each stack is sized using separate options; this option applies to the native stack only. For the Java stack option, see the link in the See also section.</p>"},{"location":"xmso/#syntax","title":"Syntax","text":"<pre><code>    -Xmso&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.  </p>"},{"location":"xmso/#default-setting","title":"Default setting","text":"<p>Default values vary by platform. See Default settings for the Eclipse OpenJ9\u2122 VM.</p> <p> Note: On 64-bit z/OS, the default size is the minimum that can be allocated by the operating system. So if you set a value that is smaller, that value is ignored by the VM.</p>"},{"location":"xmso/#see-also","title":"See also","text":"<ul> <li><code>-Xiss/-Xss/-Xssi</code> (stack size and increment for Java\u2122 threads)</li> </ul>"},{"location":"xnumanone/","title":"-Xnuma:none","text":""},{"location":"xnumanone/#-xnumanone","title":"-Xnuma:none","text":"<p>(AIX\u00ae, Linux\u00ae, and Windows\u2122 only)</p> <p>Use this option to turn off non-uniform memory architecture (NUMA) awareness when using the balanced garbage collection policy.</p> <p>For workloads that do most of their work in one thread, or workloads that maintain a full heap, turning off NUMA awareness can improve performance.</p>"},{"location":"xnumanone/#syntax","title":"Syntax","text":"<pre><code>    -Xnuma:none\n</code></pre>"},{"location":"xnumanone/#default-behavior","title":"Default behavior","text":"<p>NUMA awareness is enabled by default.</p>"},{"location":"xoptionsfile/","title":"-Xoptionsfile","text":""},{"location":"xoptionsfile/#-xoptionsfile","title":"-Xoptionsfile","text":"<p>Specifies a file that contains VM options and definitions.</p> <p>The contents of the options file are recorded in the <code>ENVINFO</code> section of a Java\u2122 dump.</p>"},{"location":"xoptionsfile/#syntax","title":"Syntax","text":"<pre><code>    -Xoptionsfile=&lt;file_name&gt;\n</code></pre> where <code>&lt;file_name&gt;</code> specifies a file that contains options that are processed as if they had been entered directly as command-line options."},{"location":"xoptionsfile/#explanation","title":"Explanation","text":"<p>At startup, the VM automatically adds <code>-Xoptionsfile=&lt;path&gt;/options.default</code> at the beginning of the command line, where <code>&lt;path&gt;</code> is the path to the VM directory.</p> <p> <code>&lt;path&gt;</code> is the VM directory, as shown in Directory conventions.  <code>&lt;path&gt;</code> is the <code>&lt;java_home&gt;/lib</code> directory, where <code>&lt;java_home&gt;</code> is the directory for your runtime environment. </p> <p>The file <code>options.default</code> can be updated with any options that you want to specify at run time.</p> <p>The options file does not support these options:</p> <ul> <li><code>-assert</code></li> <li><code>-fullversion</code></li> <li><code>-help</code></li> <li><code>-showversion</code></li> <li><code>-version</code></li> <li><code>-Xcompressedrefs</code></li> <li><code>-Xcheck:memory</code></li> <li><code>-Xoptionsfile</code></li> <li><code>-XshowSettings</code></li> </ul> <p>Although you cannot use <code>-Xoptionsfile</code> recursively within an options file, you can use <code>-Xoptionsfile</code> multiple times on the same command line to load more than one options files.</p> <p>Some options use quoted strings as parameters. Do not split quoted strings over multiple lines using the forward slash line continuation character (\\). The Yen symbol (\u00a5) is not supported as a line continuation character. For example, the following example is not valid in an options file:</p> <pre><code>-Xevents=vmstop,exec=\"cmd /c \\\necho %pid has finished.\"\n</code></pre> <p>The following example is valid in an options file:</p> <pre><code>-Xevents=vmstop, \\\nexec=\"cmd /c echo %pid has finished.\"\n</code></pre>"},{"location":"xoptionsfile/#example","title":"Example","text":"<p>Here is an example of an options file:</p> <pre><code>#My options file\n-X&lt;option1&gt;\n-X&lt;option2&gt;=\\\n&lt;value1&gt;,\\\n&lt;value2&gt;\n-D&lt;sysprop1&gt;=&lt;value1&gt;\n</code></pre>"},{"location":"xoptionsfile/#see-also","title":"See also","text":"<ul> <li>Specifying command-line options</li> <li>Javadump: TITLE, GPINFO, and ENVINFO sections</li> </ul>"},{"location":"xquickstart/","title":"-Xquickstart","text":""},{"location":"xquickstart/#-xquickstart","title":"-Xquickstart","text":"<p>This option causes the JIT compiler to run with a subset of optimizations, which can improve the performance of short-running applications.</p> <p> Note: For compatibility with other Java\u2122 virtual machines, you can also specify the <code>-client</code> option, which results in identical behavior to <code>-Xquickstart</code>.</p>"},{"location":"xquickstart/#syntax","title":"Syntax","text":"<pre><code>    -Xquickstart\n</code></pre>"},{"location":"xquickstart/#default-behavior","title":"Default behavior","text":"<p>By default, <code>-Xquickstart</code> is disabled.</p>"},{"location":"xquickstart/#explanation","title":"Explanation","text":"<p>The JIT compiler is tuned for long-running applications typically used on a server. When you specify this option, the compiler uses a subset of optimizations, which results in faster compilation times that improve startup time. However, longer running applications might run more slowly, especially applications that contain hot methods and other methods using a large amount of processing resource.</p> <p>When the AOT compiler is active (both shared classes and AOT compilation enabled), <code>-Xquickstart</code> causes all methods to be AOT compiled. The AOT compilation improves the startup time of subsequent runs, but might reduce performance for longer running applications, especially those that contain hot methods.</p> <p> Note: The implementation of <code>-Xquickstart</code> is subject to change in future releases.</p>"},{"location":"xrs/","title":"-Xrs","text":""},{"location":"xrs/#-xrs","title":"-Xrs","text":"<p>Prevents the Eclipse OpenJ9\u2122 runtime environment from handling any internally or externally generated signals such as <code>SIGSEGV</code> and <code>SIGABRT</code>. Any signals that are raised are handled by the default operating system handlers, which you might want if you are using a debugger such as GDB or WinDbg to diagnose problems in JNI code.</p> <p>Disabling signal handling in the OpenJ9 VM reduces performance by approximately 2-4%, depending on the application.</p> <p> Note: Setting this option prevents dumps being generated by the OpenJ9 VM for signals such as <code>SIGSEGV</code> and <code>SIGABRT</code>, because the VM is no longer intercepting these signals. Do not use the <code>-Xrs</code> option with the following options:</p> <ul> <li><code>-XX:+HandleSIGABRT</code></li> <li><code>-XX:+HandleSIGUSR2</code></li> </ul> <p>An error is thrown if either of the options is enabled together with the <code>-Xrs</code> option. To resolve this error, one of the options should be disabled.</p>"},{"location":"xrs/#syntax","title":"Syntax","text":"<pre><code>    -Xrs\n    -Xrs:sync\n</code></pre>"},{"location":"xrs/#parameters","title":"Parameters","text":"<p>If you specify the <code>sync</code> parameter:</p> <ul> <li>On AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae systems: Disables signal handling in the VM for <code>SIGSEGV</code>, <code>SIGFPE</code>, <code>SIGBUS</code>, <code>SIGILL</code>, <code>SIGTRAP</code>, and <code>SIGABRT</code> signals. However, the VM still handles the <code>SIGQUIT</code> and <code>SIGTERM</code> signals, among others.</li> <li>On Windows\u2122 systems: Hardware exceptions are not handled by the OpenJ9 VM when this option is specified. However, the Windows CTRL_BREAK_EVENT signal, triggered by the Ctrl-Break key combination, is still handled by the VM.</li> </ul> <p>Linux and macOS systems always use the <code>SIGUSR1</code> signal.</p>"},{"location":"xrs/#see-also","title":"See also","text":"<ul> <li>Signal handling</li> </ul>"},{"location":"xrsonrestoresynconrestore/","title":"-Xrs:onRestore / -Xrs:syncOnRestore","text":""},{"location":"xrsonrestoresynconrestore/#-xrsonrestore-xrssynconrestore","title":"-Xrs:onRestore / -Xrs:syncOnRestore","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>The <code>-Xrs</code> option is an existing option for disabling signal handling in the VM. CRIU support adds new suboptions <code>onRestore</code> and <code>syncOnRestore</code> for disabling signal handling when you restore a VM.</p> <p>If the VM was started with signal handling enabled, then when you restore the VM, the signal handling is enabled by default. It is possible that there are frames with attached signal handlers already on the stack. These frames remain unchanged and their signal handlers remain active. Likewise, some global handlers might not be removed as well. The new options prevent the addition of new signal handlers and force recompilation of Java\u2122 methods that make use of the existing signal handlers.</p> <p> Restrictions: This option takes effect only when the <code>-XX:+EnableCRIUSupport</code> option is enabled. This option can be used only on restore.</p>"},{"location":"xrsonrestoresynconrestore/#parameters","title":"Parameters","text":""},{"location":"xrsonrestoresynconrestore/#onrestore","title":"<code>onRestore</code>","text":"<pre><code>    -Xrs:onRestore\n</code></pre> <p>The <code>-Xrs:onRestore</code> option is similar to the <code>-Xrs</code> option.</p>"},{"location":"xrsonrestoresynconrestore/#synconrestore","title":"<code>syncOnRestore</code>","text":"<pre><code>    -Xrs:syncOnRestore\n</code></pre> <p>The <code>-Xrs:syncOnRestore</code> option is similar to the <code>-Xrs:sync</code> option.</p> <p>Although there are similarities between the existing options and the new CRIU related options, there are behavioural differences that limits what can be disabled with the existing options at the restore time.</p>"},{"location":"xrsonrestoresynconrestore/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xsamplingexpirationtime/","title":"-XsamplingExpirationTime","text":""},{"location":"xsamplingexpirationtime/#-xsamplingexpirationtime","title":"-XsamplingExpirationTime","text":"<p>Disables JIT sampling after a specified amount of time. </p> <p>When the JIT sampling thread is disabled, no processor cycles are used by an idle Eclipse OpenJ9\u2122 VM.</p> <p>Use this option with care; after the sampling thread is disabled, you cannot reactivate it. However, because the profiling frequency is automatically reduced, you should not have to use this option. </p> <p>Allow the sampling thread to run for long enough to identify important optimizations.</p>"},{"location":"xsamplingexpirationtime/#syntax","title":"Syntax","text":"<pre><code>    -XsamplingExpirationTime&lt;time&gt;\n</code></pre> where <code>&lt;time&gt;</code> is specified in seconds."},{"location":"xsamplingexpirationtime/#explanation","title":"Explanation","text":"<p>The JIT sampling thread profiles the running Java\u2122 application to discover commonly used methods. The memory and processor usage of the sampling thread is negligible, and the frequency of profiling is automatically reduced when the OpenJ9 VM is idle, to once per second instead of once every 10ms, or once every 100 seconds if the idle state lasts more than 50 seconds.</p>"},{"location":"xscdmx/","title":"-Xscdmx","text":""},{"location":"xscdmx/#-xscdmx","title":"-Xscdmx","text":"<p>Use the <code>-Xscdmx</code> option to control the size of the class debug area when you create a shared classes cache.</p>"},{"location":"xscdmx/#syntax","title":"Syntax","text":"<pre><code>    -Xscdmx&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscdmx/#explanation","title":"Explanation","text":"<p>The <code>-Xscdmx</code> option works in a similar way to the <code>-Xscmx</code> option, which is used to control the overall size of the shared classes cache. The size of <code>-Xscdmx</code> must be smaller than the size of <code>-Xscmx</code>. By default, the size of the class debug area is a percentage of the free class data bytes in a newly created or empty cache.</p> <p>A class debug area is still created if you use the <code>-Xnolinenumbers</code> option with the <code>-Xscdmx</code> option on the command line.</p>"},{"location":"xscminaot/","title":"-Xscminaot","text":""},{"location":"xscminaot/#-xscminaot-xscmaxaot","title":"-Xscminaot / -Xscmaxaot","text":"<p>When you create a shared classes cache, you can use these options to set the minimum and maximum number of bytes in the class cache to reserve for AOT data.</p> <p>Setting <code>-Xscmaxaot</code> is useful if you want a certain amount of cache space guaranteed for non-AOT data.</p>"},{"location":"xscminaot/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xscminaot&lt;size&gt;</code> Set minimum size for AOT class cache 0 <code>-Xscmaxaot&lt;size&gt;</code> Set maximum size for AOT class cache The amount of free space in the cache <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscminaot/#-xscminaot","title":"<code>-Xscminaot</code>","text":"<p>If <code>-Xscminaot</code> is not specified, no space is reserved for AOT data. However, AOT data is still written to the cache until the cache is full or the <code>-Xscmaxaot</code> limit is reached. </p> <p>The value of <code>-Xscminaot</code> must not exceed the value of <code>-Xscmx</code> or <code>-Xscmaxaot</code> and should be considerably less than the total cache size, because AOT data can be created only for cached classes. If the value of <code>-Xscminaot</code> equals the value of <code>-Xscmx</code>, no class data or AOT data can be stored.</p> <ul> <li>You can also adjust the <code>-Xscminaot</code> value by using:<ul> <li><code>-Xshareclasses:adjustminaot=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMinAotBytes()</code> method in the <code>com.ibm.lang.management</code> API</li> </ul> </li> <li>You can also adjust the <code>-Xscmaxaot</code> value by using:<ul> <li><code>-Xshareclasses:adjustmaxaot=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMaxAotBytes()</code> method in the <code>com.ibm.lang.management</code> API.</li> </ul> </li> </ul>"},{"location":"xscminaot/#-xscmaxaot","title":"<code>-Xscmaxaot</code>","text":"<p>The value of this option must not be smaller than the value of <code>-Xscminaot</code> and must not be larger than the value of <code>-Xscmx</code>.</p> <p>When you run an application with the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the amount of AOT data that is not stored due to the current setting of the maximum AOT data space. You can also get this information by using the <code>MemoryMXBean.getSharedClassCacheMaxAotUnstoredBytes()</code> method in the <code>com.ibm.lang.management</code> API. You can increase the maximum AOT data space size accordingly if you want to add the unstored AOT data to the shared cache.</p>"},{"location":"xscminaot/#see-also","title":"See also","text":"<ul> <li>-Xshareclasses</li> </ul>"},{"location":"xscminjitdata/","title":"-Xscminjitdata","text":""},{"location":"xscminjitdata/#-xscminjitdata-xscmaxjitdata","title":"-Xscminjitdata / -Xscmaxjitdata","text":"<p>When you create a shared classes cache, you can use these options to set a minimum and maximum number of bytes in the class cache that can be used for JIT data.</p> <p>When you run an application with the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the amount of JIT data that is not stored due to the current setting of the the maximum JIT data space. You can also get this information by using the <code>MemoryMXBean.getSharedClassCacheMaxJitDataUnstoredBytes()</code> method in the <code>com.ibm.lang.management</code> API. </p> <p>You can increase the maximum JIT data space size accordingly if you want to add the unstored data to the shared cache. However, the VM that provided the information no longer has the opportunity to store the JIT data. Subsequent VMs can store JIT data in the shared cache.</p>"},{"location":"xscminjitdata/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xscminjitdata&lt;size&gt;</code> Set minimum size for JIT data 0 (See Default behavior) <code>-Xscmaxjitdata&lt;size&gt;</code> Set maximum size for JIT data The amount of free space in the cache <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscminjitdata/#default-behavior","title":"Default behavior","text":"<p>If <code>-Xscminjitdata</code> is not specified, no space is reserved for JIT data, although JIT data is still written to the cache until the cache is full or the <code>-Xscmaxjitdata</code> limit is reached. </p>"},{"location":"xscminjitdata/#explanation","title":"Explanation","text":""},{"location":"xscminjitdata/#-xscminjitdata","title":"<code>-Xscminjitdata</code>","text":"<p>The value of <code>-Xscminjitdata</code> must not exceed the value of <code>-Xscmx</code> or <code>-Xscmaxjitdata</code>. The value of <code>-Xscminjitdata</code> must always be considerably less than the total cache size, because JIT data can be created only for cached classes. If the value of <code>-Xscminjitdata</code> equals the value of <code>-Xscmx</code>, no class data or JIT data can be stored.</p> <ul> <li>You can also adjust the <code>-Xscminjitdata</code> value by using:<ul> <li><code>-Xshareclasses:adjustminjitdata=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMinJitDataBytes()</code> method in the <code>com.ibm.lang.management</code> API.</li> </ul> </li> </ul>"},{"location":"xscminjitdata/#-xscmaxjitdata","title":"<code>-Xscmaxjitdata</code>","text":"<p>Setting <code>-Xscmaxjitdata</code> is useful if you want a certain amount of cache space guaranteed for non-JIT data. If this option is not specified, the maximum limit for JIT data is the amount of free space in the cache. The value of this option must not be smaller than the value of <code>-Xscminjitdata</code>, and must not be larger than the value of <code>-Xscmx</code>.</p> <ul> <li>You can also adjust the <code>-Xscmaxjitdata</code> value by using:<ul> <li><code>-Xshareclasses:adjustmaxjitdata=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMinJitDataBytes()</code> method in the <code>com.ibm.lang.management</code> API.</li> </ul> </li> </ul>"},{"location":"xscminjitdata/#see-also","title":"See also","text":"<ul> <li><code>-Xscmx</code></li> </ul>"},{"location":"xscmx/","title":"-Xscmx","text":""},{"location":"xscmx/#-xscmx","title":"-Xscmx","text":"<p>For a new shared classes cache, specifies either:</p> <ul> <li>the actual size of the cache, if the <code>-XX:SharedCacheHardLimit</code> option is not present</li> <li>the soft maximum size of the cache, if used with the <code>-XX:SharedCacheHardLimit</code> option (See <code>-XX:SharedCacheHardLimit</code>)</li> </ul> <p>This option applies only if a cache is being created and no cache of the same name exists.</p> <p>When you run an application with the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the soft maximum size. You can also get this information by using the <code>MemoryMXBean.getSharedClassCacheSoftmxUnstoredBytes()</code> method in the <code>com.ibm.lang.management</code> API.</p> <p>You can increase the soft maximum size accordingly if you want to add the unstored data to the shared cache. However, the VM that provided the information no longer has the opportunity to store that data. Therefore, increasing the soft maximum size does not necessarily cause any more data to be stored in the shared cache by the current VM, but subsequent VMs can add data to the shared cache.</p>"},{"location":"xscmx/#syntax","title":"Syntax","text":"<pre><code>    -Xscmx&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscmx/#explanation","title":"Explanation","text":""},{"location":"xscmx/#setting-a-soft-maximum-size","title":"Setting a soft maximum size","text":"<p>If you specify the <code>-Xscmx</code> option with the -XX:SharedCacheHardLimit option, the <code>-Xscmx</code> option sets the soft maximum size of a new shared classes cache, and the <code>-XX:SharedCacheHardLimit</code> option sets the actual maximum size. The value of the <code>-Xscmx</code> option must therefore not exceed the value of <code>-XX:SharedCacheHardLimit</code>.</p> <p>When the soft maximum limit is reached, no more data can be added into the shared cache, unless there is reserved AOT or JIT data space. If such reserved space exists, AOT or JIT data can still be added into the reserved space. The reserved AOT and JIT data spaces are counted as used space within the soft maximum size, so the soft maximum size should not be less than the minimum reserved space for AOT and JIT data if you specify the -Xscminaot or -Xscminjitdata options.</p> <p>You can change the soft maximum size by using the <code>-Xshareclasses:adjustsoftmx=&lt;size&gt;</code> option or the <code>MemoryMXBean.setSharedClassCacheSoftmxBytes()</code> method in the <code>com.ibm.lang.management</code> API. By using this API, Java\u2122 applications can dynamically monitor and adjust the cache soft maximum size as required. This function can be useful in virtualized or cloud environments, for example, where the shared cache size might change dynamically to meet business needs.</p> <p>For example, you might create a 64 MB shared cache and set a smaller value, such as 16 MB, for the <code>-Xscmx</code> option, to limit the data stored in the cache:</p> <pre><code>-XX:SharedCacheHardLimit=64m -Xscmx16m\n</code></pre> <p>You can then use the <code>com.ibm.lang.management</code> API from within a Java application to increase the soft maximum value during run time, as load increases. This change allows the application to use more shared cache space than you specified initially.</p> <p>You can increase the soft maximum size if it is currently less than the actual cache size. If you attempt to reduce the soft maximum size to a value that is less than the number of bytes already used in the cache, the number of used bytes is set as the new soft maximum size.</p>"},{"location":"xscmx/#cache-size-limits","title":"Cache size limits","text":"<p>The theoretical cache size limit is 2 GB. The size of the cache that you can specify is limited by the following factors:</p> <ul> <li>AIX\u00ae, Linux\u00ae, and macOS\u00ae: The amount of physical memory and paging space available to the system.</li> <li>Windows\u00ae: The amount of available disk space and available virtual address space.</li> <li>z/OS\u00ae: The amount of swap space available to the system.</li> </ul> <p>Non-persistent caches are stored in shared memory and are removed when a system is rebooted. On systems other than Windows, non-persistent caches are allocated by using the System V IPC shared memory mechanism. To ensure that sufficient shared memory is available for class data sharing, see Setting shared memory values.</p> <p> Note: By default, a cache is persistent on all platforms, except z/OS.</p>"},{"location":"xscmx/#see-also","title":"See also","text":"<ul> <li><code>-Xscdmx</code> (control the size of the class debug area)</li> </ul>"},{"location":"xshareclasses/","title":"-Xshareclasses","text":""},{"location":"xshareclasses/#-xshareclasses","title":"-Xshareclasses","text":"<p>Use the <code>-Xshareclasses</code> option to enable, disable, or modify class sharing behavior. Class data sharing is enabled by default for bootstrap classes only (the equivalent of specifying <code>-Xshareclasses:bootClassesOnly,nonFatal,silent</code>), unless your application is running in a container.</p> <p>This option can take a number of parameters, some of which are cache utilities. Cache utilities carry out specific operations on a specified cache without starting the Java virtual machine (VM). Although you can combine multiple suboptions, which are separated by commas, the cache utilities are mutually exclusive.</p> <p>Some cache utilities can work with caches from previous Java\u2122 versions or caches that are created by VMs with different bit-widths. These caches are referred to as \"incompatible\" caches.</p> <p>See also the Class data sharing topic, which includes some best practices for using <code>-Xshareclasses</code>.</p>"},{"location":"xshareclasses/#syntax","title":"Syntax","text":"<pre><code>    -Xshareclasses:&lt;parameter&gt;\n</code></pre> <p>When you specify <code>-Xshareclasses</code> without any parameters and without specifying either the <code>-Xscmx</code> or <code>-XX:SharedCacheHardLimit</code> options, a shared classes cache is created with a default size, as follows:</p> <ul> <li>For 64-bit platforms, the default size is 300 MB, with a \"soft\" maximum limit for the initial size of the cache (<code>-Xscmx</code>) of 64 MB, with the following exceptions:<ul> <li>For a persistent cache, if the free disk space is less than 6 GB, the default size is set to 64 MB and an <code>-Xscmx</code> size is not set.</li> <li>For a non-persistent cache on Linux\u00ae or macOS\u00ae systems, the cache size is limited by the maximum amount of memory that can be reserved by a process (<code>SHMMAX</code>). If <code>SHMMAX</code> is less than 300 MB, the default shared cache size is set to equal <code>SHMMAX</code>. If <code>SHMMAX</code> is greater than 80 MB, <code>-Xscmx</code> is set to 64 MB. If <code>SHMMAX</code> is less than 80 MB an <code>-Xscmx</code> size is not set.</li> </ul> </li> <li>For other platforms, the default size is 16 MB.</li> </ul>"},{"location":"xshareclasses/#parameters","title":"Parameters","text":""},{"location":"xshareclasses/#adjustmaxaot-cache-utility","title":"<code>adjustmaxaot</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustmaxaot=&lt;size&gt;\n</code></pre> Adjusts the maximum shared classes cache space that is allowed for AOT data. When you use the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the <code>-Xscmaxaot</code> option."},{"location":"xshareclasses/#adjustminaot-cache-utility","title":"<code>adjustminaot</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustminaot=&lt;size&gt;\n</code></pre> Adjusts the minimum shared classes cache space that is reserved for AOT data. Use the <code>-Xscminaot</code> option to set the initial minimum size."},{"location":"xshareclasses/#adjustmaxjitdata-cache-utility","title":"<code>adjustmaxjitdata</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustmaxjitdata=&lt;size&gt;\n</code></pre> Adjusts the maximum shared classes cache space that is allowed for JIT data. When you use the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the <code>-Xscmaxjitdata</code> option."},{"location":"xshareclasses/#adjustminjitdata-cache-utility","title":"<code>adjustminjitdata</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustminjitdata=&lt;size&gt;\n</code></pre> Adjusts the minimum shared classes cache space that is reserved for JIT data. Use the <code>-Xscminjitdata</code> option to set the initial minimum size."},{"location":"xshareclasses/#adjustsoftmx-cache-utility","title":"<code>adjustsoftmx</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustsoftmx=&lt;size&gt;\n</code></pre> Adjusts the soft maximum size of the cache. When you use the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the soft maximum size. For more information about the soft maximum size, see -Xscmx."},{"location":"xshareclasses/#allowclasspaths","title":"<code>allowClasspaths</code>","text":"<pre><code>    -Xshareclasses:allowClasspaths\n</code></pre> Allows a VM to store classpaths into an existing shared cache that was created by using the <code>restrictClasspaths</code> option."},{"location":"xshareclasses/#bootclassesonly","title":"<code>bootClassesOnly</code>","text":"<pre><code>    -Xshareclasses:bootClassesOnly\n</code></pre> Disables caching of classes that are loaded by class loaders other than the bootstrap class loader. If you use this suboption, the <code>nonfatal</code> suboption is also set, so this suboption is the equivalent of specifying <code>-Xshareclasses:bootClassesOnly,nonfatal</code>."},{"location":"xshareclasses/#cachedir","title":"<code>cacheDir</code>","text":"<pre><code>    -Xshareclasses:cacheDir=&lt;directory&gt;\n</code></pre> <p>Sets the directory in which cache data is read and written. Do not set the cache directory on an NFS mount or a shared mount across systems or LPARs. The following defaults apply:</p> <ul> <li>On Windows\u2122 systems, <code>&lt;directory&gt;</code> is the user's <code>C:\\Users\\&lt;username&gt;\\AppData\\Local\\javasharedresources</code> directory.</li> <li>On z/OS\u00ae systems, <code>&lt;directory&gt;</code> is the <code>/tmp/javasharedresources</code> directory.</li> <li>On other operating systems, <code>&lt;directory&gt;</code> is <code>.cache/javasharedresources</code> in the user's home directory, unless the <code>groupAccess</code> parameter is specified, in which case it is <code>/tmp/javasharedresources</code>, because some members of the group might not have access to the user's home directory. You must have sufficient permissions in <code>&lt;directory&gt;</code>. Do not set user's home directory on a NFS or shared mount.</li> </ul> <p>On AIX\u00ae, Linux, macOS, and Windows systems, the VM writes persistent cache files directly into the directory specified. Persistent cache files can be safely moved and deleted from the file system.</p> <p>Non-persistent caches are stored in shared memory and have control files that describe the location of the memory. Control files are stored in a <code>javasharedresources</code> subdirectory of the <code>cacheDir</code> specified. Do not move or delete control files in this directory. The <code>listAllCaches</code> utility, the <code>destroyAll</code> utility, and the <code>expire</code> suboption work only in the scope of a given <code>cacheDir</code>.</p> <p>On AIX, Linux, and macOS systems, if you specify the <code>cacheDir=&lt;directory&gt;</code> option, persistent caches are created with the following permissions (<code>-rw-r--r--</code>):</p> <ul> <li>User: read/write</li> <li>Group: read (read/write if you also specify <code>-Xshareclasses:groupAccess</code>)</li> <li>Other: read only</li> </ul> <p>Otherwise, persistent caches are created with the same permissions as non-persistent caches. The permissions for non-persistent caches are <code>-rw-r-----</code>, or <code>-rw-rw----</code> if you also specify <code>-Xshareclasses:groupAccess</code>.</p> <p> Note: It is good practice to set an application-specific cache directory to avoid sharing the default cache directory with the default cache, or other application caches that don't set a cache directory, and means that your application is therefore unaffected by a user running <code>java -Xshareclasses:destroyAll</code>. See Class data sharing: Best practices for using <code>-Xshareclasses</code>.</p>"},{"location":"xshareclasses/#cachedirperm","title":"<code>cacheDirPerm</code>","text":"(Not Windows)<pre><code>-Xshareclasses:cacheDirPerm=&lt;permission&gt;\n</code></pre> <p>Sets Unix-style permissions when you are creating a cache directory. <code>&lt;permission&gt;</code> must be an octal number in the ranges 0700 - 0777 or 1700 - 1777. If <code>&lt;permission&gt;</code> is not valid, the VM ends with an appropriate error message.</p> <p>The permissions that are specified by this suboption are used only when you are creating a new cache directory. If the cache directory already exists, this suboption is ignored and the cache directory permissions are not changed.</p> <p>If you set this suboption to 0000, the default directory permissions are used. If you set this suboption to 1000, the machine default directory permissions are used, but the sticky bit is enabled.</p> <p>If the cache directory is the platform default directory, <code>&lt;HomeDir&gt;/.cache/javasharedresources</code>,  being the user's home directory, this suboption is ignored and the cache directory permissions are set to 0777. <p>If you do not set this suboption, the default permissions are used according to the following conditions:</p> Condition Permissions The cache directory is <code>&lt;HomeDir&gt;/.cache/javasharedresources</code>. If this directory already exists with different permissions, the permissions are changed when the cache is opened.\u2020 0777 The cache directory is a new directory and you also specify the <code>groupAcess</code> suboption 0770 The cache directory is a new directory and you do not specify the <code>groupAccess</code> suboption 0700 The cache directory already exists and is not <code>&lt;HomeDir&gt;/.cache/javasharedresources</code> Unchanged \u2020On z/OS\u00ae systems, permissions for existing cache directories are unchanged, to avoid generating RACF\u00ae errors, which generate log messages. Note: It is good practice to explicitly set permissions for the cache directory when the defaults are not appropriate. See Class data sharing: Best practices for using <code>-Xshareclasses</code>."},{"location":"xshareclasses/#cacheretransformed","title":"<code>cacheRetransformed</code>","text":"<pre><code>    -Xshareclasses:cacheRetransformed\n</code></pre> Enables caching of classes that are transformed by using the JVMTI <code>RetransformClasses</code> function. For more information, see Redefined and retransformed classes. <p>The option <code>enableBCI</code> is enabled by default. However, if you use the <code>cacheRetransformed</code> option, this option forces cache creation into <code>-Xshareclasses:disableBCI</code> mode.</p>"},{"location":"xshareclasses/#checkurltimestamps","title":"<code>checkURLTimestamps</code>","text":"<pre><code>    -Xshareclasses:checkURLTimestamps\n</code></pre> Causes timestamps of <code>jar</code> or <code>zip</code> files to be checked every time a class is loaded. If a timestamp has changed, the class is loaded from the <code>jar</code> or <code>zip</code> file and not from the shared cache. This suboption is not enabled by default and reflects the legacy behavior of the shared classes cache. Note: The timestamp of a bootstrap <code>jar</code> or <code>zip</code> file is checked once when it is used for the first time to load a class."},{"location":"xshareclasses/#createlayer","title":"<code>createLayer</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xshareclasses:createLayer\n</code></pre> Creates layered caches. If there are multiple VMs in a race condition while creating a layered cache, more than one new layered cache can be created. To avoid this situation, use the <code>-Xshareclasses:layer=&lt;number&gt;</code> suboption to create a new layered cache with a specific layer number. See <code>layer</code> for more information about layered caches."},{"location":"xshareclasses/#destroy-cache-utility","title":"<code>destroy</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:destroy\n</code></pre> Destroys a cache that is specified by the <code>name</code>, <code>cacheDir</code>, and <code>nonpersistent</code> suboptions. A cache can be destroyed only if all VMs that are using it have ended and the user has sufficient permissions."},{"location":"xshareclasses/#destroyall-cache-utility","title":"<code>destroyAll</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:destroyAll\n</code></pre> Tries to destroy all the caches that are specified by the <code>cacheDir</code> and <code>nonpersistent</code> suboptions. On Windows and z/OS systems, a cache can be destroyed only if all VMs that are using it have shut down and the user has sufficient permissions. Note: On z/OS, when the <code>destroyAll</code> option is invoked from a 31-bit VM, 64-bit caches are not destroyed. Similarly, when the <code>destroyAll</code> option is invoked from a 64-bit VM, 31-bit caches are not destroyed. The following message is displayed:<pre><code>JVMSHRC735I: Use a nn-bit VM to perform the requested operation on the\nnn-bit shared cache \"cachename\" as the nn-bit VM\ncannot verify that the shared memory was created by the VM.\n</code></pre> <p>On AIX, Linux, and macOS systems:</p> <ul> <li> <p>Non-persistent caches can be destroyed only if all VMs that are using it have shut down and the user has sufficient permissions.</p> </li> <li> <p>Persistent caches that are still in use continue to exist even when you use this option, but they are unlinked from the file system so they are not visible to new VM invocations. If you update the VM then restart an application for which a persistent shared cache already exists, the VM unlinks the existing cache and creates a new cache. Because the unlinked caches are not visible to new VMs, you cannot find them by using the <code>-Xshareclasses:listAllCaches</code> option, and you cannot use the <code>-Xshareclasses:printStats</code> option on them. You can therefore have multiple unlinked caches that consume file system space until they are no longer in use.</p> </li> </ul>"},{"location":"xshareclasses/#destroyalllayers-cache-utility","title":"<code>destroyAllLayers</code> (Cache utility)","text":"<p>(64-bit only)</p> <pre><code>    -Xshareclasses:destroyAllLayers\n</code></pre> Destroys all shared cache layers that are specified by the <code>name</code> suboption. For example, <code>-Xshareclasses:name=Cache1,destroyAllLayers</code> destroys all layers of the cache called <code>Cache1</code>. If you use the <code>destroy</code> suboption on a layered cache, for example <code>-Xshareclasses:name=Cache1,destroy</code>, only the top layer of the cache is destroyed. For more information about layered caches, see Creating layer caches."},{"location":"xshareclasses/#destroyallsnapshots-cache-utility","title":"<code>destroyAllSnapshots</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:destroyAllSnapshots\n</code></pre> <p>Destroys all shared cache snapshots that are available as a result of the specified <code>cacheDir</code> suboption.</p>"},{"location":"xshareclasses/#destroysnapshot-cache-utility","title":"<code>destroySnapshot</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:destroySnapshot\n</code></pre> <p>Destroys a snapshot that is specified by the <code>name</code> and <code>cacheDir</code> suboptions.</p>"},{"location":"xshareclasses/#disablebci","title":"<code>disableBCI</code>","text":"<pre><code>    -Xshareclasses:disableBCI\n</code></pre> Turns off BCI support. This option can be used to override <code>-XXShareClassesEnableBCI</code>."},{"location":"xshareclasses/#enablebci","title":"<code>enableBCI</code>","text":"<pre><code>    -Xshareclasses:enableBCI\n</code></pre> This option is enabled by default. Allows a JVMTI <code>ClassFileLoadHook</code> event to be triggered every time, for classes that are loaded from the cache. This mode also prevents caching of classes that are modified by JVMTI agents. For more information about bytecode modification, see Support for bytecode instrumentation. This option is incompatible with the <code>cacheRetransformed</code> option. Using the two options together causes the VM to end with an error message, unless <code>-Xshareclasses:nonfatal</code> is specified. In this case, the VM continues without using shared classes. A cache that is created without the <code>enableBCI</code> suboption cannot be reused with the <code>enableBCI</code> suboption. Attempting to do so causes the VM to end with an error message, unless <code>-Xshareclasses:nonfatal</code> is specified. In this case, the VM continues without using shared classes. A cache that is created with the <code>enableBCI</code> suboption can be reused without specifying this suboption. In this case, the VM detects that the cache was created with the <code>enableBCI</code> suboption and uses the cache in this mode."},{"location":"xshareclasses/#expire-cache-utility","title":"<code>expire</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:expire=&lt;time_in_minutes&gt;\n</code></pre> Destroys all caches that are unused for the time that is specified before loading shared classes. This option is not a utility option because it does not cause the VM to exit. On Windows systems, which have NTFS file systems, the <code>expire</code> option is accurate to the nearest hour."},{"location":"xshareclasses/#fatal","title":"<code>fatal</code>","text":"<pre><code>    -Xshareclasses:fatal\n</code></pre> The VM does not start if class data sharing fails, for example because there was an error when accessing the cache directory. An error message is generated. This suboption is specified by default unless you use the <code>bootClassesOnly</code> suboption, which is equivalent to <code>-Xshareclasses:bootClassesOnly,nonfatal</code>. You can override this behavior by specifying <code>-Xshareclasses:bootClassesOnly,fatal</code>. See also <code>nonfatal</code>."},{"location":"xshareclasses/#findaotmethods-cache-utility","title":"<code>findAotMethods</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:findAotMethods=&lt;method_specification&gt;\n    -Xshareclasses:findAotMethods=help\n</code></pre> Print the AOT methods in the shared classes cache that match the method specifications. Methods that are already invalidated are indicated in the output. Use this suboption to check which AOT methods in the shared classes cache would be invalidated by using the same method specifications with the <code>invalidateAotMethods</code> suboption. To learn more about the syntax to use for <code>&lt;method_specification&gt;</code>, including how to specify more than one method, see Method specification syntax."},{"location":"xshareclasses/#groupaccess","title":"<code>groupAccess</code>","text":"(Not Windows)<pre><code>-Xshareclasses:groupAccess\n</code></pre> <p>Sets operating system permissions on a new cache to allow group access to the cache. Group access can be set only when permitted by the operating system <code>umask</code> setting. The default is user access only.</p> <p>On AIX, Linux, and macOS systems, if a user creates a cache by specifying the <code>groupAccess</code> suboption, other users in the same group must also specify this suboption to be granted access to the same cache.</p> <p>When <code>groupAccess</code> is specified, the default directory for a cache is <code>/tmp/javasharedresources</code>. Some systems might clear the content of the <code>/tmp</code> directory on a reboot, removing the shared cache. To avoid that problem, you are therefore recommended to use <code>cacheDir</code> to set a different location for the cache. If necessary, use <code>cacheDirPerm</code> to ensure that the cache directory permissions are set appropriately.</p> <p>In certain situations, warning messages might be generated when the <code>groupAccess</code> suboption is used.</p> <p>This message can occur when persistent caches are used:</p> <pre><code>JVMSHRC756W Failed to set group access permission on the shared cache\nfile as requested by the 'groupAccess' sub-option\n</code></pre> <p>These messages can occur when non-persistent caches are used:</p> <pre><code>JVMSHRC759W Failed to set group access permission as requested by the\n'groupAccess' sub-option on the semaphore control file associated\nwith shared classes cache.\n\nJVMSHRC760W Failed to set group access permission as requested by the\n'groupAccess' sub-option on the shared memory control file associated\nwith shared classes cache.\n</code></pre> <p>This message can occur in combination with the <code>snapshotCache</code> suboption:</p> <pre><code>JVMSHRC761W Failed to set group access permission as requested by the\n'groupAccess' sub-option on the shared cache snapshot file.\n</code></pre> <p>All of these warning messages mean that the user's umask setting does not allow either, or both, of the group <code>read</code> and <code>write</code> permission to be set on the file. The typical umask setting restricts only the <code>write</code> permission. To resolve the warning, either change the umask setting or remove the <code>groupAccess</code> suboption.</p>"},{"location":"xshareclasses/#help","title":"<code>help</code>","text":"<pre><code>    -Xshareclasses:help\n</code></pre> Lists all the command-line options."},{"location":"xshareclasses/#invalidateaotmethods-cache-utility","title":"<code>invalidateAotMethods</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:invalidateAotMethods=&lt;method_specification&gt;\n    -Xshareclasses:invalidateAotMethods=help\n</code></pre> Modify the existing shared cache to invalidate the AOT methods that match the method specifications. Use this suboption to invalidate AOT methods that cause a failure in the application, without having to destroy the shared cache. Invalidated AOT methods remain in the shared cache, but are then excluded from being loaded. VMs that have not processed the methods, or new VMs that use the cache are not affected by the invalidated methods. The AOT methods are invalidated for the lifetime of the cache, but do not prevent the AOT methods from being compiled again if a new shared cache is created. To prevent AOT method compilation into a new shared cache, use the <code>-Xaot:exclude</code> option. For more information, see -Xaot. To identify AOT problems, see Diagnosing a JIT or AOT problem. To revalidate an AOT method, see the <code>revalidateAotMethods</code> suboption. Use the <code>findAotMethod</code> suboption to determine which AOT methods match the method specifications. To learn more about the syntax to use for <code>&lt;method_specification&gt;</code>, including how to specify more than one method, see Method specification syntax."},{"location":"xshareclasses/#layer","title":"<code>layer</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xshareclasses:layer=&lt;number&gt;\n</code></pre> Creates layered caches. This suboption has the same effect as the <code>createLayer</code> suboption, but with the added ability to specify the layer number. For more information about creating a shared classes cache with layers, see Creating layer caches."},{"location":"xshareclasses/#listallcaches-cache-utility","title":"<code>listAllCaches</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:listAllCaches\n</code></pre> Lists all the compatible and incompatible caches, and snapshots that exist in the specified cache directory. If you do not specify <code>cacheDir</code>, the default directory is used. Summary information, such as Java version and current usage, is displayed for each cache. Output includes <code>cache-type</code> (persistent or non-persistent) and <code>feature</code> (compressed references (<code>cr</code>) or non-compressed references (<code>non-cr</code>))."},{"location":"xshareclasses/#mprotect","title":"<code>mprotect</code>","text":"AIX, z/OS 31-bit:<pre><code>-Xshareclasses:mprotect=[default|all|none]\n</code></pre> <p>Linux, Windows, macOS:</p> <pre><code>-Xshareclasses:mprotect=[default|all|partialpagesonstartup|onfind|nopartialpages|none]\n</code></pre> <p>where:</p> <ul> <li><code>default</code>: By default, the memory pages that contain the cache are always protected, unless a specific page is being updated. This protection helps prevent accidental or deliberate corruption to the cache. The cache header is not protected by default because this protection has a performance cost. On Linux, macOS, and Windows systems, after the startup phase, the Java virtual machine (VM) protects partially filled pages whenever new data is added to the shared classes cache in the following sequence:<ul> <li>The VM changes the memory protection of any partially filled pages to read/write.</li> <li>The VM adds the data to the cache.</li> <li>The VM changes the memory protection of any partially filled pages to read only.</li> </ul> </li> <li><code>all</code>: This value ensures that all the cache pages are protected, including the header. See Note.</li> <li><code>partialpagesonstartup</code>: This value causes the VM to protect partially filled pages during startup as well as after the startup phase. This value is available only on Linux, macOS, and Windows systems.</li> <li><code>onfind</code>: When this option is specified, the VM protects partially filled pages when it reads new data in the cache that is added by another VM. This option is available only on Linux, macOS, and Windows systems.</li> <li><code>nopartialpages</code>: Use this value to turn off the protection of partially filled pages. This value is available only on Linux, macOS, and Windows systems.</li> <li><code>none</code>: Specifying this value disables the page protection.</li> </ul> <p> Note: Specifying <code>all</code> has a negative impact on performance. You should specify <code>all</code> only for problem diagnosis and not for production. Specifying values <code>partialpagesonstartup</code> or <code>onfind</code> can also have a negative impact on performance when the cache is being populated. There is no further impact when the cache is full or no longer being modified.</p>"},{"location":"xshareclasses/#modified","title":"<code>modified</code>","text":"<pre><code>    -Xshareclasses:modified=&lt;modified_context&gt;\n</code></pre> Used when a JVMTI agent is installed that might modify bytecode at run time. If you do not specify this suboption and a bytecode modification agent is installed, classes are safely shared with an extra performance cost. The <code>&lt;modified context&gt;</code> is a descriptor that is chosen by the user; for example, myModification1. This option partitions the cache so that only VMs that are using context myModification1 can share the same classes. So if, for example, you run an application with a modification context and then run it again with a different modification context, all classes are stored twice in the cache. For more information, see Sharing modified bytecode. If you are migrating from IBM\u00ae SDK, Java Technology Edition, Version 7, or earlier releases, you must set <code>-Xshareclasses:disableBCI</code> when you use this option to retain the same behavior."},{"location":"xshareclasses/#name","title":"<code>name</code>","text":"<pre><code>    -Xshareclasses:name=&lt;name&gt;\n</code></pre> Connects to a cache of a given name, creating the cache if it does not exist. This option is also used to indicate the cache that is to be modified by cache utilities; for example, <code>destroy</code>. Use the <code>listAllCaches</code> utility to show which named caches are currently available. If you do not specify a name, the default name \"sharedcc_%u\" is used. \"%u\" in the cache name inserts the current user name. On operating systems other than Windows, you can specify \"%g\" in the cache name to insert the current group name. Note: It is good practice to explicitly specify a cache for your application. This avoids the application sharing a cache that is enabled by default or with another application that doesn't set a name, and ensures that the size of your application cache can be set appropriately and that cache space is used exclusively for your application. Note that you cannot change the size of a default cache that already exists by using the <code>-Xscmx</code> option, as that option has no effect on a pre-existing cache. See Class data sharing: Best practices for using <code>-Xshareclasses</code>."},{"location":"xshareclasses/#noaot","title":"<code>noaot</code>","text":"<pre><code>    -Xshareclasses:noaot\n</code></pre> Disables caching and loading of AOT code. AOT code already in the shared data cache can be loaded."},{"location":"xshareclasses/#nobootclasspath","title":"<code>noBootclasspath</code>","text":"<pre><code>    -Xshareclasses:noBootclasspath\n</code></pre> Disables the storage of classes that are loaded by the bootstrap class loader in the shared classes cache. Often used with the <code>SharedClassURLFilter</code> API to control exactly which classes are cached. For more information about shared class filtering, see The Java shared classes Helper API."},{"location":"xshareclasses/#notimestampchecks","title":"<code>noTimestampChecks</code>","text":"<pre><code>    -Xshareclasses:noTimestampChecks\n</code></pre> Turns off timestamp checking when finding classes in the shared cache. Use this option only when you know there are no updates to the classes from the class paths or module paths in your application. Otherwise, obsolete classes might be loaded from the shared cache. If this happens, remove the <code>noTimestampChecks</code> option."},{"location":"xshareclasses/#nocheckurltimestamps","title":"<code>nocheckURLTimestamps</code>","text":"<pre><code>    -Xshareclasses:nocheckURLTimestamps\n</code></pre> Timestamps of <code>jar</code> or <code>zip</code> files are checked only when they are added to a class loader and used for the first time to look up a class. This is the default behavior, which can improve the performance of class loading from the shared classes cache, especially on Windows systems. To revert to the behavior of the shared classes cache in earlier releases, use the <code>CheckURLTimeStamps</code> suboption. Restriction: When the <code>nocheckURLTimestamps</code> suboption is used (default), if <code>jar</code> or <code>zip</code> files are updated after a class loader starts loading classes from them, an older version of the class might be loaded from the shared classes cache. If this scenario occurs, use the <code>checkURLTimestamps</code> option."},{"location":"xshareclasses/#nojitdata","title":"<code>nojitdata</code>","text":"<pre><code>    -Xshareclasses:nojitdata\n</code></pre> Disables caching of JIT data. JIT data already in the shared data cache can be loaded."},{"location":"xshareclasses/#none","title":"<code>none</code>","text":"<pre><code>    -Xshareclasses:none\n</code></pre> Added to the end of a command line, disables class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption disables the shared class utility APIs. To disable class data sharing without disabling the utility APIs, use the <code>utilities</code> suboption. For more information about the shared class utility APIs, see The Java shared classes utility API."},{"location":"xshareclasses/#nonfatal","title":"<code>nonfatal</code>","text":"<pre><code>    -Xshareclasses:nonfatal\n</code></pre> Allows the VM to start, in most cases, even if class data sharing fails. Normal behavior for the VM is to refuse to start if class data sharing fails. If you select <code>nonfatal</code> and the shared classes cache fails to initialize, the VM attempts to connect to the cache in read-only mode. If this attempt fails, the VM starts without class data sharing. See also <code>fatal</code>. Note: Unless it is important that your application runs with class data sharing, it is good practice to set this parameter. See Creating a shared classes cache. However, cache corruption as a result of a bug in the operating system, VM, or user code might not be detected when opening the cache. In this situation, the cache is used and the application might crash."},{"location":"xshareclasses/#nonpersistent","title":"<code>nonpersistent</code>","text":"<pre><code>    -Xshareclasses:nonpersistent\n</code></pre> Uses a non-persistent cache. The cache is lost when the operating system shuts down. Non-persistent and persistent caches can have the same name. On Linux, macOS, and Windows systems, you must always use the <code>nonpersistent</code> suboption when you run utilities such as <code>destroy</code> on a non-persistent cache. Note: On macOS systems, you must set <code>kern.sysv.shmmax</code> and <code>kern.sysv.shmall</code> when using a non-persistent cache."},{"location":"xshareclasses/#nopersistentdiskspacecheck","title":"<code>noPersistentDiskSpaceCheck</code>","text":"<pre><code>    -Xshareclasses:noPersistentDiskSpaceCheck\n</code></pre> Instructs the VM not to check for available storage on the file system before creating a persistent shared classes cache. This option prevents an error on file systems that do not support the checking of free space, where a value of 0 is returned and a shared cache cannot be created. Regardless of whether you choose to set this option, if there isn't enough disk space available when the VM writes to the shared cache memory, a SIGBUS or SIGSEGV signal occurs and the VM ends. If you are using the <code>readonly</code> suboption, the VM does not check the available disk space, so you do not need to set the <code>noPersistentDiskSpaceCheck</code> suboption."},{"location":"xshareclasses/#persistent","title":"<code>persistent</code>","text":"<pre><code>    -Xshareclasses:persistent\n</code></pre> Uses a persistent cache. The cache is created on disk, which persists beyond operating system restarts. Non-persistent and persistent caches can have the same name. On AIX, you must always use the <code>persistent</code> suboption when you run utilities such as <code>destroy</code> on a persistent cache. Notes: <ul> <li>With the 31-bit VM on all versions of z/OS, the shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared class cache is limited by the system limit <code>MAXMMAPAREA</code>. For more information about the suggested value for the <code>MAXMMAPAREA</code> limit, see Setting resource limits (z/OS).</li> <li> <p>With the 64-bit VM, the shared cache is mapped as follows:</p> <ul> <li>On z/OS version 2.3 and earlier, the persistent shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared class cache is limited by the system limit <code>MAXMMAPAREA</code>.</li> <li> <p>On z/OS version 2.4 and later, the persistent shared cache is mapped above the 2 GB address range. The maximum size of persistent shared class cache is limited by the <code>MAXSHARE</code> value within the <code>SMFLIMxx</code> member of <code>SYS1.PARMLIB</code>. You can use the following machine configuration to create up to 1 GB shared class cache mapped above the 2 GB address range:</p> <ol> <li>Add the following line in the SMFLIMxx member of SYS1.PARMLIB.</li> </ol> <p><code>REGION JOBNAME(*) MAXSHARE(262144)</code></p> <ol> <li>Load the change with the following command in the SDSF panel.</li> </ol> <p><code>/SET SMFLIM=xx</code></p> </li> </ul> <p>For more information about the SMFLIMxx member of SYS1.PARMLIB, see Statements and parameters for SMFLIMxx.</p> <p>On z/OS version 2.4, fixes for APARs OA60306 and PH32235 must be installed for the support of this memory mapping. On z/OS version 2.5 and later, the fixes for APARs OA60306 and PH32235 are included by default.</p> </li> </ul>"},{"location":"xshareclasses/#printallstats-cache-utility","title":"<code>printAllStats</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:printAllStats\n</code></pre> Displays detailed information about the contents of the cache that is specified in the <code>name</code> suboption. If the name is not specified, statistics are displayed about the default cache. For layered caches, information is shown for all layers (to see information for the top layer cache only, use <code>printTopLayerStats=all</code>). Every class is listed in chronological order with a reference to the location from which it was loaded. For more information, see Shared classes cache diagnostic utilities."},{"location":"xshareclasses/#printstats-cache-utility","title":"<code>printStats</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:printStats=&lt;data_type&gt;[+&lt;data_type&gt;]\n</code></pre> Displays summary information for the cache that is specified by the <code>name</code>, <code>cacheDir</code>, and <code>nonpersistent</code> suboptions. For layered caches, information is shown for all layers (to see information for the top layer cache only, use <code>printTopLayerStats</code>). The most useful information that is displayed is how full the cache is and how many classes it contains. Stale classes are classes that are updated on the file system and which the cache has therefore marked as \"stale\". Stale classes are not purged from the cache and can be reused. Use the <code>printStats=stale</code> option to list all the stale entries and stale bytes. Specify one or more data types, which are separated by a plus symbol (+), to see more detailed information about the cache content. Data types include AOT data, class paths, and ROMMethods. For more information and for a full list of data types, see Shared classes cache diagnostic utilities."},{"location":"xshareclasses/#printtoplayerstats-cache-utility","title":"<code>printTopLayerStats</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:printTopLayerStats=&lt;data_type&gt;[+&lt;data_type&gt;]\n</code></pre> Equivalent to <code>printStats</code> but for the top layer cache only. For more information about layered caches, see Creating a layer cache."},{"location":"xshareclasses/#readonly","title":"<code>readonly</code>","text":"<pre><code>    -Xshareclasses:readonly\n</code></pre> By default, a shared classes cache is created with read/write access. Use the <code>readonly</code> suboption to open an existing cache with read-only permissions. Opening a cache read-only prevents the VM from making any updates to the cache. If you specify this suboption, the VM can connect to caches that were created by other users or groups without requiring write access. On AIX, Linux, and macOS systems, this access is permitted only if the cache was created by using the <code>-Xshareclasses:cacheDir</code> option to specify a directory with appropriate permissions. If you do not use the <code>-Xshareclasses:cacheDir</code> option, the cache is created with default permissions, which do not permit access by other users or groups. By default, this suboption is not specified. The <code>-Xshareclasses:readonly</code> option is ignored under the following conditions: <ul> <li>The JITServer AOT cache feature is enabled (<code>-XX:+JITServerUseAOTCache</code>), and the VM is a client.</li> <li>The VM is running in a container.</li> <li>AOT compilation is enabled. For more information about AOT compilation, see the Ahead-Of-Time (AOT) compiler topic.</li> <li>The shared class cache is persistent. (<code>-Xshareclasses:persistent</code>)</li> </ul> <p>If a persistent shared class cache is started under the mentioned conditions, the cache startup creates a temporary new (writable) top layer. The JITServer AOT cache uses the new top layer to store a small amount of metadata that the cache needs to function. With this top layer, the JITServer AOT cache can be used without modifying the existing layers.</p>"},{"location":"xshareclasses/#reset","title":"<code>reset</code>","text":"<pre><code>    -Xshareclasses:reset\n</code></pre> Causes a cache to be destroyed and then re-created when the VM starts up. This option can be added to the end of a command line as <code>-Xshareclasses:reset</code>."},{"location":"xshareclasses/#restorefromsnapshot-cache-utility","title":"<code>restoreFromSnapshot</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:restoreFromSnapshot\n</code></pre> <p>Restores a new non-persistent shared cache from a snapshot file. The snapshot and shared cache have the same name and location, as specified by the <code>name</code> and <code>cacheDir</code> suboptions. The non-persistent cache cannot already exist when the snapshot is restored. Restoring a snapshot does not remove the snapshot file; it can be restored multiple times. On platforms that support persistent caches, the <code>nonpersistent</code> suboption must be specified in order to restore a snapshot.</p>"},{"location":"xshareclasses/#restrictclasspaths","title":"<code>restrictClasspaths</code>","text":"<pre><code>    -Xshareclasses:restrictClasspaths\n</code></pre> Allows only the first VM that is initializing a shared cache to store classpaths in the cache. Subsequent VMs are not allowed to store classpaths in the cache unless the <code>allowClasspaths</code> option is specified. Use the <code>restrictClasspaths</code> option only if the application is designed to create class loaders of type <code>java.net.URLClassloader</code> or its subclass, such that their classpaths are unique to the instance of the application, but the classes that are loaded from these classpaths are the same. In such cases application classpaths that are stored by one VM cannot be used by another VM. <p>For example, consider two VMs, VM1 and VM2, that are using class paths CP1 and CP2 respectively, where:</p> <ul> <li>CP1: <code>url1;url2;url3;tempurl1;url4;url5</code></li> <li>CP2: <code>url1;url2;url3;tempurl2;url4;url5</code></li> </ul> <p>These class paths differ only by one entry, which is the <code>tempurl</code>. The <code>url1</code>, <code>url2</code>, <code>url3</code>, <code>url4</code>, and <code>url5</code> entries never change from run to run, whereas the <code>tempurl</code> entry is always different. This difference means that a class that is loaded from <code>url4</code> or <code>url5</code>, and stored into the shared cache by VM1, cannot be located by VM2. Therefore, an attempt by VM2 to load a class from <code>url4</code> or <code>url5</code> would cause it to store its own classpath <code>CP2</code> into the shared cache, and also add new metadata for classes that are loaded from <code>url4</code> or <code>url5</code>. Addition of such unique class paths into the shared cache is not useful. Moreover, the additional metadata might adversely affect the performance of other VMs that connect to the shared cache. Because classes loaded from <code>url4</code> or <code>url5</code> are not loaded from the shared cache when the <code>tempurl</code> differs from the original, it is good practice to put the <code>tempurl</code> as the last entry in the class path.</p> <p>In situations such as that described in the example, the <code>restrictClasspaths</code> option can be used to restrict the addition of classpaths by ensuring that the first VM initializes the shared cache, and then prevents the addition of unique classpaths by subsequent VMs that attach to the shared cache. Note that use of the <code>restrictClasspaths</code> option in any other scenario is likely to negatively impact a VM's performance when it is using an existing cache.</p>"},{"location":"xshareclasses/#revalidateaotmethods-cache-utility","title":"<code>revalidateAotMethods</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:revalidateAotMethods=&lt;method_specification&gt;\n    -Xshareclasses:revalidateAotMethods=help\n</code></pre> Modify the shared cache to revalidate the AOT methods that match the method specifications. Use this suboption to revalidate AOT methods that were invalidated by using the <code>invalidateAotMethods</code> suboption. Revalidated AOT methods are then eligible for loading into a VM, but do not affect VMs where the methods have already been processed. To learn more about the syntax to use for <code>&lt;method_specification&gt;</code>, including how to specify more than one method, see Method specification syntax."},{"location":"xshareclasses/#silent","title":"<code>silent</code>","text":"<pre><code>    -Xshareclasses:silent\n</code></pre> Disables all shared class messages, including error messages. Unrecoverable error messages, which prevent the VM from initializing, are displayed."},{"location":"xshareclasses/#snapshotcache-cache-utility","title":"<code>snapshotCache</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:snapshotCache\n</code></pre> <p>Creates a snapshot file of an existing non-persistent shared cache. The snapshot has the same name and location as the shared cache, as specified by the <code>name</code> and <code>cacheDir</code> suboptions. The shared cache can be in use when the snapshot is taken, but VMs are blocked when they try to write to the shared cache, while the cache data is copied to the file.</p> <p>Typically, after a system is reinitialized, the snapshot file is used to restore the copy of the non-persistent cache into shared memory, via the <code>restoreFromSnapshot</code> suboption. Since this process removes all non-persistent caches from shared memory, restoring the cache from the snapshot file can result in better VM startup performance, because the contents of the shared cache, including classes and AOT code, do not have to be re-created.</p> <p>A snapshot can be created only if the user has sufficient permissions to create the destination snapshot file. If a snapshot of the same name exists already, it is overwritten. On platforms that support persistent caches, the <code>nonpersistent</code> suboption must be specified in order to create a snapshot. For information about removing snapshot files, see the <code>destroySnapshot</code> and <code>destroyAllSnapshots</code> suboptions.</p>"},{"location":"xshareclasses/#utilities","title":"<code>utilities</code>","text":"<pre><code>    -Xshareclasses:utilities\n</code></pre> Can be added to the end of a command line to disable class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption is like <code>none</code>, but does not disable the shared class utility APIs. For more information, see The Java shared classes utility API."},{"location":"xshareclasses/#verbose","title":"<code>verbose</code>","text":"<pre><code>    -Xshareclasses:verbose\n</code></pre> Gives detailed output on the cache I/O activity, listing information about classes that are stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders ask their parents for a class if they can't find it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy. The standard option <code>-verbose:class</code> also enables class sharing verbose output if class sharing is enabled."},{"location":"xshareclasses/#verboseaot","title":"<code>verboseAOT</code>","text":"<pre><code>    -Xshareclasses:verboseAOT\n</code></pre> Enables verbose output when compiled AOT code is being found or stored in the cache. AOT code is generated heuristically. You might not see any AOT code that is generated at all for a small application. You can disable AOT caching by using the <code>noaot</code> suboption. See the VM Messages Guide for a list of the messages produced."},{"location":"xshareclasses/#verbosehelper","title":"<code>verboseHelper</code>","text":"<pre><code>    -Xshareclasses:verboseHelper\n</code></pre> Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your class loader."},{"location":"xshareclasses/#verboseio","title":"<code>verboseIO</code>","text":"<pre><code>    -Xshareclasses:verboseIO\n</code></pre> Gives detailed output on the cache I/O activity, listing information about classes that are stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders must ask their parents for a class before they can load it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy."},{"location":"xshareclasses/#method-specification-syntax","title":"Method specification syntax","text":"<p>The following examples show how to specify more than one method specification when you are using the <code>findAotMethods</code>, <code>invalidateAotMethods</code>, or <code>revalidateAotMethods</code> suboptions.</p> <p>Each method specification is defined as follows:</p> <pre><code>&lt;packagename&gt;/&lt;classname&gt;[.&lt;methodname&gt;[(&lt;parameters&gt;)]]\n</code></pre> <p>If you want to include more than one method specification in a single option, separate the specifications with a comma and enclose all the specifications in {braces}. For example:</p> <pre><code>{&lt;packagename/classname&gt;}[.{&lt;methodname&gt;}[({&lt;parameters&gt;})]]\n</code></pre> <ul> <li>You can use an asterisk (*) in most places as a wildcard.</li> <li>You can use an exclamation point (!) before the specification to mean \"everything except this\".</li> <li>Parameters are optional, but if specified, should be enclosed in parentheses and the following native signature formats must be used:<ul> <li><code>B</code> for byte</li> <li><code>C</code> for char</li> <li><code>D</code> for double</li> <li><code>F</code> for float</li> <li><code>I</code> for int</li> <li><code>J</code> for long</li> <li><code>S</code> for short</li> <li><code>Z</code> for Boolean</li> <li><code>L&lt;classname&gt;;</code> for objects</li> <li><code>[</code> before the signature means array</li> </ul> </li> </ul> <p>If you want to specify parameters to distinguish between methods, you can use <code>-Xshareclasses:findAotMethods=*</code> (with a wildcard) to list all the parameter variations. Copy the signature for the method that you want from the output. For example, the signature for the parameters</p> <pre><code>(byte[] bytes, int offset, int length, Charset charset)\n</code></pre> <p>is</p> <pre><code>([BIILjava/nio/charset/Charset;)\n</code></pre> <p>Here are some examples:</p> Method signature Matches... <code>*</code> All AOT methods. <code>java/lang/Object</code> All AOT methods in the <code>java.lang.Object</code> class <code>java/util/*</code> All AOT classes and methods in the <code>java.util</code> package <code>java/util/HashMap.putVal</code> All <code>putVal</code> methods in the <code>java.util.HashMap</code> class <code>java/util/HashMap.hash(Ljava/lang/Object;)</code> The private <code>java.util.HashMap.hash(java.lang.Object)</code> method <code>*.equals</code> All <code>equals</code> methods in all classes <code>{java/lang/Object,!java/lang/Object.clone}</code> All methods in <code>java.lang.Object</code> except <code>clone</code> <code>{java/util/*.*(),java/lang/Object.*(*)}</code> All classes or methods with no input parameter in the <code>java.util</code> package, and all methods in <code>java.lang.Object</code> <code>{java/util/*.*(),!java/util/*.*()}</code> Nothing. <ul> <li>Introduction to class data sharing</li> <li>-Xscmx</li> <li>-XX:SharedCacheHardLimit</li> </ul>"},{"location":"xshareclassesdisableonrestore/","title":"-Xshareclasses:disableOnRestore","text":""},{"location":"xshareclassesdisableonrestore/#-xshareclassesdisableonrestore","title":"-Xshareclasses:disableOnRestore","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>The <code>-Xshareclasses</code> option is an existing option and <code>disableOnRestore</code> is its new parameter that can be used if the CRIU feature is available. This option is disabled by default.</p> <p> Restrictions:</p> <ul> <li>This option takes effect only when the <code>-XX:+EnableCRIUSupport</code> option is enabled.</li> <li>This option can be used only on restore.</li> </ul>"},{"location":"xshareclassesdisableonrestore/#parameters","title":"Parameters","text":""},{"location":"xshareclassesdisableonrestore/#disableonrestore","title":"<code>disableOnRestore</code>","text":"<pre><code>    -Xshareclasses:disableOnRestore\n</code></pre> <p>The <code>-Xshareclasses:disableOnRestore</code> option disables further use of the shared classes cache (SCC) on restore. You can still use the shared classes utility APIs, for example, to obtain metrics about the shared cache.</p> <p>The <code>-Xshareclasses:disableOnRestore</code> option is similar to the existing <code>-Xshareclasses:none</code> option but with the following differences:</p> <ul> <li>The <code>-Xshareclasses:none</code> option turns off the cache on the VM startup but the <code>-Xshareclasses:disableOnRestore</code> option turns off the cache on restore. If you turn off the cache on startup, then specifying the <code>-Xshareclasses:disableOnRestore</code> option has no impact because there is no cache existing in the checkpoint image for the option to disable.</li> <li>The <code>-Xshareclasses:none</code> option disables the shared classes utility APIs but the <code>-Xshareclasses:disableOnRestore</code> option keeps the utility APIs working.</li> </ul>"},{"location":"xshareclassesdisableonrestore/#see-also","title":"See also","text":"<ul> <li>-Xshareclasses</li> <li>CRIU support</li> </ul>"},{"location":"xsigcatch/","title":"-Xsigcatch","text":""},{"location":"xsigcatch/#-xsigcatch-xnosigcatch","title":"-Xsigcatch / -Xnosigcatch","text":"<p>Enables and disables VM signal handling code.</p>"},{"location":"xsigcatch/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xsigcatch</code> Enable yes <code>-Xnosigcatch</code> Disable"},{"location":"xsigcatch/#see-also","title":"See also","text":"<ul> <li>Signal handling</li> </ul>"},{"location":"xsigchain/","title":"-Xsigchain","text":""},{"location":"xsigchain/#-xsigchain-xnosigchain","title":"-Xsigchain / -Xnosigchain","text":"<p>Enables and disables signal handler chaining.</p>"},{"location":"xsigchain/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xsigchain</code> Enable yes (except on z/OS\u00ae) <code>-Xnosigchain</code> Disable"},{"location":"xsigchain/#see-also","title":"See also","text":"<ul> <li>Signal handling</li> </ul>"},{"location":"xsignal/","title":"-Xsignal","text":""},{"location":"xsignal/#-xsignal","title":"-Xsignal","text":"<p>(z/OS\u00ae only)</p> <p>This option controls the behavior of Eclipse OpenJ9\u2122 VM signal handlers.</p>"},{"location":"xsignal/#syntax","title":"Syntax","text":"<pre><code>    -Xsignal:&lt;parameter&gt;=&lt;value&gt;\n</code></pre>"},{"location":"xsignal/#parameters","title":"Parameters","text":"<p> Restriction: You cannot use these parameters together.</p>"},{"location":"xsignal/#posixsignalhandler","title":"<code>posixSignalHandler</code>","text":"<pre><code>    -Xsignal:posixSignalHandler=cooperativeShutdown\n</code></pre> <p>When the VM signal handlers for SIGSEGV, SIGILL, SIGBUS, SIGFPE, SIGTRAP, and SIGABRT end a process, they call <code>exit()</code>, by default. In this case, the z/OS\u2122 Language Environment\u00ae is not aware that the VM ended abnormally.</p> <p>With <code>-Xsignal:posixSignalHandler=cooperativeShutdown</code>, the VM no longer uses <code>exit()</code> to end the process from the signal handlers. Instead, the VM behaves in one of the following ways:</p> <ul> <li>In response to a z/OS hardware exception, the VM uses <code>return()</code>.</li> <li>In response to signals raised or injected by software, the VM ends the enclave with <code>abend 3565</code>.</li> </ul> <p>Language Environment detects that the VM is ending abnormally and initiates Resource Recovery Services.</p>"},{"location":"xsignal/#userconditionhandler","title":"<code>userConditionHandler</code>","text":"(31-bit z/OS only)<pre><code>-Xsignal:userConditionHandler=percolate\n</code></pre> <p>This option results in similar behavior to the <code>-XCEEHDLR</code> option: the VM registers user condition handlers to handle the z/OS exceptions that would otherwise be handled by the VM POSIX signal handlers for the SIGBUS, SIGFPE, SIGILL, SIGSEGV, and SIGTRAP signals.</p> <p>As with the <code>-XCEEHDLR</code> option, the VM does not install POSIX signal handlers for these signals.</p> <p>This option differs from the <code>-XCEEHDLR</code> option in that the VM percolates all Language Environment\u00ae conditions that were not triggered and expected by the VM during normal running, including conditions that are severity 2 or greater. The VM generates its own diagnostic information before percolating severity 2 or greater conditions.</p> <p>The VM is in an undefined state after percolating a severity 2 or greater condition. Applications cannot resume running then call back into, or return to, the VM.</p>"},{"location":"xsignal/#see-also","title":"See also","text":"<ul> <li><code>-XCEEHDLR</code></li> <li>Signal handling</li> </ul>"},{"location":"xsoftmx/","title":"-Xsoftmx","text":""},{"location":"xsoftmx/#-xsoftmx","title":"-Xsoftmx","text":"<p>This option sets a \"soft\" maximum limit for the Java\u2122 heap.</p>"},{"location":"xsoftmx/#syntax","title":"Syntax","text":"<pre><code>    -Xsoftmx&lt;size&gt;\n</code></pre>"},{"location":"xsoftmx/#explanation","title":"Explanation","text":"<p>Use the <code>-Xmx</code> option to set a \"hard\" limit for the maximum size of the heap. By default, <code>-Xsoftmx</code> is set to the same value as <code>-Xmx</code>. The value of <code>-Xms</code> must be less than, or equal to, the value of <code>-Xsoftmx</code>.</p> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>You can set this option on the command line, then modify it at run time by using the <code>MemoryMXBean.setMaxHeapSize()</code> method in the <code>com.ibm.lang.management</code> API. By using this API, Java applications can dynamically monitor and adjust the heap size as required. This function can be useful in virtualized or cloud environments, for example, where the available memory might change dynamically to meet business needs. When you use the API, you must specify the value in bytes, such as <code>2147483648</code> instead of <code>2g</code>.</p> <p>For example, you might set the initial heap size to 1 GB and the maximum heap size to 8 GB. You might set a smaller value, such as 2 GB, for <code>-Xsoftmx</code>, to limit the heap size that is used initially:</p> <pre><code>-Xms1g -Xsoftmx2g -Xmx8g\n</code></pre> <p>You can then use the <code>com.ibm.lang.management</code> API from within a Java application to increase the <code>-Xsoftmx</code> value during run time, as load increases. This change allows the application to use more memory than you specified initially.</p> <p>If you reduce the <code>-Xsoftmx</code> value, the garbage collector attempts to respect the new limit. However, the ability to shrink the heap depends on a number of factors. There is no guarantee that a decrease in the heap size will occur. If or when the heap shrinks to less than the new limit, the heap will not grow beyond that limit.</p> <p>When the heap shrinks, the garbage collector might release memory. The ability of the operating system to reclaim and use this memory varies based on the capabilities of the operating system.</p> <p> Notes:</p> <ul> <li>When using <code>-Xgcpolicy:gencon</code> with <code>-Xsoftmx</code>, the proportion of heap space used for nursery within the <code>-Xsoftmx</code> limit is proportional to the maximum amount of nursery space specified (see Xmn/Xmnx) relative to the <code>-Xmx</code> value. For example, if the following is specified on the command line <code>-Xsoftmx2g -Xmnx4g  -Xmx8g</code>, nursery space is allowed to use 50%(4G/8G) of the specified <code>-Xsoftmx</code> value, which in this example is 1G.</li> <li>When using <code>-Xgcpolicy:balanced</code> with <code>-Xsoftmx</code> and <code>-Xmn</code>/<code>-Xmnx</code>/<code>-Xmns</code> options,  the maximum and minimum size for eden are absolute (rather than the proportional nursery behaviour for gencon), and do not depend on the <code>-Xsoftmx</code> value specified. For example, if <code>-Xmnx1G</code> is specified, then eden will be able to grow up to <code>1G</code> in size, regardless of the <code>-Xsoftmx</code> value specified.</li> <li>This option is ignored if used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</li> <li>There might be little benefit in reducing the <code>-Xsoftmx</code> value when the Java heap is using large pages. Large pages are pinned in memory and are not reclaimed by the operating system, with the exception of 1M pageable pages on z/OS\u00ae. On certain platforms and processors the VM starts with large pages enabled by default for the Java heap when the operating system is configured to provide large pages. For more information, see Configuring large page memory allocation. A future version of the Java virtual machine might provide a hint to the operating system when large pages are no longer in use.</li> </ul>"},{"location":"xsoftrefthreshold/","title":"-Xsoftrefthreshold","text":""},{"location":"xsoftrefthreshold/#-xsoftrefthreshold","title":"-Xsoftrefthreshold","text":"<p>Sets the value used by the garbage collector to determine the number of garbage collection (GC) cycles after which a soft reference is cleared if its referent has not been marked.</p>"},{"location":"xsoftrefthreshold/#syntax","title":"Syntax","text":"<pre><code>    -Xsoftrefthreshold&lt;value&gt;\n</code></pre>"},{"location":"xsoftrefthreshold/#default-behavior","title":"Default behavior","text":"<p>The default value is 32.</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xsoftrefthreshold/#explanation","title":"Explanation","text":"<p>A soft reference (where its referent is not marked) is cleared after a number of GC cycles, which is calculated as: <code>&lt;value&gt;</code> * (proportion of free heap space)</p> <p>For example, if <code>-Xsoftrefthreshold</code> is set to 32, and the heap is 25% free, soft references are cleared after 8 GC cycles.</p>"},{"location":"xss/","title":"-Xssi","text":""},{"location":"xss/#-xiss-xss-xssi","title":"-Xiss / -Xss / -Xssi","text":"<p>Sets the stack size and increment for Java\u2122 threads.</p> <p>If you exceed the maximum Java thread stack size, a <code>java/lang/OutOfMemoryError</code> message is reported.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p> <p> Note: Java methods and native methods run on two different stacks and the VM handles switching between them for JNI calls. Each stack is sized using separate options; these options apply to the Java stack only. For the native stack option, see the link in the See also section.</p>"},{"location":"xss/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xiss&lt;size&gt;</code> Set initial Java thread stack size 2 KB <code>-Xss&lt;size&gt;</code> Set maximum Java thread stack size 320 KB (31/32-bit); 1024 KB (64-bit) <code>-Xssi&lt;size&gt;</code> Set Java thread stack size increment 16 KB <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.  </p> <p>See Default settings for the Eclipse OpenJ9\u2122 VM for more about default values.</p>"},{"location":"xss/#see-also","title":"See also","text":"<ul> <li><code>-Xmso</code> (Native stack size for operating system threads)</li> </ul>"},{"location":"xsyslog/","title":"-Xsyslog","text":""},{"location":"xsyslog/#-xsyslog","title":"-Xsyslog","text":"<p>Enables operating system message logging.</p> <p> Notes:</p> <ul> <li>Changes made to message logging by using the <code>-Xsyslog</code> option do not affect messages written to the standard error stream (<code>stderr</code>).</li> <li>This option replaces the Eclipse OpenJ9\u2122 <code>-Xlog</code> option in Eclipse OpenJ9 version 0.24.0. If the <code>-XX:+LegacyXlogOption</code> is set, <code>-Xlog</code> behaves in the same way as <code>-Xsyslog</code> and with the same parameters.</li> </ul>"},{"location":"xsyslog/#syntax","title":"Syntax","text":"<pre><code>    -Xsyslog:&lt;parameter&gt;{,&lt;parameter&gt;}\n</code></pre>"},{"location":"xsyslog/#parameters","title":"Parameters","text":"<p> Restriction: The parameters <code>all</code>, <code>none</code> and <code>help</code> must be used on their own and cannot be combined. However, the other parameters can be grouped. For example, to include error, vital and warning messages use <code>-Xsyslog:error,vital,warn</code>.</p> <p>For message details see OpenJ9 VM messages.</p>"},{"location":"xsyslog/#help","title":"<code>help</code>","text":"<pre><code>    -Xsyslog:help\n</code></pre> Gives details the available parameters. (This parameter cannot be combined with others.)"},{"location":"xsyslog/#error","title":"<code>error</code>","text":"<pre><code>    -Xsyslog:error\n</code></pre> Turns on logging for all OpenJ9 VM error messages (default)."},{"location":"xsyslog/#vital","title":"<code>vital</code>","text":"<pre><code>    -Xsyslog:vital\n</code></pre> Turns on logging for selected information messages <code>JVMDUMP006I</code>, <code>JVMDUMP032I</code>, and <code>JVMDUMP033I</code>, which provide valuable additional information about dumps produced by the OpenJ9 VM (default)."},{"location":"xsyslog/#info","title":"<code>info</code>","text":"<pre><code>    -Xsyslog:info\n</code></pre> Turns on logging for all OpenJ9 VM information messages."},{"location":"xsyslog/#warn","title":"<code>warn</code>","text":"<pre><code>    -Xsyslog:warn\n</code></pre> Turns on logging for all OpenJ9 VM warning messages."},{"location":"xsyslog/#config","title":"<code>config</code>","text":"<pre><code>    -Xsyslog:config\n</code></pre> Turns on logging for all OpenJ9 VM configuration messages."},{"location":"xsyslog/#all","title":"<code>all</code>","text":"<pre><code>    -Xsyslog:all\n</code></pre> Turns on logging for all OpenJ9 VM messages. (This parameter cannot be combined with others.)"},{"location":"xsyslog/#none","title":"<code>none</code>","text":"<pre><code>    -Xsyslog:none\n</code></pre> Turns off logging for all OpenJ9 VM messages. (This parameter cannot be combined with others.)"},{"location":"xtgc/","title":"-Xtgc","text":""},{"location":"xtgc/#-xtgc","title":"-Xtgc","text":"<p>Provides garbage collection tracing options.</p>"},{"location":"xtgc/#syntax","title":"Syntax","text":"<pre><code>    -Xtgc:&lt;parameter&gt;{,&lt;parameter&gt;}\n</code></pre>"},{"location":"xtgc/#parameters","title":"Parameters","text":"Specify one one or more of the following parameters in a comma-separated list:"},{"location":"xtgc/#backtrace","title":"<code>backtrace</code>","text":"<pre><code>    -Xtgc:backtrace\n</code></pre> Before a garbage collection, a single line is printed containing the name of the main thread for garbage collection, as well as the value of the <code>osThread</code> slot in the <code>J9VMThread</code> structure."},{"location":"xtgc/#compaction","title":"<code>compaction</code>","text":"<pre><code>    -Xtgc:compaction\n</code></pre> Prints extra information showing the relative time spent by threads in the \"move\" and \"fixup\" phases of compaction"},{"location":"xtgc/#concurrent","title":"<code>concurrent</code>","text":"<pre><code>    -Xtgc:concurrent\n</code></pre> Prints extra information showing the activity of the concurrent mark background thread"},{"location":"xtgc/#dump","title":"<code>dump</code>","text":"<pre><code>    -Xtgc:dump\n</code></pre> Prints a line of output for every free chunk of memory in the system, including \"dark matter\" (free chunks that are not on the free list for some reason, typically because they are too small). Each line contains the base address and the size in bytes of the chunk. If the chunk is followed in the heap by an object, the size and class name of the object is also printed. This argument has a similar effect to the <code>terse</code> argument."},{"location":"xtgc/#file","title":"<code>file</code>","text":"<pre><code>    -Xtgc:file=&lt;filename&gt;\n</code></pre> Directs the logs to a file. Otherwise they are directed to stderr."},{"location":"xtgc/#freelist","title":"<code>freeList</code>","text":"<pre><code>    -Xtgc:freeList\n</code></pre> Before a garbage collection, prints information about the free list and allocation statistics since the last garbage collection. Prints the number of items on the free list, including \"deferred\" entries (with the scavenger, the unused space is a deferred free list entry). For TLH and non-TLH allocations, prints the total number of allocations, the average allocation size, and the total number of bytes discarded during allocation. For non-TLH allocations, also included is the average number of entries that were searched before a sufficiently large entry was found."},{"location":"xtgc/#parallel","title":"<code>parallel</code>","text":"<pre><code>    -Xtgc:parallel\n</code></pre> Produces statistics on the activity of the parallel threads during each operation (mark, sweep, scavenge etc.) of a GC cycle."},{"location":"xtgc/#rootscantime","title":"<code>rootscantime</code>","text":"<pre><code>    -Xtgc:rootscantime\n</code></pre> Prints duration of strong and weak roots scanning of a GC cycle."},{"location":"xtgc/#scavenger","title":"<code>scavenger</code>","text":"<pre><code>    -Xtgc:scavenger\n</code></pre> Prints extra information after each scavenger collection. A histogram is produced showing the number of instances of each class, and their relative ages, present in the survivor space. The information is obtained by performing a linear walk-through of the space."},{"location":"xtgc/#terse","title":"<code>terse</code>","text":"<pre><code>    -Xtgc:terse\n</code></pre> Dumps the contents of the entire heap before and after a garbage collection. For each object or free chunk in the heap, a line of trace output is produced. Each line contains the base address, \"a\" if it is an allocated object, and \"f\" if it is a free chunk, the size of the chunk in bytes, and, if it is an object, its class name."},{"location":"xthr/","title":"-Xthr","text":""},{"location":"xthr/#-xthr","title":"-Xthr","text":""},{"location":"xthr/#syntax","title":"Syntax","text":"<pre><code>    -Xthr:&lt;parameter&gt;\n</code></pre>"},{"location":"xthr/#parameters","title":"Parameters","text":""},{"location":"xthr/#adaptspin-noadaptspin","title":"<code>AdaptSpin</code> | <code>noAdaptSpin</code>","text":"<pre><code>    -Xthr:AdaptSpin\n    -Xthr:noAdaptSpin\n</code></pre> This tuning option is available to test whether performance optimizations are negatively impacting an application."},{"location":"xthr/#fastnotify-nofastnotify","title":"<code>fastNotify</code> | <code>noFastNotify</code>","text":"<pre><code>    -Xthr:fastNotify\n    -Xthr:noFastNotify\n</code></pre> When a large number of threads try to acquire a Java\u2122 monitor, throughput of an application can be reduced. This issue is known as high contention. If high contention occurs when the Java <code>wait</code> and <code>notify</code> features are regularly used, you can use <code>-Xthr:fastNotify</code> to increase throughput. However, <code>-Xthr:noFastNotify</code> is the default setting, because it is faster in all other scenarios."},{"location":"xthr/#cfsyield-nocfsyield-linux-only","title":"<code>cfsYield</code> | <code>noCfsYield</code> (Linux\u00ae only)","text":"<pre><code>    -Xthr:cfsYield\n    -Xthr:noCfsYield\n</code></pre> The default value, <code>cfsYield</code>, enables threading optimizations for running on Linux with the Completely Fair Scheduler (CFS) in the default mode (<code>sched_compat_yield=0</code>). The <code>noCfsYield</code> value disables these threading optimizations. You might want to use the <code>noCfsYield</code> value if your application uses the <code>Thread.yield()</code> method extensively, because otherwise you might see a performance decrease in cases where yielding is not beneficial."},{"location":"xthr/#minimizeusercpu","title":"<code>minimizeUserCPU</code>","text":"<pre><code>    -Xthr:minimizeUserCPU\n</code></pre> Minimizes user-mode CPU usage in thread synchronization where possible. The reduction in CPU usage might be a trade-off in exchange for decreased performance."},{"location":"xthr/#secondaryspinforobjectmonitors-nosecondaryspinforobjectmonitors","title":"<code>secondarySpinForObjectMonitors</code> | <code>noSecondarySpinForObjectMonitors</code>","text":"<pre><code>    -Xthr:secondarySpinForObjectMonitors\n    -Xthr:noSecondarySpinForObjectMonitors\n</code></pre> This tuning option is available to test whether performance optimizations are negatively impacting an application."},{"location":"xtlhprefetch/","title":"-XtlhPrefetch","text":""},{"location":"xtlhprefetch/#-xtlhprefetch","title":"-XtlhPrefetch","text":"<p>(AIX\u00ae, Windows\u2122 only)</p> <p>Speculatively prefetches bytes in the thread local heap (TLH) ahead of the current allocation pointer during object allocation. This option helps reduce the performance cost of subsequent allocations.</p>"},{"location":"xtlhprefetch/#syntax","title":"Syntax","text":"<pre><code>    -XtlhPrefetch\n</code></pre> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xtrace/","title":"-Xtrace","text":""},{"location":"xtrace/#-xtrace","title":"-Xtrace","text":"<p>Eclipse OpenJ9\u2122 VM tracing is a powerful feature to help you diagnose problems with minimal effect on performance. Tracing is enabled by default, together with a small set of trace points going to memory buffers. You can enable tracepoints at run time by using levels, components, group names, or individual tracepoint identifiers to trace VM internal operations and instrumented Java\u2122 applications. You can also trace Java methods. See the About trace section that follows for more detail.</p> <p>Trace data can be output in human-readable or in compressed binary formats. The VM provides a tool to process and convert the compressed binary data into a readable format. See Trace formatter.</p> <p> Note: You can also control trace by using the <code>com.ibm.jvm.Trace</code> API or by using JVMTI from an external agent.</p>"},{"location":"xtrace/#xtrace-option-builder","title":"Xtrace Option Builder","text":"<p>Use the Xtrace Option Builder tool to help you specify the correct options and avoid incompatibilities.</p>"},{"location":"xtrace/#syntax","title":"Syntax","text":"<pre><code>-Xtrace:&lt;parameter&gt;\n</code></pre> <p>You can get help with <code>-Xtrace</code>by using the following options:</p> <ul> <li><code>-Xtrace:help</code> \u00a0 Displays general trace help</li> <li><code>-Xtrace:what</code> \u00a0 Shows the current trace settings</li> </ul>"},{"location":"xtrace/#configuring-trace","title":"Configuring trace","text":"<p>The following parameters can be used to configure trace. (Follow links for more information about individual options.)</p> Command Result <code>-Xtrace:properties[=&lt;filename&gt;]</code> Configures trace options based on a file <code>-Xtrace:buffers=&lt;size&gt;[dynamic\\|nodynamic]</code> Modifies the size of buffers that are used to store trace data <code>-Xtrace:exception.output=&lt;filename&gt;[,&lt;size&gt;]</code> Redirects exceptions trace data to a file. <code>-Xtrace:methods=&lt;method_specification&gt;</code> Traces methods <code>-Xtrace:output=&lt;filename&gt;[,&lt;size&gt;[,&lt;generations&gt;]]</code> Sends trace data to a file, optionally of a specific size and number of generations. <code>-Xtrace:resume</code> Resumes tracing globally. <code>-Xtrace:resumecount=&lt;count&gt;</code> Enables tracing at a thread level after a specified count. <code>-Xtrace:sleeptime=&lt;time&gt;</code> Pauses trace operations for a specified length of time. <code>-Xtrace:stackdepth=&lt;n&gt;</code> Limits the maximum number of stack frames reported by the jstacktrace trace trigger action. <code>-Xtrace:suspend</code> Suspends tracing globally. <code>-Xtrace:suspendcount=&lt;count&gt;</code> Suspends tracing at a thread level after a specified count. <code>-Xtrace:trigger=&lt;clause&gt;</code> Determines when various triggered trace actions occur, including turning trace on or off. <p> Note: If an option value contains commas, it must be enclosed in braces. For example: <code>methods={java/lang/*,com/ibm/*}</code></p>"},{"location":"xtrace/#controlling-tracepoint-activation","title":"Controlling tracepoint activation","text":"<p>The following parameters can be used to control tracepoint activation. (Follow links for more information about individual options.)</p> Command Result <code>-Xtrace:maximal=&lt;tracepoint_specification&gt;</code> Records all associated data. <code>-Xtrace:minimal=&lt;tracepoint_specification&gt;</code> Records only the time stamp and tracepoint identifier. <code>-Xtrace:count=&lt;tracepoint_specification&gt;</code> Counts the tracepoints that are used in a trace configuration. <code>-Xtrace:print=&lt;tracepoint_specification&gt;</code> Prints the specified tracepoints to stderr in real time. <code>-Xtrace:iprint=&lt;tracepoint_specification&gt;</code> Prints the specified tracepoints to stderr in real time with indentation. <code>-Xtrace:exception=&lt;tracepoint_specification&gt;</code> Enables exception tracing. <code>-Xtrace:external&lt;tracepoint_specification&gt;</code> Routes trace data to trace listeners, which are registered by using the JVMTI APIs. <code>-Xtrace:none[=&lt;tracepoint_specification&gt;]</code> Prevents the trace engine from loading if it is the only trace option specified. <p> Note: These options control which individual tracepoints are activated at run time and the implicit destination of the trace data. All these properties are independent of each other and can be mixed and matched in any way that you choose. For more information, see Tracepoint activation.</p>"},{"location":"xtrace/#about-trace","title":"About trace","text":"<p>With the OpenJ9 trace feature, you can trace VM internal operations, Java applications, and Java methods, or any combination of these.</p> VM internal operations The OpenJ9 virtual machine (VM) is extensively instrumented with tracepoints for tracing operations. Interpreting this trace data requires detailed knowledge of the VM, and is intended to diagnose VM problems. No guarantee is given that tracepoints will not vary from release to release and from platform to platform. Applications VM trace contains an application trace facility that allows tracepoints to be placed in Java code, enabling you to combine trace data with the other forms of trace. This capability is supported by the <code>com.ibm.jvm.Trace</code> API. Note that an instrumented Java application runs only on an OpenJ9 VM. For more information, see Application trace. Java methods Use method trace to debug and trace application code and the system classes provided with the VM. You can trace entry to and exit from Java methods run by the VM. You can select method trace by classname, method name, or both. You can also use wildcards to create complex method selections. For more information about command syntax, see methods. <p>Trace can produce large amounts of data in a very short time. Before running trace, think carefully about what information you need in order to solve the problem. Here are some considerations:</p> <ul> <li>If you need only the trace information that is produced shortly before the problem occurs, consider wrapping the file by using the <code>output</code> option.</li> <li>In many cases, just use internal trace with an increased buffer size and snap the trace when the problem occurs.</li> <li>If the problem results in a thread stack dump or operating system signal or exception, trace buffers are snapped automatically to a file that is in the current directory. The file is called: <code>Snapnnnn. yyyymmdd.hhmmssth.process.trc</code>.</li> </ul> <p>You must also think carefully about which components need to be traced and what level of tracing is required. For example, if you are tracing a suspected shared classes problem, it might be enough to trace all components at level 1, and j9shr at level 9, while <code>maximal</code> can be used to show parameters and other information for the failing component. Tracepoint components and trace levels are described in the following sections: Tracepoint specification and Trace levels.</p> <p>There are two types of tracepoints inside the VM:</p> <ul> <li>Regular tracepoints include method tracepoints, application tracepoints, data tracepoints inside the VM and data tracepoints inside class libraries. You can display regular tracepoint data on the screen or save the data to a file. You can also use command line options to trigger specific actions when regular tracepoints fire.</li> <li>Auxiliary tracepoints are a special type of tracepoint that can be fired only when another tracepoint is being processed. For example, the stack frame information produced by the jstacktrace <code>-Xtrace:trigger</code> command. You cannot control where auxiliary tracepoint data is sent and you cannot set triggers on auxiliary tracepoints. Auxiliary tracepoint data is sent to the same destination as the tracepoint that caused them to be generated.</li> </ul> <p>Trace data can be written to one of the following locations:</p> <ul> <li>Memory buffers that can be dumped or snapped when a problem occurs. Use the <code>-Xtrace:buffers=&lt;size&gt;</code> option to control the size of the buffer allocated to each thread. Buffers allocated to a thread are discarded when that thread terminates. To examine the trace data captured in these memory buffers, you must snap or dump the data. Use the <code>-Xdump:snap</code> option to vary the events that cause a snap trace file to be produced. When produced, format the buffers by using the trace formatter.</li> <li>One or more files that are using buffered I/O. Use the <code>-Xtrace:output</code> option.</li> <li>An external agent in real time, using the <code>-Xtrace:external</code> option.</li> <li><code>stderr</code> in real time.</li> <li>Any combination of the other items in this list.</li> </ul>"},{"location":"xtrace/#default-tracing","title":"Default tracing","text":"<p>By default, the equivalent of the following trace command line is always available in the VM:</p> <pre><code>-Xtrace:maximal=all{level1},exception=j9mm{gclogger}\n</code></pre> <p>When startup is complete, the equivalent of the following command line is added to enable level 2 trace points:</p> <pre><code>-Xtrace:maximal=all{level2}\n</code></pre> <p>Level 2 is used for default tracing that would produce too much data during the startup of the VM. If you set other trace options on the command line, or before the VM finishes startup (through use of JVMTI or the <code>com.ibm.jvm.Trace</code> API), the level 2 trace points are enabled just before your trace options are processed. This behavior ensures that the default level 2 trace points do not override any changes that you specify.</p> <p>The data generated by the tracepoints is continuously captured in wrapping memory buffers for each thread.</p> <p>You can find tracepoint information in the following diagnostics data:</p> <ul> <li>System memory dumps, extracted by using jdmpview.</li> <li>Snap traces, generated when the VM encounters a problem or an output file is specified. Using dump agents describes more ways to create a snap trace.</li> <li>For exception trace only, in Javadumps.</li> </ul>"},{"location":"xtrace/#default-memory-management-tracing","title":"Default memory management tracing","text":"<p>The default trace options are designed to ensure that Javadumps always contain a record of the most recent memory management history, regardless of how much work the VM has performed since the garbage collection cycle was last called.</p> <p>The <code>exception=j9mm{gclogger}</code> clause of the default trace set specifies that a history of garbage collection cycles that have occurred in the VM is continuously recorded. The gclogger group of tracepoints in the j9mm component constitutes a set of tracepoints that record a snapshot of each garbage collection cycle. These tracepoints are recorded in their own separate buffer, called the exception buffer. The effect is that the tracepoints are not overwritten by the higher frequency tracepoints of the VM.</p> <p>The GC History section of the Javadump is based on the information in the exception buffer. If a garbage collection cycle has occurred in a traced VM, the Java dump probably contains a GC History section.</p>"},{"location":"xtrace/#default-assertion-tracing","title":"Default assertion tracing","text":"<p>The VM includes assertions, implemented as special trace points. By default, internal assertions are detected and diagnostics logs are produced to help assess the error.</p> <p>Assertion failures often indicate a serious problem, and the VM usually stops immediately. In these circumstances, raise an issue, including the standard error output and any diagnostic files that are produced.</p> <p>When an assertion trace point is reached, a message like the following output is produced on the standard error stream:</p> <pre><code>16:43:48.671 0x10a4800    j9vm.209    *   ** ASSERTION FAILED ** at jniinv.c:251:\n((javaVM == ((void *)0)))\n</code></pre> <p>This error stream is followed with information about the diagnostic logs produced:</p> <pre><code>JVMDUMP007I JVM Requesting System Dump using 'core.20060426.124348.976.dmp'\nJVMDUMP010I System Dump written to core.20060426.124348.976.dmp\nJVMDUMP007I JVM Requesting Snap Dump using 'Snap0001.20060426.124648.976.trc'\nJVMDUMP010I Snap Dump written to Snap0001.20060426.124648.976.trc\n</code></pre> <p>Assertions are special trace points. They can be enabled or disabled by using the standard trace command-line options.</p> <p>Assertion failures might occur early during VM startup, before trace is enabled. In this case, the assert message has a different format, and is not prefixed by a timestamp or thread ID. For example:</p> <pre><code>** ASSERTION FAILED ** j9vmutil.15 at thrinfo.c:371 Assert_VMUtil_true((\n  publicFlags &amp; 0x200))\n</code></pre> <p>Assertion failures that occur early during startup cannot be disabled. These failures do not produce diagnostic dumps, and do not cause the VM to stop.</p>"},{"location":"xtrace/#tracepoint-activation","title":"Tracepoint activation","text":"<p>The options that control which individual tracepoints are activated at run time and the implicit destination of the trace data are listed under Syntax: Controlling tracepoint activation</p> <p>In some cases, you must use them with other options. For example, if you specify <code>maximal</code> or <code>minimal</code> tracepoints, the trace data is put into memory buffers. If you are going to send the data to a file, you must use an <code>output</code> option to specify the destination file name.</p> <p>With the exception of <code>none</code>, all options require at least one <code>&lt;tracepoint_specification&gt;</code>, which is described in the following section. Multiple statements of each type of trace are allowed and their effect is cumulative. If you want to use multiple trace options of the same name, use a properties file. (See <code>properties</code>.)</p>"},{"location":"xtrace/#tracepoint-specification","title":"Tracepoint specification","text":"<p>Tracepoints are enabled by specifying component and tracepoint.</p> <p>If no qualifier parameters are entered, all tracepoints are enabled, except for <code>&lt;exception.output&gt;</code> trace, where the default is all {exception}.</p> <p>The <code>&lt;tracepoint_specification&gt;</code> syntax can be further broken down as follows:</p> <pre><code>[!]&lt;component&gt;[{&lt;group&gt;}] or [!]&lt;component&gt;[{&lt;type&gt;}] or [!]&lt;tracepoint_id&gt;[,&lt;tracepoint_id&gt;]\n</code></pre> <p>Where:</p> <ul> <li>The <code>!</code> symbol is a logical not. That is, the tracepoints that are in a specification starting with ! are turned off.</li> <li><code>&lt;component&gt;</code> is a Java component.</li> <li><code>&lt;group&gt;</code> is a tracepoint group, which is a set of tracepoints that are defined within a component.</li> <li><code>&lt;type&gt;</code> is the tracepoint type: <code>entry</code>, <code>exit</code>, <code>event</code>, <code>exception</code>, and <code>mem</code>.</li> <li><code>&lt;tracepoint_id&gt;</code> is the tracepoint identifier. The tracepoint identifier constitutes the component name of the tracepoint, followed by its integer number inside that component. For example, <code>j9mm.49</code>, <code>j9shr.20-29</code>, <code>j9vm.15</code>. To understand these numbers, see Determining the tracepoint ID of a tracepoint.</li> </ul> <p>Some tracepoints can be both an <code>exit</code> and an <code>exception</code>; that is, the function ended with an error. If you specify either <code>exit</code> or <code>exception</code>, these tracepoints are included.</p> <p>Lists of Java components and tracepoint groups can be found in the tables that follow.</p> <p>The following table lists the possible Java components (<code>&lt;component&gt;</code>). To include all Java components, specify all.</p> Component name Description avl VM AVL tree support io Class library java.io native code j9bcu VM byte code utilities j9bcverify VM byte code verification j9codertvm VM byte code run time j9dmp VM dump j9jcl VM class libraries j9jit VM JIT interface j9jni VM JNI support j9jvmti VM JVMTI support j9mm VM memory management j9prt VM port library j9scar VM class library interface j9shr VM shared classes j9trc VM trace j9util VM utilities j9vm VM general j9vmutil VM utilities j9vrb VM verbose stack walker map VM mapped memory support mt Java methods (see Note) net Class library TCP/IP networking native code pool VM storage pool support rpc VM RPC support simplepool VM storage pool support sunvmi VM class library interface <p> Note: When specifying the mt component you must also specify the <code>methods</code> option.</p> <p>The following table lists all the tracepoint groups (<code>&lt;group&gt;</code>). Each group is associated with one or more Java components:</p> Component name or names Group name Description j9mm <code>gclogger</code> A set of tracepoints that record each garbage collection cycle. Equivalent to <code>-verbose:gc</code> output j9prt <code>nlsmessage</code> A set of tracepoints that record each NLS message that is issued by the VM. j9jcl, j9vm <code>verboseclass</code> A set of tracepoints that record each class as it is loaded. Equivalent to <code>-verbose:class</code> output. j9jni, j9vm <code>checkjni</code> A set of tracepoints that record JNI function checks. Equivalent to <code>-Xcheck:jni</code> output. j9vm <code>checkmemory</code> A set of tracepoints that record memory checks. Equivalent to <code>-Xcheck:memory</code> output. j9vm <code>checkvm</code> A set of tracepoints that record VM checks. Equivalent to <code>-Xcheck:vm</code> output. j9jit <code>verbose</code> A set of tracepoints that record JIT compiler configuration and method compilation. Equivalent to <code>-Xjit:verbose</code> output. mt <code>compiledMethods</code> A set of tracepoints that record compiled Java methods. mt <code>nativeMethods</code> A set of tracepoints that record Java native methods. mt <code>staticMethods</code> A set of tracepoints that record Java static methods. <p>Here are some examples:</p> <p>To trace all tracepoints, specify the following command:</p> <pre><code>-Xtrace:maximal=all\n</code></pre> <pre><code>To trace all tracepoints except **j9vrb** and **j9trc**, specify the following command:\n\n    -Xtrace:minimal={all},minimal={!j9vrb,j9trc}\n</code></pre> <p>To trace all entry and exit tracepoints in j9bcu, specify the following command:</p> <pre><code>-Xtrace:maximal={j9bcu{entry},j9bcu{exit}}\n</code></pre> <pre><code>To trace all tracepoints in **j9mm** except tracepoints 20-30, specify the following command:\n\n    -Xtrace:maximal=j9mm,maximal=!j9mm.20-30\n</code></pre> <p>To trace tracepoints <code>j9prt.5</code> through <code>j9prt.15</code>, specify the following command:</p> <pre><code>-Xtrace:print=j9prt.5-15\n</code></pre> <pre><code>To trace all **j9trc** tracepoints, specify the following command:\n\n    -Xtrace:count=j9trc\n</code></pre> <p>To trace all <code>entry</code> and <code>exit</code> tracepoints, specify the following command:</p> <pre><code>-Xtrace:external={all{entry},all{exit}}\n</code></pre>"},{"location":"xtrace/#trace-levels","title":"Trace levels","text":"<p>Tracepoints have been assigned levels 0 through 9 that are based on the importance of the tracepoint.</p> <p>A level 0 tracepoint is the most important. It is reserved for extraordinary events and errors. A level 9 tracepoint is in-depth component detail. To specify a given level of tracing, the <code>level0</code> through <code>level9</code> keywords are used. You can abbreviate these keywords to l0 through l9. For example, if <code>level5</code> is selected, all tracepoints that have levels 0 through 5 are included. Level specifications do not apply to explicit tracepoint specifications that use the TPNID keyword.</p> <p>The level is provided as a modifier to a component specification, for example:</p> <pre><code>-Xtrace:maximal={all{level5}}\n</code></pre> <p>or</p> <pre><code>-Xtrace:maximal={j9mm{L2},j9trc,j9bcu{level9},all{level1}}\n</code></pre> <p>In the first example, tracepoints that have a level of 5 or less are enabled for all components. In the second example, all level 1 tracepoints are enabled. All level 2 tracepoints in j9mm are enabled. All tracepoints up to level 9 are enabled in j9bcu.</p> <p> Note: The level applies only to the current component. If multiple trace selection components are found in a trace properties file, the level is reset to the default for each new component. Level specifications do not apply to explicit tracepoint specifications that use the TPNID keyword.</p> <p>When the not operator is specified, the level is inverted; that is, <code>!j9mm{level5}</code> disables all tracepoints of level 6 or greater for the j9mm component. The following example enables trace for all components at level 9 (the default), but disables level 6 and higher for the locking component, and level 7 and higher for the storage component:</p> <pre><code>-Xtrace:print={all},print={!j9trc{l5},j9mm{l6}}\n</code></pre> <p>Here are some examples:</p> <p>To count the level zero and level one tracepoints matched, specify the following command:</p> <pre><code>-Xtrace:count=all{L1}\n</code></pre> <p>To produce maximal trace of all components at level 5 and j9mm at level 9, specify the following command:</p> <pre><code>-Xtrace:maximal={all{level5},j9mm{L9}}\n</code></pre> <p>To trace all components at level 6, but do not trace <code>j9vrb</code> at all, and do not trace the <code>entry</code> and <code>exit</code> tracepoints in the j9trc component, specify the following command:</p> <pre><code>-Xtrace:minimal={all{l6}},minimal={!j9vrb,j9trc{entry},j9trc{exit}}\n</code></pre>"},{"location":"xtrace/#parameters","title":"Parameters","text":"<p>Parameters to use with the <code>-Xtrace</code> option:</p>"},{"location":"xtrace/#buffers","title":"<code>buffers</code>","text":"<p>You can modify the size of the buffers to change how much diagnostic output is provided in a snap dump. This buffer is allocated for each thread that makes trace entries. The following table shows how this parameter can be set:</p> Command Effect <code>-Xtrace:buffers=&lt;size&gt;</code> Creates buffers of the specified <code>&lt;size&gt;</code> in k (KB) or m (MB), allocated as needed to match the rate of trace data generation to the output media. <code>-Xtrace:buffers=&lt;size&gt;dynamic</code> Creates buffers of the specified <code>&lt;size&gt;</code>, allocated as needed to match the rate of trace data generation to the output media. <code>-Xtrace:buffers=&lt;size&gt;nodynamic</code> Creates buffers of the specified <code>&lt;size&gt;</code>, with a maximum allocation of two buffers per thread. <p>If external trace is enabled, the number of buffers is doubled; that is, each thread allocates two or more buffers. The same buffer size is used for state and exception tracing, but, in this case, buffers are allocated globally. The default is 8 KB per thread.</p> <p>The <code>dynamic</code> and <code>nodynamic</code> suboptions have meaning only when tracing to an output file.</p> <p> Note: If <code>nodynamic</code> is specified, you might lose trace data if the volume of trace data exceeds the bandwidth of the trace output file. Message UTE115 is issued when the first trace entry is lost, and message UTE018 is issued when the VM ends.</p> <p>Here are some command line examples:</p> <p>To set a buffer size of 2 MB per thread, with dynamic buffering, use:</p> <pre><code>-Xtrace:buffers=2m\n</code></pre> <p>To limit each thread to 2 trace buffers, each of 128 KB:</p> <pre><code>-Xtrace:buffers={128k,nodynamic}\n</code></pre>"},{"location":"xtrace/#count-tracepoint","title":"<code>count</code> (tracepoint)","text":"<pre><code>-Xtrace:count=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The count option requests that only a count of the selected tracepoints is kept. When the VM ends, all nonzero totals of tracepoints (sorted by tracepoint id) are written to a file, called <code>utTrcCounters</code>, in the current directory. This information is useful if you want to determine the overhead of particular tracepoints, but do not want to produce a large amount (GB) of trace data.</p> <p>For example, to count the tracepoints that are used in the default trace configuration, use the following command:</p> <pre><code>-Xtrace:count=all{level1},count=j9mm{gclogger}\n</code></pre>"},{"location":"xtrace/#exception-tracepoint","title":"<code>exception</code> (tracepoint)","text":"<pre><code>-Xtrace:exception=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>When exception trace is enabled, the trace data is collected in internal buffers that are separate from the normal buffers. These internal buffers can then be written to a snap file or written to the file that is specified in an <code>exception.output</code> option.</p> <p>The <code>exception</code> option allows low-volume tracing in buffers and files that are distinct from the higher-volume information that <code>minimal</code> and <code>maximal</code> tracing have provided. In most cases, this information is exception-type data, but you can use this option to capture any trace data that you want.</p> <p>This form of tracing is channeled through a single set of buffers, as opposed to the buffer-per-thread approach for normal trace. Buffer contention might occur if high volumes of trace data are collected. A difference exists in the <code>&lt;tracepoint_specification&gt;</code> defaults for exception tracing;  see Tracepoint specification.</p> <p> Notes:</p> <ul> <li>The exception trace buffers are intended for low-volume tracing. By default, the exception trace buffers log garbage collection (GC) event tracepoints, see Default tracing. You can send additional tracepoints to the exception buffers or turn off the GC tracepoints. Changing the exception trace buffers alters the contents of the GC History section in any Javadumps.</li> <li>When exception trace is entered for an active tracepoint, the current thread ID is checked against the previous caller's thread ID. If it is a different thread, or this is the first call to exception trace, a context tracepoint is put into the trace buffer first. This context tracepoint consists only of the current thread ID, which is necessary because of the single set of buffers for exception trace. (The formatter identifies all trace entries as coming from the Exception trace pseudo thread when it formats exception trace files.)</li> </ul>"},{"location":"xtrace/#exceptionoutput","title":"<code>exception.output</code>","text":"<p>Use exception output to redirect exceptions trace data to a file.</p> <pre><code>-Xtrace:exception.output=&lt;filename&gt;[,&lt;size&gt;]\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;filename&gt;</code> is a file name, which is created automatically if it does not exist. Otherwise, it is overwritten. To embed specific values in the file name use any of the following variables: %d (today's date in \" yyyymmdd\" format), %p (process ID number of the process generating the trace), or %t (time in 24-hour hhmmss format).</li> <li>Optionally, <code>&lt;size&gt;</code> is a value in megabytes (MB), for example, use 4m to specify 4 MB. When full, it wraps nondestructively to the beginning. If you do not limit the file, it grows indefinitely, until limited by disk space.</li> </ul> <p>Here are some examples:</p> <p>Exception trace output goes to file <code>/u/traces/exception.trc</code> with no size limit:</p> <pre><code>-Xtrace:exception.output=/u/traces/exception.trc,maximal\n</code></pre> <p>Exception trace output goes to file <code>except</code> and wraps at 2 MB:</p> <pre><code>-Xtrace:exception.output={except,2m},maximal\n</code></pre> <p>Exception trace output goes to a file whose filename contains today's date in * yyyymmdd* format (for example, <code>traceout.20181025.trc</code>):</p> <pre><code>-Xtrace:exception.output=traceout.%d.trc,maximal\n</code></pre> <p>Exception trace output goes to a file whose filename contains the number of the process (the PID number) that generated it (for example, <code>tracefrompid2112.trc</code>):</p> <pre><code>-Xtrace:exception.output=tracefrompid%p.trc,maximal\n</code></pre> <p>Exception trace output goes to a file whose filename contains the time in hhmmss format (for example, <code>traceout.080312.trc</code>):</p> <pre><code>-Xtrace:exception.output=traceout.%t.trc,maximal\n</code></pre>"},{"location":"xtrace/#external-tracepoint","title":"<code>external</code> (tracepoint)","text":"<pre><code>-Xtrace:external&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The <code>external</code> option routes trace data to trace listeners, which are registered by using the JVMTI <code>RegisterTracePointSubscriber()</code> and <code>DeregisterTracePointSubscriber()</code> APIs.</p>"},{"location":"xtrace/#help","title":"<code>help</code>","text":"<pre><code>-Xtrace:help\n</code></pre> <p>Displays general trace help</p>"},{"location":"xtrace/#iprint-tracepoint","title":"<code>iprint</code> (tracepoint)","text":"<pre><code>-Xtrace:iprint=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The <code>iprint</code> option is the same as the <code>print</code> option, but uses indenting to format the trace.</p>"},{"location":"xtrace/#maximal-tracepoint","title":"<code>maximal</code> (tracepoint)","text":"<pre><code>-Xtrace:maximal=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>When specified, trace data is placed into internal trace buffers that can then be written to a snap file or written to the files that are specified in an output trace option. All associated data is traced.</p> <p><code>minimal</code> and <code>maximal</code> traces are independent from any types that follow them. For example, if the <code>maximal</code> option is specified, it does not affect a later option such as <code>print</code>.</p>"},{"location":"xtrace/#methods","title":"<code>methods</code>","text":"<p>Using method trace provides a complete and potentially large diagnosis of code paths inside your application and the system classes. Use wild cards and filtering to control method trace so that you can focus on the sections of code that interest you. Note that method trace is powerful but it also has a cost. Application throughput is affected by method trace.</p> <p>To specify one or more method specifications, use the following syntax:</p> <pre><code>-Xtrace:methods=&lt;method_specification&gt;[,&lt;method_specification&gt;]\n</code></pre> <p>The syntax for <code>&lt;method_specification&gt;</code> can be further broken down to the following suboptions:</p> <pre><code>-Xtrace:methods={[!][*][&lt;package&gt;/]&lt;class&gt;[*],[[*]&lt;method&gt;[*]|[()]]}\n</code></pre> <p>Where:</p> <ul> <li>The delimiter between parts of the package name is a forward slash, \"/\".</li> <li>The ! in the methods parameter is a NOT operator that allows you to tell the VM not to trace the specified method or methods.</li> <li>The parentheses, (), define whether or not to include method parameters in the trace.</li> <li>If a method specification includes any commas, the whole specification must be enclosed in braces, for example: <code>-Xtrace:methods={java/lang/*,java/util/*},print=mt</code></li> <li>It might be necessary to enclose your command line in quotation marks to prevent the shell intercepting and fragmenting comma-separated command lines, for example: <code>\"-Xtrace:methods={java/lang/*,java/util/*},print=mt\"</code></li> </ul> <p>To output all method trace information to stderr, use either the <code>print</code> or <code>iprint</code> suboptions:</p> <pre><code>-Xtrace:print=mt,methods=*.*\n-Xtrace:iprint=mt,methods=*.*\n</code></pre> <p>The <code>iprint</code> suboption prints to stderr with indentation. To output method trace information in binary format, see the <code>output</code> option</p> <p>Internal Native Library (INL) native methods inside the VM cannot be traced because they are not implemented by using JNI. The list of methods that are not traceable is subject to change without notice.</p> <p>Here are some examples:</p> <p>Tracing entry and exit of all methods in a given class: To trace all method entry and exit of the <code>ReaderMain</code> class in the default package and the <code>java.lang.String</code> class, specify the following command:</p> <pre><code>-Xtrace:methods={ReaderMain.*,java/lang/String.*},print=mt\n</code></pre> <p>Tracing entry, exit and input parameters of all methods in a class: To trace all method entry, exit, and input of the <code>ReaderMain</code> class in the default package, specify the following command:</p> <pre><code>-Xtrace:methods=ReaderMain.*(),print=mt\n</code></pre> <p>Tracing all methods in a given package: To trace all method entry, exit, and input of all classes in the package <code>com.ibm.socket</code>, specify the following command:</p> <pre><code>-Xtrace:methods=com/ibm/socket/*.*(),print=mt\n</code></pre> <p>Multiple method trace: To trace all method entry, exit, and input in the <code>Widget</code> class in the default package and all method entry and exit in the <code>common</code> package, specify the following command:</p> <pre><code>-Xtrace:methods={Widget.*(),common/*},print=mt\n</code></pre> <p>Using the ! operator: To trace all methods in the <code>ArticleUI</code> class in the default package except those beginning with \"get\", specify the following command:</p> <pre><code>-Xtrace:methods={ArticleUI.*,!ArticleUI.get*},print=mt\n</code></pre> <p>Tracing a specific method in a class: This example traces entry and exit of the substring method of the <code>java.lang.String class</code>. If there is more than one method with the same name, they are all traced. You cannot filter method trace by the signature of the method.</p> <pre><code>-Xtrace:print=mt,methods={java/lang/String.substring}\n</code></pre> <p>Tracing the constructor of a class: This example traces entry and exit of the constructors of the <code>java.lang.String</code> class.</p> <pre><code>-Xtrace:print=mt,methods={java/lang/String.&lt;init&gt;}\n</code></pre> <p>Here is some example output:</p> <pre><code>java \"-Xtrace:methods={java/lang*.*},iprint=mt\" HW\n10:02:42.281*0x9e900      mt.4         &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4          &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4           &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4            &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10           &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10          &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4           &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10          &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10         &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4          &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4           &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.10          &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.10         &lt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4          &gt; java/lang/String.&lt;clinit&gt;()V Compiled static method\n10:02:42.296 0x9e900      mt.4           &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4            &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4             &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.10            &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4             &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10            &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10           &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.4            &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10           &lt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.4            &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10           &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10          &lt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n</code></pre> <p>The output lines comprise of:</p> <ul> <li><code>0x9e900</code>, the current <code>execenv</code> (execution environment). Because every VM thread has its own <code>execenv</code>, you can regard <code>execenv</code> as a <code>thread-id</code>. All trace with the same <code>execenv</code> relates to a single thread.</li> <li>The individual tracepoint ID in the mt component that collects and emits the data.</li> <li>The remaining fields show whether a method is being entered (&gt;) or exited (&lt;), followed by details of the method.</li> </ul>"},{"location":"xtrace/#minimal-tracepoint","title":"<code>minimal</code> (tracepoint)","text":"<pre><code>-Xtrace:minimal=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>When specified, trace data is placed into internal trace buffers that can then be written to a snap file or written to the files that are specified in an output trace option. Only the time stamp and tracepoint identifier are recorded. When the trace is formatted, missing trace data is replaced with the characters \"???\" in the output file.</p> <p><code>minimal</code> and <code>maximal</code> traces are independent from any types that follow them. For example, if the <code>minimal</code> option is specified, it does not affect a later option such as <code>print</code>.</p>"},{"location":"xtrace/#none-tracepoint","title":"<code>none</code> (tracepoint)","text":"<pre><code>-Xtrace:none[=&lt;tracepoint_specification&gt;]\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p><code>-Xtrace:none</code> prevents the trace engine from loading if it is the only trace option specified. However, if other <code>-Xtrace</code> options are on the command line, it is treated as the equivalent of <code>-Xtrace:none=all</code> and the trace engine still loads.</p> <p>If you specify other tracepoints without specifying <code>-Xtrace:none</code>, the tracepoints are added to the default set.</p>"},{"location":"xtrace/#output","title":"<code>output</code>","text":"<p>Sends trace data to a file, optionally of a specific size and number of generations.</p> <pre><code>-Xtrace:output=&lt;filename&gt;[,&lt;size&gt;[,&lt;generations&gt;]]`\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;filename&gt;</code> is a file name, which is created automatically if it does not exist. Otherwise, it is overwritten. To embed specific values in the file name use any of the following variables: %d% (today's date in \" yyyymmdd\" format), %p% (process ID number of the process generating the trace), or %t% (time in 24-hour hhmmss format).</li> <li>Optionally, <code>&lt;size&gt;</code> is a value in megabytes (MB), for example, use 4m to specify 4 MB. When full, it wraps to the beginning. If you do not limit the file, it grows indefinitely, until limited by disk space.</li> <li>Optionally, <code>&lt;generations&gt;</code> is a value 2 through 36. These values cause up to 36 files to be used sequentially as each file reaches its <code>&lt;size&gt;</code> threshold. When a file needs to be reused, it is overwritten. If <code>&lt;generations&gt;</code> is specified, the filename must contain a # (hash, pound symbol), which will be substituted with its generation identifier, the sequence of which is 0 through 9 followed by A through Z.</li> </ul> <p> Note: When tracing to a file, buffers for each thread are written when the buffer is full or when the VM ends. If a thread has been inactive for a period of time before the VM ends, what seems to be 'old' trace data is written to the file. When formatted, it then seems that trace data is missing from the other threads, but this is an unavoidable side-effect of the buffer-per-thread design. This effect becomes especially noticeable when you use the generation facility, and format individual earlier generations.</p> <p>Here are some examples:</p> <p>Trace output goes to file <code>/u/traces/gc.problem</code> with no size limit:</p> <pre><code>-Xtrace:output=/u/traces/gc.problem,maximal=j9gc\n</code></pre> <p>Trace output goes to file <code>trace</code>, which will wrap at 2 MB:</p> <pre><code>-Xtrace:output={trace,2m},maximal=j9gc\n</code></pre> <p>Trace output goes to files <code>gc0.trc</code>, <code>gc1.trc</code>, and <code>gc2.trc</code>, each 10 MB in size:</p> <pre><code>-Xtrace:output={gc#.trc,10m,3},maximal=j9gc\n</code></pre> <p>Trace output goes to a file, where the filename contains today's date in * yyyymmdd* format (for example, <code>traceout.20181025.trc</code>):</p> <pre><code>-Xtrace:output=traceout.%d.trc,maximal=j9gc\n</code></pre> <p>Trace output goes to a file whose name contains the number of the process (the PID number) that generated it (for example, <code>tracefrompid2112.trc</code>):</p> <pre><code>-Xtrace:output=tracefrompid%p.trc,maximal=j9gc\n</code></pre> <p>Trace output goes to a file whose name contains the time in hhmmss format (for example, <code>traceout.080312.trc</code>):</p> <pre><code>-Xtrace:output=traceout.%t.trc,maximal=j9gc\n</code></pre>"},{"location":"xtrace/#print-tracepoint","title":"<code>print</code> (tracepoint)","text":"<pre><code>-Xtrace:print=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The print option causes the specified tracepoints to be routed to stderr in real time. The VM tracepoints are formatted by using <code>J9TraceFormat.dat</code>. The class library tracepoints are formatted by <code>J9TraceFormat.dat</code> and <code>TraceFormat.dat</code>.</p>"},{"location":"xtrace/#properties","title":"<code>properties</code>","text":"<p>You can use properties files to control trace. A properties file saves typing and allows you to create a library of files that are tailored to solving problems in a particular area.</p> <pre><code>-Xtrace:properties[=&lt;filename&gt;]\n</code></pre> <p>If <code>&lt;filename&gt;</code> is not specified, the VM searches for a default name of IBMTRACE.properties in the current directory.</p> <p>All the options that are in the file are processed in the sequence in which they are stored in the file, before the next option that is obtained through the normal mechanism is processed. Therefore, a command-line property always overrides a property that is in the file.</p> <p>Here is an example of a properties file:</p> <pre><code>minimal=all\n// maximal=j9mm\nmaximal=j9shr\nbuffers=128k,nodynamic\noutput=c:\\traces\\classloader.trc\nprint=tpnid(j9vm.23-25)\n</code></pre> <p>The following restrictions apply to the file:</p> <ul> <li>The file must be a flat ASCII file.</li> <li>Nesting is not supported; that is, the file cannot contain a properties option.</li> <li>You cannot leave properties that have the form <code>&lt;name&gt;=&lt;value&gt;</code> to default if they are specified in the property file; that is, you must specify a value, for example <code>maximal=all</code>.</li> <li>Do not add white space before, after, or within the trace options.</li> </ul> <p>If any error is found when the file is accessed, VM initialization fails with an explanatory error message and return code.</p> <p>To use a file <code>trace.props</code> stored in the <code>c:\\trc\\gc</code> directory, specify the following command:</p> <pre><code>-Xtrace:properties=c:\\trc\\gc\\trace.props\n</code></pre>"},{"location":"xtrace/#resume","title":"<code>resume</code>","text":"<p>The resume option resumes tracing globally.</p> <pre><code>-Xtrace:resume\n</code></pre> <p>The <code>suspend</code> and <code>resume</code> options are not recursive. That is, two suspends that are followed by a single resume cause trace to be resumed.</p>"},{"location":"xtrace/#resumecount","title":"<code>resumecount</code>","text":"<p>This trace option determines whether tracing is enabled for each thread.</p> <pre><code>-Xtrace:resumecount=&lt;count&gt;\n</code></pre> <p>If <code>&lt;count&gt;</code> is greater than zero, each thread initially has its tracing disabled and must receive <code>&lt;count&gt;</code> <code>resumethis</code> actions before it starts tracing. This option is used with the trigger option.</p> <p> Note: You cannot use <code>resumecount</code> and <code>suspendcount</code> together because they use the same internal counter.</p> <p>The following example starts with all tracing turned off. Each thread starts tracing when it has had three <code>resumethis</code> actions performed on it:</p> <pre><code>-Xtrace:resumecount=3\n</code></pre>"},{"location":"xtrace/#sleeptime","title":"<code>sleeptime</code>","text":"<p>You can specify how long the sleep lasts when using the <code>sleep</code> trigger action.</p> <pre><code>-Xtrace:sleeptime=nnn|aaams|bbbs\n</code></pre> <p>Where:</p> <ul> <li>nnn sleeps for nnn milliseconds.</li> <li>aaams sleeps for aaa milliseconds.</li> <li>bbbs sleeps for bbb seconds.</li> </ul> <p>The default length of time is 30 seconds. If no units are specified, the default time unit is milliseconds.</p>"},{"location":"xtrace/#stackdepth","title":"<code>stackdepth</code>","text":"<p>Use this option to limit the maximum number of stack frames reported by the <code>jstacktrace</code> trace trigger action.</p> <pre><code>-Xtrace:stackdepth=&lt;n&gt;\n</code></pre> <p>Where <code>&lt;n&gt;</code> is the maximum number of stack frames reported.</p>"},{"location":"xtrace/#suspend","title":"<code>suspend</code>","text":"<pre><code>-Xtrace:suspend\n</code></pre> <p>Suspends tracing globally for all threads and all forms of tracing but leaves tracepoints activated.</p>"},{"location":"xtrace/#suspendcount","title":"<code>suspendcount</code>","text":"<p>This trace option determines whether tracing is enabled for each thread.</p> <pre><code>-Xtrace:suspendcount=&lt;count&gt;\n</code></pre> <p>If <code>&lt;count&gt;</code> is greater than zero, each thread initially has its tracing enabled and must receive <code>&lt;count&gt;</code> <code>suspendthis</code> actions before it stops tracing.</p> <p> You cannot use <code>resumecount</code> and <code>suspendcount</code> together because they both set the same internal counter.</p> <p>This trace option is for use with the trigger option.</p> <p>The following example starts with tracing turned on. Each thread stops tracing when it has had three <code>suspendthis</code> actions performed on it:</p> <pre><code>-Xtrace:suspendcount=3\n</code></pre>"},{"location":"xtrace/#trigger","title":"<code>trigger</code>","text":"<p>The <code>trigger</code> parameter determines when various triggered trace actions occur. Supported actions include turning tracing on and off for all threads, turning tracing on or off for the current thread, or producing various dumps.</p> <pre><code>-Xtrace:trigger=&lt;clause&gt;[,&lt;clause&gt;]\n</code></pre> <p>This trace option does not control what is traced. It controls only whether the information that has been selected by the other trace options is produced as normal or is blocked.</p>"},{"location":"xtrace/#types","title":"Types","text":"<p>Each clause of the <code>trigger</code> parameter can be one of the following types:</p> <ul> <li>a method (<code>-Xtrace:trigger=method{...}</code>)</li> <li>a tracepoint ID (<code>-Xtrace:trigger=tpnid{...}</code>)</li> <li>a group (<code>-Xtrace:trigger=group{...}</code>)</li> </ul> <p>You can specify multiple clauses of the same type if required, but you do not need to specify all types.</p> method <pre><code> -Xtrace:trigger=method{&lt;methodspec&gt;[,&lt;entryAction&gt;[,&lt;exitAction&gt;[,&lt;delayCount&gt;[,&lt;matchcount&gt;]]]]}\n</code></pre> <p>On entering a method that matches <code>&lt;methodspec&gt;</code>, the specified <code>&lt;entryAction&gt;</code> is run. On leaving a method that matches <code>&lt;methodspec&gt;</code>, the specified <code>&lt;exitAction&gt;</code> is run. If you specify a <code>&lt;delayCount&gt;</code>, the actions are performed only after a matching <code>&lt;methodspec&gt;</code> has been entered that many times. If you specify a <code>&lt;matchCount&gt;</code>, <code>&lt;entryAction&gt;</code> and <code>&lt;exitAction&gt;</code> are performed at most that many times.</p> <p><code>&lt;methodspec&gt;</code> is the specification of a Java method, consisting of a class and a method name separated by a dot. For example, specify <code>HelloWorld.main</code>. If the class is in a package, the package name must be included, separated by slashes. For example, specify <code>java/lang/String.getBytes</code>.</p> <p>A wildcard \"*\" can be used at the start or end of the class and method names, or both. For example, you can specify <code>*/String.get*</code>. To specify a constructor method, use <code>&lt;init&gt;</code> as the method name. Method signatures cannot be specified, so a method specification applies to all overloaded methods.</p> tracepoint ID <pre><code> -Xtrace:trigger=tpnid{&lt;tpnid&gt;|&lt;tpnidRange&gt;,&lt;action&gt;[,&lt;delayCount&gt;[,&lt;matchcount&gt;]]}\n</code></pre> <p>On finding the specified active tracepoint ID (<code>&lt;tpnid&gt;</code>) or a tracepoint ID) that falls inside the specified <code>&lt;tpnidRange&gt;</code>, the specified action is run. If you specify a <code>&lt;delayCount&gt;</code>, the action is performed only after the VM finds such an active <code>&lt;tpnid&gt;</code> that many times. If you specify a <code>&lt;matchCount&gt;</code>, <code>&lt;action&gt;</code> is performed at most that many times.</p> group <pre><code> -Xtrace:trigger=group{&lt;groupname&gt;,&lt;action&gt;[,&lt;delayCount&gt;[,&lt;matchcount&gt;]]}\n</code></pre> <p>On finding any active tracepoint that is defined as being in trace group <code>&lt;groupname&gt;</code>, for example Entry or Exit, the specified action is run. If you specify a <code>&lt;delayCount&gt;</code>, the action is performed only after that many active tracepoints from group <code>&lt;groupname&gt;</code> have been found. If you specify a <code>&lt;matchCount&gt;</code>, <code>&lt;action&gt;</code> is performed at most that many times.</p>"},{"location":"xtrace/#actions","title":"Actions","text":"<p>Wherever an action (<code>&lt;action&gt;</code>, <code>&lt;entryAction&gt;</code>, or <code>&lt;exitAction&gt;</code>) must be specified in one of the <code>trigger</code> parameter clauses, you must select from these options:</p> <code>&lt;action&gt;</code> Effect <code>abort</code> Halt the VM. <code>ceedump</code> This action is applicable to z/OS\u00ae only. For more information, see z/OS LE CEEDUMPs. <code>coredump</code> Produce a system dump. See Dump agents (<code>-Xdump:system</code>) <code>heapdump</code> Produce a heap dump. See Heap dump. <code>javadump</code> Produce a Java dump. See Java dump. <code>jstacktrace</code> Examine the Java stack of the current thread and generate auxiliary tracepoints for each stack frame. The auxiliary tracepoints are written to the same destination as the tracepoint or method trace that triggered the action. You can control the number of stack frames examined with the <code>stackdepth=n</code> option. See the stackdepth option. <code>resume</code> Resume all tracing (except for threads that are suspended by the action of the resumecount property and <code>Trace.suspendThis()</code> calls). <code>resumethis</code> Decrement the suspend count for this thread. If the suspend count is zero or less, resume tracing for this thread. <code>segv</code> Cause a segmentation violation. (Intended for use in debugging.) <code>sleep</code> Delay the current thread for a length of time controlled by the sleeptime option. The default is 30 seconds. See sleeptime option. <code>snap</code> Snap all active trace buffers to a file in the current working directory. The file name has the format: <code>Snapnnnn.yyyymmdd.hhmmssth.ppppp.trc</code>, where nnnn is the sequence number of the snap file since VM startup, yyyymmdd is the date, hhmmssth is the time, and ppppp is the process ID in decimal with leading zeros removed. <code>suspend</code> Suspend all tracing (except for special trace points). <code>suspendthis</code> Increment the suspend count for this thread. If the suspend-count is greater than zero, prevent all tracing for this thread. <code>sysdump</code> (or <code>coredump</code>) Produce a system dump. See Dump agents(<code>-Xdump:system</code>). <p>Here are some examples of using the <code>trigger</code> option:</p> <p>To produce a Java dump when a method is entered, specify the following command:</p> <pre><code>-Xtrace:trigger=method{java/lang/String.getBytes,javadump}\n</code></pre> <p>To produce a system dump when a method is entered, specify the following command:</p> <pre><code>-Xtrace:trigger=method{java/lang/String.getBytes,sysdump}\n</code></pre> <p>To produce a Java dump when a class constructor is called, specify the following command:</p> <pre><code>\"-Xtrace:trigger=method{java/lang/Thread.&lt;init&gt;,javadump}\"\n</code></pre> <p> Note: This trace option is enclosed in quotation marks to avoid unwanted shell expansion of some of the characters.</p> <p>To produce a Java dump when a class static initializer is called, specify the following command:</p> <pre><code>\"-Xtrace:trigger=method{java/lang/Thread.&lt;clinit&gt;,javadump}\"\n</code></pre> <p> Note: This trace option is enclosed in quotation marks to avoid unwanted shell expansion of some of the characters.</p> <p>To produce a Java dump when a method is entered 1000 times and 1001 times, specify the following command:</p> <pre><code>-Xtrace:trigger=method{java/lang/String.getBytes,javadump,,1000,2}\n</code></pre> <p>To start tracing this thread when it enters any method in <code>java/lang/String</code>, and to stop tracing the thread after exiting the method, specify the following command:</p> <pre><code>-Xtrace:resumecount=1\n</code></pre> <p>-Xtrace:trigger=method{java/lang/String.*,resumethis,suspendthis}</p> <p>To resume all tracing when any thread enters a method in any class that starts with error, specify the following command:</p> <pre><code>-Xtrace:trigger=method{*.error*,resume}\n</code></pre> <p>To trace (all threads) while the application is active; that is, not starting or shut down. (The application name is <code>HelloWorld</code>), specify the following command:</p> <pre><code>-Xtrace:suspend,trigger=method{HelloWorld.main,resume,suspend}\n</code></pre> <p>To print a Java stack trace to the console when the mycomponent.1 tracepoint is reached, specify the following command:</p> <pre><code>-Xtrace:print=mycomponent.1,trigger=tpnid{mycomponent.1,jstacktrace}\n</code></pre> <p>To write a Java stack trace to the trace output file when the <code>Sample.code()</code> method is called, specify the following command:</p> <pre><code>-Xtrace:maximal=mt,output=trc.out,methods={mycompany/mypackage/Sample.code},trigger=method{mycompany/mypackage/Sample.code,jstacktrace}\n</code></pre>"},{"location":"xtrace/#what","title":"<code>what</code>","text":"<pre><code>-Xtrace:what\n</code></pre> <p>Shows the current trace settings</p>"},{"location":"xtrace/#see-also","title":"See also","text":"<ul> <li>Application trace</li> <li>Heap dump</li> <li>Java dump</li> <li>Dump viewer</li> </ul>"},{"location":"xtunevirtualized/","title":"-Xtune:virtualized","text":""},{"location":"xtunevirtualized/#-xtunevirtualized","title":"-Xtune:virtualized","text":"<p>Optimizes Eclipse OpenJ9\u2122 VM function for virtualized environments, such as a cloud, by reducing OpenJ9 VM CPU consumption when idle.</p> <p> Note: Performance is optimized if there is a large shared classes cache (SCC) and AOT space in the SCC is not capped.</p>"},{"location":"xtunevirtualized/#syntax","title":"Syntax","text":"<pre><code>    -Xtune:virtualized\n</code></pre> <p>This option is recommended for CPU-constrained environments, such as those found in cloud deployments that use containers. Internally, the option makes the JIT compiler more conservative with inlining and recompilation decisions, which saves CPU resources. The Garbage Collector also reduces the rate of heap expansion, which reduces the memory footprint. These changes to reduce the amount of CPU that is consumed are at the expense of a small loss in throughput.</p> <p>When <code>-Xtune:virtualized</code> is used in conjunction with the <code>-Xshareclasses</code> option, the JIT compiler is more aggressive with its use of AOT-compiled code compared to setting only <code>-Xshareclasses</code>. This action provides additional CPU savings during application start-up and ramp-up, but comes at the expense of an additional small loss in throughput.</p>"},{"location":"xtunevirtualized/#see-also","title":"See also","text":"<ul> <li>For an example of the effect of using this option, see: Measuring the strengths of OpenJDK with Eclipse OpenJ9</li> </ul>"},{"location":"xverbosegclog/","title":"-Xverbosegclog","text":""},{"location":"xverbosegclog/#-xverbosegclog","title":"-Xverbosegclog","text":"<p>Causes garbage collection (GC) output from the <code>-verbose:gc</code> option to be written to a specified file.</p>"},{"location":"xverbosegclog/#syntax","title":"Syntax","text":"<pre><code>    -Xverbosegclog[:&lt;filename&gt;[,&lt;x&gt;,&lt;y&gt;]]\n</code></pre> <p>where <code>&lt;filename&gt;</code> is the name of the file to which output is written. Dump agent tokens can be used in the filename.</p> <p>If the file cannot be found, the file is created, and output is written to the new file.</p> <p>If the file cannot be created (for example, if an invalid filename is specified), output is redirected to <code>stderr</code>.</p> <p>If you do not specify a file name, <code>verbosegc.%Y%m%d.%H%M%S.%pid.txt</code> is used (for example, <code>verbosegc.20180124.093210.1234.txt</code>).</p> <p>If you specify <code>&lt;x&gt;</code> and <code>&lt;y&gt;</code>, output is redirected to <code>x</code> files, each containing <code>y</code> GC cycles.</p>"},{"location":"xverbosegclog/#default-behavior","title":"Default behavior","text":"<p>By default, no verbose GC logging occurs.</p>"},{"location":"xverbosegclog/#see-also","title":"See also","text":"<ul> <li>Dump agent tokens for more information.</li> <li>Verbose GC logs and Log examples for more information about verbose GC logs.</li> </ul>"},{"location":"xverify/","title":"-Xverify","text":""},{"location":"xverify/#-xverify","title":"-Xverify","text":"<p>As described in the Oracle documentation, this HotSpot option enables or disables the verifier. For compatibility, this option is also supported by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xverify/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xverify</code> Enables verification for all non-bootstrap classes. <code>-Xfuture</code> verification is not enabled. yes <code>-Xverify:all</code> Enables verification for all classes and enables <code>-Xfuture</code> verification. \u00a0 You cannot use this setting in conjunction with -XX:+ClassRelationshipVerifier. \u00a0 Note: This setting might have an impact on performance. <code>-Xverify:remote</code> For compatibility, this parameter is accepted, but is equivalent to the default <code>-Xverify</code>. <code>-Xverify:none</code> Disables the verifier. \u00a0 Note: This is not a supported configuration and, as noted, was deprecated from Java 13. If you encounter problems with the verifier turned off, remove this option and try to reproduce the problem. <p> Note: The option <code>-Xverify:none</code> (and its equivalent <code>-noverify</code>) was deprecated in Java 13. Both options might be removed in a future release. OpenJ9 issues a warning if these options are used in Java 13 and later versions. </p>"},{"location":"xx_jvm_commands/","title":"Using -XX options","text":""},{"location":"xx_jvm_commands/#using-xx-command-line-options","title":"Using -XX command-line options","text":"<p>Java\u2122 VM command-line options that are specified with <code>-XX:</code> are not checked for validity. If the VM does not recognize the option, the option is ignored. These options can therefore be used across different VM versions without ensuring a particular level of the VM.  If you want to turn off this behavior to test whether your -XX options are valid, use the -XX:-IgnoreUnrecognizedXXColonOptions option.</p> <p>For options that take a <code>&lt;size&gt;</code> parameter, add a suffix to the size value: \"k\" or \"K\" to indicate kilobytes, \"m\" or \"M\" to indicate megabytes, \"g\" or \"G\" to indicate gigabytes, or \"t\" or \"T\" to indicate terabytes.</p> <p>For example, to set the <code>-XX:MaxDirectMemorySize</code> value to 16 MB, you can specify <code>-XX:MaxDirectMemorySize16M</code>, <code>-XX:MaxDirectMemorySize16m</code>, <code>-XX:MaxDirectMemorySize16384K</code>, or <code>XX:MaxDirectMemorySize16384k</code> on the command line.</p>"},{"location":"xxactiveprocessorcount/","title":"-XXActiveProcessorCount","text":""},{"location":"xxactiveprocessorcount/#-xxactiveprocessorcount","title":"-XX:ActiveProcessorCount","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122 for compatibility. Use this option to override the number of CPUs that the VM automatically detects and uses when creating threads for various subsystems.</p>"},{"location":"xxactiveprocessorcount/#syntax","title":"Syntax","text":"<pre><code>    -XX:ActiveProcessorCount=&lt;n&gt;\n</code></pre> <p>Where <code>&lt;n&gt;</code> is the number of CPUs.</p> Setting Value Default <code>&lt;n&gt;</code> 1 or greater There is no default value. This option is not enabled by default. If set to <code>0</code>, there is no effect. <p>When you set this option the following line in a Java dump file is updated to indicate the number of CPUs specified:</p> <pre><code>2CIACTIVECPU Active CPUs\n</code></pre> <p>If this option is not set, the value for this line is <code>0</code> Active CPUs.</p>"},{"location":"xxadaptivegcthreading/","title":"-XX:[+|-]AdaptiveGCThreading","text":""},{"location":"xxadaptivegcthreading/#-xx-adaptivegcthreading","title":"-XX:[+|-]AdaptiveGCThreading","text":"<p> Restriction: Currently, this feature is available only with the <code>gencon</code> GC policy.</p> <p>When this option is enabled, the active GC thread count is adjusted for each garbage collection (GC) cycle based on heuristics. That is, when a GC cycle successfully completes, the collector evaluates parallelism using aggregated thread statistics gathered during the completed cycle and projects a new thread count for the next cycle. For example, the thread count might be reduced if it is determined that an unnecessary overhead was incurred as a result of synchronization, lack of work sharing, or CPU availability. Similarly, the thread count may be increased if there's an opportunity to gain benefits from increased parallelism. </p> <p> Notes:</p> <ul> <li>This option is ignored when the GC thread count is enforced, for example when using the <code>-xgcthreads</code> or <code>-XX:ParallelGCThreads</code> options.</li> <li>By default, the number of GC threads is based on the number of CPUs reported by the operating system. This value is used as the maximum thread count. However, an upper bound can be specified by using <code>-xgcmaxthreads</code> or <code>XX:ParallelGCMaxThreads</code>.</li> </ul>"},{"location":"xxadaptivegcthreading/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]AdaptiveGCThreading\n</code></pre> Setting Effect Default <code>-XX:+AdaptiveGCThreading</code> Enable yes <code>-XX:-AdaptiveGCThreading</code> Disable <p>This optimization aims to automatically tune the GC thread count. Manually tuning and setting a thread count can be suboptimal because workloads typically change over the lifetime of an application.</p> <p>You can check the active thread count value that is used by the garbage collector to complete the cycle by inspecting verbose GC output. The following example shows active thread count being reduced from 8 to 3:</p> <pre><code>&lt;gc-end id=\"8\" type=\"scavenge\" contextid=\"4\" durationms=\"2.248\" usertimems=\"3.694\" systemtimems=\"1.345\" stalltimems=\"11.003\" timestamp=\"2021-03-12T01:35:10.768\" activeThreads=\"8\"&gt;\n&lt;gc-end id=\"20\" type=\"scavenge\" contextid=\"16\" durationms=\"7.045\" usertimems=\"6.360\" systemtimems=\"0.955\" stalltimems=\"31.964\" timestamp=\"2021-03-12T01:35:10.777\" activeThreads=\"6\"&gt;\n&lt;gc-end id=\"32\" type=\"scavenge\" contextid=\"28\" durationms=\"1.943\" usertimems=\"7.112\" systemtimems=\"0.454\" stalltimems=\"6.076\" timestamp=\"2021-03-12T01:35:10.781\" activeThreads=\"5\"&gt;\n&lt;gc-end id=\"44\" type=\"scavenge\" contextid=\"40\" durationms=\"1.253\" usertimems=\"2.910\" systemtimems=\"0.297\" stalltimems=\"2.416\" timestamp=\"2021-03-12T01:35:10.788\" activeThreads=\"4\"&gt;\n&lt;gc-end id=\"56\" type=\"scavenge\" contextid=\"52\" durationms=\"1.487\" usertimems=\"3.991\" systemtimems=\"0.447\" stalltimems=\"2.918\" timestamp=\"2021-03-12T01:35:10.790\" activeThreads=\"4\"&gt;\n&lt;gc-end id=\"68\" type=\"scavenge\" contextid=\"64\" durationms=\"0.400\" usertimems=\"1.002\" systemtimems=\"0.178\" stalltimems=\"0.658\" timestamp=\"2021-03-12T01:35:10.791\" activeThreads=\"4\"&gt;\n&lt;gc-end id=\"80\" type=\"scavenge\" contextid=\"76\" durationms=\"0.187\" usertimems=\"1.099\" systemtimems=\"0.127\" stalltimems=\"0.112\" timestamp=\"2021-03-12T01:35:10.792\" activeThreads=\"3\"&gt;\n&lt;gc-end id=\"92\" type=\"scavenge\" contextid=\"88\" durationms=\"0.195\" usertimems=\"0.940\" systemtimems=\"0.114\" stalltimems=\"0.067\" timestamp=\"2021-03-12T01:35:10.796\" activeThreads=\"3\"&gt;\n&lt;gc-end id=\"104\" type=\"scavenge\" contextid=\"100\" durationms=\"0.277\" usertimems=\"0.899\" systemtimems=\"0.118\" stalltimems=\"0.139\" timestamp=\"2021-03-12T01:35:10.797\" activeThreads=\"3\"&gt;\n</code></pre>"},{"location":"xxallowvmshutdown/","title":"-XXallowvmshutdown","text":""},{"location":"xxallowvmshutdown/#-xxallowvmshutdown","title":"-XXallowvmshutdown","text":"<p>This option is provided as a workaround for applications that cannot shut down cleanly, as described in APAR IZ59734.</p>"},{"location":"xxallowvmshutdown/#syntax","title":"Syntax","text":"<pre><code>    -XX:allowvmshutdown:[false|true]\n</code></pre> Setting Effect Default false Disable true Enable yes"},{"location":"xxalwayspretouch/","title":"-XX:[+|-]AlwaysPreTouch","text":""},{"location":"xxalwayspretouch/#-xx-alwayspretouch","title":"-XX:[+|-]AlwaysPreTouch","text":"<p>This Oracle HotSpot option enables or disables the committing of memory during initial heap inflation or heap expansion.</p>"},{"location":"xxalwayspretouch/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]AlwaysPreTouch\n</code></pre> Setting Effect Default <code>-XX:+AlwaysPreTouch</code> Enable <code>-XX:-AlwaysPreTouch</code> Disable yes"},{"location":"xxcheckpointgcthread/","title":"-XX:CheckpointGCThreads","text":""},{"location":"xxcheckpointgcthread/#-xxcheckpointgcthreads","title":"-XX:CheckpointGCThreads","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>At the VM startup, you can set the number of threads that the garbage collector uses for parallel operations (<code>-Xgcthreads</code>). At the time of taking the checkpoint, the <code>-XX:CheckpointGCThreads</code> option reduces the number of garbage collection (GC) threads that was set at startup.</p> <p> Restrictions: This option takes effect only when <code>-XX:+EnableCRIUSupport</code> is enabled.</p>"},{"location":"xxcheckpointgcthread/#syntax","title":"Syntax","text":"<pre><code>    -XX:CheckpointGCThreads=&lt;number&gt;\n</code></pre> Setting Value Default <code>&lt;number&gt;</code> Greater than 0 and less than or equal to the number of GC threads at the VM startup 4 <p>If the <code>&lt;number&gt;</code> is greater than the number of GC threads at startup, the VM ignores this option.</p>"},{"location":"xxcheckpointgcthread/#explanation","title":"Explanation","text":"<p>When taking a checkpoint, the VM reduces the number of GC threads that was specified at the startup and makes it equal to the thread count specified in the <code>-XX:CheckpointGCThreads</code> option. Since restoring threads adds latency to the overall VM restore time, you can minimize the restore time by reducing the GC thread count. After restoring from the checkpoint, the VM increases the GC thread count. The VM checks the following settings to determine the new GC thread count at the time of restore:</p> <ul> <li><code>-Xgcthreads</code> set at restore</li> <li>Default thread count at restore</li> <li>Checkpoint GC threads</li> </ul> <p>If you have specified the GC thread count at restore in the <code>-Xgcthreads</code> option and the count is greater than the checkpoint GC threads, the VM increases the thread count to the GC thread count set at restore.</p> <p>If you have not specified the GC thread count in the <code>-Xgcthreads</code> option or if the thread count is less than the checkpoint GC threads, then the VM determines the default thread count (as explained in the <code>-Xgcthreads</code> topic) at restore. If the default thread count is greater than the checkpoint thread count, then the VM increases the thread count to the default thread count.</p> <p>If the default thread count is lesser than the checkpoint thread count, then the thread count at restore time is same as the checkpoint thread count.</p>"},{"location":"xxcheckpointgcthread/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxclassrelationshipverifier/","title":"-XX:[+|-]ClassRelationshipVerifier","text":""},{"location":"xxclassrelationshipverifier/#-xx-classrelationshipverifier","title":"-XX:[+|-]ClassRelationshipVerifier","text":"<p>This option enables and disables the recording of class relationships in the verifier to delay validation until triggered by class loading.</p> <p> Note: You cannot use this setting in conjunction with <code>-Xfuture</code> or <code>-Xverify:all</code>, which itself enables <code>-Xfuture</code>.</p>"},{"location":"xxclassrelationshipverifier/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ClassRelationshipVerifier\n</code></pre> Setting Effect Default <code>-XX:+ClassRelationshipVerifier</code> Enable <code>-XX:-ClassRelationshipVerifier</code> Disable yes"},{"location":"xxclassrelationshipverifier/#explanation","title":"Explanation","text":"<p>When enabled, this option delays validating the relationships between classes until the classes are required to be loaded during program execution. In this way, classes that are not required, are never loaded thus reducing VM startup time. </p> <p>A verify error is thrown if validation fails.</p>"},{"location":"xxcodecachetotal/","title":"-XX:codecachetotal","text":""},{"location":"xxcodecachetotal/#-xxcodecachetotal","title":"-XX:codecachetotal","text":"<p>This option is an alias for the <code>-Xcodecachetotal</code> option.</p>"},{"location":"xxcodecachetotal/#syntax","title":"Syntax","text":"<pre><code>    -XX:codecachetotal=&lt;size&gt;\n</code></pre> See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter."},{"location":"xxcodecachetotal/#see-also","title":"See also","text":"<ul> <li><code>-XX:codecachetotalMaxRAMPercentage</code></li> </ul>"},{"location":"xxcodecachetotalmaxrampercentage/","title":"-XX:codecachetotalMaxRAMPercentage","text":""},{"location":"xxcodecachetotalmaxrampercentage/#-xxcodecachetotalmaxrampercentage","title":"-XX:codecachetotalMaxRAMPercentage","text":"<p>This option sets the maximum limit for the total JIT code cache size based on the amount of physical memory available to the VM.</p>"},{"location":"xxcodecachetotalmaxrampercentage/#syntax","title":"Syntax","text":"<pre><code>    -XX:codecachetotalMaxRAMPercentage=&lt;number&gt;\n</code></pre> Setting Value Default <code>&lt;number&gt;</code> Between 1 and 100 (fractional numbers are allowed) 25 <p>Where <code>&lt;number&gt;</code> is the maximum limit that is expressed as a percentage of the available physical memory.</p> <p>For example, if you specify <code>-XX:codecachetotalMaxRAMPercentage=30</code>, the VM is not allowed to use more than 30% of the available physical memory for the internal JIT code caches.</p>"},{"location":"xxcodecachetotalmaxrampercentage/#explanation","title":"Explanation","text":"<p>The default total size of the JIT code cache is computed as the minimum of the following two limits:</p> <ul> <li>A platform-based limit that is expressed as an absolute memory value. This limit is set at 256 MB for 64-bit systems and at 64 MB for 31/32-bit systems.</li> <li>A percentage of the amount of available physical memory the VM process is allowed to use. By default, the VM is not allowed to use more than 25% of the available physical memory for its code caches.</li> </ul> <p>In memory constrained environments, the percentage limit is relevant because the code cache size is then based on the available physical memory. The percentage limit prevents the VM from using too much memory for its code caches and thus, leaving too little memory for other VM or JIT data structures.</p> <p>For example, on a 64-bit system, the platform-specific code cache limit is 256 MB. If the VM is constrained to less than 1024 MB, say 512 MB, then the code cache limit becomes 128 MB (25% of 512 MB) because the percentage limit is less than the platform limit.</p> <p>To fine-tune the code cache size limit for your specific application as a percentage of the available physical memory, you can use the <code>-XX:codecachetotalMaxRAMPercentage</code> option.</p> <p>As an alternative, you can use the <code>-XX:codecachetotal</code> or the <code>-Xcodecachetotal</code> options to set the code cache size limit as an absolute value (platform-based limit). The absolute value that is specified with these options takes precedence over the percentage that is specified with the <code>-XX:codecachetotalMaxRAMPercentage</code> option.</p> <p> Restrictions:</p> <ul> <li>If the <code>-XX:codecachetotal</code> or <code>-Xcodecachetotal</code> option is specified, then the <code>-XX:codecachetotalMaxRAMPercentage</code> option is ignored.</li> <li>The percentage of the available physical memory that is specified in the <code>-XX:codecachetotalMaxRAMPercentage</code> option is used only if the total cache value thus calculated is less than the default total code cache value set for the platform (minimum of the two limits).</li> </ul>"},{"location":"xxcompactstrings/","title":"-XX:[+|-]CompactStrings","text":""},{"location":"xxcompactstrings/#-xx-compactstrings","title":"-XX:[+|-]CompactStrings","text":"<p>This HotSpot option is reimplemented by Eclipse OpenJ9\u2122 and when enabled causes an ISO8859-1 (also known as Latin-1) character representation to be used internally for <code>String</code> objects, while preserving full API compatibility.</p> <p>This feature provides heap space savings by using an 8-bit character set internally. Most benefit is gained when the majority of the <code>String</code> objects that your application uses can be encoded using the ISO8859-1 character encoding. </p> <p>If the option is not enabled, the JIT compiler is nevertheless optimized so that although there is no saving in heap space, there is also no performance penalty.</p> <p>Further details are available at JEP 254: Compact Strings.</p> <p> Note: With OpenJ9, this option is supported on OpenJDK version 8 and later versions, whereas HotSpot supports it only from Java version 9.</p>"},{"location":"xxcompactstrings/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+CompactStrings</code> Enable <code>String</code> compression yes <code>-XX:-CompactStrings</code> Disable <code>String</code> compression yes"},{"location":"xxconcgcthreads/","title":"-XX:ConcGCThreads","text":""},{"location":"xxconcgcthreads/#-xxconcgcthreads","title":"-XX:ConcGCThreads","text":"<p>This Oracle HotSpot option affects the number of threads used by the concurrent garbage collector. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxconcgcthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ConcGCThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of low-priority background threads that are attached to assist the mutator threads in concurrent mark.</p> <p>Within OpenJ9 this option is directly mapped to <code>-Xconcurrentbackground</code>.</p>"},{"location":"xxcontinuationcache/","title":"-XX:ContinuationCache","text":""},{"location":"xxcontinuationcache/#-xxcontinuationcache","title":"-XX:ContinuationCache","text":"<p> This option sets the continuation tier 1 and 2 cache size to optimize virtual thread performance.</p>"},{"location":"xxcontinuationcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:ContinuationCache:t1=&lt;size&gt;,t2=&lt;size&gt;\n</code></pre> Setting Value Default <code>t1=&lt;size&gt;</code> 0 to 2<sup>32</sup> - 1 (4,294,967,295) 1 <code>t2=&lt;size&gt;</code> 0 to 2<sup>32</sup> - 1 (4,294,967,295) Number of processors x 2 <p>Where <code>t1</code> is the tier 1 cache and <code>t2</code> is the tier 2 cache.</p> <p>The tier 1 cache holds data that is not shareable between threads.</p> <p>The tier 2 cache holds data that can be shared globally between threads.</p>"},{"location":"xxcontinuationcache/#explanation","title":"Explanation","text":"<p>When a virtual thread is created, it is associated with a continuation, which holds the target task of the virtual thread. When a virtual thread starts, the VM saves the current thread (carrier thread) state in an internal data structure that is linked with the continuation. When the associated continuation starts, the VM allocates the memory for the internal data structure and stores its reference in the continuation. When the continuation finishes, the VM stores the internal data structure in a cache instead of freeing the associated memory. New continuations can reuse the cached structure instead of allocating new memory for it. The VM can resume thread execution from the saved state later, typically on a different thread.</p> <p>If the virtual thread stops, the VM loads the state of the previous thread from the continuation and runs that thread. When the virtual thread does not complete running, the last state of the virtual thread is stored in the continuation during the stop operation. At a later point, the scheduler runs the incomplete virtual thread using the thread state stored in the continuation.</p> <p>Reusing the cached structure improves the performance of creating virtual threads. The performance benefits are more evident in applications that scale to millions of virtual threads.</p> <p>The continuation cache is implemented in two tiers, tier 1 and tier 2. You can set the maximum size for the two tiers with the <code>-XX:ContinuationCache</code> option. If an application uses more than 10000 virtual threads, setting a larger cache size might improve performance.</p> <p>When the size of the cache increases, the number of allocations reduces but the cache lookup time might also increase. Evaluate both the number of allocations and the optimal lookup time to set the appropriate cache size. </p>"},{"location":"xxcontinuationcache/#see-also","title":"See also","text":"<ul> <li><code>-XX:[+|-]ShowCarrierFrames</code></li> </ul>"},{"location":"xxcriurestorenonportablemode/","title":"-XX:[+|-]CRIURestoreNonPortableMode","text":""},{"location":"xxcriurestorenonportablemode/#-xx-criurestorenonportablemode","title":"-XX:[+|-]CRIURestoreNonPortableMode","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>This option specifies whether the JIT and AOT compilers generate nonportable compiled code on restore.</p> <p> Restrictions:</p> <ul> <li>This option takes effect only when <code>-XX:+EnableCRIUSupport</code> is enabled.</li> <li>When you disable this option,<ul> <li><code>CRIUSECProvider</code> is the only security provider in both checkpoint and restore.</li> <li>JITServer technology is disabled both before you take a checkpoint and after you restore the VM.</li> <li>the VM generates only portable code, both before you take a checkpoint and after you restore the VM.</li> </ul> </li> </ul>"},{"location":"xxcriurestorenonportablemode/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]CRIURestoreNonPortableMode\n</code></pre> Setting Effect Default <code>-XX:+CRIURestoreNonPortableMode</code> Enable yes <code>-XX:-CRIURestoreNonPortableMode</code> Disable"},{"location":"xxcriurestorenonportablemode/#explanation","title":"Explanation","text":"<p>The JIT compiler can exploit hardware features of the system on which it is running, to generate compiled code. That code might therefore fail if it is included in a checkpoint image that you later restore on a different system. For example, the compiled code might try to exploit a hardware feature that doesn't exist on the new machine, then fail. To avoid this problem, the JIT compiler by default generates code that exploits only basic hardware features, therefore portable to different systems.</p> <p>The <code>-XX:+CRIURestoreNonPortableMode</code> option is set by default so that on restore the JIT compiler can start generating nonportable compiled code. Likewise, the VM can also load nonportable AOT code post-restore. Generating nonportable compiled code also means that no further checkpoints are permitted. Only a single checkpoint can be taken in the VM's lifetime.</p> <p>If you require multiple checkpoints, you can use the <code>-XX:-CRIURestoreNonPortableMode</code> option to generate portable JIT compiled code after restore.</p>"},{"location":"xxcriurestorenonportablemode/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxdiagnosesynconvaluebasedclasses/","title":"-XX:DiagnoseSyncOnValueBasedClasses","text":""},{"location":"xxdiagnosesynconvaluebasedclasses/#-xxdiagnosesynconvaluebasedclasses","title":"-XX:DiagnoseSyncOnValueBasedClasses","text":"<p> This HotSpot option provides warnings about improper attempts to synchronize on instances of a value-based class. The option is recognized by Eclipse OpenJ9\u2122 for compatibility.</p>"},{"location":"xxdiagnosesynconvaluebasedclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:DiagnoseSyncOnValueBasedClasses=&lt;number&gt;\n</code></pre> <code>&lt;number&gt;</code> value Effect 1 Generate <code>VirtualMachineError</code> error 2 Print a warning message"},{"location":"xxdisableexplicitgc/","title":"-XX:[+|-]DisableExplicitGC","text":""},{"location":"xxdisableexplicitgc/#-xx-disableexplicitgc","title":"-XX:[+|-]DisableExplicitGC","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122 for compatibility. See \u2011Xenableexplicitgc.md / \u2011Xdisableexplicitgc for details.</p>"},{"location":"xxdisableexplicitgc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+DisableExplicitGC</code> Enable GC yes <code>-XX:-DisableExplicitGC</code> Disable GC"},{"location":"xxdisclaimjitscratch/","title":"-XX:[+|-]DisclaimJitScratch","text":""},{"location":"xxdisclaimjitscratch/#-xx-disclaimjitscratch","title":"-XX:[+|-]DisclaimJitScratch","text":"<p> Restriction: This option is deprecated; the option is accepted but ignored.</p> <p>(Linux\u00ae only)</p> <p>The <code>-XX:+DisclaimJitScratch</code> option signals to the operating system to discard temporary physical memory that is consumed by the JIT compilation threads.</p>"},{"location":"xxdisclaimjitscratch/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]DisclaimJitScratch\n</code></pre> Setting Effect Default <code>-XX:+DisclaimJitScratch</code> Enable <code>-XX:-DisclaimJitScratch</code> Disable yes"},{"location":"xxdisclaimjitscratch/#explanation","title":"Explanation","text":"<p>Discarding temporary physical memory can reduce the physical memory reported in use by the Java\u2122 application. The physical memory that is released is available to other processes without the operating system needing to search for the least recently used frames.</p> <p>The <code>-XX:-DisclaimJitScratch</code> option turns off a previously enabled <code>-XX:+DisclaimJitScratch</code> option.</p>"},{"location":"xxenable3164interoperability/","title":"-XX:[+|-]Enable3164Interoperability","text":""},{"location":"xxenable3164interoperability/#-xx-enable3164interoperability","title":"-XX:[+|-]Enable3164Interoperability","text":"<p>(z/OS\u00ae only)</p> <p>Enables support for using 31-bit native applications with the 64-bit Java\u2122 virtual machine, where that support is available. For more information, see Using 31-bit native code with the 64-bit Java VM.</p>"},{"location":"xxenablecpumonitor/","title":"-XX:[+|-]EnableCPUMonitor","text":""},{"location":"xxenablecpumonitor/#-xx-enablecpumonitor","title":"-XX:[+|-]EnableCPUMonitor","text":"<p>This option relates to the information about the CPU usage of thread categories that is available with the <code>com.ibm.lang.management.JvmCpuMonitorMXBean</code> application programming interface.</p> <p> Restriction: This option might not be supported in subsequent releases.</p>"},{"location":"xxenablecpumonitor/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]EnableCPUMonitor\n</code></pre> Setting Effect Default <code>-XX:+EnableCPUMonitor</code> Enable yes <code>-XX:-EnableCPUMonitor</code> Disable"},{"location":"xxenablecpumonitor/#explanation","title":"Explanation","text":"<p>The <code>-XX:+EnableCPUMonitor</code> option enables CPU monitoring, which allows a JMX bean to track CPU usage on a per thread basis and attributes the usage against different categories. For more information, see the <code>JvmCpuMonitorMXBean</code> interface in the <code>com.ibm.lang.management</code> API documentation.</p> <p>To turn off CPU monitoring, set the <code>-XX:-EnableCPUMonitor</code> option on the command line.</p>"},{"location":"xxenablecpumonitor/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]ReduceCPUMonitorOverhead</li> </ul>"},{"location":"xxenablecriusupport/","title":"-XX:[+|-]EnableCRIUSupport","text":""},{"location":"xxenablecriusupport/#-xx-enablecriusupport","title":"-XX:[+|-]EnableCRIUSupport","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>This option enables or disables support for Checkpoint/Restore In Userspace (CRIU).</p> <p> Restrictions: If CRIU support is enabled,</p> <ul> <li>you cannot use a Java\u2122 security manager. If you try to specify a Java security manager, for example by using the <code>-Djava.security.manager</code> system property on the Java command line or the <code>java.lang.System.setSecurityManager</code> method in your application, the VM throws the <code>java.lang.UnsupportedOperationException</code> error.</li> <li><code>CRIUSECProvider</code> is the only security provider that is available in the checkpoint phase until restore.</li> <li>JITServer is disabled in the checkpoint phase even if the server exists and you have specified the <code>-XX:+UseJITServer</code> option. When you specify the <code>-XX:+EnableCRIUSupport</code> and <code>-XX:+CRIURestoreNonPortableMode</code> options along with the <code>-XX:+UseJITServer</code> option, and the server exists, the VM enables the JITServer server automatically at the restore point. The VM client connects to a JITServer in the context of CRIU as outlined in the following table (where yes means that the VM connects to a JITServer instance and no means that the VM does not connect to a JITServer instance):</li> </ul> Nonportable mode (default)  Pre-checkpoint Nonportable mode (default)  Post restore Portable mode Pre-checkpoint Portable mode Post restore Pre-checkpoint: No options Post restore: No options no no no no Pre-checkpoint: No options Post restore: <code>-XX:+UseJITServer</code> no yes no yes Pre-checkpoint: <code>-XX:+UseJITServer</code>Post restore: No options no yes yes yes Pre-checkpoint: <code>-XX:+UseJITServer</code>Post restore: <code>-XX:-UseJITServer</code> no no yes no Pre-checkpoint: <code>-XX:-UseJITServer</code>Post restore: <code>-XX:+UseJITServer</code> no no no no <ul> <li> <p>you cannot use the <code>balanced</code> and <code>metronome</code> garbage collection (GC) policies. If you use the <code>-Xgcpolicy:balanced</code> or <code>-Xgcpolicy:metronome</code> options to specify those policies, the VM throws the following errors:</p> <p><code>JVMJ9GC090E -Xgcpolicy:balanced is currently unsupported with -XX:+EnableCRIUSupport   JVMJ9VM007E Command-line option unrecognised: -Xgcpolicy:balanced   Error: Could not create the Java Virtual Machine.   Error: A fatal exception has occurred. Program will exit.</code></p> <p><code>JVMJ9GC090E -Xgcpolicy:metronome is currently unsupported with -XX:+EnableCRIUSupport   JVMJ9VM007E Command-line option unrecognised: -Xgcpolicy:metronome   Error: Could not create the Java Virtual Machine.   Error: A fatal exception has occurred. Program will exit.</code></p> </li> </ul>"},{"location":"xxenablecriusupport/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]EnableCRIUSupport\n</code></pre> Setting Effect Default <code>-XX:+EnableCRIUSupport</code> Enable <code>-XX:-EnableCRIUSupport</code> Disable yes"},{"location":"xxenablecriusupport/#explanation","title":"Explanation","text":"<p>When you enable the option, the VM starts with the support for checkpoint and restore processes. The VM starts the JIT, GC, Security, and other internal components that make the checkpoint and restore points feasible. The option enables the use of <code>org.eclipse.openj9.criu.CRIUSupport</code> APIs. With CRIU support, you can take a checkpoint of the VM and restore the checkpoint image. When you specify the <code>-XX:+EnableCRIUSupport</code> option, the VM generates only those compiled codes that are portable (see <code>-XX:[+|-]PortableSharedCache</code>) to facilitate restoring of the checkpoint image in multiple environments. VM does not load any code from the shared classes cache that is nonportable pre-checkpoint.</p> <p>Taking a checkpoint and restoring the checkpoint image generally happens on different environments with different behaviors. OpenJ9 makes compensations for such differences to ensure successful restore. For example, the VM compensates for the downtime between checkpoint and restore for elapsed time sensitive APIs such as <code>System.nanotime()</code> and <code>java.util.Timer</code>.</p> <p>For more information about the OpenJ9 compensations and Time APIs, see the Compensation section in the OpenJ9 CRIU Support: A look under the hood\u202f(part II) blog post.</p>"},{"location":"xxenablecriusupport/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxenabledynamicagentloading/","title":"-XX:[+|-]EnableDynamicAgentLoading","text":""},{"location":"xxenabledynamicagentloading/#-xx-enabledynamicagentloading","title":"-XX:[+|-]EnableDynamicAgentLoading","text":"<p>This option enables or disables the dynamic loading of agents into a running VM.</p>"},{"location":"xxenabledynamicagentloading/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]EnableDynamicAgentLoading\n</code></pre> Setting Effect Default <code>-XX:+EnableDynamicAgentLoading</code> Enable yes <code>-XX:-EnableDynamicAgentLoading</code> Disable"},{"location":"xxenabledynamicagentloading/#explanation","title":"Explanation","text":"<p>With the Attach API, your application can connect to a running VM and load an agent dynamically into that VM to run tasks. Some libraries misuse the Attach API to dynamically load an agent to run tasks without the approval of the application owner.</p> <p>You can disable the dynamic loading of the agents into a VM after startup with the <code>-XX:-EnableDynamicAgentLoading</code> option.</p> <p> For Java\u2122 21 and later, the following warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the <code>-XX:+EnableDynamicAgentLoading</code> option. These warnings are not issued if the same agents were loaded before either by using the command-line options or an earlier dynamic loading.</p> <pre><code>WARNING: A {Java,JVM TI} agent has been loaded dynamically (file:/u/bob/agent.jar)\nWARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading to hide this warning\nWARNING: If a serviceability tool is not in use, please run with -Djdk.instrument.traceUsage for more information\nWARNING: Dynamic loading of agents will be disallowed by default in a future release\n</code></pre> <p>These warnings are issued only once for the same agent when the <code>-XX:+EnableDynamicAgentLoading</code> option is not specified.</p> <p>If the <code>-XX:+EnableDynamicAgentLoading</code> option is set, all agents that are dynamically loaded are considered as approved by the application owner, and therefore, no warnings are issued.</p> <p>Eclipse OpenJ9\u2122 supported operating systems other than AIX\u00ae have APIs to determine whether the same agent was loaded before or not, even if an agent is loaded with a platform-independent name or an absolute path to the platform-dependent library.</p> <p>AIX systems cannot detect whether an agent was previously loaded or not if the agent was loaded through a platform-independent name or an absolute path to the platform-dependent library. Therefore, on AIX systems, the warnings are issued when an agent is loaded dynamically through the Attach API (<code>VirtualMachine.loadAgentLibrary(agent)</code>) even if the same agent was loaded before through the command-line option (<code>-agentpath:/Absolute/Path/to/agentLibrary</code>) at startup. </p>"},{"location":"xxenabledynamicagentloading/#see-also","title":"See also","text":"<ul> <li>Java Virtual Machine Tool Interface</li> <li>Java Attach API</li> </ul>"},{"location":"xxensurehashed/","title":"-XX:[+|-]EnsureHashed","text":""},{"location":"xxensurehashed/#-xx-ensurehashed","title":"-XX:[+|-]EnsureHashed","text":"<p>This option specifies classes to be pre-hashed. Objects that are created from these classes are hashed and extended with a slot to store the assigned hash value when the object is created or first moved during the garbage collection process. This option might improve performance for applications that frequently hash objects of a certain type.</p>"},{"location":"xxensurehashed/#syntax","title":"Syntax","text":"<pre><code>    -XX:+EnsureHashed:&lt;classes&gt;\n    -XX:-EnsureHashed:&lt;classes&gt;\n</code></pre> Setting Effect <code>-XX:+EnsureHashed:&lt;classes&gt;</code> Specify classes <code>-XX:-EnsureHashed:&lt;classes&gt;</code> Ignore classes <p>Where <code>&lt;classes&gt;</code> is a comma-separated list of fully qualified class names, for example, <code>java/lang/String</code>.</p>"},{"location":"xxensurehashed/#explanation","title":"Explanation","text":"<p>The <code>-XX:+EnsureHashed:&lt;classes&gt;</code> option specifies the classes and the <code>-XX:-EnsureHashed:&lt;classes&gt;</code> option ignores classes that were previously specified. These options are parsed left to right.</p> <p>For example, <code>-XX:+EnsureHashed:Class1,Class2,Class3 -XX:-EnsureHashed:Class2 -XX:+EnsureHashed:Class2,Class4 -XX:-EnsureHashed:Class1,Class3</code> results in the set of <code>EnsureHashed</code> classes {<code>Class2</code>, <code>Class4</code>}.</p> <p>Objects that are created from classes <code>Thread</code> and <code>Class</code> are allocated in the tenure region directly and therefore, do not get moved by the garbage collector often. It takes time for such pre-tenured objects to get hashed and extended with a slot. To pre-hash those objects from the start and hence, improve the performance,<code>-XX:+EnsureHashed:java/lang/Class,java/lang/Thread</code> is added to the list of default options in the <code>options.default</code> file.</p>"},{"location":"xxensurehashed/#see-also","title":"See also","text":"<ul> <li><code>-Xoptionsfile</code></li> <li>GC processing</li> </ul>"},{"location":"xxexitonoutofmemoryerror/","title":"-XX:[+|-]ExitOnOutOfMemoryError","text":""},{"location":"xxexitonoutofmemoryerror/#-xx-exitonoutofmemoryerror","title":"-XX:[+|-]ExitOnOutOfMemoryError","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122. You can use the option to trigger a shut down on VM out-of-memory conditions.</p> <p> Note: Java\u2122, heap, snap, and system dumps are enabled by default but can be disabled by including <code>-XX:-HeapDumpOnOutOfMemoryError</code>.</p>"},{"location":"xxexitonoutofmemoryerror/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ExitOnOutOfMemoryError\n</code></pre> Setting Effect Default <code>-XX:+ExitOnOutOfMemoryError</code> Enable <code>-XX:-ExitOnOutOfMemoryError</code> Disable yes"},{"location":"xxgloballockreservation/","title":"-XX:[+|-]GlobalLockReservation","text":""},{"location":"xxgloballockreservation/#-xx-globallockreservation","title":"-XX:[+|-]GlobalLockReservation","text":"<p>(AIX\u00ae and Linux on Power Systems\u2122 only)</p> <p>The <code>-XX:+GlobalLockReservation</code> option enables an optimization targeted towards more efficient handling of locking and unlocking Java\u2122 objects. The <code>-XX:-GlobalLockReservation</code> option is used to disable this optimization. The optimization is enabled by default.</p>"},{"location":"xxgloballockreservation/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]GlobalLockReservation\n    -XX:+GlobalLockReservation:&lt;parameter&gt;\n</code></pre> Setting Effect Default <code>-XX:+GlobalLockReservation</code> Enable yes <code>-XX:-GlobalLockReservation</code> Disable <p>This optimization is targeted towards applications with lots of uncontended locked objects that are being locked just to be safe. When enabled, heuristics are used to try and determine when an object will be exclusively locked by a single thread so that faster, more specialized code can be used for locking the object. If the heuristics incorrectly identify an object as a target for the optimization, performance might be adversely affected.</p> <p>The <code>-XX:-GlobalLockReservation</code> option turns off global lock reservation.</p> <p>The <code>-XX:+GlobalLockReservation</code> option can be used to enable global lock reservation if it was disabled by an option that occurs earlier in command line processing or to modify some of the global lock reservation related suboptions that are described later in this document.</p>"},{"location":"xxgloballockreservation/#parameters","title":"Parameters","text":"<p>Advanced tuning parameters are shown in the following table:</p> Parameter Effect <code>reservedTransitionThreshold</code> Changes amount of time spent analyzing an object. <code>reservedAbsoluteThreshold</code> Changes amount of time spent analyzing a class for compatibility. <code>minimumReservedRatio</code> Changes aggression level for marking a class as highly compatible. <code>cancelAbsoluteThreshold</code> Changes amount of time spent analyzing a class for incompatibility. <code>minimumLearningRatio</code> Changes aggression level for marking a class as highly incompatible."},{"location":"xxgloballockreservation/#reservedtransitionthreshold","title":"reservedTransitionThreshold","text":"<pre><code>    -XX:+GlobalLockReservation:reservedTransitionThreshold=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 1 <p>Number of times an object is locked by the same thread before it is considered reserved minus a value of 2. So, with a default value of 1, an object can be reserved the third time it is locked. <code>&lt;value&gt;</code> can be 0-3 inclusive. Values of 4 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#reservedabsolutethreshold","title":"reservedAbsoluteThreshold","text":"<pre><code>    -XX:+GlobalLockReservation:reservedAbsoluteThreshold=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 10 <p>Minimum number of objects of a class that get reserved before the class can be considered highly compatible. Objects of that class are reserved the first time they are locked. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#minimumreservedratio","title":"minimumReservedRatio","text":"<pre><code>    -XX:+GlobalLockReservation:minimumReservedRatio=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 1024 <p>Minimum ratio of reserved objects to flat objects before a class can be considered highly compatible. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#cancelabsolutethreshold","title":"cancelAbsoluteThreshold","text":"<pre><code>    -XX:+GlobalLockReservation:cancelAbsoluteThreshold=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 10 <p>Minimum number of objects of a class that get converted to flat before the class can be considered highly incompatible. Objects of that class are never reserved. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#minimumlearningratio","title":"minimumLearningRatio","text":"<pre><code>    -XX:+GlobalLockReservation:minimumLearningRatio=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 256 <p>Minimum ratio of reserved objects to flat objects to prevent class from being considered highly incompatible. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxhandlesigabrt/","title":"-XX:[+|-]HandleSIGABRT","text":""},{"location":"xxhandlesigabrt/#-xx-handlesigabrt","title":"-XX:[+|-]HandleSIGABRT","text":"<p>This option affects the handling of the operating system signal <code>SIGABRT</code>. This signal represents abnormal termination, and it can either be generated by the <code>abort</code> function or the <code>kill</code> command.</p>"},{"location":"xxhandlesigabrt/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HandleSIGABRT\n</code></pre> Setting Effect Default <code>-XX:+HandleSIGABRT</code> Enable yes <code>-XX:-HandleSIGABRT</code> Disable"},{"location":"xxhandlesigabrt/#explanation","title":"Explanation","text":"<p>When enabled, the VM handles the signal <code>SIGABRT</code> and generates the various dump files. </p> <p>When the option is disabled, the VM does not handle the signal <code>SIGABRT</code>. Generally, this signal is handled by the default operating system handler.</p> <p> Note: Do not use the <code>-XX:+HandleSIGABRT</code> and <code>-Xrs</code> options together. An error is thrown if both options are enabled. To resolve this error, one of the options should be disabled.</p>"},{"location":"xxhandlesigusr2/","title":"-XX:[+|-]HandleSIGUSR2","text":""},{"location":"xxhandlesigusr2/#-xx-handlesigusr2","title":"-XX:[+|-]HandleSIGUSR2","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae only)</p> <p>This option affects the handling of the <code>SIGUSR2</code> signal. This signal is user-defined and triggers the <code>user2</code> event, which is commonly used for taking system dump files with exclusive access. The operating system installs a default signal handler for handling <code>SIGUSR2</code>. If there is no VM or application signal handler, then the operating system's signal handler is used.</p>"},{"location":"xxhandlesigusr2/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HandleSIGAUSR2\n</code></pre> Setting Effect Default <code>-XX:+HandleSIGUSR2</code> Enable yes <code>-XX:-HandleSIGUSR2</code> Disable"},{"location":"xxhandlesigusr2/#explanation","title":"Explanation","text":"<p>When enabled, the VM handles the <code>SIGUSR2</code> signal and generates the <code>user2</code> event, which can be configured with the <code>-Xdump</code> option to trigger a dump agent.</p> <p>When the option is disabled, the VM does not handle the <code>SIGUSR2</code> signal and therefore, the VM signal handler is not installed. Generally, the default operating system handler that is installed for the <code>SIGUSR2</code> signal takes over the handling of the signal.</p> <p>For more information about the signals and signal handling, see Signal handling.</p> <p> Note: Do not use the <code>-XX:+HandleSIGUSR2</code> and <code>-Xrs</code> options together. An error is thrown if both options are enabled. To resolve this error, one of the options should be disabled.</p>"},{"location":"xxhandlesigusr2/#see-also","title":"See also","text":"<ul> <li>-Xdump</li> <li>-Xrs</li> </ul>"},{"location":"xxhandlesigxfsz/","title":"-XX:[+|-]HandleSIGXFSZ","text":""},{"location":"xxhandlesigxfsz/#-xx-handlesigxfsz","title":"-XX:[+|-]HandleSIGXFSZ","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae only)</p> <p>This option affects the handling of the operating system signal <code>SIGXFSZ</code>. This signal is generated when a process attempts to write to a file that causes the maximum file size <code>ulimit</code> to be exceeded.</p>"},{"location":"xxhandlesigxfsz/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HandleSIGXFSZ\n</code></pre> Setting Effect Default <code>-XX:+HandleSIGXFSZ</code> Enable yes <code>-XX:-HandleSIGXFSZ</code> Disable"},{"location":"xxhandlesigxfsz/#explanation","title":"Explanation","text":"<p>When enabled, the VM handles the signal <code>SIGXFSZ</code> and continues, without ending. When a file is written from a Java\u2122 API class that exceeds the maximum file size <code>ulimit</code>, an exception is raised. Log files that are created by the VM are silently truncated when they reach the maximum file size <code>ulimit</code>.</p> <p>When the option is disabled, the VM does not handle the signal <code>SIGXFSZ</code>. In this situation, if the maximum file size <code>ulimit</code> for any file is reached, the operating system ends the process with a core dump.</p>"},{"location":"xxheapdumponoutofmemory/","title":"-XX:[+|-]HeapDumpOnOutOfMemory","text":""},{"location":"xxheapdumponoutofmemory/#-xx-heapdumponoutofmemory","title":"-XX:[+|-]HeapDumpOnOutOfMemory","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122. You can use the option to to disable Java\u2122, heap, snap, and system dumps on out-of-memory conditions, which are enabled by default.</p>"},{"location":"xxheapdumponoutofmemory/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HeapDumpOnOutOfMemory\n</code></pre> Setting Effect Default <code>-XX:+HeapDumpOnOutOfMemory</code> Enable yes <code>-XX:-HeapDumpOnOutOfMemory</code> Disable"},{"location":"xxheapdumppath/","title":"-XX:HeapDumpPath","text":""},{"location":"xxheapdumppath/#-xxheapdumppath","title":"-XX:HeapDumpPath","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122 for compatibility, and you can use it as an alias for <code>-Xdump:directory=&lt;path&gt;</code>.</p> <p>This option sets the directory for all VM dumps including heap dumps, Java\u2122 dumps, and system dumps.</p>"},{"location":"xxheapdumppath/#syntax","title":"Syntax","text":"<pre><code>    -XX:HeapDumpPath=&lt;path&gt;\n</code></pre> <p>where <code>&lt;path&gt;</code> is the directory to which all dump types are written. This directory path is prefixed to the path of all non-absolute dump file names, including the file names for the default dump agents.</p>"},{"location":"xxheapmanagementmxbeancompatibility/","title":"-XX:[+|-]HeapManagementMXBeanCompatibility","text":""},{"location":"xxheapmanagementmxbeancompatibility/#-xx-heapmanagementmxbeancompatibility","title":"-XX:[+|-]HeapManagementMXBeanCompatibility","text":"<p>The MXBean interface now reports more detailed information about memory pools and garbage collectors for a garbage collection policy. In addition, the names of memory pools and garbage collectors are changed to match the naming convention that is used for verbose garbage collection logging. This option provides compatibility with earlier versions of the VM.</p>"},{"location":"xxheapmanagementmxbeancompatibility/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HeapManagementMXBeanCompatibility\n</code></pre> Setting Effect Default <code>-XX:+HeapManagementMXBeanCompatibility</code> Enable <code>-XX:-HeapManagementMXBeanCompatibility</code> Disable yes <p>Setting <code>-XX:+HeapManagementMXBeanCompatibility</code> on the command line turns on compatibility with earlier versions of the VM. Information about memory pools and garbage collectors are reported in the older format.</p> <p>When compatibility is turned off, the VM reports more detailed information and matches the naming of memory pools and garbage collectors to the naming convention that is used for verbose garbage collection logging.</p>"},{"location":"xxheapmanagementmxbeancompatibility/#explanation","title":"Explanation","text":"<p>The additional information that is available from the MXBean interface for later versions is shown in the following table:</p> Garbage collection policy <code>MemoryPool</code> names <code>GarbageCollector</code> names gencon nursery-allocate, nursery-survivor, tenured-LOA, tenured-SOA, tenured scavenge, global optthruput or optavgpause tenured-LOA, tenured-SOA, tenured global balanced balanced-reserved, balanced-eden, balanced-survivor, balanced-old partial gc, global garbage collect metronome JavaHeap global <p>The <code>MemoryPoolMXBean</code> API reports values for 4 detailed memory pools instead of a single value for the overall Java\u2122 heap. In some cases the total sum of the 4 pools is more than the maximum heap size. This irregularity can be caused if data for each pool is collected between garbage collection cycles, where objects have been moved or reclaimed. If you want to collect memory usage data that is synchronized across the memory pools, use the <code>GarbageCollectionNotificationInfo</code> or <code>GarbageCollectorMXBean.getLastGcInfo</code> extensions.</p> <p>Earlier releases included only the following names:</p> <ul> <li><code>MemoryPool</code> pool name: <code>Java heap</code></li> <li><code>GarbageCollector</code> name: <code>Copy</code> and <code>MarkSweepCompact</code>.</li> </ul>"},{"location":"xxheapmanagementmxbeancompatibility/#see-also","title":"See also","text":"<ul> <li>Verbose garbage collection logging.</li> </ul> <p>For more information about IBM\u00ae MXBeans, see the <code>com.ibm.lang.management</code> API documentation.</p>"},{"location":"xxidletuningcompactonidle/","title":"-XX:[+|-]IdleTuningCompactOnIdle","text":""},{"location":"xxidletuningcompactonidle/#-xx-idletuningcompactonidle","title":"-XX:[+|-]IdleTuningCompactOnIdle","text":"<p>(Linux\u00ae only)</p> <p> Warning: From Eclipse OpenJ9\u2122 version 0.23.0 this option has no effect.</p> <p>In versions of OpenJ9 before 0.23.0, this option controls garbage collection processing with compaction when the state of the OpenJ9 VM is set to idle.</p> <p> Restrictions:</p> <ol> <li>This option was deprecated in release 0.15.0 due to operational changes. A compaction is now triggered by internal heuristics that look into the number of fragmented pages. Typically there is no need to force a compaction. This option will be removed in the future.</li> <li>This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use.</li> <li>This option is not effective if the object heap is configured to use large pages.</li> <li>This option is not effective if -XX:+IdleTuningGcOnIdle is not specified.</li> </ol>"},{"location":"xxidletuningcompactonidle/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IdleTuningCompactOnIdle\n</code></pre> Setting Effect Default Default when running in a docker container <code>-XX:+IdleTuningCompactOnIdle</code> Enable yes <code>-XX:-IdleTuningCompactOnIdle</code> Disable yes <p>The default depends on whether or not the OpenJ9 VM is running in a container. As indicated in the table, when the VM is running in a container and the state is set to idle, the VM attempts to compact the object heap following a garbage collection cycle. The garbage collection cycle is controlled by the <code>-XX:+IdleTuningGcOnIdle</code> option, which is also enabled by default when the OpenJ9 VM is running inside a container.</p> <p>If your application is not running in a container and you want compaction to be attempted every time idle GC happens as part of the idle-tuning process, set the <code>-XX:+IdleTuningCompactOnIdle</code> option on the command line when you start your application.</p> <p>The <code>-XX:+IdleTuningCompactOnIdle</code> option can be used with the <code>-XX:+IdleTuningMinIdleWaitTime</code>, which controls the amount of time that the VM must be idle before an idle state is set. If a value for the <code>-XX:+IdleTuningMinIdleWaitTime</code> option is not explicitly specified, the VM sets a default value of 180 seconds.</p>"},{"location":"xxidletuningcompactonidle/#see-also","title":"See also","text":"<ul> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:[+|-]IdleTuningGcOnIdle</li> </ul>"},{"location":"xxidletuninggconidle/","title":"-XX:[+|-]IdleTuningGcOnIdle","text":""},{"location":"xxidletuninggconidle/#-xx-idletuninggconidle","title":"-XX:[+|-]IdleTuningGcOnIdle","text":"<p>(Linux\u00ae only)</p> <p>This option controls whether a garbage collection cycle takes place when the state of the Eclipse OpenJ9\u2122 VM is set to idle. Compaction of the heap is also attempted during the idle GC when certain triggers are met.</p> <p> Restrictions: This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use. This option is not effective if the object heap is configured to use large pages.</p>"},{"location":"xxidletuninggconidle/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IdleTuningGcOnIdle\n</code></pre> Setting Effect Default Default when running in a docker container <code>-XX:+IdleTuningGcOnIdle</code> Enable yes <code>-XX:-IdleTuningGcOnIdle</code> Disable yes <p>The default depends on whether or not the OpenJ9 VM is running in a docker container. As indicated in the table, when the VM is running in a container and the state is set to idle, this option causes the VM to release free memory pages in the object heap without resizing the Java\u2122 heap and attempts to compact the heap after the garbage collection cycle if certain heuristics are triggered. The pages are reclaimed by the operating system, which reduces the physical memory footprint of the VM.</p> <p>If your application is not running in a container and you want to enable idle-tuning, set the <code>-XX:+IdleTuningGcOnIdle</code> option on the command line when you start your application.</p> <p>When enabled, the <code>-XX:+IdleTuningGcOnIdle</code> option is used with the <code>-XX:IdleTuningMinIdleWaitTime</code> and <code>-XX:IdleTuningMinFreeHeapOnIdle</code> options. If values for these options are not explicitly specified, the VM sets the following defaults:</p> <ul> <li><code>-XX:IdleTuningMinIdleWaitTime</code>=180</li> <li><code>-XX:IdleTuningMinFreeHeapOnIdle</code>=0</li> </ul>"},{"location":"xxidletuninggconidle/#see-also","title":"See also","text":"<ul> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> <li>-XX:[+|-]IdleTuningCompactOnIdle (From OpenJ9 version 0.23.0 this option has no effect.)</li> </ul>"},{"location":"xxidletuningminfreeheaponidle/","title":"-XX:IdleTuningMinFreeHeapOnIdle","text":""},{"location":"xxidletuningminfreeheaponidle/#-xxidletuningminfreeheaponidle","title":"-XX:IdleTuningMinFreeHeapOnIdle","text":"<p>(Linux\u00ae only)</p> <p>This option controls the percentage of free memory pages in the object heap that can be released when the Eclipse OpenJ9\u2122 VM is in an idle state.</p> <p> Restrictions: This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use. This option is not effective if the object heap is configured to use large pages.</p>"},{"location":"xxidletuningminfreeheaponidle/#syntax","title":"Syntax","text":"<pre><code>    -XX:IdleTuningMinFreeHeapOnIdle=&lt;percentage&gt;\n</code></pre> Setting Value Default <code>&lt;percentage&gt;</code> [0 - 100] 0 <p>When used with <code>-XX:+IdleTuningGcOnIdle</code>, this option can be used to place an upper bound on the percentage of free memory pages in the object heap that can be released when the VM is in an idle state. If <code>-XX:IdleTuningMinFreeHeapOnIdle</code> is not specified, the VM uses a default value of 0.</p>"},{"location":"xxidletuningminfreeheaponidle/#example","title":"Example","text":"<p>If you set <code>-XX:IdleTuningMinFreeHeapOnIdle=10</code>, no more than 90% of the free memory pages in the object heap can be released by the VM when it is in an idle state.</p>"},{"location":"xxidletuningminfreeheaponidle/#see-also","title":"See also","text":"<ul> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:[+|-]IdleTuningGcOnIdle</li> <li>-XX:[+|-]IdleTuningCompactOnIdle (From OpenJ9 version 0.23.0 this option has no effect.)</li> </ul>"},{"location":"xxidletuningminidlewaittime/","title":"-XX:IdleTuningMinIdleWaitTime","text":""},{"location":"xxidletuningminidlewaittime/#-xxidletuningminidlewaittime","title":"-XX:IdleTuningMinIdleWaitTime","text":"<p>** (Linux\u00ae only) **</p> <p>When the Eclipse OpenJ9\u2122 VM is idle, this option controls the minimum length of time that the VM must be idle before the state of the VM is set to idle. When the state changes to idle, a garbage collection cycle runs, the object heap is compacted, and free memory pages are released back to the operating system, which reduces the footprint of the VM. Garbage collection and compaction are controlled by the <code>-XX:+IdleTuningGcOnIdle</code> and <code>-XX:+IdleTuningCompactOnIdle</code> options, which are enabled by default when the OpenJ9 VM is running inside a docker container. (Note that from OpenJ9 version 0.23.0 the <code>-XX:+IdleTuningCompactOnIdle</code> option has no effect.)</p> <p> Restrictions: This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use. This option is not effective if the object heap is configured to use large pages.</p>"},{"location":"xxidletuningminidlewaittime/#syntax","title":"Syntax","text":"<pre><code>    -XX:IdleTuningMinIdleWaitTime=&lt;secs&gt;\n</code></pre> Setting Value Default Default when running in a docker container <code>&lt;secs&gt;</code> [0 or greater] 0 180 <p>The value used for <code>&lt;secs&gt;</code> specifies the minimum length of time in seconds that the VM is idle before the state is set to idle. Idle tuning is enabled by default when the OpenJ9 VM is running in a docker container and the VM is detected as idle for 180 seconds. </p> <p>Setting the value to 0 disables this feature, which causes the following idle tuning options to have no effect:</p> <ul> <li><code>-XX:+IdleTuningCompactOnIdle</code></li> <li><code>-XX:+IdleTuningGcOnIdle</code></li> <li><code>-XX:IdleTuningMinFreeHeapOnIdle</code></li> </ul>"},{"location":"xxidletuningminidlewaittime/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]IdleTuningGcOnIdle</li> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> <li>-XX:[+|-]IdleTuningCompactOnIdle (From OpenJ9 version 0.23.0 this option has no effect.)</li> </ul>"},{"location":"xxignoreunrecognizedrestoreoptions/","title":"-XX:[+|-]IgnoreUnrecognizedRestoreOptions","text":""},{"location":"xxignoreunrecognizedrestoreoptions/#-xx-ignoreunrecognizedrestoreoptions","title":"-XX:[+|-]IgnoreUnrecognizedRestoreOptions","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>This option specifies whether the VM ignores any unrecognized options at the time of restore.</p> <p> Restrictions: This option takes effect only when <code>-XX:+EnableCRIUSupport</code> is enabled. This option can be used only on restore.</p>"},{"location":"xxignoreunrecognizedrestoreoptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IgnoreUnrecognizedRestoreOptions\n</code></pre> Setting Effect Default <code>-XX:+IgnoreUnrecognizedRestoreOptions</code> Enable <code>-XX:-IgnoreUnrecognizedRestoreOptions</code> Disable yes"},{"location":"xxignoreunrecognizedrestoreoptions/#explanation","title":"Explanation","text":"<p>When you restore a checkpoint image, you can specify additional command-line options by using the <code>CRIUSupport.registerRestoreOptionsFile</code> API. You can also use the <code>OPENJ9_RESTORE_JAVA_OPTIONS</code> environment variable (<code>CRIUSupport.registerRestoreEnvVariables</code> API) to add the VM options on restore. If you specify options that do not exist, or are unsupported, the VM, by default, fails to start and throws a <code>JVMRestoreException</code> error. The <code>-XX:+IgnoreUnrecognizedRestoreOptions</code> option disables the failure and allows the VM to continue even if some options are not used.</p>"},{"location":"xxignoreunrecognizedrestoreoptions/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxignoreunrecognizedvmoptions/","title":"-XX:[+|-]IgnoreUnrecognizedVMOptions","text":""},{"location":"xxignoreunrecognizedvmoptions/#-xx-ignoreunrecognizedvmoptions","title":"-XX:[+|-]IgnoreUnrecognizedVMOptions","text":"<p>This Oracle option affects the behavior of the HotSpot JVM when it finds an unrecognized top-level option at startup. This option is implemented in the Eclipse OpenJ9\u2122 VM for compatibility.</p>"},{"location":"xxignoreunrecognizedvmoptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IgnoreUnrecognizedVMOptions\n</code></pre> Setting Effect Default <code>-XX:+IgnoreUnrecognizedVMOptions</code> Enable <code>-XX:-IgnoreUnrecognizedVMOptions</code> Disable yes"},{"location":"xxignoreunrecognizedxxcolonoptions/","title":"-XX:[+|-]IgnoreUnrecognizedXXColonOptions","text":""},{"location":"xxignoreunrecognizedxxcolonoptions/#-xx-ignoreunrecognizedxxcolonoptions","title":"-XX:[+|-]IgnoreUnrecognizedXXColonOptions","text":"<p>By default, any <code>-XX:</code> options that you specify on the command line are ignored if they are not recognized, which prevents an application failing to start. However, if you want to determine whether any of your <code>-XX:</code> options are unrecognized, you can turn off the behavior with this option. You might want to do this, for example, if you are switching to Eclipse OpenJ9\u2122 from an alternative VM implementation where you are using <code>-XX:</code> options to tune the runtime environment.</p>"},{"location":"xxignoreunrecognizedxxcolonoptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IgnoreUnrecognizedXXColonOptions\n</code></pre> Setting Effect Default <code>-XX:+IgnoreUnrecognizedXXColonOptions</code> Enable yes <code>-XX:-IgnoreUnrecognizedXXColonOptions</code> Disable <p>When you specify <code>-XX:-IgnoreUnrecognizedXXColonOptions</code>, if you also specify a <code>-XX:</code> option that is not recognized, that option is reported and the VM does not start. For example:</p> <pre><code>JVMJ9VM007E Command-line option unrecognised: -XX:InvalidOption\nError: Could not create the Java Virtual Machine.\nError: A fatal exception has occurred. Program will exit.\n</code></pre>"},{"location":"xxinitialheapsize/","title":"-XX:MaxHeapSize","text":""},{"location":"xxinitialheapsize/#-xxinitialheapsize-xxmaxheapsize","title":"-XX:InitialHeapSize / -XX:MaxHeapSize","text":"<p>These HotSpot options for specifying heap size are recognized by Eclipse OpenJ9\u2122 for compatibility. See -Xms / -Xmx for details.</p>"},{"location":"xxinitialheapsize/#syntax","title":"Syntax","text":"Setting Effect <code>-XX:InitialHeapSize&lt;size&gt;</code> Set initial heap size <code>-XX:MaxHeapSize&lt;size&gt;</code> Set maximum heap size"},{"location":"xxinitialrampercentage/","title":"-XX:MaxRAMPercentage","text":""},{"location":"xxinitialrampercentage/#-xxinitialrampercentage-xxmaxrampercentage","title":"-XX:InitialRAMPercentage / -XX:MaxRAMPercentage","text":"<p>These Oracle HotSpot options can be used to specify the initial and maximum size of the Java heap as a percentage of the total memory available to the VM. The options are recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxinitialrampercentage/#syntax","title":"Syntax","text":"Setting Effect <code>-XX:InitialRAMPercentage=N</code> Set initial heap size as a percentage of total memory <code>-XX:MaxRAMPercentage=N</code> Set maximum heap size as a percentage of total memory Where N is a value between 0 and 100, which can be of type \"double\". For example, 12.3456. <p> Note: If you set a value for <code>-Xms</code>, the <code>-XX:InitialRAMPercentage</code> option is ignored. If you set a value for <code>-Xmx</code>, the <code>-XX:MaxRAMPercentage</code> option is ignored.</p> <p>If your application is running in a container and you have specified <code>-XX:+UseContainerSupport</code>, both the default heap size for containers, the <code>-XX:InitialRAMPercentage</code> option, and the <code>-XX:MaxRAMPercentage</code> option are based on the available container memory.</p>"},{"location":"xxinterleavememory/","title":"-XX:[+|-]InterleaveMemory","text":""},{"location":"xxinterleavememory/#-xx-interleavememory","title":"-XX:[+|-]InterleaveMemory","text":"<p>(AIX\u00ae, Linux\u00ae, and Windows\u2122 only, but not Linux on IBM Z\u00ae)</p> <p>Use the <code>-XX:+InterleaveMemory</code> option to enable the interleaving of allocated memory across NUMA nodes.</p>"},{"location":"xxinterleavememory/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]InterleaveMemory\n</code></pre> Setting Effect Default <code>-XX:+InterleaveMemory</code> Enable <code>-XX:-InterleaveMemory</code> Disable yes"},{"location":"xxjitinlinewatches/","title":"-XX:[+|-]JITInlineWatches","text":""},{"location":"xxjitinlinewatches/#-xx-jitinlinewatches","title":"-XX:[+|-]JITInlineWatches","text":"<p>This option controls JIT operations that relate to JVMTI watched fields.</p>"},{"location":"xxjitinlinewatches/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITInlineWatches\n</code></pre> Setting Effect Default <code>-XX:+JITInlineWatches</code> Enable yes <code>-XX:-JITInlineWatches</code> Disable <p>This option enables performance improvements relating to JVMTI watched fields.</p>"},{"location":"xxjitserveraddress/","title":"-XX:JITServerAddress","text":""},{"location":"xxjitserveraddress/#-xxjitserveraddress","title":"-XX:JITServerAddress","text":"<p>This option specifies the JITServer server name or IP address for a JITServer client to connect to.</p>"},{"location":"xxjitserveraddress/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerAddress=&lt;address&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerAddress</code> Set server's name or IP address <code>localhost</code>"},{"location":"xxjitserveraddress/#explanation","title":"Explanation","text":"<p>When you enable this option, the JITServer client sends compilation requests to a server with the provided name or address. If there is no server available at that address, the JIT compiler compiles locally.</p>"},{"location":"xxjitserveraddress/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserveraotcachedir/","title":"-XX:JITServerAOTCacheDir","text":""},{"location":"xxjitserveraotcachedir/#-xxjitserveraotcachedir","title":"-XX:JITServerAOTCacheDir","text":"<p>(Linux\u00ae only)</p> <p>This option specifies the directory to be used for saving and loading JITServer AOT cache files.</p>"},{"location":"xxjitserveraotcachedir/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerAOTCacheDir=&lt;directory&gt;\n</code></pre> <p>If the option is not specified, the cache files are saved in the current working directory of the JITServer server.</p>"},{"location":"xxjitserveraotcachedir/#explanation","title":"Explanation","text":"<p>A JITServer instance can have several AOT caches, each with its own name. To enable reusing of the AOT caches by other JITServer instances (such as the instances started later), you can use the <code>-XX:+JITServerAOTCachePersistence</code> option. With this option enabled, JITServer server periodically saves its AOT caches to files. Other JITServer instances can then load these caches the first time a client requests a particular cache.</p> <p>You can specify the directory for saving the AOT cache files with the <code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code> option. When the server receives the location of the requested AOT cache file through the <code>-XX:JITServerAOTCacheDir</code> option and a request for a specific cache name, if that cache does not exist in-memory, the server searches the specified cache directory for the file with the matching name and loads it, if available.</p> <p>This option is not applicable if the JITServer AOT cache persistence feature is not enabled with the <code>-XX:+JITServerAOTCachePersistence</code> option.</p>"},{"location":"xxjitserveraotcachedir/#see-also","title":"See also","text":"<ul> <li>JITServer AOT cache</li> <li><code>-XX:[+|-]JITServerUseAOTCache</code></li> <li><code>-XX:JITServerAOTCacheName</code></li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code></li> </ul>"},{"location":"xxjitserveraotcachename/","title":"-XX:JITServerAOTCacheName","text":""},{"location":"xxjitserveraotcachename/#-xxjitserveraotcachename","title":"-XX:JITServerAOTCacheName","text":"<p>This option, used at the JITServer client JVMs, specifies the name of the AOT cache to be used at the JITServer server.</p>"},{"location":"xxjitserveraotcachename/#syntax","title":"Syntax","text":"<pre><code>     -XX:JITServerAOTCacheName=&lt;cache_name&gt;\n</code></pre> where <code>&lt;cache_name&gt;</code> specifies the name of the server-side AOT cache to be used."},{"location":"xxjitserveraotcachename/#explanation","title":"Explanation","text":"<p>A single JITServer instance can use multiple AOT caches, which are distinguished by their name.  Clients that are running applications with significantly different execution profiles can, therefore, connect to the same JITServer instance.  Specify this option at the client JVM. If you do not specify this option, the client uses a cache named <code>default</code>.</p> <p> Note: You must specify <code>-XX:+JITServerUseAOTCache</code>, otherwise the <code>-XX:JITServerAOTCacheName</code> option is ignored.</p>"},{"location":"xxjitserveraotcachename/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> <li><code>-XX:[+|-]JITServerUseAOTCache</code></li> <li><code>-XX:JITServerAOTCacheDir</code></li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code></li> </ul>"},{"location":"xxjitserveraotcachepersistence/","title":"-XX:[+|-]JITServerAOTCachePersistence","text":""},{"location":"xxjitserveraotcachepersistence/#-xx-jitserveraotcachepersistence","title":"-XX:[+|-]JITServerAOTCachePersistence","text":"<p>(Linux\u00ae only)</p> <p>This option enables or disables the JITServer server's ability to allow other JITServer instances to reuse AOT caches.</p>"},{"location":"xxjitserveraotcachepersistence/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerAOTCachePersistence\n</code></pre> Setting Effect Default <code>-XX:+JITServerAOTCachePersistence</code> Enable <code>-XX:-JITServerAOTCachePersistence</code> Disable yes"},{"location":"xxjitserveraotcachepersistence/#explanation","title":"Explanation","text":"<p>With the <code>-XX:+JITServerAOTCachePersistence</code> option, the JITServer server periodically saves its AOT caches to files. Other JITServer instances can then load these caches from files the first time a client requests a particular named cache. This feature is useful to improve performance, especially in scenarios where JITServer instances are started up and shut down regularly.</p> <p>This feature depends on the <code>-XX:+JITServerUseAOTCache</code> command-line option, which is used to enable caching of AOT-compiled methods. You must specify this option both at the client JVM and at the server.</p> <p>Use the <code>-XX:JITServerAOTCacheName=&lt;cache_name&gt;</code> option at the client to request a particular AOT cache. If the requested cache does not exist at the server in-memory, but the AOT cache persistence feature is enabled (<code>-XX:+JITServerAOTCachePersistence</code>), the server checks whether a file for that cache exists. If the AOT cache file exists, it is loaded in the background. If the AOT cache file does not exist or the AOT cache persistence feature is disabled (<code>-XX:-JITServerAOTCachePersistence</code>), the server creates an empty AOT cache and gradually populates it with AOT method bodies it compiles.</p> <p>You can use the <code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code> option to specify the directory where the AOT cache must be saved to or loaded from.</p> <p>The name of an AOT cache file has the following structure:</p> <pre><code>    JITServerAOTCache.&lt;CACHE_NAME&gt;.J&lt;JAVA_VERSION&gt;\n</code></pre> <p>Where,</p> <ul> <li><code>&lt;CACHE_NAME&gt;</code> is the name of the AOT cache requested by the client, and</li> <li><code>&lt;JAVA_VERSION&gt;</code> is the version of Java used by JITServer instance (for example, 17 will be used for Java 17)</li> </ul>"},{"location":"xxjitserveraotcachepersistence/#see-also","title":"See also","text":"<ul> <li><code>-XX:JITServerAOTCacheName</code></li> <li><code>-XX:JITServerAOTCacheDir</code></li> <li><code>-XX:[+|-]JITServerUseAOTCache</code></li> <li>JITServer AOT cache</li> </ul>"},{"location":"xxjitserveraotmx/","title":"-XX:JITServerAOTmx","text":""},{"location":"xxjitserveraotmx/#-xxjitserveraotmx","title":"-XX:JITServerAOTmx","text":"<p>(Linux\u00ae only)</p> <p>This option specifies the maximum amount of memory allocated to the JITServer AOT cache for storing the compiled code and for the associated data structures that are used in the cache's implementation.</p>"},{"location":"xxjitserveraotmx/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerAOTmx=&lt;size&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerAOTmx=&lt;size&gt;</code> Limits the amount of memory used by the JITServer AOT cache 300 MB"},{"location":"xxjitserveraotmx/#explanation","title":"Explanation","text":"<p>When the JITServer receives an AOT compilation request, it checks its AOT cache for a compatible compiled method body. If one is not found, the server performs the AOT compilation, sends the response to the client JVM, then stores the compiled method in its local AOT cache, for future use. Multiple requests and storing of the compiled methods can use a lot of memory and degrade the system's overall performance.</p> <p>You can specify the maximum memory limit for the AOT cache by using the <code>-XX:JITServerAOTmx=&lt;size&gt;</code> option, so that when the JITServer reaches that limit, it will not be able to add new AOT methods to its AOT cache. This will limit the amount of memory used for caching the compiled code and prevent memory shortages at JITServer that could lead to poor performance or even native out-of-memory events.</p>"},{"location":"xxjitserveraotmx/#see-also","title":"See also","text":"<ul> <li>JITServer AOT cache</li> </ul>"},{"location":"xxjitserverlocalsynccompiles/","title":"-XX:[+|-]JITServerLocalSyncCompiles","text":""},{"location":"xxjitserverlocalsynccompiles/#-xx-jitserverlocalsynccompiles","title":"-XX:[+|-]JITServerLocalSyncCompiles","text":"<p>When you specify this JITServer option, synchronous JIT compilations are downgraded to <code>cold</code> optimization level and compiled locally, with a remote asynchronous recompilation scheduled at a later point.</p>"},{"location":"xxjitserverlocalsynccompiles/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerLocalSyncCompiles\n</code></pre> Setting Effect Default <code>-XX:+JITServerLocalSyncCompiles</code> Enable yes <code>-XX:-JITServerLocalSyncCompiles</code> Disable <p>The option <code>-XX:[+|-]JITServerLocalSyncCompiles</code> is enabled by default in most cases. The option remains disabled when you specify <code>-Xjit:count=0</code> and in a few advanced use cases such as running the JVM in debug mode (as described in the Improved JVM debug mode based on OSR post in the Eclipse OpenJ9\u2122 blog).</p>"},{"location":"xxjitserverlocalsynccompiles/#explanation","title":"Explanation","text":"<p>During a synchronous compilation, Java\u2122 application threads have to wait for the compilation to complete. Because remote compilations usually take longer, due to network latency, remote synchronous compilations can result in large pauses in the client application.</p> <p>If you enable this option, the client performs synchronous compilations locally at <code>cold</code> optimization level and later recompiles asynchronously at a higher level remotely. This behavior can be beneficial for real-time applications.</p>"},{"location":"xxjitserverlocalsynccompiles/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserverlogconnections/","title":"-XX:[+|-]JITServerLogConnections","text":""},{"location":"xxjitserverlogconnections/#-xx-jitserverlogconnections","title":"-XX:[+|-]JITServerLogConnections","text":"<p>This option enables the logging of connection/disconnection events between the JITServer server and the JITServer client. You can use the option on both the server and the client sides.</p>"},{"location":"xxjitserverlogconnections/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerLogConnections\n</code></pre> Setting Effect Default <code>-XX:+JITServerLogConnections</code> Enable <code>-XX:-JITServerLogConnections</code> Disable yes"},{"location":"xxjitserverlogconnections/#explanation","title":"Explanation","text":"<p>This option is useful when you need to know when the server and the client successfully establish or terminate connections but verbose logs provide too much information.</p> <p>You can also enable the same logging by specifying the  <code>-Xjit:verbose={JITServerConns}</code> option.</p> <p>If you do not specify a <code>vlog</code> log file (<code>-Xjit:vlog=&lt;vlog_filename&gt;</code>), output is written to <code>stderr</code>, otherwise it is written to the <code>vlog</code> file.</p>"},{"location":"xxjitserverlogconnections/#example","title":"Example","text":"<p>This is what the typical output looks like:</p> <p>On the server side:</p> <pre><code>#JITServer: t=  2318 A new client (clientUID=11937826481210274991) connected. Server allocated a new client session.\n...\n...\n#JITServer: t= 48518 Client (clientUID=4213447851416537492) disconnected. Client session deleted\n</code></pre> <p>On the client side:</p> <pre><code>#JITServer: t=     0 Connected to a server (serverUID=10444660844386807777)\n...\n...\n#JITServer: t=   698 Lost connection to the server (serverUID=10444660844386807777)\n</code></pre>"},{"location":"xxjitserverlogconnections/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> <li>-Xjit / -Xnojit</li> </ul>"},{"location":"xxjitservermetrics/","title":"-XX:JITServerMetrics","text":""},{"location":"xxjitservermetrics/#-xx-jitservermetrics","title":"-XX:[+|-]JITServerMetrics","text":"<p>This option enables the provision of JITServer performance metrics to a monitoring agent that follows the OpenMetrics standard.</p> <p>When you enable this option, the following JITServer metrics are provided:</p> <ul> <li>The CPU utilization of the JITServer</li> <li>The physical memory that is available to the JITServer</li> <li>The number of clients that are connected to the JITServer</li> <li>The number of active compilation threads in the JITServer</li> </ul> <p> Note: You can use the <code>-XX:JITServerMetricsSSLKey</code> and <code>-XX:JITServerMetricsSSLCert</code> options for encrypting the data with SSL or TLS.</p>"},{"location":"xxjitservermetrics/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerMetrics\n</code></pre> Setting Effect Default <code>-XX:+JITServerMetrics</code> Enable <code>-XX:-JITServerMetrics</code> Disable yes"},{"location":"xxjitservermetrics/#explanation","title":"Explanation","text":"<p>When you enable this option, the JITServer process opens a TCP port, which can be used by monitoring agents (like Prometheus) to collect the custom metrics exported by the JITServer. Monitoring agents must issue HTTP <code>GET</code> requests to a URL of the form: <code>http://&lt;jitserveraddress&gt;:&lt;port&gt;/metrics</code>. The path for the HTTP request must be <code>/metrics</code>.</p> <p>The default value of <code>&lt;port&gt;</code> is 38500. You can change this value by using the <code>-XX:JITServerMetricsPort</code> command line option.</p> <p>The format for the metrics returned by the JITServer follows the OpenMetrics protocol.</p>"},{"location":"xxjitservermetrics/#example","title":"Example","text":"<p>The following example shows an HTTP request from a Prometheus monitoring agent and the response from the JITServer:</p> <p>HTTP request:</p> <p><code>GET /metrics HTTP/1.1    Host: 127.0.0.1:9403    User-Agent: Prometheus/2.31.1    Accept: application/openmetrics-text; version=0.0.1,text/plain;version=0.0.4;q=0.5,*/*;q=0.1    Accept-Encoding: gzip    X-Prometheus-Scrape-Timeout-Seconds: 3</code></p> <p>JITServer response:</p> <p><code># HELP jitserver_cpu_utilization Cpu utilization of the JITServer    # TYPE jitserver_cpu_utilization gauge    jitserver_cpu_utilization 12.000000    # HELP jitserver_available_memory Available memory for JITServer    # TYPE jitserver_available_memory gauge    jitserver_available_memory 32036204544.000000    # HELP jitserver_connected_clients Number of connected clients    # TYPE jitserver_connected_clients gauge    jitserver_connected_clients 1.000000    # HELP jitserver_active_threads Number of active compilation threads    # TYPE jitserver_active_threads gauge    jitserver_active_threads 1.000000</code></p>"},{"location":"xxjitservermetrics/#see-also","title":"See also","text":"<ul> <li>-XX:JITServerMetricsPort</li> <li>JITServer technology</li> <li><code>-XX:JITServerMetricsSSLKey</code></li> </ul>"},{"location":"xxjitservermetricsport/","title":"-XX:JITServerMetricsPort","text":""},{"location":"xxjitservermetricsport/#-xxjitservermetricsport","title":"-XX:JITServerMetricsPort","text":"<p>This option specifies the port number on which the JITServer metrics are provided to a monitoring agent.</p> <p>Use this option with the <code>-XX:+JITServerMetrics</code> option, which enables the provision of the JITServer metrics.</p>"},{"location":"xxjitservermetricsport/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerMetricsPort=&lt;port&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerMetricsPort</code> Set JITServer port for metrics 38500"},{"location":"xxjitservermetricsport/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]JITServerMetrics</li> <li>JITServer technology</li> </ul>"},{"location":"xxjitservermetricssslkey/","title":"-XX:JITServerMetricsSSLKey","text":""},{"location":"xxjitservermetricssslkey/#-xxjitservermetricssslkey-xxjitservermetricssslcert","title":"-XX:JITServerMetricsSSLKey / -XX:JITServerMetricsSSLCert","text":"<p>These options specify the names of the files that contain the private TLS or SSL key and certificate that are used for authentication and encryption of the custom metrics.</p>"},{"location":"xxjitservermetricssslkey/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerMetricsSSLKey=&lt;key_file&gt;\n    -XX:JITServerMetricsSSLCert=&lt;cert_file&gt;\n</code></pre> <p>Where <code>&lt;key_file&gt;</code> specifies the name of the file that contains the private TLS or SSL key and <code>&lt;cert_file&gt;</code> specifies the name of the file that contains the private TLS or SSL certificate. The files must all be in <code>.pem</code> file format.</p> Setting Effect Default <code>-XX:JITServerMetricsSSLKey</code> Set metrics SSL key None <code>-XX:JITServerMetricsSSLCert</code> Set metrics SSL certificate None"},{"location":"xxjitservermetricssslkey/#explanation","title":"Explanation","text":"<p>Custom metrics are exported by the JITServer server and collected by a monitoring agent, such as Prometheus. The exported data is sent in clear text by default. To secure this data with TLS or SSL authentication and encryption, specify the private key (<code>&lt;key&gt;.pem</code>) and the certificate (<code>&lt;cert&gt;.pem</code>) at the server:</p> <pre><code>    -XX:JITServerMetricsSSLKey=&lt;key&gt;.pem -XX:JITServerMetricsSSLCert=&lt;cert&gt;.pem\n</code></pre> <p>You must specify both the options for TLS or SSL authentication and encryption.</p> <p> Note: To enable the export of custom metrics, you must specify the <code>-XX:[+|-]JITServerMetrics</code> option.</p>"},{"location":"xxjitservermetricssslkey/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]JITServerMetrics</li> <li>JITServer technology</li> </ul>"},{"location":"xxjitserverport/","title":"-XX:JITServerPort","text":""},{"location":"xxjitserverport/#-xxjitserverport","title":"-XX:JITServerPort","text":"<p>This option specifies the port on which the JITServer server listens for compilation requests.</p> <p>On the JITServer server, this option sets the port that is open for connections.</p> <p>On the JITServer client, this option specifies to which server port the client should send compilation requests.</p>"},{"location":"xxjitserverport/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerPort=&lt;port&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerPort</code> Set JITServer port 38400"},{"location":"xxjitserverport/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitservershareromclasses/","title":"-XX:JITServerShareROMClasses","text":""},{"location":"xxjitservershareromclasses/#-xx-jitservershareromclasses","title":"-XX:[+|-]JITServerShareROMClasses","text":"<p>This option enables the JITServer server to share cached ROM classes between JITServer clients.</p>"},{"location":"xxjitservershareromclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerShareROMClasses\n</code></pre> Setting Effect Default <code>-XX:+JITServerShareROMClasses</code> Enable <code>-XX:-JITServerShareROMClasses</code> Disable yes <p> Note: The <code>-XX:+JITServerShareROMClasses</code> option is enabled by default at the server on specifying the <code>-XX:+JITServerUseAOTCache</code> option.</p>"},{"location":"xxjitservershareromclasses/#explanation","title":"Explanation","text":"<p>Enable this option when multiple clients that are running identical or similar applications connect to a single server.</p> <p>This option enables a caching optimization that allows the server to use ROM classes that are cached for one client while compiling for a different client. This behavior reduces the memory usage at the server because only a single copy of a particular Java\u2122 class is cached.</p>"},{"location":"xxjitservershareromclasses/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserversslcert/","title":"-XX:JITServerSSLRootCerts","text":""},{"location":"xxjitserversslcert/#-xxjitserversslcert-xxjitserversslkey-xxjitserversslrootcerts","title":"-XX:JITServerSSLCert / -XX:JITServerSSLKey / -XX:JITServerSSLRootCerts","text":"<p>Options for encrypting network communication between JITServer servers and JITServer client VMs.</p>"},{"location":"xxjitserversslcert/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerCert=&lt;cert_file&gt;\n    -XX:JITServerKey=&lt;key_file&gt;\n    -XX:JITServerSSLRootCerts=&lt;root_certs_file&gt;\n</code></pre> <p>The files must all be in <code>.pem</code> file format.</p> Setting Effect Default <code>-XX:JITServerSSLCert</code> Set server's SSL certificate None <code>-XX:JITServerSSLKey</code> Set server's SSL key None <code>-XX:JITServerSSLRootCerts</code> Set client's SSL root certificate None"},{"location":"xxjitserversslcert/#explanation","title":"Explanation","text":"<p>You can encrypt network communication by using OpenSSL 1.0.x, 1.1.x, or 3.x. To enable encryption, specify the private key (<code>&lt;key&gt;.pem</code>) and the certificate (<code>&lt;cert&gt;.pem</code>) at the server:</p> <pre><code>-XX:JITServerSSLKey=&lt;key&gt;.pem -XX:JITServerSSLCert=&lt;cert&gt;.pem\n</code></pre> <p>and use the certificate at the client:</p> <pre><code>-XX:JITServerSSLRootCerts=&lt;cert&gt;.pem\n</code></pre> <p>You must specify all three options for the client to be able to connect to the server. If the client cannot connect, it is forced to perform all compilations locally instead.</p> <p>For more details and further discussion about security considerations, see the blog post Free your JVM from the JIT with JITServer Technology.</p>"},{"location":"xxjitserversslcert/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitservertimeout/","title":"-XX:JITServerTimeout","text":""},{"location":"xxjitservertimeout/#-xxjitservertimeout","title":"-XX:JITServerTimeout","text":"<p>This option specifies the socket timeout for JITServer communication.</p> <p>You can specify this option on both the server and the client sides.</p>"},{"location":"xxjitservertimeout/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerTimeout=&lt;timeout_ms&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerTimeout</code> Set the timeout value in milliseconds for socket operations 30000 ms for the JITServer process and 10000 ms when Eclipse OpenJ9\u2122 is launched as a client VM"},{"location":"xxjitservertimeout/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserveruseaotcache/","title":"-XX:[+|-]JITServerUseAOTCache","text":""},{"location":"xxjitserveruseaotcache/#-xx-jitserveruseaotcache","title":"-XX:[+|-]JITServerUseAOTCache","text":"<p>This option enables the caching of AOT-compiled methods in the JITServer server.</p>"},{"location":"xxjitserveruseaotcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerUseAOTCache\n</code></pre> Setting Effect Default <code>-XX:+JITServerUseAOTCache</code> Enable <code>-XX:-JITServerUseAOTCache</code> Disable yes"},{"location":"xxjitserveruseaotcache/#explanation","title":"Explanation","text":"<p>When you enable this option, the JITServer server caches the AOT-compiled methods. When a JITServer client requests an AOT compilation and the requested method exists in the cache, the server does not have to recompile the method. This feature, therefore, improves the CPU utilization of the JITServer technology and of the cluster.</p> <p> Note: This option has the following requirements:</p> <ul> <li>You must specify this option both at the client JVM and at the server.</li> <li>The client JVM must have the shared class cache feature enabled and be allowed to generate AOT compilation requests.</li> </ul> <p>The <code>-XX:+JITServerShareROMClasses</code> option is enabled by default at the server on specifying the<code>-XX:+JITServerUseAOTCache</code> option.</p>"},{"location":"xxjitserveruseaotcache/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> <li><code>-XX:JITServerAOTCacheName</code></li> <li><code>-XX:JITServerAOTCacheDir</code></li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code></li> </ul>"},{"location":"xxlazysymbolresolution/","title":"-XX:[+|-]LazySymbolResolution","text":""},{"location":"xxlazysymbolresolution/#-xx-lazysymbolresolution","title":"-XX:[+|-]LazySymbolResolution","text":"<p>(Linux\u00ae and macOS\u00ae only)</p> <p>This option affects the timing of symbol resolution for functions in user native libraries.</p>"},{"location":"xxlazysymbolresolution/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]LazySymbolResolution\n</code></pre> Setting Effect Default <code>-XX:+LazySymbolResolution</code> Enable yes <code>-XX:-LazySymbolResolution</code> Disable"},{"location":"xxlazysymbolresolution/#explanation","title":"Explanation","text":"<p>Enabling this option forces the VM to delay symbol resolution for each function in a user native library, until the function is called. The <code>-XX:-LazySymbolResolution</code> option forces the VM to immediately resolve symbols for all functions in a user native library when the library is loaded.</p> <p>These options apply only to functions; variable symbols are always resolved immediately when loaded. If you attempt to use these options on an operating system other than Linux or macOS, the options are accepted, but ignored.</p>"},{"location":"xxlegacyxlogoption/","title":"-XX:[+|-]LegacyXLogOption","text":""},{"location":"xxlegacyxlogoption/#-xx-legacyxlogoption","title":"-XX:[+|-]LegacyXlogOption","text":"<p>Controls processing of the <code>-Xlog</code> option.</p>"},{"location":"xxlegacyxlogoption/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+LegacyXlogOption</code> Enable legacy <code>-Xlog</code> behavior <code>-XX:-LegacyXlogOption</code> Process <code>-Xlog</code> requests for GC logging yes"},{"location":"xxlegacyxlogoption/#explanation","title":"Explanation","text":"<p>From Eclipse OpenJ9\u2122 0.24.0, the <code>-Xlog</code> option is replaced by the <code>-Xsyslog</code> option. The <code>-XX:[+|-]LegacyXlogOption</code> controls how the <code>-Xlog</code> option is processed.</p> <ul> <li>When <code>-XX:-LegacyXlogOption</code> is set, the <code>-Xlog</code> option is recognized only when a form of this option is run that requests garbage collection (GC) logging (for example, <code>-Xlog:gc[:stderr|:file=&lt;filename&gt;]</code>). For more information, see <code>-Xlog</code>.</li> <li>When <code>-XX:+LegacyXlogOption</code> is set, the legacy <code>-Xlog</code> behavior is enabled. When enabled, the option is equivalent to the <code>-Xsyslog</code> option. That is, the <code>-Xlog</code> option can be used with the parameters documented in <code>-Xsyslog</code>.</li> </ul>"},{"location":"xxmaxdirectmemorysize/","title":"-XX:MaxDirectMemorySize","text":""},{"location":"xxmaxdirectmemorysize/#-xxmaxdirectmemorysize","title":"-XX:MaxDirectMemorySize","text":"<p>This Oracle HotSpot option sets a limit on the amount of memory that can be reserved for all Direct Byte Buffers.</p>"},{"location":"xxmaxdirectmemorysize/#syntax","title":"Syntax","text":"<pre><code>-XX:MaxDirectMemorySize=&lt;size&gt;\n</code></pre> Setting Value Default <code>&lt;size&gt;</code> [1[k|K|m|M|g|G] or greater] Depends on maximum heap size <p>The value you choose is the limit on memory that can be reserved for all Direct Byte Buffers. If a value is set for this option, the sum of all Direct Byte Buffer sizes cannot exceed the limit. After the limit is reached, a new Direct Byte Buffer can be allocated only when enough old buffers are freed to provide enough space to allocate the new buffer.</p> <p> By default, the amount of native memory used for Direct Byte Buffers is limited to 87.5% of the maximum heap size.</p> <p> By default, the amount of native memory used for Direct Byte Buffers is limited to the maximum heap size.</p>"},{"location":"xxmergecompileroptions/","title":"-XX:[+|-]MergeCompilerOptions","text":""},{"location":"xxmergecompileroptions/#-xx-mergecompileroptions","title":"-XX:[+|-]MergeCompilerOptions","text":"<p>This option enables or disables the merging of multiple <code>-Xjit</code> or <code>-Xaot</code> options into a single <code>-Xjit</code> or <code>-Xaot</code> option.</p>"},{"location":"xxmergecompileroptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]MergeCompilerOptions\n</code></pre> Setting Effect Default <code>-XX:+MergeCompilerOptions</code> Enable <code>-XX:-MergeCompilerOptions</code> Disable yes"},{"location":"xxmergecompileroptions/#explanation","title":"Explanation","text":"<p>By default, if you specify <code>-Xjit</code> option (or <code>-Xaot</code> option) multiple times, only the last option takes effect. Therefore, on adding an <code>-Xjit</code> option, the resultant behavior might not be as expected, if any instance of this option already exists. It is time-consuming to find the existing instances and try combining them manually so that the system behaves as required.</p> <p>You can use the <code>-XX:+MergeCompilerOptions</code> option to merge all the existing instances of the <code>-Xjit</code> options logically. To retain the default behavior, whereby only the last option takes effect, you can use the <code>-XX:-MergeCompilerOptions</code> option.</p> <p>If both <code>-Xjit</code> and <code>-Xaot</code> options exist and you use the <code>-XX:+MergeCompilerOptions</code> option, then multiple <code>-Xjit</code> options are merged into a single <code>-Xjit</code> option and multiple <code>-Xaot</code> options are merged into a single <code>-Xaot</code> option.</p>"},{"location":"xxmergecompileroptions/#examples","title":"Examples","text":""},{"location":"xxmergecompileroptions/#one-xjit-option","title":"One <code>-Xjit</code> option","text":"<pre><code>java -Xshareclasses:none  -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:+MergeCompilerOptions -Xshareclasses:none  -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:-MergeCompilerOptions -Xshareclasses:none  -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p>"},{"location":"xxmergecompileroptions/#multiple-xjit-options","title":"Multiple <code>-Xjit</code> options","text":"<pre><code>java -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:+MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> options that are applied - <code>verbose={compilePerformance}</code>,<code>vlog=vlog</code>,<code>version</code></p> <pre><code>java -XX:-MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p>"},{"location":"xxmergecompileroptions/#both-xxmergecompileroptions-and-xx-mergecompileroptions","title":"Both <code>-XX:+MergeCompilerOptions</code> and <code>-XX:-MergeCompilerOptions</code>","text":"<p>If there are multiple <code>-XX:[+|-]MergeCompilerOptions</code> options with multiple <code>-Xjit</code> options, the last <code>-XX:[+|-]MergeCompilerOptions</code> setting takes effect before the <code>-Xjit</code> options are processed.</p> <pre><code>java -XX:+MergeCompilerOptions -XX:-MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:-MergeCompilerOptions -XX:+MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> options that are applied - <code>{compilePerformance}</code>,<code>vlog=vlog</code>,<code>version</code></p>"},{"location":"xxmergecompileroptions/#see-also","title":"See also","text":"<ul> <li>-Xjit</li> <li>-Xaot</li> </ul>"},{"location":"xxnosuballoc32bitmem/","title":"-XXnosuballoc32bitmem","text":""},{"location":"xxnosuballoc32bitmem/#-xxnosuballoc32bitmem","title":"-XXnosuballoc32bitmem","text":"<p>(z/OS\u00ae only)</p> <p>When compressed references are used with a 64-bit Eclipse OpenJ9\u2122 VM on z/OS\u00ae, this option forces the VM to use 31-bit memory allocation functions provided by z/OS.</p>"},{"location":"xxnosuballoc32bitmem/#syntax","title":"Syntax","text":"<pre><code>    -XXnosuballoc32bitmem\n</code></pre> Setting Effect Default <code>-XXnosuballoc32bitmem</code> Enable No setting Disable yes"},{"location":"xxnosuballoc32bitmem/#explanation","title":"Explanation","text":"<p>This option is provided as a workaround for customers who need to use fewer pages of 31-bit virtual storage per VM invocation. Using this option might result in a small increase in the number of frames of central storage used by the VM. However, the option frees 31-bit pages for use by native code or other applications in the same address space.</p> <p>If this option is not specified, the VM uses an allocation strategy for 31-bit memory that reserves a region of 31-bit virtual memory.</p>"},{"location":"xxonoutofmemoryerror/","title":"-XX:OnOutOfMemoryError","text":""},{"location":"xxonoutofmemoryerror/#-xxonoutofmemoryerror","title":"-XX:OnOutOfMemoryError","text":"<p>You can use this Oracle HotSpot option to run commands when a <code>java.lang.OutOfMemoryError</code> is thrown. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxonoutofmemoryerror/#syntax","title":"Syntax","text":"<pre><code>    -XX:OnOutOfMemoryError=\"&lt;command_string&gt;\"\n</code></pre> <p>where <code>&lt;command_string&gt;</code> is a command or list of commands to run when a <code>java.lang.OutOfMemoryError</code> occurs.</p> <p>For example, the following command specifies that the <code>java -version</code> command is run if the <code>Test</code> application throws a <code>java.lang.OutOfMemoryError</code> exception:</p> <p><code>java -XX:OnOutOfMemoryError=\"java -version\" Test</code></p> <p>If you want to run multiple commands, use semicolons to separate them  within <code>&lt;command_string&gt;</code>. For example:</p> <p><code>-XX:OnOutOfMemoryError=\"&lt;java_path&gt; &lt;java_program&gt;; cat file.txt\"</code></p> <p>The <code>-XX:OnOutOfMemoryError</code> option is equivalent to the following <code>-Xdump</code> option:</p> <p><code>-Xdump:tool:events=systhrow,filter=java/lang/OutOfMemoryError,exec=&lt;command_string&gt;</code></p> <p>For more information, see <code>-Xdump</code>.  </p>"},{"location":"xxopenj9commandlineenv/","title":"-XX:[+|-]OpenJ9CommandLineEnv","text":""},{"location":"xxopenj9commandlineenv/#-xx-openj9commandlineenv","title":"-XX:[+|-]OpenJ9CommandLineEnv","text":"<p>This option controls whether the VM captures the command line in the environment variable <code>OPENJ9_JAVA_COMMAND_LINE</code>. If enabled, the variable is set by the VM after it starts. Using this variable, you can find the command-line parameters set when the VM started. It applies not just to launchers (e.g. <code>java</code>) that are included in a JDK, but to any application that uses <code>JNI_CreateJavaVM()</code>.</p>"},{"location":"xxopenj9commandlineenv/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]OpenJ9CommandLineEnv\n</code></pre> Setting Effect Default on z/OS Default on other platforms <code>-XX:+OpenJ9CommandLineEnv</code> Enable yes <code>-XX:-OpenJ9CommandLineEnv</code> Disable yes <p>This option is currently disabled by default on z/OS\u00ae because it might cause the VM to crash.</p>"},{"location":"xxopenj9commandlineenv/#see-also","title":"See also","text":"<ul> <li>Environment variables</li> </ul>"},{"location":"xxoriginaljdk8heapsizecompatibilitymode/","title":"-XX:[+|-]OriginalJDK8HeapSizeCompatibilityMode","text":""},{"location":"xxoriginaljdk8heapsizecompatibilitymode/#-xx-originaljdk8heapsizecompatibilitymode","title":"-XX:[+|-]OriginalJDK8HeapSizeCompatibilityMode","text":"<p> The default value for the maximum heap size (<code>-Xmx</code>) is 25% of the available memory with a maximum of 25 GB. However, where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB. In Eclipse OpenJ9\u2122 0.18.0 and earlier releases the default is half the available memory with a minimum of 16 MB and a maximum of 512 MB. Enable this option to revert to the earlier default value.</p> <p> Restriction: This option is supported only on Java\u2122 8. It is ignored on Java 11 and later versions.</p>"},{"location":"xxoriginaljdk8heapsizecompatibilitymode/#syntax","title":"Syntax","text":"<pre><code>-XX:[+|-]OriginalJDK8HeapSizeCompatibilityMode\n</code></pre> Setting Effect Default -XX:+OriginalJDK8HeapSizeCompatibilityMode Enable -XX:-OriginalJDK8HeapSizeCompatibilityMode Disable yes"},{"location":"xxpagealigndirectmemory/","title":"-XX:[+|-]PageAlignDirectMemory","text":""},{"location":"xxpagealigndirectmemory/#-xx-pagealigndirectmemory","title":"-XX:[+|-]PageAlignDirectMemory","text":"<p>This Oracle HotSpot option affects the alignment of direct byte buffer allocation and is implemented by the Eclipse OpenJ9\u2122 VM for compatibility.</p>"},{"location":"xxpagealigndirectmemory/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PageAlignDirectMemory\n</code></pre> Setting Effect Default <code>-XX:+PageAlignDirectMemory</code> Enable <code>-XX:-PageAlignDirectMemory</code> Disable yes <p>As discussed in the Oracle documentation, before Java\u2122 SE 7, direct buffers that were allocated using <code>java.nio.ByteBuffer.allocateDirect(int)</code> were aligned on a page boundary. This behavior changed in Java SE 7 and the <code>-XX:+PageAlignDirectMemory</code> option is provided to revert to the previous behavior.</p> <p>For more information about the changes, see RFE 4837564, which was introduced in the Java SE 7 release notes.</p>"},{"location":"xxparallelcmsthreads/","title":"-XX:ParallelCMSThreads","text":""},{"location":"xxparallelcmsthreads/#-xxparallelcmsthreads","title":"-XX:ParallelCMSThreads","text":"<p>This Oracle HotSpot option affects the number of threads used by the concurrent garbage collector. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxparallelcmsthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ParallelCMSThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of low-priority background threads that are attached to assist the mutator threads in concurrent mark.</p> <p>Within OpenJ9 this option is directly mapped to <code>-Xconcurrentbackground</code>.</p>"},{"location":"xxparallelgcmaxthreads/","title":"-XX:ParallelGCMaxThreads","text":""},{"location":"xxparallelgcmaxthreads/#-xxparallelgcmaxthreads","title":"-XX:ParallelGCMaxThreads","text":"<p>This option specifies the maximum number of threads that can be used during parallel operations of the garbage collector. Unlike <code>-XX:ParallelGCThreads</code>, this option does not enforce a thread count, but can be used to allow the garbage collector to adjust the number of parallel GC threads, if used with the Adaptive GC Threading option.</p>"},{"location":"xxparallelgcmaxthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ParallelGCMaxThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the maximum number of threads that can be used for parallel operations. </p> <p>This option is directly mapped to <code>-Xgcmaxthreads</code>.</p>"},{"location":"xxparallelgcthreads/","title":"-XX:ParallelGCThreads","text":""},{"location":"xxparallelgcthreads/#-xxparallelgcthreads","title":"-XX:ParallelGCThreads","text":"<p>This Oracle HotSpot option specifies the number of threads that are used during parallel operations of the default garbage collector. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p> <p> Notes:</p> <p>This option enforces the thread count and cannot be used with the <code>-XX:+AdaptiveGCThreading</code> option, which enables the garbage collector to adjust the number of parallel threads based on heuristics. If you want to use <code>-XX:+AdaptiveGCThreading</code>, use <code>-XX:ParallelGCMaxThreads</code> instead of <code>-XX:ParallelGCThreads</code>.</p>"},{"location":"xxparallelgcthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ParallelGCThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of threads that are used for parallel operations. </p> <p>Within OpenJ9 this option is directly mapped to <code>-Xgcthreads</code>.</p>"},{"location":"xxperftool/","title":"-XX:[+|-]PerfTool","text":""},{"location":"xxperftool/#-xx-perftool","title":"-XX:[+|-]PerfTool","text":"<p>This option enables or disables JIT support for the <code>perf</code> tool without affecting the existing <code>Xjit</code> options.</p> <p> Restriction: Since this option creates a file that is used by the Linux\u00ae system profiler, <code>perf</code>, it applies only to Linux.</p>"},{"location":"xxperftool/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PerfTool\n</code></pre> Setting Effect Default <code>-XX:+PerfTool</code> Enable <code>-XX:-PerfTool</code> Disable yes"},{"location":"xxperftool/#explanation","title":"Explanation","text":"<p>The <code>-XX:+PerfTool</code> option is a stand-alone alternative for the existing <code>-Xjit:perfTool</code> option. If multiple <code>-Xjit</code> options exist, only the last option takes effect. Therefore, if the <code>-Xjit:perfTool</code> option is added later, it overrides the existing <code>-Xjit</code> options. To overcome this issue, the <code>XX:+PerfTool</code> option enables JIT support for the <code>perf</code> tool without having any impact on the existing <code>Xjit</code> options. This enabling option creates a <code>/tmp/perf-&lt;pid&gt;.map</code> file that is used by the <code>perf</code> tool to map the samples in the JIT-compiled code to the corresponding Java method names.</p> <p>To disable the JIT support for the <code>perf</code> tool, set the <code>-XX:-PerfTool</code> option on the command line.</p>"},{"location":"xxperftool/#see-also","title":"See also","text":"<ul> <li><code>xjit</code></li> </ul>"},{"location":"xxportablesharedcache/","title":"-XX:[+|-]PortableSharedCache","text":""},{"location":"xxportablesharedcache/#-xx-portablesharedcache","title":"-XX:[+|-]PortableSharedCache","text":"<p>Use this command line option to choose whether AOT-compiled code should be portable.</p> <p>This option, when enabled, increases the portability of AOT-compiled code, in the following ways:</p> <ul> <li> <p>The code is generated based on a particular set of processor features that ensures the AOT-compiled code to be portable across processors of different microarchitectures. AOT-compiled code generated with this option is guaranteed to be portable across Intel\u00ae Sandy Bridge or newer microarchitectures on x86 platforms, IBM\u00ae z10 or newer microarchitectures on s390 platforms and IBM POWER8\u00ae or newer microarchitectures on POWER platforms.</p> </li> <li> <p>The code is generated to be portable across Eclipse OpenJ9\u2122 VMs that use compressed references and have a heap size of 1 MB to 28 GB (previously, AOT-compiled code could not be shared between VMs that use compressed references and that have different heap sizes). This feature might introduce a small (1-2%) steady-state throughput penalty when compressed references are used and the heap size is between 1 MB and 3 GB.</p> </li> </ul> <p>This feature is particularly relevant for packaging a shared classes cache into a container image (for example, applications deployed on the cloud in the form of Docker containers) due to the following reasons: - The processor on which the container image is built is likely to be different from the processor on which the container is deployed.  - In a multi-layered container image where the shared classes cache is multi-layered as well, the AOT-compiled code in shared classes cache will likely come from multiple OpenJ9 VMs with different heap size requirements.</p>"},{"location":"xxportablesharedcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PortableSharedCache\n</code></pre> Setting Effect Default <code>-XX:+PortableSharedCache</code> Enable See notes that follow <code>-XX:-PortableSharedCache</code> Disable"},{"location":"xxportablesharedcache/#default-settings","title":"Default settings","text":"<p>This option is enabled by default in containers. To disable the option in a container, specify <code>-XX:-PortableSharedCache</code>.</p> <p>The option is disabled by default outside containers. To enable the option outside a container, specify <code>-XX:+PortableSharedCache</code> for the initial JVM instance (when the creation of the shared class cache happens) as well as for every subsequent instance that makes use of the same shared class cache.</p>"},{"location":"xxpositiveidentityhash/","title":"-XX:[+|-]PositiveIdentityHash","text":""},{"location":"xxpositiveidentityhash/#-xx-positiveidentityhash","title":"-XX:[+|-]PositiveIdentityHash","text":"<p>Eclipse OpenJ9\u2122 allows both positive and negative identity hashcodes (<code>System.identityHashCode</code> / <code>Object.hashCode</code>). This is problematic for programs that incorrectly assume hashcodes can only be positive.</p> <p>When enabled, this option limits identity hash codes to non-negative values.</p> <p>Because limiting identity hash codes to non-negative values can have an impact on the performance of hash-intensive operations, this option is not enabled by default.</p>"},{"location":"xxpositiveidentityhash/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PositiveIdentityHash\n</code></pre> Setting Effect Default <code>-XX:+PositiveIdentityHash</code> Enable <code>-XX:-PositiveIdentityHash</code> Disable yes"},{"location":"xxprintcodecache/","title":"-XX:[+|-]PrintCodeCache","text":""},{"location":"xxprintcodecache/#-xx-printcodecache","title":"-XX:[+|-]PrintCodeCache","text":"<p>This Oracle HotSpot option prints the code cache memory usage when the application exits. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxprintcodecache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PrintCodeCache\n</code></pre> Setting Effect Default <code>-XX:+PrintCodeCache</code> Enable <code>-XX:-PrintCodeCache</code> Disable yes <p>As discussed in the Oracle documentation, the code cache usage can be shown when the application exits, by specifying <code>\u2013XX:+PrintCodeCache</code> on the Java launcher command line. The output looks similar to the following: </p> <pre><code>CodeCache: size=262144Kb used=454Kb max_used=457Kb free=261690Kb\n</code></pre> <ul> <li><code>size</code>: The maximum size of the code cache.</li> <li><code>used</code>: The amount of code cache memory actually in use.</li> <li><code>max_used</code>: The high water mark for code cache usage.</li> <li><code>free</code>: <code>size</code> minus <code>used</code>.</li> </ul>"},{"location":"xxprintflagsfinal/","title":"-XX:[+|-]PrintFlagsFinal","text":""},{"location":"xxprintflagsfinal/#-xx-printflagsfinal","title":"-XX:[+|-]PrintFlagsFinal","text":"<p>When enabled, this option outputs the values of a subset of configuration parameters in a format compatible with that produced by HotSpot. The parameters currently output are those expected by various software projects and packages.</p>"},{"location":"xxprintflagsfinal/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PrintFlagsFinal\n</code></pre> Setting Effect Default <code>-XX:+PrintFlagsFinal</code> Enable <code>-XX:-PrintFlagsFinal</code> Disable yes"},{"location":"xxprintflagsfinal/#example","title":"Example","text":"<p>Here is an example of typical output from <code>-XX:+PrintFlagsFinal</code>:</p> <pre><code>[Global flags]\n   size_t MaxHeapSize              = 4294967296          {product} {ergonomic}\n uint64_t MaxDirectMemorySize      = 3758096384          {product} {ergonomic}\n</code></pre>"},{"location":"xxreadipinfoforras/","title":"-XX:[+|-]ReadIPInfoForRAS","text":""},{"location":"xxreadipinfoforras/#-xx-readipinfoforras","title":"-XX:[+|-]ReadIPInfoForRAS","text":"<p>Use this command-line option to enable and disable network queries from being used to determine the host name and IP address for RAS (reliability, availability, and serviceability) troubleshooting purposes.</p>"},{"location":"xxreadipinfoforras/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ReadIPInfoForRAS\n</code></pre> Setting Effect Default <code>-XX:+ReadIPInfoForRAS</code> Enable yes <code>-XX:-ReadIPInfoForRAS</code> Disable <p>Eclipse OpenJ9\u2122 captures the host name and IP address by default, for use in diagnosing problems. But if a nameserver cannot be contacted when a network query is made, the program will wait until the resolver times out.</p> <p>You can avoid this situation by using the <code>-XX:-ReadIPInfoForRAS</code> command-line option to prevent the query from being performed.</p>"},{"location":"xxreducecpumonitoroverhead/","title":"-XX:[+|-]ReduceCPUMonitorOverhead","text":""},{"location":"xxreducecpumonitoroverhead/#-xx-reducecpumonitoroverhead","title":"-XX:[+|-]ReduceCPUMonitorOverhead","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122 only)</p> <p>This option relates to the CPU usage of thread categories that can be obtained with the <code>com.ibm.lang.management.JvmCpuMonitorMXBean</code> application programming interface. This option affects the way that the VM records the amount of CPU usage of non-Garbage Collection (GC) threads that do work on behalf of GC.</p> <p>Most GC policies require non-GC threads to do some GC housekeeping work in proportion to the amount of memory allocation that they do. Ideally the exact amount of CPU time that the thread spends doing this housekeeping work should be accounted for in the GC thread category. However there is an overhead that is associated with maintaining the CPU usage data in the correct thread category.</p> <p> Restriction: This option is not supported on z/OS\u00ae. If you attempt to use this option, the following message is generated:</p> <pre><code>JVMJ9VM145E -XX:-ReduceCPUMonitorOverhead is unsupported on z/OS. Error: Could not create the Java Virtual Machine.\n</code></pre>"},{"location":"xxreducecpumonitoroverhead/#syntax","title":"Syntax","text":"<p>-XX:[+|-]ReduceCPUMonitorOverhead</p> Setting Effect Default <code>-XX:+ReduceCPUMonitorOverhead</code> Enable yes <code>-XX:-ReduceCPUMonitorOverhead</code> Disable <p>When you enable this option, the VM does not maintain information on the amount of CPU usage that non-GC threads spend in doing work on behalf of GC. If you set <code>-XX:-ReduceCPUMonitorOverhead</code>, the Eclipse OpenJ9\u2122 VM monitors the amount of GC work that a non-GC thread does and accounts for it in the GC category. This information is made available in the <code>com.ibm.lang.management.JvmCpuMonitorMXBean</code>. Setting this option results in a small increase in application startup time, which varies according to platform.</p>"},{"location":"xxreducecpumonitoroverhead/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]EnableCPUMonitor</li> </ul>"},{"location":"xxrequirejitserver/","title":"-XX:[+|-]RequireJITServer","text":""},{"location":"xxrequirejitserver/#-xx-requirejitserver","title":"-XX:[+|-]RequireJITServer","text":"<p>When you enable this option, the JITServer client crashes with an assert if it detects that a JITServer server is unavailable.</p>"},{"location":"xxrequirejitserver/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]RequireJITServer\n</code></pre> Setting Effect Default <code>-XX:+RequireJITServer</code> Enable <code>-XX:-RequireJITServer</code> Disable yes"},{"location":"xxrequirejitserver/#explanation","title":"Explanation","text":"<p>This option is for debugging purposes only.</p> <p>When this option is disabled, a server crash forces the client to perform compilations locally. You might want to enable this option if you are running a test suite with JITServer enabled, so that a test fails if the server crashes, instead of switching to local compilations and hiding the failure.</p>"},{"location":"xxrequirejitserver/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxruntimeinstrumentation/","title":"-XX:[+|-]RuntimeInstrumentation","text":""},{"location":"xxruntimeinstrumentation/#-xx-runtimeinstrumentation","title":"-XX:[+|-]RuntimeInstrumentation","text":"<p>(AIX\u00ae, Linux\u00ae, and z/OS\u00ae only)</p> <p>This option controls the use of the Runtime Instrumentation (RI) facility in the virtual machines that support it.</p> <p>The RI facility is a feature that is available in POWER8\u00ae, zEC12, and later processors that offers hardware support for collecting profiling information at run time. The process uses minimal resources. The use of the RI facility is not enabled by default.</p>"},{"location":"xxruntimeinstrumentation/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]RuntimeInstrumentation\n</code></pre> Setting Effect Default <code>-XX:+RuntimeInstrumentation</code> Enable <code>-XX:-RuntimeInstrumentation</code> Disable yes <p> Note: On Linux, the RI facility on Power 8 and later processors uses the Performance Monitoring Unit (PMU) inside the processor. However, the PMU is also used by system profilers like oprofile or perf. Due to the current Linux kernel implementation, a user cannot reliably profile a Java\u2122 application when RI is enabled. Although this limitation might be addressed in future Linux kernels, for reliable profiling on Power systems that use Linux, the <code>-XX:-RuntimeInstrumentation</code> option must be used.</p>"},{"location":"xxsethwprefetch/","title":"-XXsetHWPrefetch","text":""},{"location":"xxsethwprefetch/#-xxsethwprefetch","title":"-XXsetHWPrefetch","text":"<p>(AIX\u00ae only)</p> <p>This option enables or disables hardware prefetch. Hardware prefetch can improve the performance of applications by prefetching memory. However, because of the workload characteristics of many Java\u2122 applications, prefetching often has an adverse effect on performance.</p>"},{"location":"xxsethwprefetch/#syntax","title":"Syntax","text":"<pre><code>    -XXsetHWPrefetch=[none|os-default]\n</code></pre> Setting Effect Default none Disable yes os-default Enable <p>The <code>-XXsetHWPrefetch:none</code> option disables hardware prefetch. Although you can disable hardware prefetch on AIX by issuing the command <code>dscrctl -n -s 1</code>, this command disables hardware prefetch for all processes, and for all future processes, which might not be desirable in a mixed workload environment. The <code>-XXsetHWPrefetch:none</code> option allows hardware prefetch to be disabled for individual VMs.</p> <p>To enable hardware prefetch with the default value for the operating system, specify <code>-XXsetHWPrefetch:os-default</code>. Use this option only for applications that can obtain a performance gain from hardware prefetch.</p>"},{"location":"xxshareanonymousclasses/","title":"-XX:[+|-]ShareAnonymousClasses","text":""},{"location":"xxshareanonymousclasses/#-xx-shareanonymousclasses","title":"-XX:[+|-]ShareAnonymousClasses","text":"<p>This option enables and disables the storage of VM anonymous classes, those created by <code>Unsafe.defineAnonymousClass</code>, in the shared classes cache.</p> <p> In OpenJDK 15 and later versions, this option also enables and disables the storage of hidden classes in the shared classes cache.</p> <p>The option is enabled by default, which means that anonymous classes (and hidden classes, in OpenJDK 15 and later) are stored in the shared classes cache and are therefore available for ahead-of-time (AOT) compilation, potentially improving startup performance.</p>"},{"location":"xxshareanonymousclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShareAnonymousClasses\n</code></pre> Setting Effect Default <code>-XX:+ShareAnonymousClasses</code> Enable yes <code>-XX:-ShareAnonymousClasses</code> Disable"},{"location":"xxshareanonymousclasses/#see-also","title":"See also","text":"<ul> <li>AOT compiler</li> <li>Introduction to class data sharing</li> <li>-Xshareclasses</li> <li>-XX:[+|-]ShareUnsafeClasses</li> </ul>"},{"location":"xxshareclassesenablebci/","title":"-XX:ShareClassesEnableBCI","text":""},{"location":"xxshareclassesenablebci/#-xxshareclassesdisablebci-xxshareclassesenablebci","title":"-XX:ShareClassesDisableBCI /  -XX:ShareClassesEnableBCI","text":"<p>The option <code>-Xshareclasses:enableBCI</code> improves startup performance without using a modification context, when using JVMTI class modification. This suboption allows classes loaded from the shared cache to be modified using a JVMTI <code>ClassFileLoadHook</code>, or a <code>java.lang.instrument</code> agent, and prevents modified classes being stored in the shared classes cache. You can turn off this option by specifying <code>-XX:ShareClassesDisableBCI</code> when you start your Java\u2122 application.</p>"},{"location":"xxshareclassesenablebci/#syntax","title":"Syntax","text":"<pre><code>    -XX:ShareClassesDisableBCI|ShareClassesEnableBCI\n</code></pre> Setting Effect Default <code>-XX:ShareClassesDisableBCI</code> Disable <code>-XX:ShareClassesEnableBCI</code> Enable yes <p>These options are equivalent to <code>-Xshareclasses:disableBCI</code> and <code>-Xshareclasses:enableBCI</code>. For more information, see <code>-Xshareclasses</code>.</p>"},{"location":"xxshareclassesenablebci/#see-also","title":"See also","text":"<ul> <li>Support for bytecode instrumentation</li> </ul>"},{"location":"xxsharedcachehardlimit/","title":"-XX:SharedCacheHardLimit","text":""},{"location":"xxsharedcachehardlimit/#-xxsharedcachehardlimit","title":"-XX:SharedCacheHardLimit","text":"<p>Specifies the size for a new shared classes cache. Use this option together with the <code>-Xscmx</code> option to set actual and soft maximum size limits respectively.</p>"},{"location":"xxsharedcachehardlimit/#syntax","title":"Syntax","text":"<pre><code>    -XX:SharedCacheHardLimit=&lt;size&gt;\n</code></pre> Setting Value Default <code>&lt;size&gt;</code> [1[k|K|m|M|g|G] or greater] <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>When you use this option with the <code>-Xscmx</code> option, the <code>-Xscmx</code> option sets the soft maximum size, and the <code>-XX:SharedCacheHardLimit</code> option sets the actual size, of a new shared classes cache. For more information, see -Xscmx.</p> <p>If you use this option without the <code>-Xscmx</code> option, the behavior is the same as using the <code>-Xscmx</code> option by itself; both options set the actual size of the shared classes cache.</p> <p>For more information about cache sizes, see Cache size limits.</p>"},{"location":"xxsharedcachehardlimit/#example","title":"Example","text":"<p>The following settings, when used together, set the soft maximum size of the shared classes cache to 16 MB and the actual maximum cache size to 64 MB.</p> <pre><code>-XX:SharedCacheHardLimit=64m -Xscmx16m\n</code></pre>"},{"location":"xxsharedcachehardlimit/#see-also","title":"See also","text":"<ul> <li>-Xscmx</li> </ul>"},{"location":"xxshareunsafeclasses/","title":"-XX:[+|-]ShareUnsafeClasses","text":""},{"location":"xxshareunsafeclasses/#-xx-shareunsafeclasses","title":"-XX:[+|-]ShareUnsafeClasses","text":"<p>This option enables and disables the storage of VM classes created through <code>Unsafe.defineClass</code> in the shared classes cache.</p> <p>The option is enabled by default, which means that unsafe classes are stored in the shared classes cache and are therefore available for ahead-of-time (AOT) compilation, potentially improving startup performance.</p>"},{"location":"xxshareunsafeclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShareUnsafeClasses\n</code></pre> Setting Effect Default <code>-XX:+ShareUnsafeClasses</code> Enable yes <code>-XX:-ShareUnsafeClasses</code> Disable"},{"location":"xxshareunsafeclasses/#see-also","title":"See also","text":"<ul> <li>AOT compiler</li> <li>Introduction to class data sharing</li> <li>-Xshareclasses</li> <li>-XX:[+|-]ShareAnonymousClasses</li> </ul>"},{"location":"xxshowcarrierframes/","title":"-XX:[+|-]ShowCarrierFrames","text":""},{"location":"xxshowcarrierframes/#-xx-showcarrierframes","title":"-XX:[+|-]ShowCarrierFrames","text":"<p> This option controls the addition of the carrier threads' stack trace to the <code>Throwable.getStackTrace()</code> method. You can add the stack trace of the carrier threads to facilitate the debugging process.</p> <p> Notes:</p> <ul> <li>The platform thread that runs a virtual thread is that virtual thread's carrier thread.</li> <li>The <code>-XX:[+|-]ShowCarrierFrames</code> option is applicable only if the current thread is a virtual thread.</li> <li>If you specify the <code>-XX:-StackTraceInThrowable</code> option, the <code>-XX:[+|-]ShowCarrierFrames</code> option has no effect. The <code>-XX:-StackTraceInThrowable</code> option removes stack trace of all threads from exceptions.</li> </ul>"},{"location":"xxshowcarrierframes/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShowCarrierFrames\n</code></pre> Setting Effect Default <code>-XX:+ShowCarrierFrames</code> Enable <code>-XX:-ShowCarrierFrames</code> Disable yes"},{"location":"xxshowcarrierframes/#explanation","title":"Explanation","text":"<p>Virtual threads require platform threads to run because the operating system identifies only platform threads. Therefore, a VM maintains multiple platform threads that are used as carrier threads to run the virtual threads. The VM assigns a virtual thread to a platform thread in a process called mounting.</p> <p>Although the virtual thread runs on a carrier thread, the stack trace of the virtual thread and its carrier thread are separate. If an exception occurs on running the virtual threads, the thread dumps do not include stack frames from the carrier thread's stack.</p> <p>You can use the <code>-XX:+ShowCarrierFrames</code> option to add the stack trace of the carrier thread in addition to the virtual thread stack trace to the <code>Throwable.getStackTrace()</code> method, if an exception occurs. </p>"},{"location":"xxshowhiddenframes/","title":"-XX:[+|-]ShowHiddenFrames","text":""},{"location":"xxshowhiddenframes/#-xx-showhiddenframes","title":"-XX:[+|-]ShowHiddenFrames","text":"<p>This reimplementation of the Oracle HotSpot diagonostic option enables or disables the display of generated hidden <code>MethodHandle</code> frames in a stack trace.</p> <p>This option doesn't affect the contents of dump files.</p> <p>Unlike the HotSpot implementation, this option doesn't require the <code>+UnlockDiagnosticVMOptions</code> option.</p>"},{"location":"xxshowhiddenframes/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShowHiddenFrames\n</code></pre> Setting Effect Default <code>-XX:+ShowHiddenFrames</code> Enable <code>-XX:-ShowHiddenFrames</code> Disable yes When disabled, this option causes the VM to hide generated hidden <code>MethodHandle</code> frames in a stacktrace."},{"location":"xxshownativestacksymbols/","title":"-XX:[+|-]ShowNativeStackSymbols","text":""},{"location":"xxshownativestacksymbols/#-xx-shownativestacksymbols","title":"-XX:[+|-]ShowNativeStackSymbols","text":"<p>This option controls whether Java\u00ae dumps show the names of functions in native call stacks.</p>"},{"location":"xxshownativestacksymbols/#syntax","title":"Syntax","text":"<pre><code>    -XX:-ShowNativeStackSymbols\n    -XX:+ShowNativeStackSymbols=&lt;value&gt;\n</code></pre> Setting Value Effect Default <code>-XX:-ShowNativeStackSymbols</code> Don't show native stack symbols, not even in response to a signal, such as a fault signal <code>-XX:+ShowNativeStackSymbols</code> basic Show all the available native stack symbols for a signaled or faulting thread, but only easily acquired native stack symbols for other threads yes <code>-XX:+ShowNativeStackSymbols</code> all Show all the available native stack symbols for all threads"},{"location":"xxshownativestacksymbols/#explanation","title":"Explanation","text":"<p>Java dumps take longer to produce when the native stack symbols are included. If your Java application has a lot of threads, you might get an incomplete Java dump. You can avoid this situation by reducing the number of native stack symbols in the Java dump or by omitting them altogether.</p>"},{"location":"xxstacktraceinthrowable/","title":"-XX:-StackTraceInThrowable","text":""},{"location":"xxstacktraceinthrowable/#-xx-stacktraceinthrowable","title":"-XX:-StackTraceInThrowable","text":"<p>This option removes stack traces from exceptions.</p>"},{"location":"xxstacktraceinthrowable/#syntax","title":"Syntax","text":"<pre><code>    -XX:-StackTraceInThrowable\n</code></pre> Setting Effect Default <code>-XX:-StackTraceInThrowable</code> Disable No <p>While stack traces are included in exceptions by default, recording them can have a negative impact on performance. Use this option if you want to remove stack traces, although this might cause difficulties with problem determination.</p> <p>When this option is enabled, <code>Throwable.getStackTrace()</code> returns an empty array and the stack trace is displayed when an uncaught exception occurs. <code>Thread.getStackTrace()</code> and <code>Thread.getAllStackTraces()</code> are not affected by this option.</p>"},{"location":"xxstacktraceinthrowable/#see-also","title":"See also","text":"<ul> <li><code>-XX:\\[+|-\\]ShowCarrierFrames</code></li> </ul>"},{"location":"xxtransparenthugepage/","title":"-XX:[+|-]TransparentHugePage","text":""},{"location":"xxtransparenthugepage/#-xx-transparenthugepage","title":"-XX:[+|-]TransparentHugePage","text":"<p>(Linux\u00ae systems only: x86, POWER\u00ae, and IBM Z\u00ae)</p> <p>If Transparent Huge Pages (THP) is set to <code>madvise</code> on your system, this option, when enabled, promotes all memory allocated to huge pages. On systems without THP, or if THP is set to <code>always</code> or <code>never</code> on your system, this option is ignored. When transparent huge pages are used, your application footprint might increase.</p>"},{"location":"xxtransparenthugepage/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+TransparentHugePage</code> Enable yes <code>-XX:-TransparentHugePage</code> Disable"},{"location":"xxusecompressedoops/","title":"-XX:[+|-]UseCompressedOops","text":""},{"location":"xxusecompressedoops/#-xx-usecompressedoops","title":"-XX:[+|-]UseCompressedOops","text":"<p>(64-bit only)</p> <p>This Oracle HotSpot option enables or disables compressed references in 64-bit JVMs. The option is recognized by the Eclipse OpenJ9\u2122 VM and is provided to help when porting applications from the HotSpot JVM to the OpenJ9 VM. This option might not be supported in subsequent releases.</p>"},{"location":"xxusecompressedoops/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseCompressedOops\n</code></pre> Setting Effect Default <code>-XX:+UseCompressedOops</code> Enable <code>-XX:-UseCompressedOops</code> Disable <p>The <code>-XX:+UseCompressedOops</code> option is similar to specifying <code>-Xcompressedrefs</code>. Compressed references are used by default when the maximum memory size for an application is set above a platform-specific value. For more information, see <code>-Xcompressedrefs</code>.  </p>"},{"location":"xxusecontainersupport/","title":"-XX:[+|-]UseContainerSupport","text":""},{"location":"xxusecontainersupport/#-xx-usecontainersupport","title":"-XX:[+|-]UseContainerSupport","text":"<p>(Linux\u00ae only)</p> <p>If your application is running in a container that imposes a memory limit, the VM allocates a larger fraction of memory to the Java heap. To turn off this behavior, set the <code>-XX:-UseContainerSupport</code> option on the command line.</p>"},{"location":"xxusecontainersupport/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseContainerSupport\n</code></pre> Setting Effect Default <code>-XX:-UseContainerSupport</code> Disable <code>-XX:+UseContainerSupport</code> Enable yes <p>When using container technology, applications are typically run on their own and do not need to compete for memory. The Eclipse OpenJ9\u2122 VM detects when it is running inside a container that imposes a memory limit, and adjusts the maximum Java heap size appropriately.</p> <p>The following table shows the values that are used when <code>-XX:+UseContainerSupport</code> is set:</p> Container memory limit &lt;size&gt; Maximum Java heap size Less than 1 GB 50% &lt;size&gt; 1 GB - 2 GB &lt;size&gt; - 512 MB Greater than 2 GB 75% &lt;size&gt; <p>The default heap size is capped at 25 GB, which is the limit of heap size for 3-bit shift of compressed references (see -Xcompressedrefs), to prevent silent switching to 4-bit shift of compressed references, which has possible performance penalties. You can use the <code>-Xmx</code> option or the <code>-XX:MaxRAMPercentage</code> option to overwrite the 25 GB limit.</p> <p>The default heap size for containers takes affect only when the following conditions are met:</p> <ol> <li>The application is running in a container environment.</li> <li>The memory limit for the container is set.</li> <li>The <code>-XX:+UseContainerSupport</code> option is set, which is the default behavior.</li> </ol> <p>To prevent the VM adjusting the maximum heap size when running in a container, set <code>-XX:-UseContainerSupport</code>.</p> <p>When <code>-XX:MaxRAMPercentage</code> / <code>-XX:InitialRAMPercentage</code> are used with <code>-XX:+UseContainerSupport</code>, the corresponding heap setting is determined based on the memory limit of the container. For example, to set the maximum heap size to 80% of the container memory, specify the following options:</p> <pre><code>-XX:+UseContainerSupport -XX:MaxRAMPercentage=80\n</code></pre> <p> Note: If you set a value for <code>-Xms</code>, the <code>-XX:InitialRAMPercentage</code> option is ignored. If you set a value for <code>-Xmx</code>, the <code>-XX:MaxRAMPercentage</code> option is ignored.</p>"},{"location":"xxusegcstartuphints/","title":"-XX:[+|-]UseGCStartupHints","text":""},{"location":"xxusegcstartuphints/#-xx-usegcstartuphints","title":"-XX:[+|-]UseGCStartupHints","text":"<p>When this option is enabled, the VM calculates, over several application restarts, an appropriate startup heap size for your application. You can therefore use this option instead of calculating and setting an <code>-Xms</code> value yourself. Setting an initial size for the heap that is larger than the default helps to avoid frequent garbage collections during the startup phase of an application.</p>"},{"location":"xxusegcstartuphints/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseGCStartupHints\n</code></pre> Setting Effect Default <code>-XX:+UseGCStartupHints</code> Enable yes <code>-XX:-UseGCStartupHints</code> Disable <p>When enabled, the VM records the heap size when a startup complete event occurs, storing the value into the shared classes cache. On subsequent restarts, the garbage collector (GC) reads this value early in startup processing and expands the heap to an appropriate value. For accuracy and stability, averages are taken over a few restarts to stabilize the value used. The heap size recorded is specific to the application command line, therefore a different hint is stored for every unique command line.</p> <p>You can check the value used by the garbage collector for heap expansion by inspecting verbose GC output. The following example shows heap expansion based on hints from the previous run when using the <code>gencon</code> policy:</p> <pre><code>&lt;heap-resize id=\"2\" type=\"expand\" space=\"nursery\" amount=\"205258752\" count=\"1\" timems=\"0.328\" reason=\"hint from previous runs\" timestamp=\"2019-06-05T13:26:32.021\" /&gt;\n&lt;heap-resize id=\"3\" type=\"expand\" space=\"tenure\" amount=\"692649984\" count=\"1\" timems=\"0.326\" reason=\"hint from previous runs\" timestamp=\"2019-06-05T13:26:32.022\" /&gt;\n</code></pre> <p>The final value stored to the shared cache is not recorded in the verbose GC output.</p> <p> Notes:</p> <ul> <li>When enabled, this option overrides any initial heap size that is specified on the command line, for example by using the <code>-Xms</code> option.</li> <li>Because the shared classes cache is used to store heap size information, this option does not work if class data sharing (<code>-Xshareclasses</code>) is disabled.</li> </ul> <p> Restriction: This feature is not currently available with the Balanced GC policy.</p>"},{"location":"xxusejitserver/","title":"-XX:[+|-]UseJITServer","text":""},{"location":"xxusejitserver/#-xx-usejitserver","title":"-XX:[+|-]UseJITServer","text":"<p>This option starts the Eclipse OpenJ9\u2122 VM in JITServer client mode.</p>"},{"location":"xxusejitserver/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseJITServer\n</code></pre> Setting Effect Default <code>-XX:+UseJITServer</code> Enable <code>-XX:-UseJITServer</code> Disable yes"},{"location":"xxusejitserver/#explanation","title":"Explanation","text":"<p>When you enable this option, the VM tries to connect to a server and send all JIT compilation requests to it. For more information, see JITServer Technology.</p> <p>You must specify this option for any other <code>-XX:*JITServer*</code> options to take effect.</p>"},{"location":"xxusejitserver/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxusenogc/","title":"-XX:[+|-]UseNoGC","text":""},{"location":"xxusenogc/#-xx-usenogc","title":"-XX:[+|-]UseNoGC","text":"<p>The <code>-XX:+UseNoGC</code> option enables a garbage collection policy that expands the Java object heap in the normal way until the limit is reached, but memory is not reclaimed through garbage collection.</p>"},{"location":"xxusenogc/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseNoGC\n</code></pre> Setting Effect Default <code>-XX:+UseNoGC</code> Enable <code>-XX:-UseNoGC</code> Disable yes"},{"location":"xxusenogc/#explanation","title":"Explanation","text":"<p>This policy can be useful for test purposes and for short-lived applications. When the limit is reached an <code>OutOfMemory</code> error is generated and the VM shuts down.</p> <p>The <code>-XX:-UseNoGC</code> option turns off a previously enabled <code>-XX:+UseNoGC</code> option.</p> <p>This policy can also be enabled with the <code>-Xgcpolicy:nogc</code> option. See <code>-Xgcpolicy:nogc</code> for more details about this policy and when it is appropriate to use it.</p>"},{"location":"xxusezlibnx/","title":"-XX:[+|-]UseZlibNX","text":""},{"location":"xxusezlibnx/#-xx-usezlibnx","title":"-XX:[+|-]UseZlibNX","text":"<p>AIX\u00ae with IBM POWER9\u00ae and later only</p> <p>This option enables or disables the adding of the <code>zlibNX</code> library directory location to the <code>LIBPATH</code> environment variable.</p>"},{"location":"xxusezlibnx/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseZlibNX\n</code></pre> Setting Effect Default <code>-XX:+UseZlibNX</code> Enable yes <code>-XX:-UseZlibNX</code> Disable"},{"location":"xxusezlibnx/#explanation","title":"Explanation","text":"<p>AIX system adds the <code>zlibNX</code> library location, if available, to the <code>LIBPATH</code> variable by default. But having the <code>zlibNX</code> library directory location in the <code>LIBPATH</code> variable might cause some issues. For example, Git clone fails when executed from Java\u00ae when <code>zlibNX</code> is on the <code>LIBPATH</code> in the environment.</p> <p>You can disable adding of the <code>zlibNX</code> library location to the <code>LIBPATH</code> variable with the <code>-XX:-UseZlibNX</code> option.</p>"},{"location":"xxusezlibnx/#see-also","title":"See also","text":"<ul> <li>Hardware acceleration</li> <li>Configuring your system</li> </ul>"},{"location":"xxutfcache/","title":"-XX:[+|-]UTFCache","text":""},{"location":"xxutfcache/#-xx-utfcache","title":"-XX:[+|-]UTFCache","text":"<p>This option enables or disables the UTF to String cache used to enhance reflection performance.</p>"},{"location":"xxutfcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UTFCache\n</code></pre> Setting Effect Default <code>-XX:+UTFCache</code> Enable yes <code>-XX:-UTFCache</code> Disable <p>The option, <code>-XX:+UTFCache</code>, causes the VM to cache the conversion of UTF8 data to java String objects during reflection. This is the default option.</p> <p>When specifying the <code>-XX:-UTFCache</code> option, the VM does not performing this caching.</p>"},{"location":"xxverboseverification/","title":"-XX:[+|-]VerboseVerification","text":""},{"location":"xxverboseverification/#-xx-verboseverification","title":"-XX:[+|-]VerboseVerification","text":"<p>You can use this option to control the output of verbose diagnostic data that relates to verification.</p> <p>The Oracle documentation to support this option is no longer available, because it is no longer used by the HotSpot VM. An explanation is provided here.</p>"},{"location":"xxverboseverification/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]VerboseVerification\n</code></pre> Setting Effect Default <code>-XX:-VerboseVerification</code> Disable yes <code>-XX:+VerboseVerification</code> Enable <p>Use  <code>-XX:-VerboseVerification</code> to enable the output of verbose diagnostic data to <code>stderr</code> that is generated during verification from the class file <code>StackMapTable</code> attribute. The data provides extra contextual information about bytecode verification, which helps diagnose bytecode or stackmap deficiencies in the field.</p> <p>Class files that have <code>StackMapTable</code> attributes (that is, class files that conform to version 50.0 or later of the class file format specification), are introduced in Java\u2122 V6. Class files with <code>StackMapTable</code> attributes are marked as <code>new format</code> in the verbose output, as shown in the example. Class files without the <code>StackMapTable</code> attributes are marked as <code>old format</code>. The <code>StackMapTable</code> diagnostic information is available only to classes verified with the new format.</p> <p>Here is an example of <code>StackMapTable</code> diagnostic output:</p> <pre><code>Verifying class java.example.ibm.com with new format\nVerifying method java.example.ibm.com.foo(Ljava/lang/String;Ljava/lang/Class;[Ljava/lang/String;Ljava/io/PrintStream;)I\nStackMapTable: frame_count = 3\ntable = {\n  bci: @37\n  flags: { }\n  locals: { 'java/lang/String', 'java/lang/Class', '[Ljava/lang/String;', 'java/io/PrintStream', 'java/lang/Class' }\n  stack: { 'java/lang/ThreadDeath' }\n  bci: @42\n  flags: { }\n  locals: { 'java/lang/String', 'java/lang/Class', '[Ljava/lang/String;', 'java/io/PrintStream', 'java/lang/Class' }\n  stack: { 'java/lang/Throwable' }\n  bci: @79\n  flags: { }\n  locals: { 'java/lang/String', 'java/lang/Class', '[Ljava/lang/String;', 'java/io/PrintStream', 'java/lang/Class',\n        'java/lang/Throwable' }\n  stack: { }\n }\nEnd class verification for: java.example.ibm.com\n</code></pre>"},{"location":"xxvmlockclassloader/","title":"-XX:[+|-]VMLockClassLoader","text":""},{"location":"xxvmlockclassloader/#-xx-vmlockclassloader","title":"-XX:[+|-]VMLockClassLoader","text":"<p>This option affects synchronization on class loaders that are not parallel-capable class loaders, during class loading.</p>"},{"location":"xxvmlockclassloader/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]VMLockClassLoader\n</code></pre> Setting Effect Default <code>-XX:+VMLockClassLoader</code> Enable yes <code>-XX:-VMLockClassLoader</code> Disable <p>The option, <code>-XX:+VMLockClassLoader</code>, causes the VM to force synchronization on a class loader that is not a parallel capable class loader during class loading. This action occurs even if the <code>loadClass()</code> method for that class loader is not synchronized. For information about parallel capable class loaders, see <code>java.lang.ClassLoader.registerAsParallelCapable()</code>. Note that this option might cause a deadlock if class loaders use non-hierarchical delegation. For example, setting the system property <code>osgi.classloader.lock=classname</code> with Equinox is known to cause a deadlock. This is the default option.</p> <p>When specifying the <code>-XX:-VMLockClassLoader</code> option, the VM does not force synchronization on a class loader during class loading. The class loader still conforms to class library synchronization, such as a synchronized <code>loadClass()</code> method.</p>"},{"location":"xzero/","title":"-Xzero","text":""},{"location":"xzero/#-xzero","title":"-Xzero","text":"<p>Enables reduction of the memory footprint of the Java\u2122 runtime environment when concurrently running multiple Java invocations.</p> <p>This option is deprecated and will be removed in a future release.</p> <p> This option can be used only with Java SE version 8 runtime environments. </p> <p><code>-Xzero</code> might not be appropriate for all types of applications because it changes the implementation of <code>java.util.ZipFile</code>, which might cause extra memory usage.</p>"},{"location":"xzero/#syntax","title":"Syntax","text":"Setting Effect <code>-Xzero:none</code> Disable all sub options <code>-Xzero:describe</code> Prints the sub options in effect <code>-Xzero:sharebootzip</code> Enables the sharebootzip sub option <code>-Xzero:nosharebootzip</code> Disables the sharebootzip sub option <p>The following parameters are no longer supported. The options are parsed but do nothing:</p> Setting Effect <code>-Xzero:j9zip</code> Enables the j9zip sub option <code>-Xzero:noj9zip</code> Disables the j9zip sub option <code>-Xzero:sharezip</code> Enables the sharezip sub option <code>-Xzero:nosharezip</code> Disables the sharezip sub option"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"About the docs","text":""},{"location":"#eclipse-openj9","title":"Eclipse OpenJ9","text":"<p>Welcome to the user documentation for the Eclipse OpenJ9\u2122 virtual machine (VM).</p> <p>This user documentation supports the configuration, tuning, and diagnosis of the OpenJ9 VM in an OpenJDK runtime. However, due to differences between the Java SE class libraries, specific options might apply only to one Java SE version. Icons are used to indicate where differences apply. For example:</p> <p> This sentence applies only to Java 11 binaries that include the OpenJ9 VM. Icons for LTS releases are this colour. </p> <p> This sentence applies only to Java 16 or later binaries that include the OpenJ9 VM. Icons for feature releases are this colour. </p> <p>To see which Java releases are LTS releases and which are feature releases, and for information about release cadence, supported platforms, and build environments, see Supported environments.</p> <p> Note: Documentation to support OpenJ9 is still under construction. The current content covers some high level information about OpenJ9 components together with the command-line options and environment variables that you can use to configure the VM when you start your application. Because OpenJ9 was contributed to the Eclipse Foundation by IBM, this content contains some links to additional information that forms part of the IBM\u00ae SDK, Java\u2122 Technology Edition product documentation in IBM Documentation. That content supplements the documentation here until a more complete set of user documentation is available.</p> <p>We welcome contributions to the user documentation. If you would like to get involved, please read our Contribution guidelines. If you spot any errors in the documentation, please raise an issue at our GitHub repository.</p>"},{"location":"#supported-environments","title":"Supported environments","text":"<p>OpenJDK binaries that contain the OpenJ9 VM are supported on a range of hardware and operating systems. This range is expanding as work progresses at the Eclipse foundation. See the current list of supported environments for details.</p> <p> Note: This user guide also contains information about configuring, tuning, and debugging OpenJ9 on the z/OS\u00ae platform.</p>"},{"location":"#documentation-for-specific-releases","title":"Documentation for specific releases","text":"<p>Several versions of the documentation are available, covering all releases of OpenJ9:</p> <ul> <li>Online documentation for the last release</li> <li>Online, in-progress documentation for the forthcoming release</li> <li>Downloads of earlier releases: to download a zip file, click the filename, then click Download. After downloading a <code>.zip</code> file, extract it, then open the <code>index.html</code> file in your browser.</li> </ul>"},{"location":"#useful-links","title":"Useful links","text":"<ul> <li>Eclipse OpenJ9 website home page</li> <li>Eclipse OpenJ9 GitHub repository</li> <li>Eclipse Foundation OpenJ9 project page</li> </ul>"},{"location":"allocation/","title":"Heap allocation","text":""},{"location":"allocation/#heap-allocation","title":"Heap allocation","text":"<p>The process of managing memory in the VM is handled by the allocator and the garbage collector. These components operate on an area of memory that is reserved for VM processing called the Java\u2122 heap.</p> <p>The allocator assigns areas of the heap for Java objects. Objects are considered as live when they have a chain of references to them that start from root references, such as those found in thread stacks. When that reference or pointer no longer exists, the objects are considered as garbage.</p> <p>The garbage collector reclaims memory by removing objects when they are no longer required. To find out more about the garbage collector, see Garbage collection.</p> <p>Depending on your application workload or service level agreement, you can choose from a number of Eclipse OpenJ9\u2122 garbage collection (GC) policies. Each GC policy uses a different strategy to manage memory on the heap. The structure of the heap also depends on the strategy in force. For more information about choosing a GC policy, see Garbage collection policies.</p>"},{"location":"allocation/#the-allocator","title":"The allocator","text":"<p>The allocator manages pools of free memory and how the free memory is consumed. It is also responsible for allocating areas of storage in the Java heap for objects at the request of applications, class libraries, or the VM.</p> <p>In general, allocation requires a heap lock to synchronize concurrent threads that try to access the same area of memory at the same time. When an object is allocated, the heap lock is released. If there is insufficient space to allocate the object, allocation fails, the heap lock is released, and the garbage collector is called. If GC manages to recover some space on the heap, the allocator can resume operations. If GC does not recover enough space, it returns an <code>OutOfMemoryError</code> exception.</p> <p>Acquiring a heap lock for every allocation would be an intensive operation with an impact to performance. To get around this problem, small objects are allocated to allocation caches.</p>"},{"location":"allocation/#allocation-caches","title":"Allocation caches","text":"<p>To improve performance, allocation caches are reserved in the heap for different threads. These allocation caches are known as thread local heaps (TLH) and allow each thread to allocate memory from its cache without acquiring the heap lock. Objects are allocated from the TLH unless there is insufficient space remaining in the TLH to satisfy the request. In this situation, the allocation might proceed directly from the heap for larger objects by using a heap lock or the TLH might be refreshed for smaller objects.</p> <p>If a thread allocates a lot of objects, the allocator gives that thread a larger TLH to reduce contention on the heap lock.</p> <p>A TLH is predefined with an initial default size of 2 KB. On every TLH refresh, the requested size for that thread is increased by an increment (default 4 KB). The requested size can grow up to a predefined maximum (default 128 KB). If a TLH refresh fails to complete, a GC cycle is triggered.</p> <p>After every GC cycle, the requested size of the TLH for each thread is reduced, sometimes by as much as 50%, to take account of threads that reduce their allocation rate and no longer need large TLHs.</p> <p>For very inactive threads, the requested size can even drop below the initial value, down to the predefined minimum (512/768 bytes). For very active threads, the maximum TLH requested size might be reached before the next GC occurs.</p> <p>Larger TLHs can help reduce heap lock contention, but might also reduce heap utilization and increase heap fragmentation.</p> <p>The following options control the requested TLH size:</p> <ul> <li><code>-Xgc:tlhMaximumSize=&lt;bytes&gt;</code></li> <li><code>-Xgc:tlhInitialSize=&lt;bytes&gt;</code></li> <li><code>-Xgc:tlhIncrementSize=&lt;bytes&gt;</code></li> </ul> <p>Typically, when the maximum TLH size is increased, you should also increase the increment proportionally, so that active threads can reach the maximum requested TLH size more quickly.</p>"},{"location":"allocation/#heap-configuration","title":"Heap configuration","text":"<p>Depending on the memory management strategy in force, the Java heap can be configured in a number of ways. The simplest configuration consists of a single area of memory, often referred to as a flat heap. Other configurations divide the heap into different areas or regions, which might contain objects of different ages (generations) or sizes.</p>"},{"location":"allocation/#area-based-heaps","title":"Area-based heaps","text":"<p>The default GC policy for OpenJ9 uses a heap configuration that is divided into two main areas: the nursery area for new object allocation, and the tenure area for objects that continue to be reachable for a longer period of time. Most objects have short lifecycles and can be reclaimed by the garbage collector more quickly by focusing only on the nursery area. Global GC cycles that cause application pauses in order to clear and defragment the tenure area are less frequent.</p>"},{"location":"allocation/#soa-and-loa","title":"SOA and LOA","text":"<p>All area-based heaps subdivide part of the heap into the Small Object Area (SOA) and the Large Object Area (LOA).</p> <p>The allocator initially attempts to allocate objects in the SOA, regardless of size. If the allocation cannot be satisfied the following actions are possible, depending on object size:</p> <ul> <li>If the object is smaller than 64 KB, an allocation failure occurs, which triggers a GC action.</li> <li>If the object is larger than 64 KB, the allocator attempts to allocate the object in the LOA. If the allocation cannot be satisfied, an allocation failure occurs, which triggers a GC action.</li> </ul> <p>The GC action that is triggered by the allocation failure depends on the GC policy in force.</p> <p>The overall size of the LOA is calculated when the heap is initialized, and recalculated at the end of each global GC cycle. The garbage collector can expand or contract the LOA, depending on usage, to avoid allocation failures.</p> <p>You can control the size of the LOA by using the <code>-Xloainitial</code>, <code>-Xloaminimum</code>, and <code>-Xloamaximum</code> command line options. If the LOA is not used, the garbage collector contracts the LOA after a few cycles, down to the value of <code>-Xloaminimum</code>. You can also specify <code>-Xnoloa</code> to prevent an LOA being created.</p> <p>An SOA and LOA are used by the OpenJ9 GC policies: <code>gencon</code>, <code>optavgpause</code>, and <code>optthruput</code>. For the <code>gencon</code> policy, the LOA and SOA are contained within the tenure area, which is designated for ageing objects. For more information about policies, see Garbage collection policies.</p>"},{"location":"allocation/#region-based-heaps","title":"Region-based heaps","text":"<p>The Java heap can also be subdivided into multiple regions. The <code>balanced</code> GC policy uses a heap that is divided into thousands of equal size regions in order to manage multiple generations of objects. The <code>metronome</code> GC policy also uses multiple regions, which are grouped by size-class to manage a singe generation of objects. To learn more about how the regions are configured for each policy, see Garbage collection policies.</p> <p>In addition to regions, the <code>balanced</code> and <code>metronome</code> policies use structures called arraylets to store large arrays in the heap.</p>"},{"location":"allocation/#arraylets","title":"Arraylets","text":"<p>A Java heap that is subdivided into regions might not be able to contain a large enough region for data arrays. This problem is solved by using arraylets. An arraylet has a spine, which contains the class pointer and size, and leaves, which contain the data associated with the array. The spine also contains arrayoids, which are pointers to the respective arraylet leaves, as shown in the following diagram.</p> <p></p> <p>There are a number of advantages to using arraylets.</p> <ul> <li> <p>Because the heap tends to fragment over time, some GC policies might be forced to run a global garbage collection and defragmentation (compaction) to recover sufficient contiguous memory to allocate a large array. By removing the requirement for large arrays to be allocated in contiguous memory, the garbage collector is more likely to be able to satisfy such an allocation without requiring unscheduled garbage collection, particularly a global defragmentation operation.</p> </li> <li> <p>Additionally, the garbage collector never needs to move an arraylet leaf once it has been allocated. The cost of relocating an array is therefore limited to the cost of relocating the spine, so large arrays do not contribute to higher defragmentation times.</p> </li> </ul> <p> Note: Despite the general advantage of using arraylets, they can slow down processing when the Java Native Interface (JNI) is being used. The JNI provides flexibility by enabling Java programs to call native code; for example, C or C++, and if direct addressability to the inside of an object is needed, a JNI critical section can be used. However, that requires the object to be in a contiguous region of memory, or at least appear to be so. The JNI, therefore, creates a temporary contiguous array that is the same size as the original array and copies everything, element by element, to the temporary array. After the JNI critical section is finished, everything is copied from the temporary array back to the arraylet, element by element.</p>"},{"location":"allocation/#heap-sizing","title":"Heap sizing","text":"<p>The overall size of the Java heap is determined by two command-line options, <code>-Xms</code>, which sets the initial size of the heap, and <code>-Xmx</code>, which sets the maximum size of the heap. Finer tuning of the heap depends on the heap configuration that is being used by a GC policy. For example, an LOA within the heap can be sized by using the <code>-Xloainitial</code>, <code>-Xloaminimum</code>, and <code>-Xloamaximum</code> command-line options. A nursery area within the heap can be sized by using the <code>-Xmn</code>, <code>-Xmns</code>, and <code>-Xmnx</code> command-line options. For more information about policies and the heap configurations that are used, see GC policies. To determine the values that are in use for the Java heap, use the <code>-verbose:sizes</code> option when you run your Java application.</p> <p>When the Java heap runs out of space, <code>OutOfMemoryError</code> exceptions are generated. If you are confident that your heap settings are appropriate for your application but are still receiving an <code>OutOfMemoryError</code> exception, check the Java dump file that gets automatically generated when the error occurs. A Java dump file can tell you more about what your application was attempting to do at the time of the error. For example, see the Java OutOfMemoryError scenario.</p>"},{"location":"allocation/#expansion-and-contraction","title":"Expansion and contraction","text":"<p>At startup, the VM allocates a single contiguous area of virtual storage to match the value of <code>-Xmx</code>. By default, this is 25% of the available memory up to a maximum of 25 GB. The actual Java heap size starts at the value set by <code>-Xms</code> and expands automatically, as required, up to the maximum heap size. The VM can also contract the size of the Java heap. Expansion and contraction occur as part of a GC cycle when the VM has exclusive access to the heap. The only GC policy that does not support heap expansion and contraction is the <code>metronome</code> GC policy, where the heap is always fully expanded.</p> <p> Note: On operating systems that support paging, the VM allocates a single contiguous area that matches the value of <code>-Xms</code>. Additional memory is committed as the heap expands by using the paging process.</p> <p>Expansion occurs to maintain free space on the Java heap for object allocation. By default, the heap is expanded to maintain 30% free space, but this proportion can be adjusted by setting one of the following command-line options:</p> <ul> <li><code>-Xminf</code> determines the minimum proportion of the heap that must be free after garbage is removed.</li> <li><code>-Xmaxf</code> determines the maximum proportion of the heap that must be free after garbage is removed.</li> </ul> <p>If expansion is required, the amount of memory that the heap can expand by is controlled by the following command-line options:</p> <ul> <li><code>-Xmine</code> sets the minimum amount that the heap can expand by.</li> <li><code>-Xmaxe</code> sets the maximum amount that the heap can expand by. The default is unlimited expansion up to the maximum heap size (<code>-Xmx</code>).</li> </ul> <p>Expansion can also be triggered if more time is being spent on GC processing than is specified by the <code>-Xmaxt</code> option. In this case, the heap expands by an amount that provides 17% more free space, within the limits imposed by the <code>-Xmine</code> and <code>-Xmaxe</code> values.</p> <p>Heap contraction occurs under certain conditions and might be preceded by heap compaction. If the last three GC cycles caused a heap expansion, contraction does not occur. Otherwise, contraction is triggered when the proportion of free heap space that is specified by the <code>-Xmaxf</code> option is reached. The amount of memory to reduce the heap by is calculated to the nearest 1024-byte boundary, down to the minimum size specified for the initial Java heap (<code>-Xms</code>). To prevent heap contraction, set the <code>-Xmaxf</code> value to <code>1</code>, which sets the maximum free space allowed on the heap to 100%.</p> <p>When the heap contracts, physical memory is not released unless paging is supported by the underlying operating system.</p>"},{"location":"allocation/#balanced-gc-policy","title":"<code>balanced</code> GC policy","text":"<p>For the <code>balanced</code> GC policy, if the <code>-Xminf</code>/<code>-Xmaxf</code> and/or <code>-Xmint</code>/<code>-Xmaxt</code> criteria are not being met and this results in a heap resize, then the heap resize that occurs, happens only on non-eden heap (similar to how these options apply to tenure part for gencon).</p> <p>The non-eden heap resizing occurs at the end of a GMP cycle, or global collection. At this point, heap resizing decision is made by observing both <code>-Xmint</code>/<code>-Xmaxt</code> and <code>-Xminf</code>/<code>-Xmaxf</code> and comparing them to the appropriate proportion of time spent in GC, and free heap respectively.</p> <p>If either <code>-Xmint</code>/<code>-Xmaxt</code> and/or <code>-Xminf</code>/<code>-Xmaxf</code> criteria are not being met, there is no guarantee that a heap resize will occur. The heap sizing logic is looking at the following two things:</p> <ul> <li>if % of time in GC pauses is between <code>-Xmint</code>/<code>-Xmaxt</code>. If it's greater than <code>-Xmaxt</code>, the VM will try to expand the heap, if it's less than <code>-Xmint</code>, then contract it.</li> <li>if % of free heap is between <code>-Xminf</code>/<code>-Xmaxf</code>. If it's too high, i.e. greater than <code>-Xmaxf</code>(too much free), heap size will contract, if too low, i.e. lesser than <code>-Xminf</code>, it will expand.</li> </ul> <p>Since these two criteria may be providing opposite recommendations (for example, lots of free memory, but high % of time in GC) causing oscillations in heap size, the <code>balanced</code> GC heap sizing logic finds a balance between these two criteria.</p>"},{"location":"allocation/#compressed-references","title":"Compressed references","text":"<p>On 64-bit systems, the VM can use compressed references to decrease the size of Java objects and make better use of the available space in the Java heap. By storing objects in a 32-bit representation, the object size is identical to that in a 32-bit VM, which creates a smaller memory footprint. These 4 byte (32-bit) compressed references are converted to 64-bit values at runtime with minimal overhead. Smaller objects enable larger heap sizes that result in less frequent garbage collection and improve memory cache utilization. Overall, the performance of 64-bit applications that store compressed rather than uncompressed 64-bit object references is significantly improved.</p> <p>Compressed references are used by default when the maximum Java heap size is in the range 0 - 57 GB on AIX\u00ae, Linux\u00ae, and Windows\u00ae systems. The upper limit is also 57 GB on z/OS\u00ae systems that have APAR OA49416 installed (25 GB without APAR OA49416). All GC policies observe these limits except for the <code>metronome</code> policy, which can support a heap size of up to 25 GB only with compressed references.</p> <p>When the VM uses compressed references, classes, threads, and monitors are stored in the lowest 4 GB of address space. However, this area of memory is also used by native libraries, the operating system, and for small Java heaps. If you receive native memory <code>OutOfMemoryError</code> exceptions in the lowest 4 GB when running with compressed references enabled, these errors might result from the lowest 4 GB of address space becoming full. Try specifying a large heap with the <code>-Xmx</code> option, which puts the Java heap into a higher area of address space or using the <code>-Xmcrs</code> option to reserve space in the lowest 4 GB of address space for compressed references.</p> <p>To turn off compressed references, use the <code>-Xnocompressedrefs</code> command-line option.</p>"},{"location":"aot/","title":"AOT Compiler","text":""},{"location":"aot/#ahead-of-time-aot-compiler","title":"Ahead-Of-Time (AOT) compiler","text":"<p>The AOT compiler dynamically compiles Java methods into native AOT code at runtime and stores them in the shared classes cache. This activity enables the VM to start an application faster the next time it runs because it doesn't need to spend time interpreting Java methods. The VM automatically chooses which methods should be AOT-compiled based on heuristics that identify the start-up phase of large applications. AOT code is always used in combination with class data sharing and is enabled automatically when <code>-Xshareclasses</code> is set on the command line. When a cached AOT method is run it might also be optimized further by the Just-In-Time (JIT) compiler.</p> <p>If you want to turn off AOT compilation and disable the use of AOT-compiled code, set the <code>-Xnoaot</code> suboption. When the AOT compiler is disabled, the JIT compiles frequently used methods into native code. However, because the JIT compiler operates while the application is running, the startup time for an application will increase.</p>"},{"location":"aot/#see-also","title":"See also","text":"<ul> <li>Diagnosing a JIT or AOT problem</li> <li>JIT compiler</li> <li>Introduction to class data sharing</li> </ul>"},{"location":"api-conditionhandling/","title":"Condition exception handling","text":""},{"location":"api-conditionhandling/#condition-handling-api-documentation","title":"Condition Handling API documentation","text":""},{"location":"api-cuda/","title":"CUDA4J","text":""},{"location":"api-cuda/#cuda4j-api-documentation","title":"CUDA4J API documentation","text":""},{"location":"api-daa/","title":"Data access acceleration","text":""},{"location":"api-daa/#data-access-acceleration-api-documentation","title":"Data access acceleration API documentation","text":""},{"location":"api-dtfj/","title":"DTFJ","text":""},{"location":"api-dtfj/#dtfj-api-documentation","title":"DTFJ API documentation","text":""},{"location":"api-gpu/","title":"GPU","text":""},{"location":"api-gpu/#gpu-api-documentation","title":"GPU API documentation","text":""},{"location":"api-jdk11/","title":"Java 11 API","text":""},{"location":"api-jdk11/#openj9-jdk-11-api-documentation","title":"OpenJ9 JDK 11 API documentation","text":""},{"location":"api-jdk17/","title":"Java 17 API","text":""},{"location":"api-jdk17/#openj9-jdk-17-api-documentation","title":"OpenJ9 JDK 17 API documentation","text":""},{"location":"api-jdk21/","title":"Java 21 API","text":""},{"location":"api-jdk21/#openj9-jdk-21-api-documentation","title":"OpenJ9 JDK 21 API documentation","text":""},{"location":"api-jvm/","title":"JVM diagnostic utilities","text":""},{"location":"api-jvm/#jvm-diagnostic-utilities-api-documentation","title":"JVM diagnostic utilities API documentation","text":""},{"location":"api-langmgmt/","title":"Monitoring and management","text":""},{"location":"api-langmgmt/#monitoring-and-management-api-documentation","title":"Monitoring and management API documentation","text":""},{"location":"api-overview/","title":"Overview","text":""},{"location":"api-overview/#api-documentation","title":"API documentation","text":"<p>The Eclipse OpenJ9\u2122 VM provides supplementary application programming interfaces and extensions, which can be used to improve performance, assist with problem determination, or help monitor and manage the OpenJ9 VM. The documentation also includes links to the API documentation for the Java\u2122 SE and JDK reference implementation.</p>"},{"location":"api-overview/#native-data-operations","title":"Native data operations","text":"<p>If your Java application manipulates native data, the Data Access Accelerator API package (<code>com.ibm.dataaccess</code>) can help improve application performance. Classes are available for the following types of operation:</p> <ul> <li>performing arithmetic, comparison, and validation of packed decimal data</li> <li>converting between decimal data types as well as to and from <code>BigDecimal</code> and <code>BigInteger</code> types</li> <li>marshalling Java binary types to and from byte arrays</li> </ul>"},{"location":"api-overview/#gpu-acceleration","title":"GPU acceleration","text":"<p>You can improve the performance of your applications by offloading certain processing functions from your processor (CPU) to a graphics processing unit (GPU). If your application contains code that would benefit from parallel processing, you can use the CUDA4J API package (<code>com.ibm.cuda</code>) to specify in your code when to offload processing to the GPU. You can also use the GPU API package (<code>com.ibm.gpu</code>)  to accelerate certain Java functions, such as <code>sort</code> operations.</p>"},{"location":"api-overview/#problem-determination","title":"Problem determination","text":"<p>The JVM diagnostic utilities API package (<code>com.ibm.jvm</code>) provides classes for controlling dump, log, and trace operations.</p> <p>The Diagnostic Tool Framework for Java (DTFJ) API packages (<code>com.ibm.dtfj.*</code>) allow custom applications to be written that can access a wide range of information in a system dump or a Java dump.</p>"},{"location":"api-overview/#monitoring-and-management","title":"Monitoring and management","text":"<p>The shared classes API package (<code>com.ibm.oti.shared</code>) provides a large number of classes for managing permissions, finding and storing classes and byte data, and obtaining statistics about a shared classes cache. Classes are also available to enable class sharing for a custom class loader implementation.</p> <p>OpenJ9 includes MXBean extensions to the <code>java.lang.management</code> API (<code>com.ibm.lang.management</code> and <code>openj9.lang.management</code>), which can be used to monitor and manage the VM. These extensions provide access to information about the state of the OpenJ9 VM and the environment in which it is running.</p>"},{"location":"api-shrc/","title":"Shared classes","text":""},{"location":"api-shrc/#shared-classes-api-documentation","title":"Shared classes API documentation","text":""},{"location":"attachapi/","title":"Java Attach API","text":""},{"location":"attachapi/#java-attach-api","title":"Java Attach API","text":"<p>With the Attach API, your application can connect to a running VM and load an agent into that VM to run tasks. The typical use case for this feature is to load an agent that can be used to monitor the application that's running in the target VM.</p> <p>For example, if you wanted to start monitoring an application that is already running with the Attach API enabled, you could use a tool such as the IBM Health Center. In this case, a Health Center agent can start in its own VM and attach to the target VM where the application is running to start recording and sending data to the Health Center client.</p> <p>The Eclipse OpenJ9\u2122 implementation of the Attach API is equivalent to the reference implementation (API documentation is available on the Oracle website). However, you can use the Attach API only to connect to another OpenJ9 VM.</p> <p>When you run a Java\u2122 application, VM support for the Attach API is enabled by default on all platforms except z/OS\u00ae. For security reasons on z/OS, processes that use the default z/OS OMVS segment cannot enable the Attach API.</p> <p>To enable or disable the Attach API, use the <code>-Dcom.ibm.tools.attach.enable=[yes|no]</code> command line option.</p>"},{"location":"attachapi/#securing-the-attach-api","title":"Securing the Attach API","text":"<p>Because the Attach API can be used to connect to a running application, you must control access to it to ensure that only authorized users or processes can use it. Disable the Attach API if you do not intend to use it.</p> <p>If you do not want to disable the Attach API but want to control the unauthorized dynamic loading of agents into the VM by using the Attach API, use the <code>-XX:-EnableDynamicAgentLoading</code> option.</p> <p>On Windows systems, the Attach API uses the system temporary directory, which is typically <code>C:\\Users\\&lt;USERNAME&gt;\\AppData\\Local\\Temp</code>. The Attach API creates a common subdirectory, which is <code>.com_ibm_tools_attach</code> by default. Because files and directories in the system temporary directory are handled by Windows security, only the process owner can connect to their processes.</p> <p>On UNIX systems, the Attach API uses <code>/tmp</code> and creates a common subdirectory, which is <code>.com_ibm_tools_attach</code> by default. The common subdirectory must be on a local drive, not a network drive. Security is handled by POSIX file permissions. The Attach API directory must be owned by <code>root</code> user and must have read, write, and execute file permissions for <code>user</code>, <code>group</code>, and <code>other</code> (<code>drwxrwxrwx</code>). The sticky bit is set so that only the owner and <code>root</code> can delete or rename files or directories within it. A process that uses the Java Attach API must be owned by the same UNIX user ID as the target process.</p> <pre><code>~/tmp $ ls -al\ntotal 0\ndrwxr-xr-x   3 user_a staff    96  6 Aug 17:11 .\ndrwxr-xr-x+ 89 user_a staff  2848  6 Aug 17:11 ..\ndrwxrwxrwx+  7 root   staff   224  6 Aug 17:22 .com_ibm_tools_attach\n</code></pre> <p>In the default Attach API directory you can find certain files that start with an underscore <code>_*</code>, which are involved in synchronization. These files can be owned by any user but must have read and write permissions set. The files are empty and are automatically re-created if deleted. When your application attaches to a VM, a process directory is created.</p> <pre><code>~/tmp/.com_ibm_tools_attach $ ls -l\ntotal 3\n-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _attach_lock\n-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _controller\n-rw-rw-rw-  1 user_a  staff    0  6 Aug 17:12 _notifier\ndrwx--x--x  6 user_b  staff  192  6 Aug 17:21 process_a\n</code></pre> <p>The files in the subdirectory for a process, with the exception of a lock file, are accessible only by the owner of a process. The permissions for these files are <code>rwxr-xr-x</code> with the exception of the <code>attachNotificationSync</code> file, as shown in the following example.</p> <pre><code>~/tmp/.com_ibm_tools_attach/process_a $ ls -l\ntotal 4\n-rwxrw-rw-  1 user_b  staff  0  6 Aug 17:18 attachNotificationSync\n-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_a\n-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_b\n-rwxr-xr-x  1 user_b  staff  0  6 Aug 17:21 file_c\n</code></pre> <p>Notes for z/OS:</p> <ul> <li>z/OS systems must also set POSIX permissions on files and cannot rely on RACF\u00ae or system level security to protect applications.</li> <li>To avoid z/OS console messages reporting security violations in <code>/tmp</code>, add a security exception or specify a different common subdirectory by setting the <code>com.ibm.tools.attach.directory</code> system property.</li> </ul>"},{"location":"attachapi/#configuring","title":"Configuring","text":"<p>A number of system properties are available to configure the Attach API when you start a Java application, as shown in the following table:</p> System property Description <code>-Dcom.ibm.tools.attach.directory=&lt;directory_name&gt;</code> Specify a different common directory for Attach API working files. <code>-Dcom.ibm.tools.attach.displayName=&lt;my_display_name&gt;</code> Change the display name recorded by an agent <code>-Dcom.ibm.tools.attach.id=&lt;my_vm_ID&gt;</code> Change the VM identifier recorded by an agent <code>-Dcom.ibm.tools.attach.timeout=&lt;value_in_milliseconds&gt;</code> Change the connection timeout <code>-Dcom.ibm.tools.attach.shutdown_timeout=&lt;value_in_milliseconds&gt;</code> Specify the timeout for ending the Attach API wait loop thread <code>-Dcom.ibm.tools.attach.command_timeout=&lt;value_in_milliseconds&gt;</code> Specify the timeout for sending a command to the target VM after initial attachment <p>To learn more about each property, click the link in the table.</p>"},{"location":"attachapi/#troubleshooting","title":"Troubleshooting","text":"<p>Problems with the Attach API generate one of the following exceptions:</p> <ul> <li><code>com.sun.tools.attach.AgentLoadException</code></li> <li><code>com.sun.tools.attach.AgentInitializationException</code></li> <li><code>com.sun.tools.attach.AgentNotSupportedException</code></li> <li><code>com.sun.tools.attach.AttachOperationFailedException</code></li> <li><code>java.io.IOException</code></li> </ul> <p>Exceptions from agents on the target VM go to <code>stderr</code> or <code>stdout</code> for the target VM. These exceptions are not reported in the output of the attaching VM.</p> <p>Here are some problems that you might encounter:</p> <ul> <li>On Unix systems, the file permissions are incorrectly set, causing access issues. Resolve these issues by reading and complying with Securing the Attach API. Also check that the Attach API is not disabled.</li> <li>The common directory is deleted, the contents of the common directory are deleted, or permissions of the common directory or subdirectories are changed. As a result, the source VM might not be able list target VMs or attach to them. Deletion of the common directory can also cause semaphore leaks.</li> <li>The system temporary directory is full or inaccessible and the Attach API cannot initialize. Try specifying a different directory in which to create the common subdirectory by using the <code>-Dcom.ibm.tools.attach.directory</code> system property.</li> <li>A short delay between the start of the target VM and the initialization of the Attach API process can cause an <code>AttachNotSupportedException: No provider for virtual machine id</code> issue when the <code>VirtualMachine.attach(String id)</code> method is called.</li> <li>The target process is overloaded, suspended, or no longer running, or the port that is used to connect to the target is subject to a wait time (use the <code>netstat -a</code> command to check for ports in the <code>TIME_WAIT</code> state). These situations can cause an <code>AttachNotSupportedException</code> when the <code>attach</code> method is called.</li> <li>A JVMTI agent is corrupt or attempts to run an operation that is not available after the VM starts. These situations can cause an <code>AgentLoadException</code> or <code>AgentInitializationException</code> when one of the following methods is called: <code>loadAgent()</code>, <code>loadAgentLibrary()</code>, or <code>loadAgentPath()</code>. Depending on the method invoked, try loading the agent at VM startup by using one of the following command-line options <code>-javaagent</code>, <code>-agentlib</code>, or <code>-agentpath</code>. For more information about these options, see Java Virtual Machine Tool Interface.</li> </ul> <p>If you have checked for these potential issues but you are still experiencing problems, a number of command line system properties are available to help narrow down the cause. These options are shown in the following table:</p> System property Description <code>-Dcom.ibm.tools.attach.logging=&lt;yes|no&gt;</code> Turn on tracing of attach API events <code>-Dcom.ibm.tools.attach.log.name=&lt;my_log_name&gt;</code> Specify the path and prefix for the log files <p>To learn more about each property, click the link in the table.</p>"},{"location":"builds/","title":"OpenJ9 builds","text":""},{"location":"builds/#eclipse-openj9-builds","title":"Eclipse OpenJ9 builds","text":"<p>Eclipse Foundation projects are not permitted to distribute, market or promote JDK binaries unless they have passed a Java SE Technology Compatibility Kit licensed from Oracle, to which the Eclipse OpenJ9\u2122 project does not currently have access. See the Eclipse Adoptium Project Charter.</p>"},{"location":"builds/#supported-platforms","title":"Supported platforms","text":"<p>The community develops and maintains a test infrastructure for the OpenJ9 source across a broad range of platforms. For information about the platforms and minimum operating system levels supported, see the Platform support matrix.</p>"},{"location":"builds/#building-your-own-binaries","title":"Building your own binaries","text":"<p>If you want to build your own binaries of OpenJDK with OpenJ9, a complete set of build instructions for several platforms can be found in the OpenJ9 GitHub repository.  </p>"},{"location":"builds/#installation-pre-requisites","title":"Installation pre-requisites","text":"<p>Note the following:</p> <ul> <li>For the best performance, OpenSSL support should be enabled in the build. In builds that aren't configured with <code>--enable-openssl-bundling</code>, the OpenSSL library is expected to be found on the system path. If you want to use OpenSSL cryptographic acceleration, you must install OpenSSL 1.0.2, 1.1.x, or 3.x on your system. If the library is not found on the system path, the in-built Java crytographic implementation is used instead, which performs less well.</li> <li> On Linux systems, the <code>fontconfig.x86_64</code> package should be installed to avoid a <code>NullPointerException</code> error when the AWT font subsystem is initialized.</li> <li>From Eclipse OpenJ9 release 0.16.0 (OpenJDK 13) and release 0.17.0 (OpenJDK 8 and 11), CUDA is now enabled on Windows (x86-64) and Linux (x86-64 and IBM POWER LE) platforms, which allows you to offload certain Java application processing tasks to a general purpose graphics processing unit (GPU). To take advantage of this feature, your system must support NVIDIA Compute Unified Device Architecture (CUDA). The JIT requires the CUDA Toolkit 7.5 and your GPU device must have a minimum compute capability of 3.0.</li> </ul>"},{"location":"cmdline_general/","title":"Standard options","text":""},{"location":"cmdline_general/#standard-command-line-options","title":"Standard command-line options","text":"<p>The Eclipse OpenJ9\u2122 virtual machine supports the standard Java\u2122 options that are common to all Java virtual machine implementations, including Oracle's HotSpot VM. Some of the common options supported are summarised in the following table:</p> Standard option name Purpose <code>-classpath:&lt;resource_name&gt;[:&lt;resource_name&gt;]</code> Sets the search path for application classes and resources (directories and compressed or .jar files). <code>cp</code> can be used instead of <code>classpath</code>. <code>-help</code>, <code>-?</code> Prints a usage message. <code>-fullversion</code> Prints the build and version information for a VM <code>-showversion</code> Prints product version and continues. <code>-verbose:&lt;option&gt;[,&lt;option&gt;]</code> Enables verbose output. Options include <code>class</code>, <code>dynload</code>, <code>gc</code>, <code>init</code>, <code>jni</code>, <code>sizes</code>, <code>stack</code>, and <code>module</code>. (See Notes) <code>-version</code> Prints the full build and version information a VM <p> Notes:</p> <ul> <li><code>-verbose:class</code>: Writes an entry to <code>stderr</code> for each class that is loaded.</li> <li><code>-verbose:dynload</code>: Writes detailed class information to <code>stderr</code> as each bootstrap class is loaded by the VM:</li> <li><code>-verbose:gc</code>: Provides verbose garbage collection information.</li> <li><code>-verbose:init</code>: Writes information to <code>stderr</code> describing VM initialization and termination.</li> <li><code>-verbose:jni</code>: Writes information to <code>stderr</code> describing the JNI services called by the application and VM.</li> <li><code>-verbose:sizes</code>: Writes information to <code>stderr</code> describing the active memory usage settings.</li> <li><code>-verbose:stack</code>: Writes information to <code>stderr</code> describing the Java and C stack usage for each thread.</li> <li><code>-verbose:module</code>:  Writes information to <code>stderr</code> for each module that is loaded and unloaded.</li> </ul> <p>For more information about standard options, see Oracle Java SE Standard Options</p>"},{"location":"cmdline_general/#openj9-extensions","title":"OpenJ9 extensions","text":"<p>OpenJ9 supports the following extension to the <code>-verbose</code> option:</p> <ul> <li><code>-verbose:stacktrace</code> : Writes either the module name or the <code>Classloader</code> name (with the code source location when available) to the end of each line of a Java stack trace.</li> </ul>"},{"location":"cmdline_migration/","title":"Switching to OpenJ9","text":""},{"location":"cmdline_migration/#switching-to-eclipse-openj9","title":"Switching to Eclipse OpenJ9","text":"<p>If you are already familiar with HotSpot command-line options but want the advantages of Eclipse OpenJ9\u2122, the following information will prove helpful. In all cases, check individual topics for minor discrepancies in the way these options might work.</p> <p> Note: For information about HotSpot equivalences and differences for items other than command-line options, see New to Eclipse OpenJ9?</p>"},{"location":"cmdline_migration/#compatible-options","title":"Compatible options","text":"<p>You can use the following command-line options in OpenJ9, just as you did in HotSpot; you can continue to use the HotSpot option in OpenJ9 without having to change your code:</p> Option Usage <code>-X</code> Displays help on nonstandard options. <code>-Xbootclasspath</code> Specifies the search path for bootstrap classes and resources. <code>-Xcheck:jni</code> Runs additional checks for JNI functions during VM startup. <code>-Xfuture</code> Turns on strict class-file format checks. <code>-Xint</code> Runs an application in interpreted-only mode. <code>-Xlog</code> Some forms of <code>-Xlog</code> that enable garbage collection logging are recognized. (Equivalent to <code>-Xverbosegclog</code>). <code>-Xmn</code> Sets the initial and maximum size of the new area when using -Xgcpolicy:gencon. <code>-Xms</code> Sets the initial size of the heap. (Equivalent to <code>-XX:InitialHeapSize</code>) <code>-Xmx</code> Specifies the maximum size of the object memory allocation pool. (Equivalent to <code>-XX:MaxHeapSize</code>) <code>-Xnoclassgc</code> Disables class garbage collection (GC). <code>-Xrs</code> Prevents the OpenJ9 run time environment from handling signals. <code>-Xss</code> Sets the Java\u2122 thread stack size. (Equivalent to <code>-XX:ThreadStackSize</code>).  Note: Unlike HotSpot, this option applies only to the Java stack. OpenJ9 has a separate native stack for operating system threads (see <code>-Xmso</code>) <code>-Xverify:mode</code> Enables or disables the verifier. <code>-XX:ConcGCThreads</code> Configures the number of GC mutator background threads. <code>-XX:[+|-]AlwaysPreTouch</code> Enables/disables committing of memory during initial heap inflation or heap expansion. <code>-XX:[+|-]CompactStrings</code> Enables/disables <code>String</code> compression. Note: This option is enabled by default in OpenJ9 on Java 11 and later. In the earlier versions, this option is disabled by default. <code>-XX:DiagnoseSyncOnValueBasedClasses=&lt;number&gt;</code> Configure warnings for value-based classes. <code>-XX:[+|-]DisableExplicitGC</code> Enables/disables explicit <code>System.gc()</code> calls. (Alias for <code>-Xdisableexplicitgc</code> / <code>-Xenableexplicitgc</code>) <code>-XX:[+|-]ExitOnOutOfMemoryError</code> Triggers VM shutdown on out-of-memory conditions. <code>-XX:[+|-]HeapDumpOnOutOfMemory</code> Enables/disables dumps on out-of-memory conditions. <code>-XX:HeapDumpPath</code> Specifies a directory for all VM dumps including heap dumps, javacores, and system dumps. (Alias for <code>-Xdump:directory</code>) <code>-XX:[+|-]IgnoreUnrecognizedVMOptions</code> Specifies whether to ignore unrecognized top-level VM options. <code>-XX:InitialHeapSize</code> Sets the initial size of the heap. (Alias for <code>-Xms</code>) <code>-XX:InitialRAMPercentage</code> Sets the initial size of the Java heap as a percentage of total memory. <code>-XX:MaxDirectMemorySize</code> Sets a limit on the amount of memory that can be reserved for all direct byte buffers. <code>-XX:MaxHeapSize</code> Specifies the maximum size of the object memory allocation pool. (Alias for <code>-Xmx</code>) <code>-XX:MaxRAMPercentage</code> Sets the maximum size of the Java heap as a percentage of total memory. <code>-XX:OnOutOfMemoryError</code> Runs specified commands when a <code>java.lang.OutOfMemoryError</code> is thrown. (Equivalent to <code>-Xdump:tool:events=systhrow,filter=java/lang/OutOfMemoryError,exec=</code>) <code>-XX:ParallelCMSThreads</code> Configures the number of GC mutator background threads. <code>-XX:ParallelGCThreads</code> Configures the number of GC threads. <code>-XX:[+|-]PrintCodeCache</code> Prints code cache usage when the application exits. <code>-XX:[+|-]ShowHiddenFrames</code> Specifies whether generated hidden <code>MethodHandle</code> frames are displayed in a stack trace.  Note: Unlike HotSpot, this option doesn't require the <code>+UnlockDiagnosticVMOptions</code> option. <code>-XX:[+|-]UseCompressedOops</code> Disables compressed references in 64-bit JVMs. (See also <code>-Xcompressedrefs</code>) <code>-XX:[+|-]UseContainerSupport</code> Sets a larger fraction of memory to the Java heap when the VM detects that it is running in a container."},{"location":"cmdline_migration/#equivalent-options","title":"Equivalent options","text":"<p>These HotSpot command-line options have equivalents in OpenJ9 that are not specified in the same way, but perform a related function:</p> HotSpot Option OpenJ9 Option Usage <code>-Xcomp</code> <code>-Xjit:count=0</code><sup>1</sup> <code>-Xcomp</code> disables interpreted method invocations. <code>-Xgc</code> <code>-Xgcpolicy</code><sup>2</sup> Configuring your garbage collection policy. <code>-XX:+UseNUMA</code> <code>-Xnuma:none</code><sup>3</sup> Controls non-uniform memory architecture (NUMA) awareness. <p> Notes:</p> <ol> <li> <p>HotSpot uses <code>-Xcomp</code> to force compilation of methods on first invocation. However, this option is deprecated. Whilst it can be used for compatibility, using <code>-Xjit:count=0</code> is preferred.</p> </li> <li> <p>HotSpot uses <code>-Xgc</code> to both select policies and configure them; OpenJ9 uses <code>-Xgcpolicy</code> to select policies, reserving <code>-Xgc</code> for configuration.</p> </li> <li> <p>In HotSpot, NUMA awareness is turned off by default and is turned on by using the <code>-XX:+UseNUMA</code> option. Conversely, the OpenJ9 VM automatically enables NUMA awareness and uses <code>-Xnuma:none</code> to turn it off.</p> <ul> <li>If you were previously using HotSpot in its default mode, you must now explicitly turn off NUMA awareness in OpenJ9.</li> <li>If you are used to using <code>-XX:+UseNUMA</code> in HotSpot, you no longer need to explicitly turn on NUMA awareness; it's on by default.</li> </ul> </li> </ol>"},{"location":"cmdline_migration/#creating-compatible-behavior","title":"Creating compatible behavior","text":"<p>You can set the following options to make OpenJ9 behave in the same way as HotSpot.</p> Option Usage <code>-Djava.lang.string.substring.nocopy=true</code> Avoid String sharing by <code>String.substring()</code>. <code>-Xnuma:none</code> Disable non-uniform memory architecture (NUMA) awareness. <code>-XX:+CompactStrings</code> Enables <code>String</code> compression. <code>-XX:[+|-]HandleSIGABRT</code> Force handling of SIGABRT signals to be compatible with HotSpot."},{"location":"cmdline_migration/#compatible-environment-variables","title":"Compatible environment variables","text":"<p>The <code>JAVA_TOOL_OPTIONS</code> environment variable can be used to set command line options as described in OpenJ9 command-line options and Environment variables.</p>"},{"location":"cmdline_specifying/","title":"Specifying options","text":""},{"location":"cmdline_specifying/#eclipse-openj9-command-line-options","title":"Eclipse OpenJ9 command-line options","text":"<p>When you start a Java\u2122 application you can specify various options on the command line to configure the runtime environment. These options include:</p> <ul> <li>System properties</li> <li>Standard options</li> <li>Nonstandard (or -X) options</li> <li>-XX options</li> </ul> <p>Although the command line is the traditional way to specify command-line options, you can also pass options to the Eclipse OpenJ9\u2122 virtual machine (VM) by using a manifest file, options files, and environment variables.</p> <p>Options specified on the command line override the equivalent environment variables. For example, specifying <code>java -cp &lt;dir1&gt;</code> completely overrides setting the environment variable <code>CLASSPATH=&lt;dir2&gt;</code>.</p>"},{"location":"cmdline_specifying/#quotation-marks","title":"Quotation marks","text":"<p>Use single or double quotation marks for command-line options only when explicitly directed to do so. Single and double quotation marks have different meanings on different platforms, operating systems, and shells. Do not use <code>'-X&lt;option&gt;'</code> or <code>\"-X&lt;option&gt;\"</code>. Instead, you must use <code>-X&lt;option&gt;</code>. For example, do not use <code>'-Xmx500m'</code> and <code>\"-Xmx500m\"</code>. Write this option as <code>-Xmx500m</code>.</p>"},{"location":"cmdline_specifying/#precedence","title":"Precedence","text":"<p>The sequence of the Java options on the command line defines which options take precedence during startup. Rightmost options have precedence over leftmost options. In the following example, the <code>-Xjit</code> option takes precedence:</p> <pre><code>java -Xint -Xjit myClass\n</code></pre> <p>At startup, the list of VM arguments is constructed in the following order, with the lowest precedence first:</p> <ol> <li> <p>Certain options are created automatically by the VM, which specify arguments such as search paths and version information. The VM automatically adds <code>-Xoptionsfile=&lt;path&gt;/options.default</code> at the beginning of the command line, where <code>&lt;path&gt;</code> is the path to the VM directory.</p> <p>You can modify the <code>options.default</code> file to include any options that you want to specify for your application instead of entering these options on the command line. For more information about the path and construction of the file, see -Xoptionsfile.</p> </li> <li> <p>Options can be specified in an executable JAR file by using the META-INF/MANIFEST.MF file. Options are placed in the main section in a header named <code>IBM-Java-Options</code>. Only one <code>IBM-Java-Options</code> header is permitted, but the header can contain multiple options, separated by spaces. A long sequence of options can be split using a header continuation but are treated as a single line.</p> <p>Example manifest file:</p> <pre><code>Manifest-Version: 1.0\nClass-Path: .\nMain-Class: HelloWorld\nIBM-Java-Options: -Xshareclasses:name=mycache,nonfa\n tal,cacheDirPerm=1000 -Dproperty=example -Da.long.system.pro\n perty=\"this is a long system property value to\n  demonstrate long VM arguments\n in the manifest file\"\n</code></pre> <p>This example manifest file is parsed as the following string:</p> <pre><code>-Xshareclasses:name=mycache,nonfatal,cacheDirPerm=1000\n-Dproperty=example\n-Da.long.system.property=this is a long system property value to\ndemonstrate long VM arguments in the manifest file\n</code></pre> <p>Options specified in the manifest file are subject to the same restrictions as options files. For more information, see the -Xoptionsfile topic in the user guide.</p> </li> <li> <p>Environment variables that are described in OpenJ9 environment variables are translated into command-line options. For example, the following environment variable adds the parameter <code>-Xrs</code> to the list of arguments:</p> <ul> <li> <p>On Windows\u2122 systems:</p> <pre><code>set IBM_NOSIGHANDLER=&lt;non_null_string&gt;\n</code></pre> </li> <li> <p>On AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae systems:</p> <pre><code>export IBM_NOSIGHANDLER=&lt;non_null_string&gt;\n</code></pre> </li> </ul> </li> <li> <p>The <code>OPENJ9_JAVA_OPTIONS</code> environment variable. You can set command-line options using this environment variable. The options that you specify with this environment variable are added to the command line when a VM starts in that environment. The environment variable can contain multiple blank-delimited argument strings, but must not contain comments. For example:</p> <ul> <li> <p>On Windows systems:</p> <pre><code>set OPENJ9_JAVA_OPTIONS=-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\n</code></pre> </li> <li> <p>On AIX, Linux, macOS, and z/OS systems:</p> <pre><code>export OPENJ9_JAVA_OPTIONS=\"-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\"\n</code></pre> </li> </ul> <p> Note: The environment variable <code>JAVA_TOOL_OPTIONS</code> is equivalent to <code>OPENJ9_JAVA_OPTIONS</code> and is available for compatibility with JVMTI. The equivalent <code>IBM_JAVA_OPTIONS</code> environment variable is deprecated and will be removed in a future release.</p> </li> <li> <p>Options that are specified on the command line. For example:</p> <pre><code>java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass\n</code></pre> <p>The Java launcher adds some automatically generated arguments to this list, such as the names of the main class.</p> </li> <li> <p>The <code>_JAVA_OPTIONS</code> environment variable. You can override previous options using this environment variable. The options that you specify with this environment variable are added to the end of the command line when a VM starts in that environment. The environment variable can contain multiple blank-delimited argument strings, but must not contain comments. For example:</p> <ul> <li> <p>On Windows systems:</p> <pre><code>set _JAVA_OPTIONS=-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\n</code></pre> </li> <li> <p>On AIX, Linux, macOS, and z/OS systems:</p> <pre><code>export _JAVA_OPTIONS=\"-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump\"\n</code></pre> </li> </ul> </li> </ol> <p>You can also use the <code>-Xoptionsfile</code> parameter to specify VM options. This parameter can be used on the command line, or as part of the <code>OPENJ9_JAVA_OPTIONS</code> environment variable. The contents of an option file are expanded in place during startup. For more information about the structure and contents of this type of file, see -Xoptionsfile.</p> <p>To troubleshoot startup problems, you can check which options are used by the OpenJ9 VM. Append the following command-line option, and inspect the Java core file that is generated:</p> <pre><code>-Xdump:java:events=vmstart\n</code></pre> <p>Here is an extract from a Java core file that shows the options that are used:</p> <pre><code>    2CIUSERARG               -Xdump:java:file=/home/test_javacore.txt,events=vmstop\n    2CIUSERARG               -Dtest.cmdlineOption=1\n    2CIUSERARG               -XXallowvmshutdown:true\n    2CIUSERARG               -Xoptionsfile=test1.test_options_file\n</code></pre>"},{"location":"configuring/","title":"Configuring your system","text":""},{"location":"configuring/#configuring-your-system","title":"Configuring your system","text":"<p>Configuring your local system can help you optimize the runtime environment for your Java application. Options include setting operating system environment variables and configuring system resources so that Eclipse OpenJ9\u2122 can exploit the underlying operating system and hardware capabilities.</p> <p>When you install a Java\u2122 runtime environment on your system you can set the PATH environment variable so that the operating system can find the Java programs and utilities to run your application. To tell your application where to find user classes, you can use the -cp option or set the CLASSPATH environment variable. However, if you set CLASSPATH globally, all invocations of Java are affected. How to set these environment variables is covered in many publications about Java, such as The Java Tutorials: PATH and CLASSPATH.</p> <p>On some systems, a further environment variable might be required if your application requires shared libraries but does not specify their exact location. You can set the following environment variables to specify the directory location of the shared libraries, although setting a global value affects all invocations of Java:</p> <ul> <li>LIBPATH (AIX\u00ae and z/OS\u00ae)</li> <li>LD_LIBRARY_PATH (Linux\u00ae)</li> <li>DYLD_LIBRARY_PATH (macOS\u00ae)</li> <li>PATH (Windows\u00ae)</li> </ul> <p> Although most Java applications should run without changing anything on the underlying system, a unique pre-requisite exists for AIX systems on OpenJDK version 11 and later; you must have the 16.1 XL C++ Runtime installed. </p>"},{"location":"configuring/#setting-resource-limits-aix-linux-and-macos","title":"Setting resource limits (AIX, Linux, and macOS)","text":"<p>The operating system sets resource limits for a shell, and to processes started by the shell, to ensure that a single process cannot consume all available resources. However, these limits can affect certain operations that might need to run for a Java application, such as producing a dump file.</p>"},{"location":"configuring/#setting-ulimit-values","title":"Setting ulimit values","text":"<p>Some resource limits are controlled by the ulimit command. A soft limit is the value set by the kernel for a resource and a hard limit imposes a maximum value on the soft limit. A privileged process can change either limit, but an unprivileged process can change only its soft limit (between 0 and the hard limit) or irreversibly lower its hard limit. To see the current limits set for a system, run <code>ulimit -a</code>. The output is similar to the following example:</p> <pre><code>core file size          (blocks, -c) 0\ndata seg size           (kbytes, -d) unlimited\nfile size               (blocks, -f) unlimited\nmax locked memory       (kbytes, -l) unlimited\nmax memory size         (kbytes, -m) unlimited\nopen files                      (-n) 256\npipe size            (512 bytes, -p) 1\nstack size              (kbytes, -s) 8192\ncpu time               (seconds, -t) unlimited\nmax user processes              (-u) 2784\nvirtual memory          (kbytes, -v) unlimited\n</code></pre> <p>To show hard limits, use <code>ulimit -Ha</code>.</p> <p>You can change limits for specific resources on a temporary basis by running the ulimit command. Alternatively, you can store limit settings in a configuration file, which is <code>/etc/security/limits</code> for AIX or <code>etc/security/limits.conf</code> for Linux. For more information about configuring resource limits, refer to the documentation for your operating system.   </p> <p>The main use case for changing <code>ulimit</code> resources is when enabling a system dump to ensure that all the required data can be collected for analysis. For more information, see Enabling a full system dump.</p>"},{"location":"configuring/#setting-shared-memory-values","title":"Setting shared memory values","text":"<p>Another use case for changing resource limits is to ensure that there is sufficient shared memory allocated for class data sharing. By default, the shared classes cache consists of memory-mapped files that are created on disk and persist when the system is restarted. If you choose to use non-persistent caches by setting the <code>-Xshareclasses:nonpersistent</code> option, caches are not retained on startup and are allocated by using the System V IPC shared memory mechanism.</p> <ul> <li>On AIX systems, the kernel dynamically adjusts the shared memory settings as required. No special configuration is required.</li> <li>On Linux systems, the SHMMAX setting limits the amount of shared memory that can be allocated, which affects the shared classes cache size. You can find the value of SHMMAX for your system in the <code>/proc/sys/kernel/shmmax</code> file. For non-persistent caches, set this value to an appropriate size for your applications. To make these changes permanent, edit <code>/etc/sysctl.conf</code> and reboot your system.</li> <li>On macOS systems, you must set kern.sysv.shmmax and kern.sysv.shmall when using a nonpersistent cache. Modify the settings in your <code>/etc/sysctl.conf</code> file and reboot your system. To check the value, run <code>sysctl kern.sysv.shmmax</code>.</li> </ul> <p> Note: The virtual address space of a process is shared between the shared classes cache and the Java heap. Increasing the maximum size for the shared classes cache might reduce the size of the Java heap that you can create.</p> <p>Shared memory limits are also important when configuring large page memory allocation on Linux systems. For more information, see Configuring large page memory allocation: Linux systems.</p>"},{"location":"configuring/#setting-resource-limits-zos","title":"Setting resource limits (z/OS)","text":"<p>Resource limits imposed by z/OS might affect Java operations. To learn how these resource limits are set, see Customizing the BPXPRMxx member of SYS1.PARMLIB.</p> <p>The OpenJ9 class data sharing feature is implemented by using shared memory segments on z/OS. Special consideration should be given to the following parameters that relate to the shared memory and IPC semaphore settings:</p> <ul> <li>IPCSHMSPAGES</li> <li>IPCSHMMPAGES</li> <li>IPCSHMNSEGS</li> </ul> <p>Incorrect or suboptimal settings might prevent shared classes from working or impact performance. By default, the VM attempts to create a 16 MB cache on Java 8 and a 300 MB cache on Java 11 and later. If you set a cache size for your application by specifying the <code>-Xscmx</code> option on the command line, the VM rounds the value up to the nearest megabyte. Ensure that the value set for IPCSHMMPAGES takes this adjustment into consideration.</p> <p>To see the current settings, enter the following z/OS operator command:</p> <pre><code>D OMVS,O\n</code></pre> <p>The suggested minimum values for Java applications are shown in the following table:</p> Parameter Value MAXPROCSYS 900 MAXPROCUSER 512 MAXUIDS 500 MAXTHREADS 10000 MAXTHREADTASKS 5000 MAXASSIZE 2147483647 MAXCPUTIME 2147483647 MAXMMAPAREA 40960 IPCSHMSPAGES 262144 IPCSHMMPAGES 25600 IPCSHMNSEGS 10 IPCSEMNIDS 500 IPCSEMNSEMS 1000 SHRLIBRGNSIZE 67 108 864 <p> Note: The number of threads that can be created by a Java process is limited by the lower of the two values for MAXTHREADS and MAXTHREADSTASKS.</p> <p>You can change these settings dynamically without re-IPLing the system. For example, to set MACPROCUSER to 256, run <code>SETOMVS MAXPROCUSER=256</code></p> <p>z/OS uses region sizes to determine the amount of storage available to running programs. For a Java runtime environment, the  region size must be sufficiently large to avoid storage related error messages or abends. Rather than restricting region size, allow the VM to use what it needs. Region size can be affected by one of the following parameters: JCL REGION, BPXPRMxx MAXASSIZE, the RACF OMVS segment ASSIZEMAX, or IEFUSI (Step initiation exit).</p> <p>SHRLIBRGNSIZE controls how much storage is reserved in each address space for mapping shared DLLs that have the +l extended attribute set. If this storage space is exceeded, DLLs are loaded into the address space instead of using a single copy of z/OS UNIX System Services storage that is shared between the address spaces. The z/OS command D OMVS,L shows the SHRLIBRGNSIZE size and peak usage. If this size is set to a much higher value than is needed, the Java application might have problems acquiring native storage. These problems can cause a z/OS abend, such as <code>878-10</code>, or a Java <code>OutOfMemoryError</code>.</p>"},{"location":"configuring/#configuring-language-environment-runtime-options","title":"Configuring Language Environment runtime options","text":"<p>Language Environment\u00ae runtime options affect performance and storage usage. These options can be optimized for your application.</p> <p>Runtime options are typically embedded in programs by using #pragma runopts settings. In many cases, these options provide suitable default values that are known to produce good performance results. However, these options can be overridden to tune the runtime environment of your application.</p> <p>On 64-bit z/OS systems, the following runtime options affect Java applications:</p> <ul> <li>HEAP64: Controls allocation of the user heap. A suggested starting point for an override is HEAP64(512M,4M,KEEP,16M,4M,KEEP,0K,0K,FREE).</li> <li>HEAPPOOLS64: Used to manage Java heap storage above the 2 G bar. The Java USS launcher sets HEAPPOOLS64(ALIGN) for more optimal management of multi-threaded applications. Other Java launchers might have different settings. Before you set an override for HEAPPOOLS64, use RPTOPTS(ON) to confirm the active settings for your environment and RPTSTG(ON) to review storage usage and tuning recommendations. Note that the host product might have already set cell sizes and numbers that are known to produce good performance.</li> <li>STACK64: Controls the allocation and management of stack storage. A suggested default is STACK64(1M,1M,128M).</li> <li>THREADSTACK64: Controls the allocation of thread-level stack storage for both the upward and downward-growing stack. A suggested default is THREADSTACK64(OFF,1M,1M,128M).</li> </ul> <p>A suitable MEMLIMIT value is also required. The OpenJ9 VM requirement is the sum of the following amounts:</p> <ul> <li>User heap storage required by the VM and native libraries, as controlled by HEAP64 (minimum 512 M) settings.</li> <li>User stack storage (3 MB multiplied by the expected number of concurrent threads), as controlled by STACK64 settings.</li> <li><code>-Xmx</code> largest expected VM heap size.</li> <li>The JIT data cache maximum size.</li> <li>The JIT code cache maximum size, if RMODE64 is supported.</li> </ul> <p> Note: If you intend to use the Concurrent Scavenge mode of the default Generational Concurrent (<code>gencon</code>) garbage collection policy by using hardware-based support, the virtual storage used might exceed the Java maximum heap size. Set the z/OS memory limit to a larger value than the maximum heap size. For more information, see <code>-Xgc:concurrentScavenge</code>.</p> <p>The following guides are available to help you configure Language Environment runtime options and callable services:</p> <ul> <li>See z/OS Language Environment Programming Guide for guidance on how to override the default options. Use RPTOPTS (ON) to write the options that are in effect to stderr on termination.</li> <li>See z/OS Language Environment Programming Reference for a full list of the available runtime options.</li> <li>See z/OS Language Environment Debugging Guide for tuning guidance by using RPTSTG (ON).</li> </ul> <p> Warning: Changing the runtime options can often degrade performance.</p>"},{"location":"configuring/#configuring-large-page-memory-allocation","title":"Configuring large page memory allocation","text":"<p>If your application allocates a large amount of memory and frequently accesses that memory, you might be able to improve performance by enabling large page support on your system.</p> <p>Some Linux kernels implement Transparent HugePage Support (THP), which automates the provision of large pages to back virtual memory, as described in Linux systems. Alternatively, you can enable large page support by setting the <code>-Xlp:objectheap</code> and <code>-Xlp:codecache</code> options on the command line when you start your application. These options have the following effects:</p> <ul> <li>The <code>-Xlp:objectheap</code> option requests that the Java object heap is allocated by using large pages.</li> <li>The <code>-Xlp:codecache</code> option requests that the JIT code cache is allocated by using large pages.</li> </ul> <p>You must also enable large pages on your local system. This process differs according to the operating system.</p>"},{"location":"configuring/#aix-systems","title":"AIX systems","text":"<p>AIX supports large page sizes of 64 KB and 16 MB, and a huge page size of 16 GB depending on the underlying system P hardware. To determine which page sizes are supported on a particular system, run <code>pagesize -a</code>.</p> <p>To use large pages to back an application's data and heap segments, specify the LDR_CNTRL environment variable. You can set different page sizes for different purposes. The following variables can be used:</p> <ul> <li>TEXTPSIZE: Page size to use for text</li> <li>STACKPSIZE: Page size to use for stacks</li> <li>DATAPSIZE: Page size to use for native data or HEAP64</li> </ul> <p>The following example sets 4 KB for text and 64 KB for stack, native data, and heap areas:</p> <pre><code>LDR_CNTRL=TEXTPSIZE=4K@STACKPSIZE=64K@DATAPSIZE=64K\n</code></pre> <p>For more information, including support considerations, see Large pages and Multiple page size support in the AIX documentation.</p> <p>The 16 MB and 16 GB page sizes, which are intended for very high performance environments, require special user permissions. You must also configure the number of pages that you require, which cannot be adjusted on demand. For 16 MB large pages, you set the number of large pages by using the <code>vmo</code> command. For 16 GB huge pages you must define the number of pages by using the hardware management console. For more information, see Page sizes for very high-performance environments in the AIX documentation.</p>"},{"location":"configuring/#linux-systems","title":"Linux systems","text":"<p>Large pages are typically referred to as huge pages on Linux systems. To configure huge page memory allocation, the kernel must support huge pages. If huge pages are supported, the following lines are present in the /proc/meminfo file:</p> <pre><code>HugePages_Total:    \nHugePages_Free:     \nHugepagesize:     \n</code></pre> <p>If these lines do not exist, update your Linux kernel. If <code>HugePages_Total</code> has a value of <code>0</code>, huge pages are available, but not enabled. To enable huge pages, add the following line to your /etc/sysctl.conf file and reload the configuration by running <code>sysctl -p</code>:</p> <pre><code>vm.nr_hugepages=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of huge pages required.</p> <p>Configure the number of huge pages that you require at boot time to ensure that the VM has access to sufficient contiguous pages. The following kernel parameters must be set appropriately for your system:</p> <ul> <li>SHMMAX: The maximum size of the shared memory segment (bytes).</li> <li>SHMALL: The total amount of shared memory in the system (bytes or pages).</li> </ul> <p>The user running the Java process must either be ROOT or have permissions to use huge pages. For the appropriate permissions, the user must be a member of a group that has its group identifier (gid) stored in /proc/sys/vm/hugetlb_shm_group. The locked memory limit must also be increased to at least the size of the Java heap by using the ulimit -l command.</p> <p>Where huge page support is available, the following default sizes apply for the object heap:</p> <ul> <li>Linux on x86: 2 MB</li> <li>Linux on IBM Power Systems: Varies depending on kernel version, check <code>/proc/meminfo</code></li> <li>Linux on IBM Z: 1 MB</li> </ul> <p>Transparent HugePage Support (THP) is an automated mechanism of using huge pages to back virtual memory. On Linux kernels that support THP, it is typically enabled by default with the madvise option and can be relied on to provide huge pages as required without any user configuration. To disable THP for your application, use the OpenJ9 <code>-XX:-TransparentHugePage</code> option on the command line. To disable THP system-wide, change the sysfs boot time defaults with the command <code>transparent_hugepage=never</code>. For more information about THP see Transparent HugePage Support.</p>"},{"location":"configuring/#windows-systems","title":"Windows systems","text":"<p>On Windows systems, large pages are typically 2 MB in size. To use large pages, the VM user must have the Windows Lock pages in memory setting enabled in the Local Security Policy. Applications must also be run with Admin privileges in order to use large page memory allocations.</p> <p>For more information, see the following resources from Microsoft:</p> <ul> <li>Large page support</li> <li><code>GetLargePageMinimum</code> function (<code>memoryapi.h</code>)</li> </ul>"},{"location":"configuring/#zos-systems","title":"z/OS systems","text":"<p>When available, 1 MB pageable pages are the default size for the object heap and the code cache. Other page sizes are available for the object heap, depending on the system architecture as shown in the following table:</p> Large page size System architecture required <code>-Xlp:codecache</code> <code>-Xlp:objectheap</code> 2 GB nonpageable IBM zEnterprise EC12 processor or later Not supported Supported (64-bit VM only) 1 MB nonpageable System z10 processor or later Not supported Supported (64-bit VM only) 1 MB pageable IBM zEnterprise EC12 processor or later (see Note) Supported Supported <p> Note: The Flash Express feature (#0402) helps avoid demoting 1 MB pageable pages to 4 KB pages when there is system paging activity.</p> <p>If a particular page size cannot be allocated, a smaller page size is attempted, in descending order. For example, if 2 GB nonpageable pages are requested but not available, the VM tries to allocate 1MB nonpageable pages. If 1 MB nonpageable pages are not available, the VM tries to allocate 1MB pageable pages. If large pages are not available, 4 KB pages are allocated.</p> <p>If you want to use nonpageable large pages for the object heap, a system programmer must configure z/OS for nonpageable large pages in the IEASYSxx parmlib member. Users who require large pages must also be authorized to the IARRSM.LRGPAGES resource in the RACF FACILITY class with read authority.</p> <p>Use the following z/OS system command to show large page usage for an LPAR:</p> <pre><code>MODIFY AXR,IAXDMEM\n</code></pre> <p>For more information, see Displaying real storage memory statistics in the z/OS product documentation.</p> <p>For usage information, including examples, see <code>-Xlp:objectheap</code>.</p>"},{"location":"configuring/#configuring-dynamic-lpar-support-aix-only","title":"Configuring Dynamic LPAR support (AIX only)","text":"<p>Dynamic logical partitioning (DLPAR) provides a mechanism to add or remove system resources, such as memory or CPU, to or from the operating system in a logical partition without rebooting. Changing these resources dynamically can have an impact on Java applications that are running on the LPAR.</p> <p>To enable an application to respond to DLPAR events, you can use OpenJ9 MXBean extensions to the <code>java.lang.management</code> API. The following classes are available in the <code>com.ibm.lang.management</code> package:</p> <ul> <li><code>AvailableProcessorsNotificationInfo</code>: Use to listen for changes to the number of available processors.</li> <li><code>ProcessingCapacityNotificationInfo</code>: Use to listen for changes to processing capacity.</li> <li><code>TotalPhysicalMemoryNotificationInfo</code>: Use to listen for changes to the total amount of physical memory that is available.</li> </ul> <p>These extensions can listen for events and trigger any necessary adjustments to the runtime environment. For example, if a Java VM is running in an LPAR with 2GB of memory, but the available memory might be adjusted between 1GB and 8GB, you might set the following options for the Java heap at run time:</p> <pre><code>\u2013Xms1g \u2013Xsoftmx2g \u2013Xmx8g\n</code></pre> <p>This command-line string sets an initial heap size of 1 GB, a soft (adjustable) maximum heap size of 2 GB, and a maximum heap size of 8 GB. You can then use the <code>MemoryMXBean</code> API to dynamically respond to changes in memory resources. The following classes can be used:</p> <ul> <li><code>getMaxHeapSize()</code>: Query the maximum heap size.</li> <li><code>isSetMaxHeapSizeSupported()</code>: Query whether the VM can support dynamic updates.</li> <li><code>setMaxHeapSize()</code>: Adjust the maximum heap size.</li> </ul> <p>For more information about the <code>com.ibm.lang.managment</code> package, which extends the <code>jdk.management</code> module, see the API documentation.</p>"},{"location":"criusupport/","title":"CRIU support","text":""},{"location":"criusupport/#criu-support","title":"CRIU support","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p> Notes:</p> <ul> <li>Support for the Checkpoint/Restore In Userspace (CRIU) tool is currently provided as a technical preview in container environments. CRIU support is available for the customized CRIU version that is packaged with the Semeru container image. This preview is supported for use in production environments, however, all APIs and command-line options are subject to change.</li> <li>CRIU support is not available on OpenJDK 20 in version 0.39.0 release.</li> </ul> <p>In OpenJ9, the CRIU support includes an API that you can use to stop the VM at a checkpoint, save its state, and then run the VM from the point where it was stopped. The period of time between when the VM starts and when the application takes a checkpoint is referred to as the checkpoint phase. The application writes the VM state that was saved at the checkpoint to one or more image files. The saved state includes memory pages, methods, file systems, processes, and network connections. You can restore the VM from these files multiple times from the same point and in multiple environments.</p> <p>Because the checkpoint image files have the live state of the VM that is used to restore the VM in different systems, they should not contain cryptographically-sensitive security data. If the image files contain sensitive security data, the security components are vulnerable to exploitation even if you don't move the image files between systems. The CRIU technical preview introduces the <code>CRIUSECProvider</code> security provider, which provides the following limited set of security services: <code>MessageDigest</code> and <code>SecureRandom</code>. When you enable CRIU support, all existing security providers are removed from the security provider list during the checkpoint phase and <code>CRIUSECProvider</code> is added. When you restore the VM in the nonportable restore mode (<code>-XX:+CRIURestoreNonPortableMode</code>), <code>CRIUSECProvider</code> is removed from the security provider list and the previous security providers are added back again.</p> <p>When the VM starts from the saved point instead of the beginning, the VM startup time improves.</p>"},{"location":"criusupport/#enabling-criu-support","title":"Enabling CRIU support","text":"<p>CRIU support is not enabled by default. You must enable it by specifying the <code>-XX:+EnableCRIUSupport</code> command-line option when you start your application.</p>"},{"location":"criusupport/#configuring-criu-support","title":"Configuring CRIU support","text":"<p>You can access the OpenJ9 CRIU support capabilities by specifying different options. The VM enables the addition of VM options on restore through the <code>CRIUSupport.registerRestoreOptionsFile</code> API and environment variables through the <code>CRIUSupport.registerRestoreEnvVariables</code> API. <code>OPENJ9_RESTORE_JAVA_OPTIONS</code> is a special environment variable for adding the VM options on restore.</p> <p>There are new options that work at checkpoint as well as at restore and some new options that work at restore only. There are also some existing options that work on restore but some of them behave differently.</p>"},{"location":"criusupport/#new-options","title":"New options","text":"<p>You can use the following options only during the checkpoint phase:</p> <ul> <li><code>-XX:[+|-]CRIURestoreNonPortableMode</code>: Specifies whether the JIT and AOT compiler generates nonportable compiled code on restore.</li> <li><code>-XX:CheckpointGCThreads</code>: Reduces the number of garbage collection (GC) threads that exist when you create a checkpoint image, to speed up the later restoration of the checkpoint image.</li> <li><code>-Dorg.eclipse.openj9.criu.ImmutableEnvVars</code>: Adds the environment variables in the <code>immutableEnvvars</code> list. The VM can detect these variables during the checkpoint and restore phases.</li> </ul> <p>You can use the following options only when you restore a VM. If you specify these options when you start the VM (during the checkpoint phase), the VM does not start:</p> <ul> <li><code>-XX:[+|-]IgnoreUnrecognizedRestoreOptions</code>: Specifies whether a restored VM ignores unrecognized command-line options and starts anyway or throws a <code>JVMRestoreException</code> error and does not start.</li> <li><code>-Xshareclasses:disableOnRestore</code>: Disables further use of the shared classes cache (SCC) on restore.</li> <li><code>-Xrs:onRestore</code> and <code>-Xrs:syncOnRestore</code>: Disables signal handling on restore. These options behave in a similar way to the existing <code>-Xrs</code> and <code>-Xrs:sync</code> options. However, there are differences because some signal handlers might exist when a checkpoint is taken, and remain after restoration.</li> </ul>"},{"location":"criusupport/#existing-options","title":"Existing options","text":"<p>Of the existing command-line options, only the following are supported when you run a restored VM and some of these options have changed behavior:</p> Options Changed behavior <code>-Xverbosegclog</code> <code>-XcompilationThreads</code> <code>-XsamplingExpirationTime</code> <code>-XX:[+|-]PrintCodeCache</code> <code>-Xtrace</code> If you specify an <code>output</code> file before a checkpoint and another <code>output</code> file for restore, both the files are written according to the <code>-Xtrace</code> options associated with the <code>output</code> file. <code>-Xdump</code> Dump events that are triggered on exception throws or catches cannot be enabled on restore. <code>-Xgcthreads</code> This option is ignored if the number of GC threads is less than the checkpoint GC thread count. <code>-Xjit</code> If <code>-Xint</code> or <code>-Xnoaot</code> and <code>-Xnojit</code> are specified pre-checkpoint, the compiler remains disabled post-restore. <code>-Xaot</code> If <code>-Xnoaot</code> is specified pre-checkpoint, then specifying <code>-Xaot</code> post-restore does not enable AOT compilation or load. <code>-Xjit</code> / <code>-Xaot</code> You can specify the following parameters with the <code>-Xjit</code> and <code>-Xaot</code> options when you run a restored VM:<code>count</code>: Applies only to new methods; existing interpreted methods will not have their counts that are updated. <code>limit</code>, <code>limitFile</code>, <code>exclude</code>: Invalidates the existing compiled methods that do not match the filters. The filters are then enforced for all future JIT and AOT compilations. <code>loadLimit</code>, <code>loadLimitFile</code>, <code>loadExclude</code>: Applies only to future AOT loads; does not impact existing compiled methods. <code>verbose</code>: Effective post-restore; does not override verbose options specified pre-checkpoint. <code>vlog</code>: A vlog file is opened post-restore. If this option was specified pre-checkpoint, the old file is closed first. <code>-Xnoaot</code> Prevents AOT compilations and loads; does not affect the existing compiled methods and does not prevent JIT compilation. <code>-Xnojit</code> Invalidates all existing compiled methods and prevents JIT compilations; does not prevent AOT compilations and loads. <p>If you specify an unsupported option, the VM throws a <code>JVMRestoreException</code> error by default. If you specify the <code>-XX:+IgnoreUnrecognizedRestoreOptions</code> option, the VM does not throw any exception and just ignores the unsupported option.</p> <p>For more more information on CRIU support, see the <code>openj9.criu</code> module in your OpenJ9 JDK version (OpenJDK 11 and later) API documentation.</p> <p> Restrictions:</p> <ul> <li>If an <code>-Xtrace</code> or JIT log output file is specified on startup and doesn\u2019t exist on restore, or is modified in any way between checkpoint and restore, the restore operation fails.</li> <li>Method tracing might not work consistently if a method is compiled pre-checkpoint.</li> <li>The Java\u2122 heap is configured at startup. The VM detects the available memory on the system and sizes the heap based on it. With the CRIU support, this means that the size of the Java heap (<code>-Xms</code>, <code>-Xmx</code>) and the respective heap regions, such as nursery and tenure at checkpoint will be same on restore. If a checkpoint is taken in a container with no memory limits and then restored in a container with memory limits, the restored VM instance does not detect the memory limits.</li> <li>There is currently no support for changing locales. A checkpoint must be taken with the intended target locale on restore for it to function properly.</li> </ul>"},{"location":"criusupport/#see-also","title":"See Also","text":"<ul> <li>CRIU</li> <li>Fast JVM startup with OpenJ9 CRIU Support</li> <li>Getting started with OpenJ9 CRIU Support</li> <li>OpenJ9 CRIU Support: A look under the hood</li> <li>OpenJ9 CRIU Support: A look under the hood\u202f(part II)</li> </ul>"},{"location":"d_jvm_commands/","title":"Using System properties","text":""},{"location":"d_jvm_commands/#using-system-property-command-line-options","title":"Using system property command-line options","text":"<p>Java\u2122 system properties determine the environment in which a Java program runs by starting a Java virtual machine with a set of values. You can choose to use the default values for Java system properties or you can specify values for them by adding parameters to the command line when you start your application.</p> <p>To set a system property from the command line, use:</p> <pre><code>java -D&lt;property_name&gt;=&lt;value&gt; &lt;program_name&gt;\n</code></pre> <p>For example, to specify the UTF-8 file encoding for your application <code>MyProgram</code>, use:</p> <pre><code>java -Dfile.encoding=UTF-8 MyProgram\n</code></pre>"},{"location":"dcomibmenableclasscaching/","title":"-Dcom.ibm.enableClassCaching","text":""},{"location":"dcomibmenableclasscaching/#-dcomibmenableclasscaching","title":"-Dcom.ibm.enableClassCaching","text":"<p>Setting this property to <code>true</code> enables caching of the Latest User Defined Class Loader (LUDCL).</p>"},{"location":"dcomibmenableclasscaching/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableClassCaching=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenableclasscaching/#explanation","title":"Explanation","text":"<p>By reducing repeated lookups, Java\u2122 applications that use deserialization extensively can see a performance improvement.</p>"},{"location":"dcomibmenableclasscaching/#see-also","title":"See also","text":"<ul> <li> Java Object Serialization Specification</li> </ul>"},{"location":"dcomibmenablelegacydumpsecurity/","title":"-Dcom.ibm.enableLegacyDumpSecurity","text":""},{"location":"dcomibmenablelegacydumpsecurity/#-dcomibmenablelegacydumpsecurity","title":"-Dcom.ibm.enableLegacyDumpSecurity","text":"<p>To improve security, the security checks in the certain <code>com.ibm.jvm.Dump</code> APIs are now enabled by default, when the <code>SecurityManger</code> is enabled. Use this system property to turn off security checking for these APIs.</p>"},{"location":"dcomibmenablelegacydumpsecurity/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableLegacyDumpSecurity=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenablelegacydumpsecurity/#explanation","title":"Explanation","text":"<p>Security checking is enabled in the following APIs:</p> <ul> <li><code>com.ibm.jvm.Dump.JavaDump()</code></li> <li><code>com.ibm.jvm.Dump.HeapDump()</code></li> <li><code>com.ibm.jvm.Dump.SnapDump()</code></li> </ul>"},{"location":"dcomibmenablelegacydumpsecurity/#see-also","title":"See also","text":"<ul> <li>-Dcom.ibm.enableLegacyLogSecurity</li> <li>-Dcom.ibm.enableLegacyTraceSecurity</li> </ul>"},{"location":"dcomibmenablelegacylogsecurity/","title":"-Dcom.ibm.enableLegacyLogSecurity","text":""},{"location":"dcomibmenablelegacylogsecurity/#-dcomibmenablelegacylogsecurity","title":"-Dcom.ibm.enableLegacyLogSecurity","text":"<p>To improve security, the security checks in the certain <code>com.ibm.jvm.Log</code> APIs are now enabled by default, when the <code>SecurityManger</code> is enabled. Use this system property to turn off security checking for these APIs.</p>"},{"location":"dcomibmenablelegacylogsecurity/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableLegacyLogSecurity=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenablelegacylogsecurity/#explanation","title":"Explanation","text":"<p>Security checking is enabled in the following APIs:</p> <ul> <li><code>com.ibm.jvm.Log.QueryOptions()</code></li> <li><code>com.ibm.jvm.Log.SetOptions(String)</code></li> </ul>"},{"location":"dcomibmenablelegacylogsecurity/#see-also","title":"See also","text":"<ul> <li>-Dcom.ibm.enableLegacyDumpSecurity</li> <li>-Dcom.ibm.enableLegacyTraceSecurity</li> </ul>"},{"location":"dcomibmenablelegacytracesecurity/","title":"-Dcom.ibm.enableLegacyTraceSecurity","text":""},{"location":"dcomibmenablelegacytracesecurity/#-dcomibmenablelegacytracesecurity","title":"-Dcom.ibm.enableLegacyTraceSecurity","text":"<p>To improve security, the security checks in certain <code>com.ibm.jvm.Trace</code> APIs are now enabled by default, when the <code>SecurityManger</code> is enabled. Use this system property to turn off security checking for these APIs.</p>"},{"location":"dcomibmenablelegacytracesecurity/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.enableLegacyTraceSecurity=[true|false]\n</code></pre> Setting Effect Default true Enable yes false Disable"},{"location":"dcomibmenablelegacytracesecurity/#explanation","title":"Explanation","text":"<p>Security checking is enabled in the following APIs:</p> <ul> <li><code>com.ibm.jvm.Trace.set(String)</code></li> <li><code>com.ibm.jvm.Trace.snap()</code></li> <li><code>com.ibm.jvm.Trace.suspend()</code></li> <li><code>com.ibm.jvm.Trace.suspendThis()</code></li> <li><code>com.ibm.jvm.Trace.resume()</code></li> <li><code>com.ibm.jvm.Trace.resumeThis()</code></li> <li><code>com.ibm.jvm.Trace.registerApplication(String, String[])</code></li> </ul>"},{"location":"dcomibmenablelegacytracesecurity/#see-also","title":"See also","text":"<ul> <li>-Dcom.ibm.enableLegacyDumpSecurity</li> <li>-Dcom.ibm.enableLegacyLogSecurity</li> </ul>"},{"location":"dcomibmgpudisable/","title":"-Dcom.ibm.gpu.disable","text":""},{"location":"dcomibmgpudisable/#-dcomibmgpudisable","title":"-Dcom.ibm.gpu.disable","text":"<p> Restriction: This system property is supported only on Java\u2122 11 and later.</p> <p>If you have enabled GPU processing with <code>-Dcom.ibm.gpu.enable</code>, use this system property to turn off processing that can be offloaded to a graphics processing unit (GPU).</p>"},{"location":"dcomibmgpudisable/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.gpu.disable\n</code></pre>"},{"location":"dcomibmgpudisable/#explanation","title":"Explanation","text":"<p>Because establishing and completing communication with a GPU incurs an additional overhead, not all processing requirements benefit from being offloaded to the GPU. GPU processing is therefore disabled by default. However, if you have enabled GPU processing with <code>-Dcom.ibm.gpu.enable</code>, this property turns GPU processing off.</p>"},{"location":"dcomibmgpudisable/#see-also","title":"See also","text":"<ul> <li>Exploiting GPUs</li> <li>-Dcom.ibm.gpu.enable</li> <li>-Dcom.ibm.gpu.verbose</li> </ul>"},{"location":"dcomibmgpuenable/","title":"-Dcom.ibm.gpu.enable","text":""},{"location":"dcomibmgpuenable/#-dcomibmgpuenable","title":"-Dcom.ibm.gpu.enable","text":"<p> Restriction: This system property is supported only on Java\u2122 11 and later.</p> <p>Use this system property to control the type of processing that can be offloaded to a graphics processing unit (GPU) when processing requirements meet a specific threshold. This feature can improve the performance of certain Java functions.</p>"},{"location":"dcomibmgpuenable/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.gpu.enable=[all|sort]\n</code></pre> Setting Effect all Turns on GPU processing for all possible Java functions. sort Turns on GPU processing only for the Java <code>sort()</code> function. <p>By default, this property is not set.</p>"},{"location":"dcomibmgpuenable/#explanation","title":"Explanation","text":"<p>Because establishing and completing communication with a GPU incurs an additional overhead, not all processing requirements benefit from being offloaded to the GPU. When set, this property enables GPU processing for any array that meets a minimum size.</p>"},{"location":"dcomibmgpuenable/#see-also","title":"See also","text":"<ul> <li>Exploiting GPUs</li> <li>-Dcom.ibm.gpu.disable</li> <li>-Dcom.ibm.gpu.verbose</li> </ul>"},{"location":"dcomibmgpuverbose/","title":"-Dcom.ibm.gpu.verbose","text":""},{"location":"dcomibmgpuverbose/#-dcomibmgpuverbose","title":"-Dcom.ibm.gpu.verbose","text":"<p> Restriction: This system property is supported only on Java\u2122 11 and later.</p> <p>This system property can be used to help identify problems with graphics processing unit (GPU) processing.</p>"},{"location":"dcomibmgpuverbose/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.gpu.verbose\n</code></pre> <p>This property is not set by default.</p>"},{"location":"dcomibmgpuverbose/#explanation","title":"Explanation","text":"<p>When specified, this option generates verbose output to STDOUT, which can be piped to a file.</p>"},{"location":"dcomibmgpuverbose/#see-also","title":"See also","text":"<ul> <li>Exploiting GPUs</li> <li>-Dcom.ibm.gpu.disable</li> <li>-Dcom.ibm.gpu.enable</li> </ul>"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/","title":"-Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns","text":""},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#-dcomibmlangmanagementoperatingsystemmxbeaniscputime100ns","title":"-Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns","text":"<p>Changes the unit of the return value of the <code>OperatingSystemMXBean.getProcessCpuTime()</code> method.</p>"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns=[true|false]\n</code></pre> Setting Effect Default true Enable false Disable yes"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#explanation","title":"Explanation","text":"<p>The Oracle <code>java.lang.management</code> package includes MBean categories such as <code>Memory</code>, <code>OperatingSystem</code>, and <code>GarbageCollector</code>. The Eclipse OpenJ9\u2122 VM  provides additional MXBeans to extend the monitoring and management capabilities. For example, the <code>OperatingSystemMXBean</code>, which monitors operating system settings such as physical and virtual memory size, processor capacity, and processor utilization.</p> <p>The <code>OperatingSystemMXBean.getProcessCpuTime()</code> method returns a value in nanoseconds (10<sup>-9</sup> s), for compatibility with the <code>com.sun.management.OperatingSystemMXBean</code> and <code>UnixOperatingSystemMXBean</code> interfaces.</p> <p>In earlier VM releases, the return value was in hundreds of nanoseconds. If you want to revert to this behavior, set the <code>-Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns</code> property to <code>true</code>.</p> <p>The default value for this property is <code>false</code>.</p>"},{"location":"dcomibmlangmanagementosmxbeaniscputime100ns/#see-also","title":"See also","text":"<ul> <li>Monitoring and management API documentation </li> </ul>"},{"location":"dcomibmlangmanagementverbose/","title":"-Dcom.ibm.lang.management.verbose","text":""},{"location":"dcomibmlangmanagementverbose/#-dcomibmlangmanagementverbose","title":"-Dcom.ibm.lang.management.verbose","text":"<p>Enables verbose information from <code>java.lang.management</code> operations to be written to the output channel during VM operations.</p>"},{"location":"dcomibmlangmanagementverbose/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.lang.management.verbose\n</code></pre> <p>There are no options for this system property.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/","title":"-Dcom.ibm.oti.shared.SharedClassGlobalFilterClass","text":""},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#-dcomibmotisharedsharedclassglobalfilterclass","title":"-Dcom.ibm.oti.shared.SharedClassGlobalFilterClass","text":"<p>This system property applies a global filter to all non-bootstrap class loaders that share classes.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.oti.shared.SharedClassGlobalFilterClass=&lt;filter_class_name&gt;\n</code></pre> <p>This property is not set by default.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#explanation","title":"Explanation","text":"<p>A filter can be used to decide which classes are found and stored by a custom class loader in a shared classes cache. The filter is applied to a particular package by implementing the <code>SharedClassFilter</code> interface.</p>"},{"location":"dcomibmotisharedsharedclassglobalfilterclass/#see-also","title":"See also","text":"<ul> <li>The Java shared classes Helper API</li> <li>Shared classes Helper API package: <code>com.ibm.oti.shared</code></li> </ul>"},{"location":"dcomibmtoolsattachcommand_timeout/","title":"-Dcom.ibm.tools.attach.command_timeout","text":""},{"location":"dcomibmtoolsattachcommand_timeout/#-dcomibmtoolsattachcommand_timeout","title":"-Dcom.ibm.tools.attach.command_timeout","text":"<p>Specify the timeout for sending a command to the target VM after the initial attachment.</p>"},{"location":"dcomibmtoolsattachcommand_timeout/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.command_timeout=&lt;ms&gt;\n</code></pre> Setting Value Default <code>&lt;ms&gt;</code> [1 millisecond or greater] 0 milliseconds (no timeout)"},{"location":"dcomibmtoolsattachcommand_timeout/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachdirectory/","title":"-Dcom.ibm.tools.attach.directory","text":""},{"location":"dcomibmtoolsattachdirectory/#-dcomibmtoolsattachdirectory","title":"-Dcom.ibm.tools.attach.directory","text":"<p>Specify a different common directory for Attach API working files.</p>"},{"location":"dcomibmtoolsattachdirectory/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.directory=&lt;directory_name&gt;\n</code></pre> Setting Value Default <code>&lt;directory_name&gt;</code> [string] <code>.com_ibm_tools_attach</code> <p>To change the value for <code>directory_name</code>, specify a different directory name. If the directory does not exist, it is created. However, if a parent directory is specified, it must exist. The common directory must be on a local drive, not a network drive.</p>"},{"location":"dcomibmtoolsattachdirectory/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachdisplayname/","title":"-Dcom.ibm.tools.attach.displayName","text":""},{"location":"dcomibmtoolsattachdisplayname/#-dcomibmtoolsattachdisplayname","title":"-Dcom.ibm.tools.attach.displayName","text":"<p>Change the default display name for the target virtual machine.</p>"},{"location":"dcomibmtoolsattachdisplayname/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.displayName=&lt;my_display_name&gt;\n</code></pre> Setting Value Default <code>&lt;my_display_name&gt;</code> [string] The command line invocation used to start the application <p>To change the value for <code>&lt;my_display_name&gt;</code> that is recorded by an agent, enter a character string of your choice.</p>"},{"location":"dcomibmtoolsattachdisplayname/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachenable/","title":"-Dcom.ibm.tools.attach.enable","text":""},{"location":"dcomibmtoolsattachenable/#-dcomibmtoolsattachenable","title":"-Dcom.ibm.tools.attach.enable","text":"<p>Enable the Attach API for this application.</p>"},{"location":"dcomibmtoolsattachenable/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.enable=[yes|no]\n</code></pre> <p>On AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122 systems, the following default applies:</p> Value Effect Default yes Enable yes no Disable <p>On z/OS\u00ae systems, the following default applies:</p> Value Effect Default yes Enable no Disable yes"},{"location":"dcomibmtoolsattachenable/#explanation","title":"Explanation","text":"<p>A useful reference for information about the Java\u2122 Attach API can be found at http://docs.oracle.com/javase/8/docs/technotes/guides/attach/index.html. The following extract is taken from the Oracle documentation:</p> <p>The Attach API is an extension that provides a mechanism to attach to a Java virtual machine. A tool written in the Java Language, uses this API to attach to a target  virtual machine and load its tool agent into that virtual machine.</p> <p>A usage example is to late attach the IBM\u00ae Health Center agent to a virtual machine (VM) that is already running.</p> <p>The Eclipse OpenJ9\u2122 implementation of the Attach API is equivalent to the Oracle implementation. However, the OpenJ9 implementation cannot be used to attach to, or accept attach requests from, other VM implementations.</p>"},{"location":"dcomibmtoolsattachenable/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachid/","title":"-Dcom.ibm.tools.attach.id","text":""},{"location":"dcomibmtoolsattachid/#-dcomibmtoolsattachid","title":"-Dcom.ibm.tools.attach.id","text":"<p>Specify a different virtual machine (VM) identifier.</p>"},{"location":"dcomibmtoolsattachid/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.id=&lt;my_vm_ID&gt;\n</code></pre> Setting Value Default <code>&lt;my_vm_ID&gt;</code> [string] Target VM process ID <p>To change the VM identifier recorded by an agent, change the value for <code>&lt;my_vm_ID&gt;</code>. The string must start with an alphabetic character. The remaining characters must be alphanumeric or underscore. Case-sensitivity is system dependent. If the VM identifier is already in use, the attach API modifies it to create a unique value.</p>"},{"location":"dcomibmtoolsattachid/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachlogging/","title":"-Dcom.ibm.tools.attach.logging","text":""},{"location":"dcomibmtoolsattachlogging/#-dcomibmtoolsattachlogging","title":"-Dcom.ibm.tools.attach.logging","text":"<p>Enable logging for Attach API events.</p>"},{"location":"dcomibmtoolsattachlogging/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.logging=[yes|no]\n</code></pre> Value Effect Default yes Enable no Disable yes"},{"location":"dcomibmtoolsattachlogging/#explanation","title":"Explanation","text":"<p>Turn on tracing and logging of Attach API events to help diagnose problems. One timestamped log file is created for each Java\u2122 process in the current directory for the running JVM .</p>"},{"location":"dcomibmtoolsattachlogging/#see-also","title":"See also","text":"<ul> <li>Java Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachlogname/","title":"-Dcom.ibm.tools.attach.log.name","text":""},{"location":"dcomibmtoolsattachlogname/#-dcomibmtoolsattachlogname","title":"-Dcom.ibm.tools.attach.log.name","text":"<p>Specify the path and prefix for the log files.</p>"},{"location":"dcomibmtoolsattachlogname/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.log.name=&lt;path/prefix&gt;\n</code></pre> Setting Value Default <code>&lt;path/prefix&gt;</code> [string] VM process directory <p>By default, when <code>-Dcom.ibm.tools.attach.logging=true</code> is set, timestamped log files are written to the current directory for the running VM. Use the  <code>-Dcom.ibm.tools.attach.log.name</code> option to change the path and prefix for the logfiles.</p>"},{"location":"dcomibmtoolsattachlogname/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachshutdown_timeout/","title":"-Dcom.ibm.tools.attach.shutdown_timeout","text":""},{"location":"dcomibmtoolsattachshutdown_timeout/#-dcomibmtoolsattachshutdown_timeout","title":"-Dcom.ibm.tools.attach.shutdown_timeout","text":"<p>Specify a timeout before ending the Attach API wait loop thread.</p>"},{"location":"dcomibmtoolsattachshutdown_timeout/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.shutdown_timeout=&lt;ms&gt;\n</code></pre> Setting Value Default <code>&lt;ms&gt;</code> [1 millisecond or greater] 10000 milliseconds (10 seconds)"},{"location":"dcomibmtoolsattachshutdown_timeout/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.timeout</li> </ul>"},{"location":"dcomibmtoolsattachtimeout/","title":"-Dcom.ibm.tools.attach.timeout","text":""},{"location":"dcomibmtoolsattachtimeout/#-dcomibmtoolsattachtimeout","title":"-Dcom.ibm.tools.attach.timeout","text":"<p>Specify a time that an application should wait when attempting to connect to a target virtual machine (VM) before ending.</p>"},{"location":"dcomibmtoolsattachtimeout/#syntax","title":"Syntax","text":"<pre><code>    -Dcom.ibm.tools.attach.timeout=&lt;ms&gt;\n</code></pre> Setting Value Default <code>&lt;ms&gt;</code> [501 milliseconds or greater] 120000 milliseconds (120 seconds) <p>If you specify a value of 500 milliseconds or lower, no connection attempt is made.</p>"},{"location":"dcomibmtoolsattachtimeout/#example","title":"Example","text":"<p>To timeout after 60 seconds, specify:</p> <p><code>-Dcom.ibm.tools.attach.timeout=60000</code></p>"},{"location":"dcomibmtoolsattachtimeout/#see-also","title":"See also","text":"<ul> <li>Java\u2122 Attach API</li> <li>-Dcom.ibm.tools.attach.command_timeout</li> <li>-Dcom.ibm.tools.attach.directory</li> <li>-Dcom.ibm.tools.attach.displayName</li> <li>-Dcom.ibm.tools.attach.enable</li> <li>-Dcom.ibm.tools.attach.id</li> <li>-Dcom.ibm.tools.attach.logging</li> <li>-Dcom.ibm.tools.attach.log.name</li> <li>-Dcom.ibm.tools.attach.shutdown_timeout</li> </ul>"},{"location":"dfileencoding/","title":"-Dfile.encoding","text":""},{"location":"dfileencoding/#-dfileencoding","title":"-Dfile.encoding","text":"<p>Use this OpenJDK property to define the file encoding that is required.</p>"},{"location":"dfileencoding/#syntax","title":"Syntax","text":"<pre><code>    -Dfile.encoding=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [string] Unicode 3.0 standards where <code>&lt;value&gt;</code> defines the file encoding that is required."},{"location":"dfileencoding/#explanation","title":"Explanation","text":"<p>By default the GBK converter follows Unicode 3.0 standards. To force the GBK converter to follow Unicode 2.0 standards, use a value of <code>bestfit936</code>.</p>"},{"location":"diag_overview/","title":"Overview","text":""},{"location":"diag_overview/#diagnostic-data-and-tooling","title":"Diagnostic data and tooling","text":"<p>Eclipse OpenJ9\u2122 contains a broad range of diagnostic capabilities to help identify, isolate, and solve run time problems. These capabilities include dump files, verbose logs, and trace files, which are supported by a variety of diagnostic tools and interfaces.</p>"},{"location":"diag_overview/#dumps","title":"Dumps","text":"<p>Various types of dumps are produced by default in response to certain events, such as a GPF fault or an <code>OutOfMemoryError</code> exception. You can also trigger the production of dumps by using the <code>com.ibm.jvm.Dump</code> API or by specifying <code>-Xdump</code> options on the command line.</p> <p>All dumps are produced by dump agents, which are initialized when the OpenJ9 VM starts. Different dumps target different areas of the runtime environment. If you want to generate a dump to diagnose a particular type of problem, you need to understand what data the dump will provide. The following dumps are typically used for problem diagnosis:   </p> <ul> <li>Java dumps (<code>-Xdump:java</code>) contain information that relates to the OpenJ9 VM and the Java\u2122 application, such as the operating environment, locks, threads, hooks, shared classes, and class loaders.</li> <li>Heap dumps (<code>-Xdump:heap</code>) show the content of the Java heap.</li> <li>System dumps (<code>-Xdump:system</code>) contain a raw process image or address space of an application.  </li> </ul> <p>Other types of dump include binary JIT dumps, stack dumps, and snap dumps. For a complete list of dump agents and the diagnostic data they produce, see Dump agents.</p>"},{"location":"diag_overview/#verbose-log-files","title":"Verbose log files","text":"<p>Some components of OpenJ9 can also produce verbose output or log files to assist with problem determination.</p> <ul> <li> <p>Class data sharing provides a number of <code>-Xshareclasses</code> suboptions to provide detailed data about the content of a shared classes cache, cache I/O activity, and information about the Java Helper API (where used). For example, the <code>-Xshareclasses:printAllStats</code> suboption lists every class in chronological order with a reference to the location from which it was loaded. For more information, see -Xshareclasses.   </p> </li> <li> <p>Garbage collection operations can be analyzed by producing verbose output from the <code>-verbose:gc</code> standard option. This output can be redirected to a file by specifying the <code>-Xverbosegclog</code> option. Information can be obtained about GC initialization, stop-the-world processing, finalization, reference processing, and allocation failures. Even more granular information can be obtained with the -Xtgc option. For more information, see verbose GC logs.</p> </li> <li> <p>The JIT compiler provides verbose logging, which records all compiler operations. To find out how to enable logging, read the JIT troubleshooting content.</p> </li> <li> <p>Class loader operations can be analyzed by producing verbose output from the <code>-verbose:dynload</code> standard option, which shows detailed information as each class is loaded by the VM.</p> </li> </ul>"},{"location":"diag_overview/#trace-files","title":"Trace files","text":"<p>The OpenJ9 trace facility can be used to trace applications, Java methods, or internal JVM operations with minimal impact on performance. Trace is configured by using the -Xtrace command line option, which allows you to control what is traced and when.</p> <p>Trace data is produced in binary format and must be processed by the OpenJ9 trace formatter to convert it to a readable form. For more information, see Trace formatter.</p>"},{"location":"diag_overview/#diagnostic-tools","title":"Diagnostic tools","text":"<p>A number of diagnostic tools are available with OpenJ9 to assist with the analysis of dump and trace files.</p>"},{"location":"diag_overview/#dump-extractor","title":"Dump extractor","text":"<p>The dump extractor (<code>jpackcore</code>) supports a full analysis of core files on specific platforms by collecting key files from a system and packaging them into an archive along with a core dump. This archive file is extremely useful when reporting issues to the OpenJ9 community, helping to ensure a faster analysis and turnaround. For more information, see Dump extractor.</p>"},{"location":"diag_overview/#dump-viewer","title":"Dump viewer","text":"<p>Because system dumps are binary files, OpenJ9 provides a dump viewer tool (<code>jdmpview</code>) to analyze the contents. This tool can work with dumps from any platforms independently of a system debugger. For more information, see Dump viewer.</p>"},{"location":"diag_overview/#trace-formatter","title":"Trace formatter","text":"<p>The trace formatter tool converts binary trace point data in a trace file into a readable format for analysis. For more information, see Trace formatter.</p>"},{"location":"diag_overview/#option-builder","title":"Option builder","text":"<p>OpenJ9 contains an extensive set of command-line options to assist with problem diagnosis. Certain options are complex, containing many sub-options with numerous parameters. Whilst these offer a great degree of flexibility, the syntax can be difficult to construct. Option builder tools are available that provide a simple graphical user interface to help you construct your command-line argument. For more information, see Option builder.</p>"},{"location":"diag_overview/#hotspot-compatible-tools","title":"HotSpot-compatible tools","text":"<p>A number of tools are available for compatibility with the reference implementation. These tools are independently implemented by OpenJ9 but have similar functions, allowing users to migrate more easily. The available tools are listed in the Tools section.  </p> <p> Note: If you are already familiar with tools that are provided with HotSpot, see Switching to OpenJ9, which explains some of the differences you might encounter when using OpenJ9.</p>"},{"location":"diag_overview/#eclipse-marketplace-tools","title":"Eclipse marketplace tools","text":"<p>OpenJ9 provides support for a number of monitoring and diagnostic tools that can be found in the Eclipse marketplace. Each tool provides a graphical user interface to help you visualize data and, in some cases, can provide tuning or debugging recommendations.</p> <ul> <li>Health Center: Provides real-time monitoring of running applications with minimal overhead over the network. You can monitor a whole range of operations including, class loading, CPU usage, GC heap and pause times, I/O activity, lock contention, method trace, native memory usage, profiling, and live threads. For more information, read the Health Center documentation.</li> <li>Garbage Collection Memory Vizualizer (GCMV): Plots GC and native memory data over time. You can view and save data as a report, raw log, tabulated data, or in graphical format. The tool helps to diagnose problems such as memory leaks with data presented in various visual formats for analysis. Tuning recommendations are also provided. For more information, read the GCMV documentation.</li> <li>Eclipse Memory Analyzer\u2122: Examines the Java object heap to help find memory leaks or reduce memory consumption. Support is available for OpenJ9 via the DTFJ interface (Install from the Eclipse Help menu; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java). More information about Eclipse MAT can be found on the project website page.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, the Java VisualVM utility is functionally similar to Health Center.</p>"},{"location":"diag_overview/#interfaces","title":"Interfaces","text":""},{"location":"diag_overview/#jvm-tool-interface-jvmti","title":"JVM tool interface (JVMTI)","text":"<p>OpenJ9 supports the Java Virtual Machine Tool Interface (JVMTI) and provides extensions that allow JVMTI tools to obtain diagnostic information or trigger diagnostic operations in the VM. For more information, see Java Virtual Machine Tool Interface.</p>"},{"location":"diag_overview/#dtfj-interface","title":"DTFJ Interface","text":"<p>OpenJ9 includes the Diagnostic Tool Framework for Java (DTFJ) API. Custom applications can be written that use this API to access a wide range of information in a system dump or a Java dump. DTFJ can be used with the Eclipse Memory Analyzer tool (MAT) to examine the Java object heap for memory leaks and to reduce memory consumption. For more information, see Diagnostic Tool Framework for Java.</p>"},{"location":"diag_overview/#language-management-interface","title":"Language Management interface","text":"<p>OpenJ9 provides MXBean additions and extensions to the standard <code>java.lang.management</code> API, which enables you to use tools such as JConsole to monitor and manage your Java applications. For more information, see Language management interface.</p>"},{"location":"diag_overview/#jpda-tools","title":"JPDA tools","text":"<p>OpenJ9 is compliant with the Java Platform Debugging Architecture (JPDA), which means you can use any JPDA tool for diagnosis, including Eclipse JDT Debug.</p>"},{"location":"djavacompiler/","title":"-Djava.compiler","text":""},{"location":"djavacompiler/#-djavacompiler","title":"-Djava.compiler","text":"<p>This Oracle HotSpot property is used for loading a JIT compiler from a named, native library. This option can be used on the command line to specify the JIT compiler for the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"djavacompiler/#syntax","title":"Syntax","text":"<pre><code>    -Djava.compiler=j9jit29\n</code></pre>"},{"location":"djavalangstringbuffergrowaggressively/","title":"-Djava.lang.stringBuffer.growAggressively","text":""},{"location":"djavalangstringbuffergrowaggressively/#-djavalangstringbuffergrowaggressively","title":"-Djava.lang.stringBuffer.growAggressively","text":"<p> Restriction: This system property is supported only on Java\u2122 8.</p> <p> Setting this property to <code>false</code> reverts to the behavior (Eclipse OpenJ9\u2122 0.18 and earlier) of growing a 1 G <code>char[]</code> or larger <code>StringBuffer</code> or <code>StringBuilder</code> only as much as necessary to accommodate the <code>String</code> being added. The default behavior is to immediately grow to the maximum possible size, similarly to Java 11 and later. The default behavior is compatible with the Oracle HotSpot VM.</p>"},{"location":"djavalangstringbuffergrowaggressively/#syntax","title":"Syntax","text":"<pre><code>    -Djava.lang.stringBufferAndBuilder.growAggressively=[true|false]\n</code></pre> Setting Effect Default true Above 1 G, grow to the maximum size yes false Above 1 G, grow only as required"},{"location":"djavalangstringsubstringnocopy/","title":"-Djava.lang.string.substring.nocopy","text":""},{"location":"djavalangstringsubstringnocopy/#-djavalangstringsubstringnocopy","title":"-Djava.lang.string.substring.nocopy","text":"<p> Restriction: This system property is supported only on Java\u2122 8. String sharing cannot be enabled on Java 11 and later.</p> <p> Setting this property to <code>true</code> avoids sharing a String object when substring() is used to subset a String beginning from offset zero. Avoiding sharing is compatible with the Oracle HotSpot VM.</p>"},{"location":"djavalangstringsubstringnocopy/#syntax","title":"Syntax","text":"<pre><code>    -Djava.lang.string.substring.nocopy=[true|false]\n</code></pre> Setting Effect Default true No sharing false Sharing yes"},{"location":"djdknativecbc/","title":"-Djdk.nativeCBC","text":""},{"location":"djdknativecbc/#-djdknativecbc","title":"-Djdk.nativeCBC","text":"<p>This option enables or disables OpenSSL native cryptographic support for the CBC algorithm.</p>"},{"location":"djdknativecbc/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeCBC=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeCBC</code> true yes <code>-Djdk.nativeCBC</code> false"},{"location":"djdknativecbc/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the CBC algorithm. If you want to turn off this algorithm only, set this option to <code>false</code>. To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativechacha20/","title":"-Djdk.nativeChaCha20","text":""},{"location":"djdknativechacha20/#-djdknativechacha20","title":"-Djdk.nativeChaCha20","text":"<p>This option enables or disables OpenSSL native cryptographic support for the ChaCha20 and ChaCha20-Poly1305 algorithms.</p> <p> Restrictions:</p> <ul> <li> These algorithms are not supported on Java\u2122 8. </li> <li>These algorithms are not supported on OpenSSL 1.0.x.</li> </ul>"},{"location":"djdknativechacha20/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeChaCha20=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeChaCha20</code> true yes <code>-Djdk.nativeChaCha20</code> false"},{"location":"djdknativechacha20/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the ChaCha20 and ChaCha20-Poly1305 algorithms. If you want to turn off support for these algorithms only, set this option to <code>false</code>. To turn off support for these and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativecrypto/","title":"-Djdk.nativeCrypto","text":""},{"location":"djdknativecrypto/#-djdknativecrypto","title":"-Djdk.nativeCrypto","text":"<p>This option controls the use of OpenSSL native cryptographic support.</p>"},{"location":"djdknativecrypto/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeCrypto=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeCrypto</code> true yes <code>-Djdk.nativeCrypto</code> false"},{"location":"djdknativecrypto/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the Digest, CBC, GCM, RSA, ChaCha20 and ChaCha20-Poly1305, ECDH key agreement, EC key generation, XDH key agreement, and XDH key generation algorithms. If you want to turn off the OpenSSL implementation, set this option to <code>false</code>.</p> <p> Restriction:  The ChaCha20 and ChaCha20-Poly1305 algorithms are not supported on Java\u2122 8. The XDH key agreement and XDH key generation algorithms also are not supported on Java 8. </p> <p>If you want to turn off the algorithms individually, use the following system properties:</p> <ul> <li><code>-Djdk.nativeCBC</code></li> <li><code>-Djdk.nativeChaCha20</code> ( Not supported on Java 8. )</li> <li><code>-Djdk.nativeGCM</code></li> <li><code>-Djdk.nativeRSA</code></li> <li><code>-Djdk.nativeDigest</code></li> <li><code>-Djdk.nativeEC</code></li> <li><code>-Djdk.nativeECKeyGen</code></li> <li> <code>-Djdk.nativeXDHKeyAgreement</code></li> <li><code>-Djdk.nativeXDHKeyGen</code> </li> </ul>"},{"location":"djdknativedigest/","title":"-Djdk.nativeDigest","text":""},{"location":"djdknativedigest/#-djdknativedigest","title":"-Djdk.nativeDigest","text":"<p>This option enables or disables OpenSSL native cryptographic support for the Digest algorithm.</p>"},{"location":"djdknativedigest/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeDigest=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeDigest</code> true yes <code>-Djdk.nativeDigest</code> false"},{"location":"djdknativedigest/#explanation","title":"Explanation","text":"<p>To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativeec/","title":"-Djdk.nativeEC","text":""},{"location":"djdknativeec/#-djdknativeec","title":"-Djdk.nativeEC","text":"<p>This option enables or disables OpenSSL native cryptographic support for the ECDH key agreement algorithm.</p>"},{"location":"djdknativeec/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeEC=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeEC</code> true yes <code>-Djdk.nativeEC</code> false"},{"location":"djdknativeec/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the ECDH key agreement algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativeeckeygen/","title":"-Djdk.nativeECKeyGen","text":""},{"location":"djdknativeeckeygen/#-djdknativeeckeygen","title":"-Djdk.nativeECKeyGen","text":"<p>This option enables or disables OpenSSL native cryptographic support for the EC key generation algorithm.</p>"},{"location":"djdknativeeckeygen/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeECKeyGen=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeECKeyGen</code> true yes <code>-Djdk.nativeECKeyGen</code> false"},{"location":"djdknativeeckeygen/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the EC key generation algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativegcm/","title":"-Djdk.nativeGCM","text":""},{"location":"djdknativegcm/#-djdknativegcm","title":"-Djdk.nativeGCM","text":"<p>This option enables or disables OpenSSL native cryptographic support for the GCM algorithm.</p>"},{"location":"djdknativegcm/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeGCM=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeGCM</code> true yes <code>-Djdk.nativeGCM</code> false"},{"location":"djdknativegcm/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the GCM algorithm. If you want to turn off this algorithm only, set this option to <code>false</code>. To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativersa/","title":"-Djdk.nativeRSA","text":""},{"location":"djdknativersa/#-djdknativersa","title":"-Djdk.nativeRSA","text":"<p>This option enables or disables OpenSSL native cryptographic support for the RSA algorithm.</p>"},{"location":"djdknativersa/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeRSA=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeRSA</code> true yes <code>-Djdk.nativeRSA</code> false"},{"location":"djdknativersa/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the RSA algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off all the algorithms, see the -Djdk.nativeCrypto system property command line option.</p>"},{"location":"djdknativexdhkeyagreement/","title":"-Djdk.nativeXDHKeyAgreement","text":""},{"location":"djdknativexdhkeyagreement/#-djdknativexdhkeyagreement","title":"-Djdk.nativeXDHKeyAgreement","text":"<p> This option enables or disables OpenSSL native cryptographic support for the XDH key agreement algorithm.</p> <p> Restrictions:</p> <ul> <li>This algorithm is supported on Java\u2122 11 and later.</li> <li>This algorithm is supported on OpenSSL 1.1.1 onwards.</li> </ul>"},{"location":"djdknativexdhkeyagreement/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeXDHKeyAgreement=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeXDHKeyAgreement</code> true yes <code>-Djdk.nativeXDHKeyAgreement</code> false"},{"location":"djdknativexdhkeyagreement/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the XDH key agreement algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"djdknativexdhkeygen/","title":"-Djdk.nativeXDHKeyGen","text":""},{"location":"djdknativexdhkeygen/#-djdknativexdhkeygen","title":"-Djdk.nativeXDHKeyGen","text":"<p> This option enables or disables OpenSSL native cryptographic support for the XDH key generation algorithm.</p> <p> Restrictions:</p> <ul> <li>This algorithm is supported on Java\u2122 11 and later.</li> <li>This algorithm is supported on OpenSSL 1.1.1 onwards.</li> </ul>"},{"location":"djdknativexdhkeygen/#syntax","title":"Syntax","text":"<pre><code>    -Djdk.nativeXDHKeyGen=[true|false]\n</code></pre> Setting value Default <code>-Djdk.nativeXDHKeyGen</code> true yes <code>-Djdk.nativeXDHKeyGen</code> false"},{"location":"djdknativexdhkeygen/#explanation","title":"Explanation","text":"<p>OpenSSL support is enabled by default for the XDH key generation algorithm. If you want to turn off support for this algorithm only, set this option to <code>false</code>. To turn off support for this and other algorithms, see the <code>-Djdk.nativeCrypto</code> system property command line option.</p>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/","title":"-Dorg.eclipse.openj9.criu.ImmutableEnvVars","text":""},{"location":"dorgeclipseopenj9criuimmutableenvvars/#-dorgeclipseopenj9criuimmutableenvvars","title":"-Dorg.eclipse.openj9.criu.ImmutableEnvVars","text":"<p>This system property specifies the environment variables that you want to add to the <code>ImmutableEnvVars</code> list.</p> <p> Restrictions: This option takes effect only when the <code>-XX:+EnableCRIUSupport</code> option is enabled. This option can be used only during the checkpoint phase.</p>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/#syntax","title":"Syntax","text":"<pre><code>    -Dorg.eclipse.openj9.criu.ImmutableEnvVars=&lt;environment_variables&gt;\n</code></pre> <p>Where <code>&lt;environment_variables&gt;</code> is a comma-separated list of environment variables. For example:</p> <pre><code>-Dorg.eclipse.openj9.criu.ImmutableEnvVars=INVOKED,WLP_USER_DIR,WLP_OUTPUT_DIR,LOG_DIR,X_LOG_DIR,LOG_FILE,X_LOG_FILE,VARIABLE_SOURCE_DIRS,X_CMD\n</code></pre> <p>The following environment variables are included in the list by default and cannot be removed:</p> <ul> <li><code>LANG</code></li> <li><code>LC_ALL</code></li> <li><code>LC_CTYPE</code></li> </ul>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/#explanation","title":"Explanation","text":"<p>The environment variables are a property of the operating system environment and not the VM. The VM considers these properties as immutable and does not allow the environment variables to change values between checkpoint and restore.</p> <p>During the checkpoint and restore phases, the VM can detect the environment variables that are in the <code>immutableEnvvars</code> list. You can add any other immutable variables that you want the VM to detect in the <code>ImmutableEnvVars</code> list with the <code>-Dorg.eclipse.openj9.criu.ImmutableEnvVars</code> option. If an environment variable is not in the list, the VM does not detect that variable even if the underlying system has defined it. These environment variables exist for the entire lifetime of the VM (checkpoint and restore).</p> <p>At restore, the VM can also detect the environment variables that are added through the <code>CRIUSupport.registerRestoreEnvVariables</code> API.</p> <p>For more information about how environment variables are handled during the checkpoint and restore process, see the Environment Variables section in the OpenJ9 CRIU Support: A look under the hood\u202f(part II) blog post.</p>"},{"location":"dorgeclipseopenj9criuimmutableenvvars/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"dump_heapdump/","title":"Heap dump","text":""},{"location":"dump_heapdump/#heap-dump","title":"Heap dump","text":"<p>Heap dumps contain a snapshot of all the live objects that are being used by a running Java\u2122 application on the Java heap. You can obtain detailed information for each object instance, such as the address, type, class name, or size, and whether the instance has references to other objects.</p> <p>There are two formats for heap dumps; the classic format and the Portable Heap Dump (PHD) format, which is the default. Whilst the classic format is generated in ascii text and can be read, the PHD format is binary and and must be processed for analysis.</p>"},{"location":"dump_heapdump/#obtaining-dumps","title":"Obtaining dumps","text":"<p>Heap dumps are generated by default in PHD format when the Java heap runs out of space. If you want to trigger the production of a heap dump in response to other situations, or in classic format, you can use one of the following options:</p> <ul> <li>Configure the heap dump agent. For more information, see the -Xdump option.</li> <li>Use the <code>com.ibm.jvm.Dump</code> API programmatically in your application code. For more information, see the  JVM diagnostic utilities API documentation. </li> </ul>"},{"location":"dump_heapdump/#analyzing-dumps","title":"Analyzing dumps","text":"<p>The best method to analyze a PHD heap dump is to use the Eclipse Memory Analyzer\u2122 tool (MAT) or the IBM Memory Analyzer tool. These tools process the dump file and provide a visual representation of the objects in the Java Heap. Both tools require the Diagnostic Tool Framework for Java (DTFJ) plugin. To install the DTFJ plugin in the Eclipse IDE, select the following menu items:</p> <pre><code>Help &gt; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java   \n</code></pre> <p>The following sections contain detailed information about the content of each type of heap dump file.</p>"},{"location":"dump_heapdump/#portable-heap-dump-phd-format","title":"Portable Heap Dump (PHD) format","text":"<p>A PHD format dump file contains a header section and a body section. The body section can contain information about object, array, or class records. Primitive numbers are used to describe the file format, as detailed in the following table:</p> Primitive number Length in bytes <code>byte</code> 1 <code>short</code> 2 <code>int</code> 4 <code>long</code> 8 <code>word</code> 4 (32-bit platforms) or 8 (64-bit platforms)"},{"location":"dump_heapdump/#general-structure","title":"General structure","text":"<p>The following structure comprises the header section of a PHD file:</p> <ul> <li>A UTF string indicating that the file is a <code>portable heap dump</code></li> <li>An <code>int</code> containing the PHD version number</li> <li>An <code>int</code> containing flags:<ul> <li><code>1</code> indicates that the <code>word</code> length is 64-bit.</li> <li><code>2</code> indicates that all the objects in the dump are hashed. This flag is set for heap dumps that use 16-bit hash codes. Eclipse OpenJ9\u2122 heap dumps use 32-bit hash codes that are created only when used. For example, these hash codes are created when the APIs <code>Object.hashCode()</code> or <code>Object.toString()</code> are called in a Java application. If this flag is not set, the presence of a hash code is indicated by the hash code flag on the individual PHD records.</li> <li><code>4</code> indicates that the dump is from an OpenJ9 VM.</li> </ul> </li> <li>A <code>byte</code> containing a tag with a value of <code>1</code> that indicates the start of the header.</li> <li>A number of optional header records, each preceded by a one-byte header tag. Header record tags have a different range of values from the body, or object record tags. The end of the header is indicated by the end of header tag. The following tags are included:<ul> <li><code>header tag 1</code> - not used</li> <li><code>header tag 2</code> - indicates the end of the header</li> <li><code>header tag 3</code> - not used</li> <li><code>header tag 4</code> - indicates the VM version (Variable length UTF string)</li> </ul> </li> </ul> <p>The body of a PHD file is indicated by a <code>byte</code> that contains a tag with a value of 2, after which there are a number of dump records. Dump records are preceded by a 1 byte tag with the following record types:</p> <ul> <li>Short object: <code>0x80</code> bit of the tag is set</li> <li>Medium object: <code>0x40</code> bit of the tag is set (top bit value is 0)</li> <li>Primitive Array: <code>0x20</code> bit if the tag is set (all other tag values have the top 3 bits with a value of 0)</li> <li>Long record: tag value is <code>4</code></li> <li>Class record: tag value is <code>6</code></li> <li>Long primitive array: tag value is <code>7</code></li> <li>Object array: tag value is <code>8</code></li> </ul> <p>These records are described in more detail in the sections that follow.</p> <p>The end of the PHD body is indicated by a <code>byte</code> that contains a tag with a value of 3.</p>"},{"location":"dump_heapdump/#object-records","title":"Object records","text":"<p>Object records can be short, medium, or long, depending on the number of object references in the heap dump.</p> <p>1. Short object record</p> <p>The following information is contained within the tag byte:</p> <ul> <li> <p>The 1 byte tag, which consists of the following bits:</p> Bit number Value or description 1 Bit is set (0x80) 2 and 3 Indicates the class cache index. The value represents an index into a cache of the last 4 classes used. 4 and 5 Contain the number of references. Most objects contain 0 - 3 references. If there are 4 - 7 references, the Medium object record is used. If there are more than 7 references, the Long object record is used. 6 Indicates whether the gap is a 1 <code>byte</code> value or a <code>short</code>. The gap is the difference between the address of this object and the previous object. If set, the gap is a <code>short</code>. If the gap does not fit into a <code>short</code>, the Long object record format is used. 7 and 8 Indicates the size of each reference (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) </li> <li> <p>A <code>byte</code> or a <code>short</code> containing the gap between the address of this object and the address of the preceding object. The value is signed and represents the number of 32-bit words between the two addresses. Most gaps fit into 1 byte.</p> </li> <li>If all objects are hashed, a <code>short</code> containing the hash code.</li> <li>The array of references, if references exist. The tag shows the number of elements, and the size of each element. The value in each element is the gap between the address of the references and the address of the current object. The value is a signed number of 32-bit words. Null references are not included.</li> </ul> <p>2. Medium object record</p> <p>These records provide the actual address of the class rather than a cache index. The following format is used:</p> <ul> <li> <p>The 1 byte tag, consisting of the following bits:</p> Bit number Value or description 1 0 2 Set (0x40) 3, 4, and 5 Contain the number of references 6 Indicates whether the gap is a 1 <code>byte</code> value or a <code>short</code> (see Short object record description) 7 and 8 Indicates the size of each reference (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) </li> <li> <p>A <code>byte</code> or a <code>short</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record description)</p> </li> <li>A <code>word</code> containing the address of the class of this object.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code.</li> <li>The array of references (See the Short object record description).</li> </ul> <p>3. Long object record</p> <p>This record format is used when there are more than 7 references, or if there are extra flags or a hash code. The following format is used:</p> <ul> <li> <p>The 1 byte tag, containing the value 4.</p> </li> <li> <p>A <code>byte</code> containing flags, consisting of the following bits:</p> Bit number Value or description 1 and 2 Indicates whether the gap is a <code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> format 3 and 4 Indicates the size of each reference  (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) 5 and 6 Unused 7 Indicates if the object was hashed and moved. If this bit is set, the record includes the hash code 8 Indicates if the object was hashed </li> <li> <p>A <code>byte</code>, <code>short</code>, <code>int</code>, or <code>long</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record description).</p> </li> <li>A <code>word</code> containing the address of the class of this object.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. Otherwise, an optional <code>int</code> containing the hash code if the hashed and moved bit is set in the record flag byte.</li> <li>An <code>int</code> containing the length of the array of references.</li> <li>The array of references (See the Short object record description).</li> </ul>"},{"location":"dump_heapdump/#array-records","title":"Array records","text":"<p>PHD arrays can be primitive arrays or object arrays, as described in the sections that follow.</p> <p>1. Primitive array record</p> <p>The following information is contained in an array record:</p> <ul> <li> <p>The 1 byte tag, consisting of the following bits:</p> Bit number Value or description 1 and 2 0 3 Set (0x20) 4, 5, and 6 Contains the array type ( 0=bool, 1=char, 2=float, 3=double, 4=<code>byte</code>, 5=<code>short</code>, 6=<code>int</code>, and 7=<code>long</code>) 7 and 8 Indicates the length of the array size and the length of the gap (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) </li> <li> <p><code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record description).</p> </li> <li><code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> containing the array length.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code.</li> <li>An unsigned <code>int</code> containing the size of the instance of the array on the heap, including header and padding. The size is measured in 32-bit words, which you can multiply by four to obtain the size in bytes. This format allows encoding of lengths up to 16GB in an unsigned <code>int</code>.</li> </ul> <p>2. Long primitive array record</p> <p>This type of record is used when a primitive array has been hashed.</p> <ul> <li> <p>The 1 byte tag with a  value of 7.</p> </li> <li> <p>A byte containing the following flags:</p> Bit number Value or description 1, 2, and 3 Contains the array type ( 0=bool, 1=char, 2=float, 3=double, 4=<code>byte</code>, 5=<code>short</code>, 6=<code>int</code>, and 7=<code>long</code>) 4 Indicates the length of the array size and the length of the gap (0=<code>byte</code>, 1=<code>word</code>). 5 and 6 Unused 7 Indicates if the object was hashed and moved. If this bit is set, the record includes the hash code. 8 Indicates if the object was hashed </li> <li> <p>a <code>byte</code> or <code>word</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record  description).</p> </li> <li>a <code>byte</code> or <code>word</code> containing the array length.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. Otherwise, an optional <code>int</code> containing the hash code if the hashed and moved bit is set in the record flag byte.</li> <li>An unsigned <code>int</code> containing the size of the instance of the array on the heap, including header and padding. The size is measured in 32-bit words, which you can multiply by four to obtain the size in bytes. This format allows encoding of lengths up to 16GB in an unsigned <code>int</code>.</li> </ul> <p>3. Object array record</p> <p>The following format applies:</p> <ul> <li> <p>The 1 byte tag with a  value of 8.</p> </li> <li> <p>A byte containing the following flags:</p> Bit number Value or description 1 and 2 Indicates whether the gap is <code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code>. 3 and 4 Indicates the size of each reference  (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) 5 and 6 Unused 7 Indicates if the object was hashed and moved. If this bit is set, the record includes the hash code. 8 Indicates if the object was hashed </li> <li> <p>A <code>byte</code>, <code>short</code>, <code>int</code> or <code>long</code> containing the gap between the address of this object and the address of the preceding object (See the Short object record format description).</p> </li> <li>A <code>word</code> containing the address of the class of the objects in the array. Object array records do not update the class cache.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. If the hashed and moved bit is set in the records flag, this field contains an <code>int</code>.</li> <li>An <code>int</code> containing the length of the array of references.</li> <li>The array of references (See the Short object record description).</li> <li>An unsigned <code>int</code> containing the size of the instance of the array on the heap, including header and padding. The size is measured in 32-bit words, which you can multiply by four to obtain the size in bytes. This format allows encoding of lengths up to 16GB in an unsigned <code>int</code>.</li> <li>An final <code>int</code> value is shown at the end. This <code>int</code> contains the true array length, shown as a number of array elements. The true array length might differ from the length of the array of references because null references are excluded.</li> </ul>"},{"location":"dump_heapdump/#class-records","title":"Class records","text":"<p>The PHD class record encodes a class object and contains the following format:</p> <ul> <li> <p>The 1 byte tag, containing the value 6.</p> </li> <li> <p>A byte containing the following flags:</p> Bit number Value or description 1 and 2 Indicates whether the gap is byte, <code>short</code>, <code>int</code> or <code>long</code> 3 and 4 Indicates the size of each static reference  (0=<code>byte</code>, 1=<code>short</code>, 2=<code>int</code>, 3=<code>long</code>) 5 Indicates if the object was hashed </li> <li> <p>A byte, <code>short</code>, <code>int</code> or <code>long</code> containing the gap between the address of this class and the address of the preceding object (See the Short object record description).</p> </li> <li>An <code>int</code> containing the instance size.</li> <li>If all objects are hashed, a <code>short</code> containing the hash code. Otherwise, an optional <code>int</code> containing the hash code if the hashed and moved bit is set in the record flag byte.</li> <li>A <code>word</code> containing the address of the superclass.</li> <li>A UTF string containing the name of this class.</li> <li>An <code>int</code> containing the number of static references.</li> <li>The array of static references (See the Short object record description).</li> </ul>"},{"location":"dump_heapdump/#classic-heap-dump-format","title":"Classic Heap Dump format","text":"<p>Classic heap dumps are produced in ascii text on all platforms except z/OS, which are encoded in EBCDIC. The dump is divided into the following sections:</p>"},{"location":"dump_heapdump/#header-record","title":"Header record","text":"<p>A single string containing information about the runtime environment, platform, and build levels, similar to the following example:</p> <pre><code>// Version: JRE 1.8.0 Linux amd64-64 (build 1.8.0_232-b09)\n</code></pre>"},{"location":"dump_heapdump/#object-records_1","title":"Object records","text":"<p>A record of each object instance in the heap with the following format:</p> <pre><code>&lt;object address, in hexadecimal&gt; [&lt;length in bytes of object instance, in decimal&gt;] OBJ &lt;object type&gt;\n&lt;heap reference, in hexadecimal&gt; &lt;heap reference, in hexadecimal&gt; ...\n</code></pre> <p>The following object types (<code>object type</code>) might be shown:</p> <ul> <li>class name (including package name)</li> <li>class array type</li> <li>primitive array type</li> </ul> <p>These types are abbreviated in the record. To determine the type, see the Java VM Type Signature table.</p> <p>Any references found are also listed, excluding references to an object's class or NULL references.</p> <p>The following example shows an object instance (16 bytes in length) of type <code>java/lang/String</code>, with a reference to a char array:</p> <pre><code>0x00000000E0000AF0 [16] OBJ java/lang/String\n    0x00000000E0000B00\n</code></pre> <p>The object instance (length 32 bytes) of type char array, as referenced from the <code>java/lang/String</code>, is shown in the following example:</p> <pre><code>0x00000000E0000B00 [32] OBJ [C\n</code></pre> <p>The following example shows an object instance (24 bytes in length) of type array of <code>java/lang/String</code>:</p> <pre><code>0x00000000FFF07498 [24] OBJ [Ljava/lang/String;\n    0x00000000E0005D78 0x00000000E0005D50 0x00000000E0005D28 0x00000000E0005D00\n</code></pre>"},{"location":"dump_heapdump/#class-records_1","title":"Class records","text":"<p>A record of each class in the following format:</p> <pre><code>&lt;class object address, in hexadecimal&gt; [&lt;length in bytes of class object, in decimal&gt;] CLS &lt;class type&gt;\n&lt;heap reference, in hexadecimal&gt; &lt;heap reference, in hexadecimal&gt;...\n</code></pre> <p>The following class types (<code>&lt;class type&gt;</code>) might be shown:</p> <ul> <li>class name (including package name)</li> <li>class array type</li> <li>primitive array types</li> </ul> <p>These types are abbreviated in the record. To determine the type, see the Java VM Type Signature table.</p> <p>Any references found in the class block are also listed, excluding NULL references.</p> <p>The following example shows a class object (80 bytes in length) for <code>java/util/Date</code>, with heap references:</p> <pre><code>0x00000000E00174F0 [80] CLS java/util/Date\n    0x00000000FFF1BB60 0x00000000FFF29630\n</code></pre>"},{"location":"dump_heapdump/#trailer-record-1","title":"Trailer record 1","text":"<p>A single record containing record counts, in decimal.</p> <p>For example:</p> <pre><code>// Breakdown - Classes: 630, Objects: 3692, ObjectArrays: 576, PrimitiveArrays: 2249\n</code></pre>"},{"location":"dump_heapdump/#trailer-record-2","title":"Trailer record 2","text":"<p>A single record containing totals, in decimal.</p> <p>For example:</p> <pre><code>// EOF:  Total 'Objects',Refs(null) : 7147,22040(12379)\n</code></pre> <p>The values in the example reflect the following counts:</p> <ul> <li><code>7147</code> total objects</li> <li><code>22040</code> total references</li> <li><code>(12379)</code> total NULL references as a proportion of the total references count</li> </ul>"},{"location":"dump_heapdump/#java-vm-type-signatures","title":"Java VM Type Signatures","text":"<p>The following table shows the abbreviations used for different Java types in the heap dump records:</p> Java VM Type Signature Java Type <code>Z</code> <code>boolean</code> <code>B</code> <code>byte</code> <code>C</code> <code>char</code> <code>S</code> <code>short</code> <code>I</code> <code>int</code> <code>J</code> <code>long</code> <code>F</code> <code>float</code> <code>D</code> <code>double</code> <code>L&lt;fully-qualified class&gt;;</code> <code>&lt;fully-qualified class&gt;</code> <code>[&lt;type&gt;</code> <code>&lt;type&gt;[](array of &lt;type&gt;)</code> <code>(&lt;arg-types&gt;)&lt;ret-type&gt;</code> <code>method</code>"},{"location":"dump_heapdump/#see-also","title":"See also","text":"<ul> <li>DTFJ interface</li> </ul>"},{"location":"dump_javadump/","title":"Java dump","text":""},{"location":"dump_javadump/#java-dump","title":"Java dump","text":"<p>Java\u2122 dumps, sometimes referred to as Java cores, are produced when the VM ends unexpectedly because of an operating system signal, <code>OutOfMemoryError</code>, or a user-initiated keystroke combination. You can also generate a Java dump by calling the Dump API programmatically from your application or specifying the <code>-Xdump:java</code> option on the command line.</p> <p>If your Java application crashes or hangs, Java dumps can provide useful information to help you diagnose the root cause.</p> <ul> <li>If your application crashes, Java dumps are generated automatically for the following types of failure:<ul> <li>the VM receives an unexpected signal or an assertion failure</li> <li>the VM runs out of memory</li> </ul> </li> <li> <p>If your application hangs, you can trigger the generation of a Java dump by sending a SIGQUIT signal (<code>kill -3</code>) to the VM.</p> <p> Note: On Windows\u00ae, if you started the VM in a console window you can force the VM to produce a Java dump in response to a SIGBREAK signal (Ctrl-Break keyboard combination). If you didn't start in a console window, there is no equivalent to a Linux <code>kill</code> command on Windows for sending signals. The only option here is to trigger a full system dump by finding the VM process in the Processes tab of the Windows Task Manager and clicking Create dump file.</p> </li> </ul> <p>To help you understand how a Java dump can help you with problem diagnosis, this topic includes a few scenarios to help you interpret the data:</p> <ul> <li>A crash caused by a general protection fault (gpf)</li> <li>A Java heap OutOfMemoryError (OOM)</li> <li>A native OutOfMemoryError (OOM)</li> <li>A deadlock situation</li> <li>A hang</li> </ul>"},{"location":"dump_javadump/#java-dump-contents","title":"Java dump contents","text":"<p>Java dumps summarize the state of the VM when the event occurs, with most of the information relating to components of the VM. The file is made up of a number of sections that provide different types of information.</p>"},{"location":"dump_javadump/#title","title":"TITLE","text":"<p>The first section of the Java dump file provides information about the event that triggered the production of the dump. In the following example, you can see that a <code>vmstop</code> event triggered the dump at a specified date and time.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"vmstop\" (00000002) Detail \"#0000000000000000\" received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/doc-javacore/javacore.20210423.140244.1175.0001.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x106 (vm_access+exclusive_vm_access+trace_disabled)\n</code></pre>"},{"location":"dump_javadump/#gpinfo","title":"GPINFO","text":"<p>The GPINFO section provides general information about the system that the VM is running on. The following example is taken from a Java dump that was generated on a Linux system.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       GPINFO subcomponent dump routine\nNULL           ================================\n2XHOSLEVEL     OS Level         : Linux 3.10.0-862.11.6.el7.x86_64\n2XHCPUS        Processors -\n3XHCPUARCH       Architecture   : amd64\n3XHNUMCPUS       How Many       : 4\n3XHNUMASUP       NUMA is either not supported or has been disabled by user\nNULL\n1XHERROR2      Register dump section only produced for SIGSEGV, SIGILL or SIGFPE.\nNULL\n</code></pre> <p>The content of this section can vary, depending on the cause of the dump. For example, if the dump was caused by a general protection fault (gpf), the library in which the crash occurred is also recorded, together with a value shown as <code>VM flags</code>. This value can provide some clues about which component of the VM might have been involved. Look for the following line in the output:</p> <pre><code>1XHFLAGS       VM flags:0000000000000000\n</code></pre> <p>The hexadecimal number that is recorded for <code>VM flags</code> ends in MSSSS, where M is the VM component and SSSS is component-specific code as shown in the following table:</p> Component Code value INTERPRETER 0x10000 GC 0x20000 GROW_STACK 0x30000 JNI 0x40000 JIT_CODEGEN 0x50000 BCVERIFY 0x60000 RTVERIFY 0x70000 SHAREDCLASSES 0x80000 <p>A value of <code>0000000000000000</code> (0x00000) indicates that a crash occurred outside of the VM.</p>"},{"location":"dump_javadump/#envinfo","title":"ENVINFO","text":"<p>This section contains useful information about the environment in which the crash took place, including the following data:</p> <ul> <li>Java version (<code>1CIJAVAVERSION</code>)</li> <li>Eclipse OpenJ9\u2122 VM and subcomponent version information (<code>1CIVMVERSION</code>, <code>1CIJ9VMVERSION</code>, <code>1CIJITVERSION</code>, <code>1CIOMRVERSION</code>, <code>1CIJCLVERSION</code>)</li> <li>VM start time (<code>1CISTARTTIME</code>) and process information (<code>1CIPROCESSID</code>)</li> <li>Java home (<code>1CIJAVAHOMEDIR</code>) and DLL (<code>1CIJAVADLLDIR</code>) directories</li> <li>User arguments passed on the command line (<code>1CIUSERARGS</code>), identifying those that are ignored (<code>1CIIGNOREDARGS</code>)</li> <li>User limits imposed by the system (<code>1CIUSERLIMITS</code>)</li> <li>Environment variables in place (<code>1CIENVVARS</code>)</li> <li>System information (<code>1CISYSINFO</code>)</li> <li>CPU information (<code>1CICPUINFO</code>)</li> <li>Control group (Cgroup) information (<code>1CICGRPINFO</code>)</li> </ul> <p>For clarity, the following example shows a shortened version of this section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       ENVINFO subcomponent dump routine\nNULL           =================================\n1CIJAVAVERSION JRE 9 Linux amd64-64 (build 9.0.4-internal+0-adhoc..openj9-openjdk-jdk9)\n1CIVMVERSION   20180830_000000\n1CIJ9VMVERSION 8e7c6ec\n1CIJITVERSION  8e7c6ec\n1CIOMRVERSION  553811b_CMPRSS\n1CIJCLVERSION  ec1d223 based on jdk-9.0.4+12\n1CIJITMODES    JIT enabled, AOT enabled, FSD disabled, HCR enabled\n1CIRUNNINGAS   Running as a standalone JVM\n1CIVMIDLESTATE VM Idle State: ACTIVE\n1CICONTINFO    Running in container : FALSE\n1CICGRPINFO    JVM support for cgroups enabled : TRUE\n1CISTARTTIME   JVM start time: 2018/08/30 at 21:55:47:387\n1CISTARTNANO   JVM start nanotime: 22012135233549\n1CIPROCESSID   Process ID: 30285 (0x764D)\n1CICMDLINE     [not available]\n1CIJAVAHOMEDIR Java Home Dir:   /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk\n1CIJAVADLLDIR  Java DLL Dir:    /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/bin\n1CISYSCP       Sys Classpath:\n1CIUSERARGS    UserArgs:\n2CIUSERARG               -Xoptionsfile=/home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/options.default\n...\n1CIIGNOREDARGS Ignored Args:\n2CIIGNOREDARG            -XX:+UseCompressedOop\n2CIIGNOREDARG            -XX:CompressedClassSpaceSize=528482304\nNULL\n1CIUSERLIMITS  User Limits (in bytes except for NOFILE and NPROC)\nNULL           ------------------------------------------------------------------------\nNULL           type                            soft limit           hard limit\n2CIUSERLIMIT   RLIMIT_AS                        unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_CORE                              0            unlimited\n2CIUSERLIMIT   RLIMIT_CPU                       unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_DATA                      unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_FSIZE                     unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_LOCKS                     unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_MEMLOCK                       65536                65536\n2CIUSERLIMIT   RLIMIT_NOFILE                         4096                 4096\n2CIUSERLIMIT   RLIMIT_NPROC                          4096                30592\n2CIUSERLIMIT   RLIMIT_RSS                       unlimited            unlimited\n2CIUSERLIMIT   RLIMIT_STACK                       8388608            unlimited\n2CIUSERLIMIT   RLIMIT_MSGQUEUE                     819200               819200\n2CIUSERLIMIT   RLIMIT_NICE                              0                    0\n2CIUSERLIMIT   RLIMIT_RTPRIO                            0                    0\n2CIUSERLIMIT   RLIMIT_SIGPENDING                    30592                30592\nNULL\n1CIENVVARS     Environment Variables\nNULL           ------------------------------------------------------------------------\n2CIENVVAR      XDG_VTNR=1\n2CIENVVAR      SSH_AGENT_PID=2653\n...\nNULL\n1CISYSINFO     System Information\nNULL           ------------------------------------------------------------------------\n2CISYSINFO     /proc/sys/kernel/core_pattern = core\n2CISYSINFO     /proc/sys/kernel/core_uses_pid = 1\nNULL\n1CICPUINFO     CPU Information\nNULL           ------------------------------------------------------------------------\n2CIPHYSCPU     Physical CPUs: 8\n2CIONLNCPU     Online CPUs: 8\n2CIBOUNDCPU    Bound CPUs: 8\n2CIACTIVECPU   Active CPUs: 0\n2CITARGETCPU   Target CPUs: 8\n2CIJITFEATURE  CPU features (JIT): fpu cx8 cmov mmx sse sse2 ssse3 fma sse4_1 popcnt aesni osxsave avx avx2 rdt_m\n2CIAOTFEATURE  CPU features (AOT): fpu cx8 cmov mmx sse sse2 ssse3 fma sse4_1 popcnt aesni osxsave avx avx2 rdt_m\nNULL\n1CICGRPINFO    Cgroup Information\nNULL           ------------------------------------------------------------------------\n2CICGRPINFO    subsystem : cpu\n2CICGRPINFO    cgroup name : /\n3CICGRPINFO    CPU Period : 100000 microseconds\n3CICGRPINFO    CPU Quota : Not Set\n3CICGRPINFO    CPU Shares : 1024\n3CICGRPINFO    Period intervals elapsed count : 0\n3CICGRPINFO    Throttled count : 0\n3CICGRPINFO    Total throttle time : 0 nanoseconds\n2CICGRPINFO    subsystem : cpuset\n2CICGRPINFO    cgroup name : /\n3CICGRPINFO    CPU exclusive : 1\n3CICGRPINFO    Mem exclusive : 1\n3CICGRPINFO    CPUs : 0-7\n3CICGRPINFO    Mems : 0\n2CICGRPINFO    subsystem : memory\n2CICGRPINFO    cgroup name : /\n3CICGRPINFO    Memory Limit : Not Set\n3CICGRPINFO    Memory + Swap Limit : Not Set\n3CICGRPINFO    Memory Usage : 5363396608 bytes\n3CICGRPINFO    Memory + Swap Usage : 5363396608 bytes\n3CICGRPINFO    Memory Max Usage : 0 bytes\n3CICGRPINFO    Memory + Swap Max Usage : 0 bytes\n3CICGRPINFO    Memory limit exceeded count : 0\n3CICGRPINFO    Memory + Swap limit exceeded count : 0\n3CICGRPINFO    OOM Killer Disabled : 0\n3CICGRPINFO    Under OOM : 0\nNULL\n</code></pre>"},{"location":"dump_javadump/#nativememinfo","title":"NATIVEMEMINFO","text":"<p>This section records information about native memory that is requested by using library functions such as <code>malloc()</code> and <code>mmap()</code>. Values are provided as a breakdown, per component, indicating the total number of bytes allocated and the number of native memory allocations. In the following example, 4,682,840 bytes of native memory are allocated (but not yet freed) to VM Classes, which correspond to 141 allocations.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       NATIVEMEMINFO subcomponent dump routine\nNULL           =================================\n0MEMUSER\n1MEMUSER       JRE: 2,569,088,312 bytes / 4653 allocations\n1MEMUSER       |\n2MEMUSER       +--VM: 2,280,088,336 bytes / 2423 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Classes: 4,682,840 bytes / 141 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Memory Manager (GC): 2,054,966,784 bytes / 433 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Heap: 2,014,113,792 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 40,852,992 bytes / 432 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Threads: 10,970,016 bytes / 156 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Stack: 197,760 bytes / 16 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Native Stack: 10,616,832 bytes / 17 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 155,424 bytes / 123 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Trace: 180,056 bytes / 263 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JVMTI: 17,776 bytes / 13 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JNI: 36,184 bytes / 52 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Port Library: 208,179,632 bytes / 72 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Unused &lt;32bit allocation regions: 208,168,752 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 10,880 bytes / 71 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 1,055,048 bytes / 1293 allocations\n1MEMUSER       |\n2MEMUSER       +--JIT: 288,472,816 bytes / 140 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Code Cache: 268,435,456 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Data Cache: 2,097,216 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 17,940,144 bytes / 138 allocations\n1MEMUSER       |\n2MEMUSER       +--Class Libraries: 13,432 bytes / 25 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--VM Class Libraries: 13,432 bytes / 25 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--sun.misc.Unsafe: 3,184 bytes / 13 allocations\n4MEMUSER       |  |  |  |\n5MEMUSER       |  |  |  +--Direct Byte Buffers: 1,056 bytes / 12 allocations\n4MEMUSER       |  |  |  |\n5MEMUSER       |  |  |  +--Other: 2,128 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 10,248 bytes / 12 allocations\n1MEMUSER       |\n2MEMUSER       +--Unknown: 513,728 bytes / 2065 allocations\nNULL\n</code></pre> <p>This section does not record memory that is allocated by application or JNI code and is typically a little less than the value recorded by operating system tools.</p>"},{"location":"dump_javadump/#meminfo","title":"MEMINFO","text":"<p>This section relates to memory management, providing a breakdown of memory usage in the VM for the object heap, internal memory, memory used for classes, the JIT code cache, and JIT data cache in decimal and hexadecimal format. You can also find out which garbage collection policy is in use when the dump is produced.</p> <p>The object memory area (<code>1STHEAPTYPE</code>) records each memory region in use, its start and end address, and region size. Further information is recorded about the memory segments that are used for internal memory, class memory, the JIT code cache, and JIT data cache (<code>1STSEGMENT</code>). This information includes the address of the segment control data structure, the start and end address of the native memory segment, as well as the segment size.</p> <p>For clarity, the following example shows a shortened version of this section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       MEMINFO subcomponent dump routine\nNULL           =================================\nNULL\n1STHEAPTYPE    Object Memory\nNULL           id                 start              end                size               space/region\n1STHEAPSPACE   0x00007FF4F00744A0         --                 --                 --         Generational\n1STHEAPREGION  0x00007FF4F0074CE0 0x0000000087F40000 0x0000000088540000 0x0000000000600000 Generational/Tenured Region\n1STHEAPREGION  0x00007FF4F0074930 0x00000000FFE00000 0x00000000FFF00000 0x0000000000100000 Generational/Nursery Region\n1STHEAPREGION  0x00007FF4F0074580 0x00000000FFF00000 0x0000000100000000 0x0000000000100000 Generational/Nursery Region\nNULL\n1STHEAPTOTAL   Total memory:                     8388608 (0x0000000000800000)\n1STHEAPINUSE   Total memory in use:              2030408 (0x00000000001EFB48)\n1STHEAPFREE    Total memory free:                6358200 (0x00000000006104B8)\nNULL\n1STSEGTYPE     Internal Memory\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F004CBC8 0x00007FF4CD33C000 0x00007FF4CD33C000 0x00007FF4CE33C000 0x01000440 0x0000000001000000\n1STSEGMENT     0x00007FF4F004CB08 0x00007FF4DE43D030 0x00007FF4DE517770 0x00007FF4DE53D030 0x00800040 0x0000000000100000\nNULL\n1STSEGTOTAL    Total memory:                    17825792 (0x0000000001100000)\n1STSEGINUSE    Total memory in use:               894784 (0x00000000000DA740)\n1STSEGFREE     Total memory free:               16931008 (0x00000000010258C0)\nNULL\n1STSEGTYPE     Class Memory\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F03B5638 0x0000000001053D98 0x000000000105BD98 0x000000000105BD98 0x00010040 0x0000000000008000\n1STSEGMENT     0x00007FF4F03B5578 0x0000000001048188 0x0000000001050188 0x0000000001050188 0x00010040 0x0000000000008000\n...\nNULL\n1STSEGTOTAL    Total memory:                     3512520 (0x00000000003598C8)\n1STSEGINUSE    Total memory in use:              3433944 (0x00000000003465D8)\n1STSEGFREE     Total memory free:                  78576 (0x00000000000132F0)\nNULL\n1STSEGTYPE     JIT Code Cache\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F00961F8 0x00007FF4CE43D000 0x00007FF4CE445790 0x00007FF4DE43D000 0x00000068 0x0000000010000000\nNULL\n1STSEGTOTAL    Total memory:                   268435456 (0x0000000010000000)\n1STSEGINUSE    Total memory in use:                34704 (0x0000000000008790)\n1STSEGFREE     Total memory free:              268400752 (0x000000000FFF7870)\n1STSEGLIMIT    Allocation limit:               268435456 (0x0000000010000000)\nNULL\n1STSEGTYPE     JIT Data Cache\nNULL           segment            start              alloc              end                type       size\n1STSEGMENT     0x00007FF4F0096668 0x00007FF4CC553030 0x00007FF4CC753030 0x00007FF4CC753030 0x00000048 0x0000000000200000\nNULL\n1STSEGTOTAL    Total memory:                     2097152 (0x0000000000200000)\n1STSEGINUSE    Total memory in use:              2097152 (0x0000000000200000)\n1STSEGFREE     Total memory free:                      0 (0x0000000000000000)\n1STSEGLIMIT    Allocation limit:               402653184 (0x0000000018000000)\nNULL\n1STGCHTYPE     GC History\nNULL\n</code></pre> <p>In the example, the GC History (<code>1STGCHTYPE</code>) section is blank. This section is populated if a garbage collection cycle occurred in a VM that is being diagnosed with the trace facility.</p>"},{"location":"dump_javadump/#locks","title":"LOCKS","text":"<p>This section of the Java dump provides information about locks, which protect shared resources from being accessed by more than one entity at a time. The information is essential in a deadlock situation, where two threads attempt to synchronize on an object and lock an instance of a class. Precise information is recorded about the threads that are causing the problem, which enables you to identify the root cause.</p> <p>The following example shows a typical LOCKS section, where no deadlocks existed at the time the dump was triggered. For clarity, the following example shows a shortened version of this section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       LOCKS subcomponent dump routine\nNULL           ===============================\nNULL\n1LKPOOLINFO    Monitor pool info:\n2LKPOOLTOTAL     Current total number of monitors: 3\nNULL\n1LKMONPOOLDUMP Monitor Pool Dump (flat &amp; inflated object-monitors):\n2LKMONINUSE      sys_mon_t:0x00007FF4B0001D78 infl_mon_t: 0x00007FF4B0001DF8:\n3LKMONOBJECT       java/lang/ref/ReferenceQueue@0x00000000FFE26A10: &lt;unowned&gt;\n3LKNOTIFYQ            Waiting to be notified:\n3LKWAITNOTIFY            \"Common-Cleaner\" (J9VMThread:0x0000000000FD0100)\nNULL\n1LKREGMONDUMP  JVM System Monitor Dump (registered monitors):\n2LKREGMON          Thread global lock (0x00007FF4F0004FE8): &lt;unowned&gt;\n2LKREGMON          &amp;(PPG_mem_mem32_subAllocHeapMem32.monitor) lock (0x00007FF4F0005098): &lt;unowned&gt;\n2LKREGMON          NLS hash table lock (0x00007FF4F0005148): &lt;unowned&gt;\n...\nNULL\n</code></pre>"},{"location":"dump_javadump/#threads","title":"THREADS","text":"<p>The THREADS section of a Java dump file provides summary information about the VM thread pool and detailed information about Java threads, native threads, and stack traces. Understanding the content of this section can help you diagnose problems that are caused by blocked or waiting threads.</p> <p>A Java thread runs on a native thread. Several lines are recorded for each Java thread in the <code>Thread Details</code> subsection, which include the following key pieces of information:</p> <ul> <li><code>3XMTHREADINFO</code>: The thread name, address information for the VM thread structures and Java thread object, the thread state, and thread priority.</li> <li><code>3XMJAVALTHREAD</code>: The Java thread ID and daemon status from the thread object.</li> <li><code>3XMTHREADINFO1</code>: The native operating system thread ID, priority, scheduling policy, internal VM thread state, and VM thread flags.</li> <li><code>3XMTHREADINFO2</code>: The native stack address range.</li> <li><code>3XMTHREADINFO3</code>: Java call stack information (<code>4XESTACKTRACE</code>) or Native call stack information (<code>4XENATIVESTACK</code>).</li> <li><code>5XESTACKTRACE</code>: This line indicates whether locks were taken by a specific method.</li> </ul> <p>Java thread priorities are mapped to operating system priority values. Thread states are shown in the following table:</p> Thread state value Status Description R Runnable The thread is able to run CW Condition Wait The thread is waiting S Suspended The thread is suspended by another thread Z Zombie The thread is destroyed P Parked The thread is parked by <code>java.util.concurrent</code> B Blocked The thread is waiting to obtain a lock <p>For threads that are parked (P), blocked (B), or waiting (CW), an additional line (<code>3XMTHREADBLOCK</code>) is included in the output that shows what the thread is parked on, blocked on, or waiting for. For threads that are waiting for a class initialization lock (<code>java/lang/J9VMInternals$ClassInitializationLock</code>), this line includes the name of the thread that is currently working to progress the initialization of the class. You can use this information to diagnose deadlocks that are caused by class initialization, which might not be detected and reported in the LOCKS section.</p> <p>For clarity, the following example shows a shortened version of a typical THREADS section, where <code>...</code> indicates that lines are removed:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 19\n2XMPOOLLIVE        Current total number of live threads: 18\n2XMPOOLDAEMON      Current total number of live daemon threads: 15\nNULL\n1XMTHDINFO     Thread Details\nNULL\n...\n3XMTHREADINFO      \"JIT Diagnostic Compilation Thread-007 Suspended\" J9VMThread:0x0000000000035200, omrthread_t:0x00007F3F8C0D02C8, java/lang/Thread:0x00000000FFF42120, state:R, prio=10\n3XMJAVALTHREAD            (java/lang/Thread getId:0x9, isDaemon:true)\n3XMJAVALTHRCCL            sun/misc/Launcher$AppClassLoader(0x00000000FFF3BF98)\n3XMTHREADINFO1            (native thread ID:0x618F, native priority:0xB, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000081)\n3XMTHREADINFO2            (native stack address range from:0x00007F3F879C5000, to:0x00007F3F87AC5000, size:0x100000)\n3XMCPUTIME               CPU usage total: 0.052410771 secs, current category=\"JIT\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           No Java callstack associated with this thread\n...\nNULL\n...\n3XMTHREADINFO      \"Class Initialization Thread 2\" J9VMThread:0x0000000000124D00, omrthread_t:0x00007F3F8C1494C8, java/lang/Thread:0x00000000FFF53EE8, state:CW, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x13, isDaemon:false)\n3XMJAVALTHRCCL            sun/misc/Launcher$AppClassLoader(0x00000000FFF3BF98)\n3XMTHREADINFO1            (native thread ID:0x6199, native priority:0x5, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000181)\n3XMTHREADINFO2            (native stack address range from:0x00007F3F74AB4000, to:0x00007F3F74AF4000, size:0x40000)\n3XMCPUTIME               CPU usage total: 0.008712260 secs, current category=\"Application\"\n3XMTHREADBLOCK     Waiting on: java/lang/J9VMInternals$ClassInitializationLock@0x00000000FFF61C90 Owned by: &lt;unowned&gt; Initializing thread: \"Class Initialization Thread 1\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=4096 (0x1000)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/Class.forNameImpl(Native Method)\n4XESTACKTRACE                at java/lang/Class.forName(Class.java:339)\n4XESTACKTRACE                at ClassInitLockBug$ClassInitThread.run(ClassInitLockBug.java:16)\n...\nNULL\n...\nNULL\n3XMTHREADINFO      \"Class Initialization Thread 1\" J9VMThread:0x0000000000124100, omrthread_t:0x00007F3F8C148F50, java/lang/Thread:0x00000000FFF53D80, state:CW, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x12, isDaemon:false)\n3XMJAVALTHRCCL            sun/misc/Launcher$AppClassLoader(0x00000000FFF3BF98)\n3XMTHREADINFO1            (native thread ID:0x6198, native priority:0x5, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000481)\n3XMTHREADINFO2            (native stack address range from:0x00007F3F74AF5000, to:0x00007F3F74B35000, size:0x40000)\n3XMCPUTIME               CPU usage total: 0.010221701 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=12736 (0x31C0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/Thread.sleepImpl(Native Method)\n4XESTACKTRACE                at java/lang/Thread.sleep(Thread.java:983)\n4XESTACKTRACE                at java/lang/Thread.sleep(Thread.java:966)\n4XESTACKTRACE                at TestClass.&lt;clinit&gt;(ClassInitLockBug.java:29)\n4XESTACKTRACE                at java/lang/Class.forNameImpl(Native Method)\n4XESTACKTRACE                at java/lang/Class.forName(Class.java:339)\n4XESTACKTRACE                at ClassInitLockBug$ClassInitThread.run(ClassInitLockBug.java:16)\n...\nNULL\n...\nNULL\n1XMTHDSUMMARY  Threads CPU Usage Summary\nNULL           =========================\nNULL\n1XMTHDCATINFO  Warning: to get more accurate CPU times for the GC, the option -XX:-ReduceCPUMonitorOverhead can be used. See the user guide for more information.\nNULL\n1XMTHDCATEGORY All JVM attached threads: 0.698865000 secs\n1XMTHDCATEGORY |\n2XMTHDCATEGORY +--System-JVM: 0.653723000 secs\n2XMTHDCATEGORY |  |\n3XMTHDCATEGORY |  +--GC: 0.047248000 secs\n2XMTHDCATEGORY |  |\n3XMTHDCATEGORY |  +--JIT: 0.512971000 secs\n1XMTHDCATEGORY |\n2XMTHDCATEGORY +--Application: 0.045142000 secs\n</code></pre>"},{"location":"dump_javadump/#hooks","title":"HOOKS","text":"<p>This section shows internal VM event callbacks, which are used for diagnosing performance problems in the VM. Multiple hook interfaces are listed, which include their individual hook events.</p> <p>The following example shows data for the <code>J9VMHookInterface</code>, including the total time for all previous events, the call site location (&lt;source file&gt;:&lt;line number&gt;), start time, and duration of the last callback and the longest callback (all times measured in microseconds). The hook data is reset after each Java dump.</p> <pre><code>NULL           ------------------------------------------------------------------------\nSECTION HOOK   subcomponent dump routine\nNULL           =========================\n1NOTE          These data are reset every time a javacore is taken\n1HKINTERFACE   MM_OMRHookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   MM_PrivateHookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   MM_HookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   J9VMHookInterface\nNULL           ------------------------------------------------------------------------\n2HKEVENTID     1\n3HKCALLCOUNT       1239\n3HKTOTALTIME       219564us\n3HKLAST            Last Callback\n4HKCALLSITE            trcengine.c:395\n4HKSTARTTIME           Start Time: 2019-10-18T00:15:14.664\n4HKDURATION            Duration : 16us\n3HKLONGST          Longest Callback\n4HKCALLSITE            trcengine.c:395\n4HKSTARTTIME           Start Time: 2019-10-18T21:28:34.895\n4HKDURATION            Duration : 5012us\nNULL\n...\n1HKINTERFACE   J9VMZipCachePoolHookInterface\nNULL           ------------------------------------------------------------------------\n1HKINTERFACE   J9JITHookInterface\nNULL           ------------------------------------------------------------------------\n2HKEVENTID     3\n3HKCALLCOUNT       3113\n3HKTOTALTIME       4904us\n3HKLAST            Last Callback\n4HKCALLSITE            common/mgmtinit.c:193\n4HKSTARTTIME           Start Time: 2019-10-18T16:04:15.320\n4HKDURATION            Duration : 3us\n3HKLONGST          Longest Callback\n4HKCALLSITE            common/mgmtinit.c:193\n4HKSTARTTIME           Start Time: 2019-10-18T16:37:17.633\n4HKDURATION            Duration : 27us\nNULL\n...\n</code></pre>"},{"location":"dump_javadump/#shared-classes","title":"SHARED CLASSES","text":"<p>If the shared classes cache is enabled at run time, the information that is provided in a Java dump file describes settings that were used when creating the cache, together with summary information about the size and content of the cache.</p> <p>In the following example, the shared classes cache was created with a Class Debug Area (<code>-Xnolinenumbers=false</code>). Byte code instrumentation (BCI) is enabled, which is the default, and VMs sharing the cache are allowed to store classpaths, which is also the default.</p> <p>The <code>Cache Summary</code> shows a cache size (<code>2SCLTEXTCSZ</code>) of 16776608 bytes, with a soft maximum size (<code>2SCLTEXTSMB</code>) also of 16776608 bytes, which leaves 12691668 bytes of free space (<code>2SCLTEXTFRB</code>). The size of the Class Debug Area (<code>2SCLTEXTDAS</code>) is 1331200 bytes and only 11% of this space is used.</p> <p>In the <code>Cache Memory Status</code> subsection, the line <code>2SCLTEXTCMDT</code> indicates the name and location of the shared cache and <code>cr</code> indicates that the cache is a 64-bit compressed references cache.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       SHARED CLASSES subcomponent dump routine\nNULL           ========================================\nNULL\n1SCLTEXTCRTW   Cache Created With\nNULL           ------------------\nNULL\n2SCLTEXTXNL        -Xnolinenumbers       = false\n2SCLTEXTBCI        BCI Enabled           = true\n2SCLTEXTBCI        Restrict Classpaths   = false\nNULL\n1SCLTEXTCSUM   Cache Summary\nNULL           ------------------\nNULL\n2SCLTEXTNLC        No line number content                    = false\n2SCLTEXTLNC        Line number content                       = true\nNULL\n2SCLTEXTRCS        ROMClass start address                    = 0x00007F423061C000\n2SCLTEXTRCE        ROMClass end address                      = 0x00007F42307B9A28\n2SCLTEXTMSA        Metadata start address                    = 0x00007F42313D42FC\n2SCLTEXTCEA        Cache end address                         = 0x00007F4231600000\n2SCLTEXTRTF        Runtime flags                             = 0x00102001ECA6028B\n2SCLTEXTCGN        Cache generation                          = 35\nNULL\n2SCLTEXTCSZ        Cache size                                = 16776608\n2SCLTEXTSMB        Softmx bytes                              = 16776608\n2SCLTEXTFRB        Free bytes                                = 12691668\n2SCLTEXTRCB        ROMClass bytes                            = 1694248\n2SCLTEXTAOB        AOT code bytes                            = 0\n2SCLTEXTADB        AOT data bytes                            = 0\n2SCLTEXTAHB        AOT class hierarchy bytes                 = 32\n2SCLTEXTATB        AOT thunk bytes                           = 0\n2SCLTEXTARB        Reserved space for AOT bytes              = -1\n2SCLTEXTAMB        Maximum space for AOT bytes               = -1\n2SCLTEXTJHB        JIT hint bytes                            = 308\n2SCLTEXTJPB        JIT profile bytes                         = 2296\n2SCLTEXTJRB        Reserved space for JIT data bytes         = -1\n2SCLTEXTJMB        Maximum space for JIT data bytes          = -1\n2SCLTEXTNOB        Java Object bytes                         = 0\n2SCLTEXTZCB        Zip cache bytes                           = 919328\n2SCLTEXTSHB        Startup hint bytes                        = 0\n2SCLTEXTRWB        ReadWrite bytes                           = 114080\n2SCLTEXTJCB        JCL data bytes                            = 0\n2SCLTEXTBDA        Byte data bytes                           = 0\n2SCLTEXTMDA        Metadata bytes                            = 23448\n2SCLTEXTDAS        Class debug area size                     = 1331200\n2SCLTEXTDAU        Class debug area % used                   = 11%\n2SCLTEXTDAN        Class LineNumberTable bytes               = 156240\n2SCLTEXTDAV        Class LocalVariableTable bytes            = 0\nNULL\n2SCLTEXTNRC        Number ROMClasses                         = 595\n2SCLTEXTNAM        Number AOT Methods                        = 0\n2SCLTEXTNAD        Number AOT Data Entries                   = 0\n2SCLTEXTNAH        Number AOT Class Hierarchy                = 1\n2SCLTEXTNAT        Number AOT Thunks                         = 0\n2SCLTEXTNJH        Number JIT Hints                          = 14\n2SCLTEXTNJP        Number JIT Profiles                       = 20\n2SCLTEXTNCP        Number Classpaths                         = 1\n2SCLTEXTNUR        Number URLs                               = 0\n2SCLTEXTNTK        Number Tokens                             = 0\n2SCLTEXTNOJ        Number Java Objects                       = 0\n2SCLTEXTNZC        Number Zip Caches                         = 5\n2SCLTEXTNSH        Number Startup Hint Entries               = 0\n2SCLTEXTNJC        Number JCL Entries                        = 0\n2SCLTEXTNST        Number Stale classes                      = 0\n2SCLTEXTPST        Percent Stale classes                     = 0%\nNULL\n2SCLTEXTCPF        Cache is 24% full\nNULL\n1SCLTEXTCMST   Cache Memory Status\nNULL           ------------------\n1SCLTEXTCNTD       Cache Name                    Feature                  Memory type              Cache path\nNULL\n2SCLTEXTCMDT       sharedcc_doc-javacore         CR                       Memory mapped file       /tmp/javasharedresources/C290M4F1A64P_sharedcc_doc-javacore_G35\nNULL\n1SCLTEXTCMST   Cache Lock Status\nNULL           ------------------\n1SCLTEXTCNTD       Lock Name                     Lock type                TID owning lock\nNULL\n2SCLTEXTCWRL       Cache write lock              File lock                Unowned\n2SCLTEXTCRWL       Cache read/write lock         File lock                Unowned\nNULL\n</code></pre> <p>The following example shows information for a layered cache:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       SHARED CLASSES subcomponent dump routine\nNULL           ========================================\nNULL\n1SCLTEXTCSTL   Cache Statistics for Top Layer\nNULL\n1SCLTEXTCRTW       Cache Created With\nNULL               ------------------\nNULL\n2SCLTEXTXNL            -Xnolinenumbers       = false\n2SCLTEXTBCI            BCI Enabled           = true\n2SCLTEXTBCI            Restrict Classpaths   = false\nNULL\n1SCLTEXTCSUM       Cache Summary\nNULL               ------------------\nNULL\n2SCLTEXTNLC            No line number content                    = false\n2SCLTEXTLNC            Line number content                       = false\nNULL\n2SCLTEXTRCS            ROMClass start address                    = 0x00007F0EDB567000\n2SCLTEXTRCE            ROMClass end address                      = 0x00007F0EDB567000\n2SCLTEXTMSA            Metadata start address                    = 0x00007F0EDC40241C\n2SCLTEXTCEA            Cache end address                         = 0x00007F0EDC54B000\n2SCLTEXTRTF            Runtime flags                             = 0x80102001ECA602BB\n2SCLTEXTCGN            Cache generation                          = 41\n2SCLTEXTCLY            Cache layer                               = 1\nNULL\n2SCLTEXTCSZ            Cache size                                = 16776608\n2SCLTEXTSMB            Softmx bytes                              = 16776608\n2SCLTEXTFRB            Free bytes                                = 15315996\n2SCLTEXTARB            Reserved space for AOT bytes              = -1\n2SCLTEXTAMB            Maximum space for AOT bytes               = -1\n2SCLTEXTJRB            Reserved space for JIT data bytes         = -1\n2SCLTEXTJMB            Maximum space for JIT data bytes          = -1\n2SCLTEXTRWB            ReadWrite bytes                           = 114080\n2SCLTEXTDAS            Class debug area size                     = 1331200\n2SCLTEXTDAU            Class debug area % used                   = 0%\n2SCLTEXTDAN            Class LineNumberTable bytes               = 0\n2SCLTEXTDAV            Class LocalVariableTable bytes            = 0\nNULL\n2SCLTEXTCPF            Cache is 8% full\nNULL\n1SCLTEXTCMST       Cache Memory Status\nNULL               ------------------\n1SCLTEXTCNTD           Cache Name                    Feature                  Memory type              Cache path\nNULL\n2SCLTEXTCMDT           Cache1                        CR                       Memory mapped file       /tmp/javasharedresources/C290M4F1A64P_Cache1_G41L01\nNULL\n1SCLTEXTCMST       Cache Lock Status\nNULL               ------------------\n1SCLTEXTCNTD           Lock Name                     Lock type                TID owning lock\nNULL\n2SCLTEXTCWRL           Cache write lock              File lock                Unowned\n2SCLTEXTCRWL           Cache read/write lock         File lock                Unowned\nNULL\n1SCLTEXTCSAL   Cache Statistics for All Layers\nNULL\n2SCLTEXTRCB            ROMClass bytes                            = 1459040\n2SCLTEXTAOB            AOT code bytes                            = 57624\n2SCLTEXTADB            AOT data bytes                            = 272\n2SCLTEXTAHB            AOT class hierarchy bytes                 = 1840\n2SCLTEXTATB            AOT thunk bytes                           = 632\n2SCLTEXTJHB            JIT hint bytes                            = 484\n2SCLTEXTJPB            JIT profile bytes                         = 0\n2SCLTEXTNOB            Java Object bytes                         = 0\n2SCLTEXTZCB            Zip cache bytes                           = 1134016\n2SCLTEXTSHB            Startup hint bytes                        = 0\n2SCLTEXTJCB            JCL data bytes                            = 0\n2SCLTEXTBDA            Byte data bytes                           = 0\nNULL\n2SCLTEXTNRC            Number ROMClasses                         = 503\n2SCLTEXTNAM            Number AOT Methods                        = 16\n2SCLTEXTNAD            Number AOT Data Entries                   = 1\n2SCLTEXTNAH            Number AOT Class Hierarchy                = 28\n2SCLTEXTNAT            Number AOT Thunks                         = 11\n2SCLTEXTNJH            Number JIT Hints                          = 15\n2SCLTEXTNJP            Number JIT Profiles                       = 0\n2SCLTEXTNCP            Number Classpaths                         = 1\n2SCLTEXTNUR            Number URLs                               = 0\n2SCLTEXTNTK            Number Tokens                             = 0\n2SCLTEXTNOJ            Number Java Objects                       = 0\n2SCLTEXTNZC            Number Zip Caches                         = 21\n2SCLTEXTNSH            Number Startup Hint Entries               = 0\n2SCLTEXTNJC            Number JCL Entries                        = 0\n2SCLTEXTNST            Number Stale classes                      = 0\n2SCLTEXTPST            Percent Stale classes                     = 0%\n</code></pre>"},{"location":"dump_javadump/#classes","title":"CLASSES","text":"<p>The classes section shows information about class loaders. The first part is a summary that records each available class loader (<code>2CLTEXTCLLOADER</code>) followed by the number of libraries and classes that it loaded. This information is followed by a more detailed list of libraries (<code>1CLTEXTCLLIB</code>) and classes (<code>1CLTEXTCLLO</code>) that are loaded.</p> <p>In the example you can see that the <code>java/lang/InternalAnonymousClassLoader</code> loaded two classes, <code>jdk/internal/loader/BuiltinClassLoader$$Lambda$2/00000000F03876A0(0x0000000001030F00)</code> and <code>jdk/internal/loader/BuiltinClassLoader$$Lambda$1/00000000F00D2460(0x0000000001018A00)</code>.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       CLASSES subcomponent dump routine\nNULL           =================================\n1CLTEXTCLLOS    Classloader summaries\n1CLTEXTCLLSS        12345678: 1=primordial,2=extension,3=shareable,4=middleware,5=system,6=trusted,7=application,8=delegating\n2CLTEXTCLLOADER     p---st-- Loader *System*(0x00000000FFE1D258)\n3CLNMBRLOADEDLIB        Number of loaded libraries 5\n3CLNMBRLOADEDCL         Number of loaded classes 638\n2CLTEXTCLLOADER     -x--st-- Loader jdk/internal/loader/ClassLoaders$PlatformClassLoader(0x00000000FFE1D4F0), Parent *none*(0x0000000000000000)\n3CLNMBRLOADEDLIB        Number of loaded libraries 0\n3CLNMBRLOADEDCL         Number of loaded classes 0\n2CLTEXTCLLOADER     ----st-- Loader java/lang/InternalAnonymousClassLoader(0x00000000FFE1DFD0), Parent *none*(0x0000000000000000)\n3CLNMBRLOADEDLIB        Number of loaded libraries 0\n3CLNMBRLOADEDCL         Number of loaded classes 2\n2CLTEXTCLLOADER     -----ta- Loader jdk/internal/loader/ClassLoaders$AppClassLoader(0x00000000FFE1DAD0), Parent jdk/internal/loader/ClassLoaders$PlatformClassLoader(0x00000000FFE1D4F0)\n3CLNMBRLOADEDLIB        Number of loaded libraries 0\n3CLNMBRLOADEDCL         Number of loaded classes 0\n1CLTEXTCLLIB    ClassLoader loaded libraries\n2CLTEXTCLLIB        Loader *System*(0x00000000FFE1D258)\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/compressedrefs/jclse9_29\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/java\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/compressedrefs/j9jit29\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/zip\n3CLTEXTLIB              /home/me/openj9-openjdk-jdk9/build/linux-x86_64-normal-server-release/images/jdk/lib/nio\n1CLTEXTCLLOD    ClassLoader loaded classes\n2CLTEXTCLLOAD       Loader *System*(0x00000000FFE1D258)\n3CLTEXTCLASS            [Ljava/lang/Thread$State;(0x0000000001056400)\n...\n2CLTEXTCLLOAD       Loader jdk/internal/loader/ClassLoaders$PlatformClassLoader(0x00000000FFE1D4F0)\n2CLTEXTCLLOAD       Loader java/lang/InternalAnonymousClassLoader(0x00000000FFE1DFD0)\n3CLTEXTCLASS            jdk/internal/loader/BuiltinClassLoader$$Lambda$2/00000000F03876A0(0x0000000001030F00)\n3CLTEXTCLASS            jdk/internal/loader/BuiltinClassLoader$$Lambda$1/00000000F00D2460(0x0000000001018A00)\n2CLTEXTCLLOAD       Loader jdk/internal/loader/ClassLoaders$AppClassLoader(0x00000000FFE1DAD0)\n</code></pre>"},{"location":"dump_javadump/#scenarios","title":"Scenarios","text":""},{"location":"dump_javadump/#general-protection-fault","title":"General Protection Fault","text":"<p>In this scenario, a Java application has crashed due to a General Protection Fault (GPF), automatically generating a Java dump file.</p> <p>The first section of the file (TITLE) tells you that the GPF triggered the Java dump.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"gpf\" (00002000) received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/test/JNICrasher/javacore.20210423.140244.29399.0002.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x100 (trace_disabled)\n1TIPREPINFO    Exclusive VM access not taken: data may not be consistent across javacore sections\n</code></pre> <p>To troubleshoot this problem, you need to know which thread caused the GPF to occur. The thread that was running at the time of the crash is reported as the current thread in the THREADS section of the Java dump. Here is an extract from the THREADS section:</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 16\n2XMPOOLLIVE        Current total number of live threads: 15\n2XMPOOLDAEMON      Current total number of live daemon threads: 14\nNULL\n1XMCURTHDINFO  Current thread\n3XMTHREADINFO      \"main\" J9VMThread:0xB6B60E00, omrthread_t:0xB6B049D8, java/lang/Thread:0xB55444D0, state:R, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x1, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x72D8, native priority:0x5, native policy:UNKNOWN, vmstate:R, vm thread flags:0x00000000)\n3XMTHREADINFO2            (native stack address range from:0xB6CE3000, to:0xB74E4000, size:0x801000)\n3XMCPUTIME               CPU usage total: 0.319865924 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=778008 (0xBDF18)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at JNICrasher.doSomethingThatCrashes(Native Method)\n4XESTACKTRACE                at JNICrasher.main(JNICrasher.java:7)\n3XMTHREADINFO3           Native callstack:\n4XENATIVESTACK               (0xB6C6F663 [libj9prt29.so+0x3b663])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6C6F1CE [libj9prt29.so+0x3b1ce])\n4XENATIVESTACK               (0xB6C6F2C6 [libj9prt29.so+0x3b2c6])\n4XENATIVESTACK               (0xB6C6ED93 [libj9prt29.so+0x3ad93])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6C6ED07 [libj9prt29.so+0x3ad07])\n4XENATIVESTACK               (0xB6C6AA3D [libj9prt29.so+0x36a3d])\n4XENATIVESTACK               (0xB6C6C3A4 [libj9prt29.so+0x383a4])\n4XENATIVESTACK               (0xB667FA19 [libj9dmp29.so+0xfa19])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB66878CF [libj9dmp29.so+0x178cf])\n4XENATIVESTACK               (0xB6688083 [libj9dmp29.so+0x18083])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6680C0D [libj9dmp29.so+0x10c0d])\n4XENATIVESTACK               (0xB667F9D7 [libj9dmp29.so+0xf9d7])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB668B02F [libj9dmp29.so+0x1b02f])\n4XENATIVESTACK               (0xB668B4D3 [libj9dmp29.so+0x1b4d3])\n4XENATIVESTACK               (0xB66740F1 [libj9dmp29.so+0x40f1])\n4XENATIVESTACK               (0xB66726FA [libj9dmp29.so+0x26fa])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB66726A9 [libj9dmp29.so+0x26a9])\n4XENATIVESTACK               (0xB6676AE4 [libj9dmp29.so+0x6ae4])\n4XENATIVESTACK               (0xB668D75A [libj9dmp29.so+0x1d75a])\n4XENATIVESTACK               (0xB6A28DD4 [libj9vm29.so+0x81dd4])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6A289EE [libj9vm29.so+0x819ee])\n4XENATIVESTACK               (0xB6A29A40 [libj9vm29.so+0x82a40])\n4XENATIVESTACK               (0xB6C52B6A [libj9prt29.so+0x1eb6a])\n4XENATIVESTACK               __kernel_rt_sigreturn+0x0 (0xB7747410)\n4XENATIVESTACK               (0xB75330B6 [libffi29.so+0x50b6])\n4XENATIVESTACK               ffi_raw_call+0xad (0xB7531C53 [libffi29.so+0x3c53])\n4XENATIVESTACK               (0xB69BE4AB [libj9vm29.so+0x174ab])\n4XENATIVESTACK               (0xB6A665BC [libj9vm29.so+0xbf5bc])\n4XENATIVESTACK               (0xB6A15552 [libj9vm29.so+0x6e552])\n4XENATIVESTACK               (0xB6A30894 [libj9vm29.so+0x89894])\n4XENATIVESTACK               (0xB6A6F169 [libj9vm29.so+0xc8169])\n4XENATIVESTACK               (0xB6C52F6E [libj9prt29.so+0x1ef6e])\n4XENATIVESTACK               (0xB6A6F1FA [libj9vm29.so+0xc81fa])\n4XENATIVESTACK               (0xB6A30994 [libj9vm29.so+0x89994])\n4XENATIVESTACK               (0xB6A2CE4C [libj9vm29.so+0x85e4c])\n4XENATIVESTACK               (0xB770487D [libjli.so+0x787d])\n4XENATIVESTACK               (0xB7719F72 [libpthread.so.0+0x6f72])\n4XENATIVESTACK               clone+0x5e (0xB763543E [libc.so.6+0xee43e])\n</code></pre> <p>The extract tells you that the current thread was <code>java/lang/Thread</code>, and information is provided about the Java call stack and native call stack (<code>3XMTHREADINFO3</code>) at the point at which the crash occurred. To simulate a crash caused by a bug in an application, this example calls a JNI method whose native implementation causes a crash. The Java call stack shows the call to the JNI native method (<code>JNIcrasher</code>), and the native call stack shows the point of failure. In this example, the native call stack does not include any function names to help you isolate the error in the native code. You can get this information from a system dump, which is usually produced alongside the Java dump. Open the system dump with the Dump viewer and use the <code>info thread</code> command to print the Java and native stack for the current thread.</p> <p>The next time you run the application, you can use the -XX:+ShowNativeStackSymbols=all command line option to display the corresponding function names in the native call stack.</p> <pre><code>4XENATIVESTACK               protectedBacktrace+0x12 (0x00007F3F9213E312 [libj9prt29.so+0x25312])\n4XENATIVESTACK               omrsig_protect+0x1e3 (0x00007F3F92142AD3 [libj9prt29.so+0x29ad3])\n4XENATIVESTACK               omrintrospect_backtrace_thread_raw+0xbf (0x00007F3F9213E80F [libj9prt29.so+0x2580f])\n4XENATIVESTACK               omrsig_protect+0x1e3 (0x00007F3F92142AD3 [libj9prt29.so+0x29ad3])\n4XENATIVESTACK               omrintrospect_backtrace_thread+0x70 (0x00007F3F9213E1D0 [libj9prt29.so+0x251d0])\n4XENATIVESTACK               setup_native_thread+0x1d2 (0x00007F3F9213F652 [libj9prt29.so+0x26652])\n4XENATIVESTACK               omrintrospect_threads_startDo_with_signal+0x474 (0x00007F3F921403F4 [libj9prt29.so+0x273f4])\n4XENATIVESTACK               omrsig_protect+0x1e3 (0x00007F3F92142AD3 [libj9prt29.so+0x29ad3])\n</code></pre>"},{"location":"dump_javadump/#java-outofmemoryerror","title":"Java OutOfMemoryError","text":"<p>In this scenario, the Java heap runs out of memory, causing an <code>OutOfMemoryError</code>, which automatically generates a Java dump file.</p> <p>The first section of the file (TITLE) tells you that a <code>systhrow</code> event triggered the Java dump as a result of an OOM (<code>java/lang/OutOfMemoryError</code>) for Java heap space.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"systhrow\" (00040000) Detail \"java/lang/OutOfMemoryError\" \"Java heap space\" received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/cheesemp/test/javacore.20210423.140244.18885.0003.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x104 (exclusive_vm_access+trace_disabled)\n</code></pre> <p>The MEMINFO section records how much memory is allocated to the Java heap (<code>1STHEAPTYPE Object Memory</code>), how much is in use, and how much is free. Solving your problem might be as simple as setting a larger heap size when you start your application.</p> <p>If you don't know what size the Java heap was set to, you might find that information in the ENVINFO section, which records the command-line options that were used when the application started. Look or search for the <code>1CIUSERARGS    UserArgs:</code> string and review the entries that are recorded for all lines that start <code>2CIUSERARG</code>. The Java heap size is set by the <code>-Xmx</code> option. If the size has not been set on the command line by <code>-Xmx</code>, the default value applies, which you can find in Default Settings.</p> <p>In this scenario, the solution to the problem is not an adjustment to the Java heap size. Here is the MEMINFO section:</p> <pre><code>0SECTION       MEMINFO subcomponent dump routine\nNULL           =================================\nNULL\n1STHEAPTYPE    Object Memory\nNULL           id         start      end        size       space/region\n1STHEAPSPACE   0xB6B49D20     --         --         --     Generational\n1STHEAPREGION  0xB6B4A078 0x95750000 0xB5470000 0x1FD20000 Generational/Tenured Region\n1STHEAPREGION  0xB6B49F10 0xB5470000 0xB54C0000 0x00050000 Generational/Nursery Region\n1STHEAPREGION  0xB6B49DA8 0xB54C0000 0xB5750000 0x00290000 Generational/Nursery Region\nNULL\n1STHEAPTOTAL   Total memory:         536870912 (0x20000000)\n1STHEAPINUSE   Total memory in use:  302603160 (0x12095B98)\n1STHEAPFREE    Total memory free:    234267752 (0x0DF6A468)\n</code></pre> <p>The output shows that only 56% of the Java heap is in use, so this suggests that the application is trying to do something suboptimal. To investigate further, you need to work out which thread was the current thread when the OOM occurred to see what it was trying to do. As in the previous scenario, you can find the current thread in the THREADS section. Here is an extract from the output:</p> <pre><code>0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 16\n2XMPOOLLIVE        Current total number of live threads: 16\n2XMPOOLDAEMON      Current total number of live daemon threads: 15\nNULL\n1XMCURTHDINFO  Current thread\n3XMTHREADINFO      \"main\" J9VMThread:0xB6B60C00, omrthread_t:0xB6B049D8, java/lang/Thread:0x95764520, state:R, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x1, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x49C6, native priority:0x5, native policy:UNKNOWN, vmstate:R, vm thread flags:0x00001020)\n3XMTHREADINFO2            (native stack address range from:0xB6CB5000, to:0xB74B6000, size:0x801000)\n3XMCPUTIME               CPU usage total: 8.537823831 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/StringBuffer.ensureCapacityImpl(StringBuffer.java:696)\n4XESTACKTRACE                at java/lang/StringBuffer.append(StringBuffer.java:486(Compiled Code))\n5XESTACKTRACE                   (entered lock: java/lang/StringBuffer@0x957645B8, entry count: 1)\n4XESTACKTRACE                at java/lang/StringBuffer.append(StringBuffer.java:428(Compiled Code))\n4XESTACKTRACE                at HeapBreaker.main(HeapBreaker.java:34(Compiled Code))\n3XMTHREADINFO3           Native callstack:\n4XENATIVESTACK               (0xB6C535B3 [libj9prt29.so+0x3b5b3])\n4XENATIVESTACK               (0xB6C36F3E [libj9prt29.so+0x1ef3e])\n4XENATIVESTACK               (0xB6C5311E [libj9prt29.so+0x3b11e])\n4XENATIVESTACK               (0xB6C53216 [libj9prt29.so+0x3b216])\n4XENATIVESTACK               (0xB6C52CE3 [libj9prt29.so+0x3ace3])\n4XENATIVESTACK               (0xB6C36F3E [libj9prt29.so+0x1ef3e])\n4XENATIVESTACK               (0xB6C52C57 [libj9prt29.so+0x3ac57])\n4XENATIVESTACK               (0xB6C4E9CD [libj9prt29.so+0x369cd])\n4XENATIVESTACK               (0xB6C502FA [libj9prt29.so+0x382fa])\n</code></pre> <p>To simulate a Java <code>OutOfMemoryError</code>, this example application repeatedly appends characters to a <code>StringBuffer</code> object in an infinite loop. The Java call stack shows the <code>HeapBreaker.main</code> method appending characters (<code>java/lang/StringGuffer.append</code>) until the method <code>java/lang/StringBuffer.ensureCapacityImpl()</code> throws the <code>OutOfMemoryError</code>.</p> <p>StringBuffer objects are wrappers for character arrays (<code>char[]</code>) and when the capacity of the underlying array is reached, the contents are automatically copied into a new, larger array. The new array is created in the <code>StringBuffer.ensureCapacity()</code> method, which more or less doubles the size of the old array. In this scenario, the array takes up all the remaining space in the Java heap.</p> <p>The MEMINFO section of the Java dump file can also tell you when an unexpectedly large allocation request causes an OOM. Look for the GC History (<code>1STGCHTYPE</code>) section, which details allocation requests that trigger GC activity. In the sample output you can see that a large allocation request (<code>requestedbytes=603979784</code>) triggered a global GC. When the GC could not free up sufficient space in the heap to satisfy the request, the allocation failure generated the OOM.</p> <pre><code>1STGCHTYPE     GC History\n3STHSTTYPE     14:29:29:580239000 GMT j9mm.101 -   J9AllocateIndexableObject() returning NULL! 0 bytes requested for object of class B6BBC300 from memory space 'Generational' id=B6B49D20\n3STHSTTYPE     14:29:29:579916000 GMT j9mm.134 -   Allocation failure end: newspace=2686912/3014656 oldspace=231597224/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:579905000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2686912/3014656 oldspace=231597224/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:579859000 GMT j9mm.475 -   GlobalGC end: workstackoverflow=0 overflowcount=0 memory=234284136/536870912\n3STHSTTYPE     14:29:29:579807000 GMT j9mm.90 -   GlobalGC collect complete\n3STHSTTYPE     14:29:29:579776000 GMT j9mm.137 -   Compact end: bytesmoved=301989896\n3STHSTTYPE     14:29:29:313899000 GMT j9mm.136 -   Compact start: reason=compact to meet allocation\n3STHSTTYPE     14:29:29:313555000 GMT j9mm.57 -   Sweep end\n3STHSTTYPE     14:29:29:310772000 GMT j9mm.56 -   Sweep start\n3STHSTTYPE     14:29:29:310765000 GMT j9mm.94 -   Class unloading end: classloadersunloaded=0 classesunloaded=0\n3STHSTTYPE     14:29:29:310753000 GMT j9mm.60 -   Class unloading start\n3STHSTTYPE     14:29:29:310750000 GMT j9mm.55 -   Mark end\n3STHSTTYPE     14:29:29:306013000 GMT j9mm.54 -   Mark start\n3STHSTTYPE     14:29:29:305957000 GMT j9mm.474 -   GlobalGC start: globalcount=9\n3STHSTTYPE     14:29:29:305888000 GMT j9mm.475 -   GlobalGC end: workstackoverflow=0 overflowcount=0 memory=234284136/536870912\n3STHSTTYPE     14:29:29:305837000 GMT j9mm.90 -   GlobalGC collect complete\n3STHSTTYPE     14:29:29:305808000 GMT j9mm.137 -   Compact end: bytesmoved=189784\n3STHSTTYPE     14:29:29:298042000 GMT j9mm.136 -   Compact start: reason=compact to meet allocation\n3STHSTTYPE     14:29:29:297695000 GMT j9mm.57 -   Sweep end\n3STHSTTYPE     14:29:29:291696000 GMT j9mm.56 -   Sweep start\n3STHSTTYPE     14:29:29:291692000 GMT j9mm.55 -   Mark end\n3STHSTTYPE     14:29:29:284994000 GMT j9mm.54 -   Mark start\n3STHSTTYPE     14:29:29:284941000 GMT j9mm.474 -   GlobalGC start: globalcount=8\n3STHSTTYPE     14:29:29:284916000 GMT j9mm.135 -   Exclusive access: exclusiveaccessms=0.016 meanexclusiveaccessms=0.016 threads=0 lastthreadtid=0xB6B61100 beatenbyotherthread=0\n3STHSTTYPE     14:29:29:284914000 GMT j9mm.469 -   Allocation failure cycle start: newspace=2678784/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=603979784\n3STHSTTYPE     14:29:29:284893000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2678784/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:284858000 GMT j9mm.560 -   LocalGC end: rememberedsetoverflow=0 causedrememberedsetoverflow=0 scancacheoverflow=0 failedflipcount=0 failedflipbytes=0 failedtenurecount=0 failedtenurebytes=0 flipcount=2 flipbytes=64 newspace=2678784/3014656 oldspace=80601248/533856256 loa=5338112/5338112 tenureage=0\n3STHSTTYPE     14:29:29:284140000 GMT j9mm.140 -   Tilt ratio: 89\n3STHSTTYPE     14:29:29:283160000 GMT j9mm.64 -   LocalGC start: globalcount=8 scavengecount=335 weakrefs=0 soft=0 phantom=0 finalizers=0\n3STHSTTYPE     14:29:29:283123000 GMT j9mm.135 -   Exclusive access: exclusiveaccessms=0.016 meanexclusiveaccessms=0.016 threads=0 lastthreadtid=0xB6B61100 beatenbyotherthread=0\n3STHSTTYPE     14:29:29:283120000 GMT j9mm.469 -   Allocation failure cycle start: newspace=753616/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=603979784\n3STHSTTYPE     14:29:29:283117000 GMT j9mm.133 -   Allocation failure start: newspace=753616/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=603979784\n3STHSTTYPE     14:29:29:269762000 GMT j9mm.134 -   Allocation failure end: newspace=2686928/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:269751000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:269718000 GMT j9mm.560 -   LocalGC end: rememberedsetoverflow=0 causedrememberedsetoverflow=0 scancacheoverflow=0 failedflipcount=0 failedflipbytes=0 failedtenurecount=0 failedtenurebytes=0 flipcount=0 flipbytes=0 newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112 tenureage=0\n3STHSTTYPE     14:29:29:268981000 GMT j9mm.140 -   Tilt ratio: 89\n3STHSTTYPE     14:29:29:268007000 GMT j9mm.64 -   LocalGC start: globalcount=8 scavengecount=334 weakrefs=0 soft=0 phantom=0 finalizers=0\n3STHSTTYPE     14:29:29:267969000 GMT j9mm.135 -   Exclusive access: exclusiveaccessms=0.016 meanexclusiveaccessms=0.016 threads=0 lastthreadtid=0xB6B61100 beatenbyotherthread=0\n3STHSTTYPE     14:29:29:267966000 GMT j9mm.469 -   Allocation failure cycle start: newspace=0/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=48\n3STHSTTYPE     14:29:29:267963000 GMT j9mm.133 -   Allocation failure start: newspace=0/3014656 oldspace=80601248/533856256 loa=5338112/5338112 requestedbytes=48\n3STHSTTYPE     14:29:29:249015000 GMT j9mm.134 -   Allocation failure end: newspace=2686928/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:249003000 GMT j9mm.470 -   Allocation failure cycle end: newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112\n3STHSTTYPE     14:29:29:248971000 GMT j9mm.560 -   LocalGC end: rememberedsetoverflow=0 causedrememberedsetoverflow=0 scancacheoverflow=0 failedflipcount=0 failedflipbytes=0 failedtenurecount=0 failedtenurebytes=0 flipcount=0 flipbytes=0 newspace=2686976/3014656 oldspace=80601248/533856256 loa=5338112/5338112 tenureage=0\n</code></pre> <p>Although the Java code that was used in this scenario deliberately triggered an <code>OutOfMemoryError</code> in a pronounced way, similar allocation issues can and do occur when dealing with large data sets such as XML files.</p> <p>The next step in diagnosing the problem is to open the system dump that gets generated automatically when an <code>OutOfMemoryError</code> occurs. Open the dump with the Eclipse Memory Analyzer\u2122 tool (MAT) and search for the <code>StringBuffer</code> object, which should provide further clues about what went wrong. A common example is seeing the same <code>String</code> duplicated over and over again, which might indicate that code is stuck in a loop.</p> <p> Note: If you want to use MAT to analyze your system dump, you must install the Diagnostic Tool Framework for Java (DTFJ) plug-in in the Eclipse IDE. Select the following menu items:</p> <pre><code>Help &gt; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt;\n</code></pre> <p>If, unlike the previous scenario, you receive an <code>OutOfMemoryError</code> and the MEMINFO section shows that there is very little space left on the Java heap, the current thread information is typically not important. The current thread is simply the thread that happened to be current when the space ran out. In this situation, you might want to increase your Java heap size. For help with this task, see How to do heap sizing.</p>"},{"location":"dump_javadump/#native-outofmemoryerror","title":"Native OutOfMemoryError","text":"<p>In this scenario, the VM runs out of native memory. Native memory is memory that is used by the VM for storing all virtualized resources and data that it needs for VM operations. Native memory that is available to the VM process is limited by the operating system. The native memory available to the VM might also be subject to additional limits imposed by the operating system, for example Unix <code>ulimits</code>.</p> <p>When a <code>NativeOutOfMemoryError</code> occurs, a Java dump is generated by default. The first section of the file (TITLE) tells you that a systhrow event triggered the Java dump as a result of an OOM (<code>java/lang/OutOfMemoryError</code>) for native memory.</p> <pre><code>0SECTION       TITLE subcomponent dump routine\nNULL           ===============================\n1TICHARSET     UTF-8\n1TISIGINFO     Dump Event \"systhrow\" (00040000) Detail \"java/lang/OutOfMemoryError\" \"native memory exhausted\" received\n1TIDATETIMEUTC Date: 2021/04/23 at 18:02:44:017 (UTC)\n1TIDATETIME    Date: 2021/04/23 at 14:02:44:017\n1TITIMEZONE    Timezone: UTC-4 (EDT)\n1TINANOTIME    System nanotime: 379202644260787\n1TIFILENAME    Javacore filename:    /home/cheesemp/test/javacore.20210423.140244.19708.0003.txt\n1TIREQFLAGS    Request Flags: 0x81 (exclusive+preempt)\n1TIPREPSTATE   Prep State: 0x104 (exclusive_vm_access+trace_disabled)\n</code></pre> <p>Sometimes, the current thread is responsible for causing the <code>NativeOutOfMemoryError</code>. Information about the current thread can be found in the THREADS section, as shown in the following output.</p> <pre><code>0SECTION       THREADS subcomponent dump routine\nNULL           =================================\nNULL\n1XMPOOLINFO    JVM Thread pool info:\n2XMPOOLTOTAL       Current total number of pooled threads: 16\n2XMPOOLLIVE        Current total number of live threads: 16\n2XMPOOLDAEMON      Current total number of live daemon threads: 15\nNULL\n1XMCURTHDINFO  Current thread\n3XMTHREADINFO      \"main\" J9VMThread:0xB6C60C00, omrthread_t:0xB6C049D8, java/lang/Thread:0xB55E3C10, state:R, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x1, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x4CFD, native priority:0x5, native policy:UNKNOWN, vmstate:R, vm thread flags:0x00001020)\n3XMTHREADINFO2            (native stack address range from:0xB6D4E000, to:0xB754F000, size:0x801000)\n3XMCPUTIME               CPU usage total: 3.654896026 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at sun/misc/Unsafe.allocateDBBMemory(Native Method)\n4XESTACKTRACE                at java/nio/DirectByteBuffer.&lt;init&gt;(DirectByteBuffer.java:127(Compiled Code))\n4XESTACKTRACE                at java/nio/ByteBuffer.allocateDirect(ByteBuffer.java:311)\n4XESTACKTRACE                at NativeHeapBreaker.main(NativeHeapBreaker.java:9)\n3XMTHREADINFO3           Native callstack:\n4XENATIVESTACK               (0xB6A9F5B3 [libj9prt29.so+0x3b5b3])\n...\n4XENATIVESTACK               (0xB582CC9C [libjclse7b_29.so+0x40c9c])\n4XENATIVESTACK               Java_sun_misc_Unsafe_allocateDBBMemory+0x88 (0xB5827F6B [libjclse7b_29.so+0x3bf6b])\n4XENATIVESTACK               (0x94A2084A [&lt;unknown&gt;+0x0])\n4XENATIVESTACK               (0xB6B2538B [libj9vm29.so+0x6c38b])\n4XENATIVESTACK               (0xB6B4074C [libj9vm29.so+0x8774c])\n4XENATIVESTACK               (0xB6B7F299 [libj9vm29.so+0xc6299])\n4XENATIVESTACK               (0xB6A82F3E [libj9prt29.so+0x1ef3e])\n4XENATIVESTACK               (0xB6B7F32A [libj9vm29.so+0xc632a])\n4XENATIVESTACK               (0xB6B4084C [libj9vm29.so+0x8784c])\n4XENATIVESTACK               (0xB6B3CD0C [libj9vm29.so+0x83d0c])\n4XENATIVESTACK               (0xB776F87D [libjli.so+0x787d])\n4XENATIVESTACK               (0xB7784F72 [libpthread.so.0+0x6f72])\n4XENATIVESTACK               clone+0x5e (0xB76A043E [libc.so.6+0xee43e])\n</code></pre> <p>For clarity in the <code>Native callstack</code> output, <code>...</code> indicates that some lines are removed.</p> <p>The Java call stack shows the transition from Java to native code (<code>sun/misc/Unsafe.allocateDBBMemory(Native Method)</code>), indicating a request for Direct Byte Buffer (DBB) storage. DBB storage is backed by native memory, with the Java heap containing only a reference to the native heap buffer. In this scenario, DBB storage is the likely culprit for this <code>NativeOutOfMemoryError</code>.</p> <p>The next step is to investigate the NATIVEMEMINFO section of the Java dump file, which reports the amount of memory used by the JRE process, broken down into component areas.</p> <pre><code>0SECTION       NATIVEMEMINFO subcomponent dump routine\nNULL           =================================\n0MEMUSER\n1MEMUSER       JRE: 3,166,386,688 bytes / 4388 allocations\n1MEMUSER       |\n2MEMUSER       +--VM: 563,176,824 bytes / 1518 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Classes: 3,104,416 bytes / 120 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Memory Manager (GC): 548,181,888 bytes / 398 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Heap: 536,932,352 bytes / 1 allocation\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 11,249,536 bytes / 397 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Threads: 10,817,120 bytes / 147 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Java Stack: 115,584 bytes / 16 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Native Stack: 10,616,832 bytes / 17 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 84,704 bytes / 114 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Trace: 163,688 bytes / 268 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JVMTI: 17,320 bytes / 13 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JNI: 23,296 bytes / 55 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Port Library: 8,576 bytes / 74 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 860,520 bytes / 443 allocations\n1MEMUSER       |\n2MEMUSER       +--JIT: 3,744,728 bytes / 122 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Code Cache: 2,097,152 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--JIT Data Cache: 524,336 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--Other: 1,123,240 bytes / 120 allocations\n1MEMUSER       |\n2MEMUSER       +--Class Libraries: 2,599,463,024 bytes / 2732 allocations\n2MEMUSER       |  |\n3MEMUSER       |  +--Harmony Class Libraries: 1,024 bytes / 1 allocation\n2MEMUSER       |  |\n3MEMUSER       |  +--VM Class Libraries: 2,599,462,000 bytes / 2731 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--sun.misc.Unsafe: 2,598,510,480 bytes / 2484 allocations\n4MEMUSER       |  |  |  |\n5MEMUSER       |  |  |  +--Direct Byte Buffers: 2,598,510,480 bytes / 2484 allocations\n3MEMUSER       |  |  |\n4MEMUSER       |  |  +--Other: 951,520 bytes / 247 allocations\n1MEMUSER       |\n2MEMUSER       +--Unknown: 2,112 bytes / 16 allocations\nNULL\n</code></pre> <p>In the <code>VM Class Libraries</code> section, the amount of memory allocated for <code>Direct Byte Buffers</code> is shown. Because the <code>NativeOutOfMemoryError</code> was received on a small 32-bit system, a value of <code>2,598,510,480 bytes</code> indicates that the operating system has run out of memory. On a larger UNIX\u00ae system, the process might have run out of memory because of the <code>ulimit</code> setting. Increasing the value for <code>ulimit</code> might avoid the error, which you can do temporarily by setting <code>ulimit -f unlimited</code> in your current session.</p> <p>The theoretical maximum size for a 32-bit process is the size of the 32-bit address space, which is 4 GB. On most operating systems, a portion of the address space for each process is used by the kernel, such that the real limit for 32-bit processes is actually significantly less than 4 GB. As a result, running out of native memory with a 32-bit VM is quite common.</p> <p>The same 4 GB limit is also important if you are using a 64-bit VM with compressed references. In compressed references mode, all references to objects, classes, threads, and monitors are represented by 32-bit values for performance reasons, so these structures can be allocated only at 32-bit addresses. However, the operating system might place other allocations within this 4 GB of address space, and if this area becomes sufficiently full or fragmented, the VM throws a native <code>NativeOutOfMemoryError</code> error. These errors typically occur when the VM tries to create a new thread or load a class. The Current Thread History section should contain more information about what the thread was doing at the VM level when the <code>NativeOutOfMemoryError</code> error occurred.</p> <p>You can usually avoid this type of problem by using the <code>-Xmcrs</code> option to reserve a contiguous area of memory within the lowest 4 GB of memory at VM startup.</p> <p>Another common cause of a <code>NativeOutOfMemoryError</code> is when an application loads duplicate classes. Classes are allocated outside of the Java heap in native memory. If the value reported for <code>Classes</code> in the NATIVEMEMINFO section is very large, duplicate classes might be the cause of your problem. The Eclipse Memory Analyzer tool (MAT) can tell you if you have duplicate classes by using the Class Loader Explorer feature. Because a system dump is automatically generated as well as a Java dump in response to a <code>NativeOutOfMemoryError</code>, simply open the system dump in MAT to continue your diagnosis.</p>"},{"location":"dump_javadump/#deadlock","title":"Deadlock","text":"<p>Deadlocks occur when two threads attempt to synchronize on an object and lock an instance of a class. When this happens, your application stops responding and hangs. Generating a Java dump file will quickly tell you whether you have a deadlock situation. Trigger the Java dump by sending a SIGQUIT signal (<code>kill -3</code>) to the VM.</p> <p>The VM can detect the most common types of deadlock scenario involving Java monitors. If this type of deadlock is detected, information is provided in the LOCKS section. More complex deadlocks, including those that involve a mixture of native mutexes and Java monitors, are not detected.</p> <p>Here is the output from the code that was used to cause a common deadlock scenario:</p> <pre><code>NULL\n1LKDEADLOCK    Deadlock detected !!!\nNULL           ---------------------\nNULL\n2LKDEADLOCKTHR  Thread \"Worker Thread 2\" (0x94501D00)\n3LKDEADLOCKWTR    is waiting for:\n4LKDEADLOCKMON      sys_mon_t:0x08C2B344 infl_mon_t: 0x08C2B384:\n4LKDEADLOCKOBJ      java/lang/Object@0xB5666698\n3LKDEADLOCKOWN    which is owned by:\n2LKDEADLOCKTHR  Thread \"Worker Thread 3\" (0x94507500)\n3LKDEADLOCKWTR    which is waiting for:\n4LKDEADLOCKMON      sys_mon_t:0x08C2B3A0 infl_mon_t: 0x08C2B3E0:\n4LKDEADLOCKOBJ      java/lang/Object@0xB5666678\n3LKDEADLOCKOWN    which is owned by:\n2LKDEADLOCKTHR  Thread \"Worker Thread 1\" (0x92A3EC00)\n3LKDEADLOCKWTR    which is waiting for:\n4LKDEADLOCKMON      sys_mon_t:0x08C2B2E8 infl_mon_t: 0x08C2B328:\n4LKDEADLOCKOBJ      java/lang/Object@0xB5666688\n3LKDEADLOCKOWN    which is owned by:\n2LKDEADLOCKTHR  Thread \"Worker Thread 2\" (0x94501D00)\n</code></pre> <p>This output tells you that <code>Worker Thread 2</code> is waiting for <code>Worker Thread 3</code>, which is waiting for <code>Worker Thread 1</code>. Because <code>Worker Thread 1</code> is also waiting for <code>Worker Thread 2</code>, there is a deadlock. The next place to look is the output for Java and native stacks, in the THREADS section. By looking at the stack for each of these worker threads, you can trace the problem back to specific lines in your application code.</p> <p>In this example, you can see from the following output that for all worker threads, the stack traces (<code>4XESTACKTRACE</code>/<code>5XESTACKTRACE</code>) indicate a problem in line 35 of the application <code>DeadLockTest.java</code>:</p> <pre><code>3XMTHREADINFO      \"Worker Thread 1\" J9VMThread:0x92A3EC00, omrthread_t:0x92A3C2B0, java/lang/Thread:0xB5666778, state:B, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x13, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x52CF, native priority:0x5, native policy:UNKNOWN, vmstate:B, vm thread flags:0x00000201)\n3XMTHREADINFO2            (native stack address range from:0x9297E000, to:0x929BF000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.004365543 secs, current category=\"Application\"\n3XMTHREADBLOCK     Blocked on: java/lang/Object@0xB5666688 Owned by: \"Worker Thread 2\" (J9VMThread:0x94501D00, java/lang/Thread:0xB56668D0)\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at WorkerThread.run(DeadLockTest.java:35)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB5666678, entry count: 1)\n...\n3XMTHREADINFO      \"Worker Thread 2\" J9VMThread:0x94501D00, omrthread_t:0x92A3C8F0, java/lang/Thread:0xB56668D0, state:B, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x14, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x52D0, native priority:0x5, native policy:UNKNOWN, vmstate:B, vm thread flags:0x00000201)\n3XMTHREADINFO2            (native stack address range from:0x946BF000, to:0x94700000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.004555580 secs, current category=\"Application\"\n3XMTHREADBLOCK     Blocked on: java/lang/Object@0xB5666698 Owned by: \"Worker Thread 3\" (J9VMThread:0x94507500, java/lang/Thread:0xB5666A18)\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at WorkerThread.run(DeadLockTest.java:35)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB5666688, entry count: 1)\n...\n3XMTHREADINFO      \"Worker Thread 3\" J9VMThread:0x94507500, omrthread_t:0x92A3CC10, java/lang/Thread:0xB5666A18, state:B, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x15, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x52D1, native priority:0x5, native policy:UNKNOWN, vmstate:B, vm thread flags:0x00000201)\n3XMTHREADINFO2            (native stack address range from:0x9467E000, to:0x946BF000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.003657010 secs, current category=\"Application\"\n3XMTHREADBLOCK     Blocked on: java/lang/Object@0xB5666678 Owned by: \"Worker Thread 1\" (J9VMThread:0x92A3EC00, java/lang/Thread:0xB5666778)\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at WorkerThread.run(DeadLockTest.java:35)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB5666698, entry count: 1)\n</code></pre>"},{"location":"dump_javadump/#hang","title":"Hang","text":"<p>An application can hang for a number of reasons but the most common cause is excessive global garbage collection (GC) activity, where your application is repeatedly paused because your Java heap has almost run out of memory. You can identify this problem by looking at verbose GC output. Collect this output by specifying the <code>-verbose:gc</code> option.</p> <p>Deadlock situations can also manifest themselves as hangs. For more information on diagnosing this type of problem from a Java dump, see the deadlock scenario.</p> <p>If you have eliminated verbose GC activity and deadlocks, another common hang scenario involves threads that compete and wait for Java object locks. This type of problem can usually be diagnosed by examining a Java dump. The simplest hang scenario involving Java object locks is where a thread acquires a lock that other threads are waiting for, but it doesn't release the lock for some reason.</p> <p>The first place to look in the Java dump output is the LOCKS section. This section lists all the monitors and shows which threads have acquired a lock and which threads are waiting. If the hang is caused by a thread not releasing a lock that other threads need, you can see a list of waiting threads in the output.</p> <p>In this example scenario, the Java dump LOCKS section shows that <code>Worker Thread 0</code> (<code>3LKMONOBJECT</code>) has acquired a lock and there are 19 other worker threads waiting to obtain the lock.</p> <pre><code>NULL           ------------------------------------------------------------------------\n0SECTION       LOCKS subcomponent dump routine\nNULL           ===============================\nNULL\n1LKPOOLINFO    Monitor pool info:\n2LKPOOLTOTAL     Current total number of monitors: 1\nNULL\n1LKMONPOOLDUMP Monitor Pool Dump (flat &amp; inflated object-monitors):\n2LKMONINUSE      sys_mon_t:0x92711200 infl_mon_t: 0x92711240:\n3LKMONOBJECT       java/lang/Object@0xB56658D8: Flat locked by \"Worker Thread 0\" (J9VMThread:0x92A3EC00), entry count 1\n3LKWAITERQ            Waiting to enter:\n3LKWAITER                \"Worker Thread 1\" (J9VMThread:0x92703F00)\n3LKWAITER                \"Worker Thread 2\" (J9VMThread:0x92709C00)\n3LKWAITER                \"Worker Thread 3\" (J9VMThread:0x92710A00)\n3LKWAITER                \"Worker Thread 4\" (J9VMThread:0x92717F00)\n3LKWAITER                \"Worker Thread 5\" (J9VMThread:0x9271DC00)\n3LKWAITER                \"Worker Thread 6\" (J9VMThread:0x92723A00)\n3LKWAITER                \"Worker Thread 7\" (J9VMThread:0x92729800)\n3LKWAITER                \"Worker Thread 8\" (J9VMThread:0x92733700)\n3LKWAITER                \"Worker Thread 9\" (J9VMThread:0x92739400)\n3LKWAITER                \"Worker Thread 10\" (J9VMThread:0x92740200)\n3LKWAITER                \"Worker Thread 11\" (J9VMThread:0x92748100)\n3LKWAITER                \"Worker Thread 12\" (J9VMThread:0x9274DF00)\n3LKWAITER                \"Worker Thread 13\" (J9VMThread:0x92754D00)\n3LKWAITER                \"Worker Thread 14\" (J9VMThread:0x9275AA00)\n3LKWAITER                \"Worker Thread 15\" (J9VMThread:0x92760800)\n3LKWAITER                \"Worker Thread 16\" (J9VMThread:0x92766600)\n3LKWAITER                \"Worker Thread 17\" (J9VMThread:0x9276C300)\n3LKWAITER                \"Worker Thread 18\" (J9VMThread:0x92773100)\n3LKWAITER                \"Worker Thread 19\" (J9VMThread:0x92778F00)\nNULL\n</code></pre> <p>The next step is to determine why <code>Worker Thread 0</code> is not releasing the lock. The best place to start is the stack trace for this thread, which you can find by searching on the thread name or J9VMThread ID in the THREADS section.</p> <p>The following extract shows the details for <code>\"Worker Thread 0\" (J9VMThread:0x92A3EC00)</code>:</p> <pre><code>NULL\n3XMTHREADINFO      \"Worker Thread 0\" J9VMThread:0x92A3EC00, omrthread_t:0x92A3C280, java/lang/Thread:0xB56668B8, state:CW, prio=5\n3XMJAVALTHREAD            (java/lang/Thread getId:0x13, isDaemon:false)\n3XMTHREADINFO1            (native thread ID:0x511F, native priority:0x5, native policy:UNKNOWN, vmstate:CW, vm thread flags:0x00000401)\n3XMTHREADINFO2            (native stack address range from:0x9297E000, to:0x929BF000, size:0x41000)\n3XMCPUTIME               CPU usage total: 0.000211878 secs, current category=\"Application\"\n3XMHEAPALLOC             Heap bytes allocated since last GC cycle=0 (0x0)\n3XMTHREADINFO3           Java callstack:\n4XESTACKTRACE                at java/lang/Thread.sleep(Native Method)\n4XESTACKTRACE                at java/lang/Thread.sleep(Thread.java:941)\n4XESTACKTRACE                at WorkerThread.doWork(HangTest.java:37)\n4XESTACKTRACE                at WorkerThread.run(HangTest.java:31)\n5XESTACKTRACE                   (entered lock: java/lang/Object@0xB56658D8, entry count: 1)\n</code></pre> <p>In the last line of this output, you can see where the thread acquired the lock. Working up from this line, you can see that <code>WorkerThread.run</code> was called, which in turn called <code>WorkerThread.doWork</code>. The stack shows that the thread then entered a call to <code>java/lang/Thread.sleep</code> in HangTest.java on line 37, which is preventing the thread from completing its work and releasing the lock. In this example, the <code>sleep</code> call was added to induce a hang, but in real-world scenarios the cause could be any blocking operation, such as reading from an input stream or socket. Another possibility is that the thread is waiting for another lock owned by yet another thread.</p> <p>It is important to remember that each Java dump represents a single snapshot in time. You should generate at least three Java dumps separated by a short pause, for example 30 seconds, and compare the output. This comparison tells you whether the threads involved are stuck in a fixed state or whether they are moving.</p> <p>In this example, the threads do not move and the investigation needs to focus on the logic in <code>WorkerThread.doWork</code> to understand why <code>Worker Thread 0</code> entered the <code>java/lang/Thread.sleep</code> call.</p> <p>Another common scenario is where each Java dump shows a number of threads waiting for a lock owned by another thread, but the list of waiting threads and the lock-owning thread change over time. In this case, the cause is likely to be a bottleneck caused by thread contention, where the threads are continually competing for the same lock. In severe cases, the lock is held only for a small amount of time but there are lots of threads trying to obtain it. Because more time is spent handling the lock and scheduling the thread than executing application code, the degradation in performance is manifested as a hang. Thread contention is usually caused by an application design problem. You can use a similar approach to the one used in this scenario to determine which lines of code are responsible for the contention.</p>"},{"location":"dump_systemdump/","title":"System dump","text":""},{"location":"dump_systemdump/#system-dump","title":"System dump","text":"<p>System dumps, often known as core dumps, are platform-specific and contain a raw binary dump of the process memory. This type of dump has a complete copy of the Java heap, including the contents of all Java objects in the application.</p>"},{"location":"dump_systemdump/#obtaining-system-dumps","title":"Obtaining system dumps","text":"<p>System dumps are produced in response to specific events. To discover which events generate a dump, run the <code>-Xdump:what</code> command. The following output captures the information shown for a system dump:</p> <pre><code>-Xdump:system:\n    events=gpf+abort+traceassert+corruptcache,\n    label=/home/user/core.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..0,\n    priority=999,\n    request=serial\n</code></pre> <p>This output shows that events such as a general protection fault (gpf) or native <code>abort()</code> call can trigger a system dump. For more information about controlling the behavior of dump agents, see Dump agents.</p>"},{"location":"dump_systemdump/#enabling-a-full-system-dump-aix-linux-and-macos","title":"Enabling a full system dump (AIX, Linux, and macOS)","text":"<p>If you require a system dump that contains details of all the native threads that are running, you must change the resource limits for your operating system. Otherwise, the native thread details that are stored in the dump are only for the native thread that was running when the VM ended.</p> <ol> <li> <p>Set the system resource limits by running the following commands:    <code>ulimit -c unlimited; ulimit -n unlimited; ulimit -d unlimited; ulimit -f unlimited;</code></p> <p>Where:</p> </li> </ol> <ul> <li><code>-c</code> sets core files</li> <li><code>-n</code> sets the number of open files</li> <li><code>-d</code> sets the data limit</li> <li><code>-f</code> sets the file limit</li> </ul> <ol> <li>For AIX systems, use the system management interface tool (SMIT) to enable a full CORE dump that is not a pre-430 style CORE dump. You can also set this configuration with the following command line option:</li> </ol> <p><code>chdev -l sys0 -a fullcore='true' -a pre430core='false'</code></p>"},{"location":"dump_systemdump/#analyzing-a-system-dump","title":"Analyzing a system dump","text":"<p>To examine a system dump you can use the Dump viewer (<code>jdmpview</code>), a platform-specific debugging tool, or the Eclipse Memory Analyzer\u2122 tool (MAT).</p> <p>If you want to use MAT to analyze your system dump, you must install the  Diagnostic Tool Framework for Java (DTFJ) plugin in the Eclipse IDE. Select the following menu items:</p> <pre><code>Help &gt; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java   \n</code></pre>"},{"location":"enhancementstoopenjdksecurity/","title":"Enhancements to OpenJDK security","text":""},{"location":"enhancementstoopenjdksecurity/#enhancements-to-openjdk-security","title":"Enhancements to OpenJDK security","text":"<p>Eclipse OpenJ9\u2122 includes the following enhancements to the OpenJDK security components.</p>"},{"location":"enhancementstoopenjdksecurity/#support-for-pkcs11-token-labels","title":"Support for PKCS#11 token labels","text":"<p>(z/OS\u00ae and Linux on IBM Z\u00ae only)</p> <p>On z/OS and Linux on IBM Z, OpenJ9 supports the use of an extra attribute, <code>tokenlabel</code>, in the SunPKCS11 configuration file. Use this attribute to assign a label to a PKCS#11 token.</p> <p>The number of slots and their order depend on the number of tokens in the ICSF token database, their values, and the SAF CRYPTOZ class protection profiles that are currently defined. The ICSF PKCS#11 support ensures that a token resides in its current slot only for the duration of a PKCS#11 session (if the token is not deleted). If you restart an application, or tokens are created or removed, the token might move to a different slot. An application that uses the <code>slot</code> or <code>slotListIndex</code> attributes might fail if it doesn\u2019t first check which slot the token is in. You can avoid this issue by using the <code>tokenlabel</code> attribute instead.</p> <p>You can specify only one of the attributes - <code>slot</code>, <code>slotListIndex</code>, or <code>tokenlabel</code>. If you do not specify any of these attributes, the default behavior is that the <code>slotListIndex</code> attribute is set to 0.</p> <p>For more information about the SunPKCS11 configuration file, see PKCS#11 Reference Guide.</p>"},{"location":"env_var/","title":"Environment variables","text":""},{"location":"env_var/#environment-variables","title":"Environment variables","text":"<p>Although the Eclipse OpenJ9\u2122 virtual machine (VM) recognizes many environment variables, most are superseded by command-line arguments. Use command-line arguments rather than environment variables, which are retained only for compatibility.</p> <p> Note: Environment variables are overridden by command-line arguments.</p>"},{"location":"env_var/#finding-and-setting-environment-variables","title":"Finding and setting environment variables","text":"<p>To show the current environment, run:</p> <ul> <li><code>set</code> (Windows\u2122)</li> <li><code>env</code> (AIX\u00ae, Linux\u00ae, and macOS\u00ae)</li> <li><code>set</code> (z/OS\u00ae)</li> </ul> <p>To show a particular environment variable, run:</p> <ul> <li><code>echo %ENVNAME%</code> (Windows)</li> <li><code>echo $ENVNAME</code> (AIX, Linux, macOS, and z/OS)</li> </ul> <p>Use values exactly as shown in the documentation. The names of environment variables are case-sensitive in AIX, Linux, macOS, and z/OS.</p> <p>To set the environment variable LOGIN_NAME to Fred, run:</p> <ul> <li><code>set LOGIN_NAME=Fred</code> (Windows)</li> <li><code>export LOGIN_NAME=Fred</code> (AIX/Linux/macOS: ksh or bash shells)</li> <li><code>setenv LOGIN_NAME Fred</code> (csh shells)</li> </ul> <p>These variables are set only for the current shell or command-line session.</p> <p>If you are setting multiple values for an environment variable in a list:</p> <ul> <li>On AIX, Linux, macOS, and z/OS the separator is typically a colon (:).</li> <li>On Windows the separator is typically a semicolon (;).</li> </ul>"},{"location":"env_var/#general-options","title":"General options","text":"<p>General VM environment variables are shown in the following table:</p> Environment\u00a0variable Usage information <code>OPENJ9_JAVA_COMMAND_LINE</code> This variable is set by the VM after it starts. Using this variable, you can find the command-line parameters set when the VM started. See <code>-XX:[+|-]OpenJ9CommandLineEnv</code> for more information. <code>OPENJ9_JAVA_OPTIONS=&lt;option&gt;</code> Set this variable to store default Java options, including -X, -D, or -verbose:gc style options. For example, -Xms256m -Djava.compiler. Any options set are overridden by equivalent options that are specified when Java is started. This variable does not support certain options, see the list in -Xoptionsfile. If you specify the name of a trace output file either directly, or indirectly, by using a properties file, the output file might be accidentally overwritten if you run utilities such as the trace formatter, dump extractor, or dump viewer. To avoid this problem, add %d, %p or %t to the trace file names. See -Xtrace:output. Note: The equivalent to <code>OPENJ9_JAVA_OPTIONS</code>, <code>IBM_JAVA_OPTIONS</code> is deprecated and will be removed in a future release. <code>JAVA_FONTS=&lt;list of directories&gt;</code> Set this environment variable to specify the font directory. Setting this variable is equivalent to setting the property <code>java.awt.fonts</code> on Windows operating systems, and <code>sun.java2d.fontpath</code> on other operating systems. <code>_JAVA_OPTIONS=&lt;option&gt;</code> Set this variable to add Java options to the end of the command line. Supported options and trace file issues are the same as for <code>OPENJ9_JAVA_OPTIONS</code>."},{"location":"env_var/#dump-agent-options","title":"Dump agent options","text":"<p>The preferred mechanism for controlling the production of dumps is by using the <code>-Xdump</code> option. However, these legacy environment variables are preserved and can still be used. The following table describes dump agent options:</p> Environment Variable Usage Information <code>JAVA_DUMP_OPTS</code> Used to control the conditions under which dumps are produced. <p>If you set agents for a condition by using the <code>JAVA_DUMP_OPTS</code> environment variable, default dump agents for that condition are disabled; however, any <code>-Xdump</code> options that are specified on the command line are used.</p> <p>The <code>JAVA_DUMP_OPTS</code> environment variable uses the following syntax:</p> <pre><code>JAVA_DUMP_OPTS=\"ON&lt;condition&gt;(&lt;agent&gt;[&lt;count&gt;],&lt;agent&gt;[&lt;count&gt;]),\nON&lt;condition&gt;(&lt;agent&gt;[&lt;count&gt;],...),...)\"\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;condition&gt;</code> is one of the following values:<ul> <li><code>ANYSIGNAL</code></li> <li><code>DUMP</code></li> <li><code>ERROR</code></li> <li><code>INTERRUPT</code></li> <li><code>EXCEPTION</code></li> <li><code>OUTOFMEMORY</code></li> </ul> </li> <li><code>&lt;agent&gt;</code> is one of the following values:<ul> <li><code>ALL</code></li> <li><code>NONE</code></li> <li><code>JAVADUMP</code></li> <li><code>SYSDUMP</code></li> <li><code>HEAPDUMP</code></li> <li><code>CEEDUMP</code> (z/OS specific)</li> </ul> </li> <li><code>&lt;count&gt;</code> is the number of times to run the specified agent for the specified condition. This value is optional. By default, the agent runs every time that the condition occurs.</li> </ul> <p><code>JAVA_DUMP_OPTS</code> is parsed by taking the leftmost occurrence of each condition, so duplicates are ignored. The following setting produces a system dump for the first error condition only:</p> <pre><code>ONERROR(SYSDUMP[1]),ONERROR(JAVADUMP)\n</code></pre> <p>Also, the <code>ONANYSIGNAL</code> condition is parsed before all others, so</p> <pre><code>ONINTERRUPT(NONE),ONANYSIGNAL(SYSDUMP)\n</code></pre> <p>has the same effect as</p> <pre><code>ONANYSIGNAL(SYSDUMP),ONINTERRUPT(NONE)\n</code></pre> <p>If the <code>JAVA_DUMP_TOOL</code> environment variable is set, that variable is assumed to specify a valid executable name and is parsed for replaceable fields, such as %pid. If %pid is detected in the string, the string is replaced with the VM's own process ID. The tool that is specified by <code>JAVA_DUMP_TOOL</code> is run after any system dump or heap dump is taken, before anything else.</p> <p>The dump settings are applied in the following order. Settings later in the list take precedence:</p> <ol> <li>Default VM dump behavior.</li> <li><code>-Xdump</code> command-line options that specify <code>-Xdump:&lt;type&gt;:defaults</code>, see OpenJ9 default options.</li> <li><code>DISABLE_JAVADUMP</code>, <code>IBM_HEAPDUMP</code>, and <code>IBM_HEAP_DUMP</code> environment variables.</li> <li><code>IBM_JAVADUMP_OUTOFMEMORY</code> and <code>IBM_HEAPDUMP_OUTOFMEMORY</code> environment variables.</li> <li><code>JAVA_DUMP_OPTS</code> environment variable.</li> <li>Remaining <code>-Xdump</code> command-line options.</li> </ol> <p>Setting <code>JAVA_DUMP_OPTS</code> affects only those conditions that you specify. Actions on other conditions are unchanged.</p>"},{"location":"env_var/#signal-mapping","title":"Signal mapping","text":"<p>When setting the <code>JAVA_DUMP_OPTS</code> environment variable, the mapping of operating system signals to the \"condition\" is shown in the following table:</p> Condition z/OS Windows Linux, macOS, and AIX EXCEPTION SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGSYS, SIGXFSV SIGILL, SIGSEGV, SIGFPE SIGTRAP, SIGILL, SIGSEGV, SIGFPE, SIGBUS, SIGXFSV INTERRUPT SIGINT, SIGTERM, SIGHUP SIGINT, SIGTERM SIGINT, SIGTERM, SIGHUP ERROR SIGABRT SIGABRT SIGABRT DUMP SIGQUIT SIGBREAK SIGQUIT"},{"location":"env_var/#java-dump-options","title":"Java dump options","text":"<p>The preferred mechanism for controlling the production of Java dumps is by using the <code>-Xdump:java</code> option. However, these legacy environment variables are preserved and can still be used.</p> Environment Variable Usage Information <code>DISABLE_JAVADUMP=[TRUE|FALSE]</code> Setting <code>DISABLE_JAVADUMP</code> to <code>TRUE</code> is the equivalent of using <code>-Xdump:java:none</code> and stops the default production of Java dumps. <code>IBM_JAVACOREDIR=&lt;directory&gt;</code> The default location into which the Java dump is written. On z/OS, the <code>_CEE_DMPTARG</code> environment variable is used instead. <code>IBM_JAVADUMP_OUTOFMEMORY=[TRUE|FALSE]</code> By setting this environment variable to <code>FALSE</code>, you disable Java dumps for an out-of-memory exception. When not set, a Java dump is generated when an out-of-memory exception is thrown but not caught and handled by the application. Set to <code>TRUE</code> to generate a dump when an out-of-memory exception is thrown, even if it is handled by the application. Set to <code>FALSE</code> to disable Java dumps for an out-of-memory exception. <code>TMPDIR=&lt;directory&gt;</code> This variable specifies an alternative temporary directory. This directory is used only when Java dumps and Heap dumps cannot be written to their target directories, or the current working directory. The default is <code>/tmp</code> (<code>C:\\temp</code> for Windows). <p> Note: You can use the dump agent <code>JAVA_DUMP_OPTS</code> variable to control the conditions under which Java dumps are produced.</p>"},{"location":"env_var/#heap-dump-options","title":"Heap dump options","text":"<p>The preferred mechanism for controlling the production of Java dumps is by using the <code>-Xdump:heap</code> option. However, these legacy environment variables are preserved and can still be used.</p> Environment Variable Usage Information <code>IBM_HEAPDUMP=[TRUE|FALSE]</code> Setting this option to <code>TRUE</code> enables heap dump production by using signals. <code>IBM_HEAP_DUMP=[TRUE|FALSE]</code> Setting this option to <code>TRUE</code> enables heap dump production by using signals. <code>IBM_HEAPDUMPDIR=&lt;directory&gt;</code> The default location into which the heap dump is written. On z/OS, the <code>_CEE_DMPTARG</code> environment variable is used instead. <code>IBM_HEAPDUMP_OUTOFMEMORY=[TRUE|FALSE]</code> Controls the generation of a heap dump when an out-of-memory exception is thrown. When not set, a heap dump is generated when an out-of-memory exception is thrown but not caught and handled by the application. Set to TRUE to generate a dump when an out-of-memory exception is thrown, even if it is handled by the application. Set to FALSE to disable heap dump for an out-of-memory exception. <code>IBM_JAVA_HEAPDUMP_TEST</code> Use this environment variable to cause the VM to generate both PHD and text versions of heap dumps. Equivalent to <code>opts=PHD+CLASSIC</code> on the <code>-Xdump:heap</code> option. <code>IBM_JAVA_HEAPDUMP_TEXT</code> Use this environment variable to cause the VM to generate a text (human readable) Heap dump. Equivalent to <code>opts=CLASSIC</code> on the <code>-Xdump:heap</code> option. <code>TMPDIR=&lt;directory&gt;</code> This variable specifies an alternative temporary directory. This directory is used only when Java dumps and heap dumps cannot be written to their target directories, or the current working directory. The default is <code>/tmp</code> (<code>C:\\temp</code> for Windows). <p> Note: You can use the dump agent <code>JAVA_DUMP_OPTS</code> variable to control the conditions under which Heap dumps are produced.</p>"},{"location":"env_var/#other-diagnostic-options","title":"Other diagnostic options","text":"<p>The following table lists other environment variables that can be set for diagnostic purposes:</p> Environment variable Usage Instructions <code>IBM_COREDIR=&lt;directory&gt;</code> Set this variable to specify an alternative location for system dumps, JIT dumps, and snap trace. On z/OS, <code>_CEE_DMPTARG</code> is used instead for snap trace, and transaction dumps are written to TSO according to <code>JAVA_DUMP_TDUMP_PATTERN</code>. On Linux and macOS, the dump is written to the directory that is specified directory by the operating system before being moved to the specified location. <code>IBM_JAVA_ABEND_ON_FAILURE=Y</code> (z/OS only) This setting tells the Java launcher to mark the Task Control Block (TCB) with an abend code if the OpenJ9 VM fails to load or is terminated by an uncaught exception. By default, the Java launcher does not mark the TCB. <code>JAVA_DUMP_TDUMP_PATTERN=&lt;string&gt;</code> (z/OS only) The specified <code>&lt;string&gt;</code> is passed to IEATDUMP to use as the data/set name for the Transaction Dump. The default <code>&lt;string&gt;</code> is <code>%uid.JVM.TDUMP.%job.D%y%m%d.T%H%M%S</code> (31-bit) or <code>%uid.JVM.%job.D%y%m%d.T%H%M%S.X&amp;amp;DS</code> (64-bit), where <code>%uid</code> is found from the C code fragment shown in Notes. <code>JAVA_THREAD_MODEL=&lt;string&gt;</code> <code>&lt;string&gt;</code> can be defined as one of the following values: NATIVE (all threads are created as <code>_MEDIUM_WEIGHT</code>), HEAVY (all threads are created as <code>_HEAVY_WEIGHT</code>), MEDIUM (same as NATIVE), or NULL. The default is NATIVE. <code>IBM_XE_COE_NAME=&lt;value&gt;</code> Set this variable to generate a system dump when the specified exception occurs. The value that is supplied is the package description of the exception; for example, <code>java/lang/InternalError</code>. A Signal 11 is followed by a JVMXE message and then the VM ends. <code>JAVA_PLUGIN_TRACE=TRUE</code> When this variable is set to <code>TRUE</code> or 1, a Java plug-in trace is produced for the session when an application runs. Traces are produced from both the Java and Native layer. By default, this variable is set to <code>FALSE</code>, so that a Java plug-in trace is not produced. <p> Notes: C code fragment to discover <code>%uid</code> for <code>JAVA_DUMP_TDUMP_PATTERN=&lt;string&gt;</code>:</p> <pre><code>pwd = getpwuid(getuid());\npwd-&gt;pw_name;\n</code></pre>"},{"location":"env_var/#deprecated-jit-options","title":"Deprecated JIT options","text":"<p>The following table describes deprecated environment variables for the JIT compiler:</p> Environment Variable Usage Information <code>IBM_MIXED_MODE_THRESHOLD</code> Use <code>-Xjit:count=&lt;value&gt;</code> instead of this variable. <code>JAVA_COMPILER</code> Use <code>-Djava.compiler=&lt;value&gt;</code> instead of this variable."},{"location":"gc/","title":"GC policies","text":""},{"location":"gc/#garbage-collection-policies","title":"Garbage collection policies","text":"<p>Eclipse OpenJ9\u2122 provides several garbage collection (GC) policies that are designed around different application workloads and service level agreements. Each GC policy consists of a set of characteristics and features that aim to optimize one or more performance aspects of a running application. These performance aspects include application throughput, memory footprint, average pause times, worst-case pause times, and startup time.</p> <p>Different policies require a Java heap that is configured in different ways in order to achieve different goals. The simplest configuration consists of a single area of memory, often referred to as a flat heap. Other configurations divide the heap into different areas or regions, which might contain objects of different ages (generations) or sizes.</p> <p>A GC cycle is a repeatable process that involves a set of GC operations. These operations process all or parts of the Java heap to complete a discrete function and are discussed in more detail in GC operations.</p> <p>GC policies use different GC cycles to manage different aspects of the heap. For example, the <code>gencon</code> policy runs a partial GC cycle on the nursery area of the heap to complete a scavenge operation. At other times, <code>gencon</code> also runs a global GC cycle on the entire Java heap to complete mark and sweep (and optionally compact) operations.  </p> <p>GC cycles might be divided into increments that run over a period of time to reduce maximum pause times. These increments might involve stop-the-world (STW) pauses that must halt application threads to give certain GC operations exclusive access to the Java heap. Alternatively, increments might include GC operations that can run concurrently with application processing.</p> <p>The following table shows the heap configuration and the GC cycles and operations used by different policies:</p> Policy Heap configuration GC cycles / operations <code>gencon</code> Two areas: nursery and tenure  Two generation groups: new/older Global GC cycle: concurrent mark-sweep operations, optionally followed by a compact operation  Partial GC cycle: STW scavenge operation or concurrent scavenge operation (if optionally enabled) <code>balanced</code> Multiple regions of equal size  Multiple generations Global GC mark cycle: incremental concurrent mark operation (global mark phase)  Partial GC cycle: STW copy forward operation and optional mark, sweep, or compact operations <code>optavgpause</code> One area: flat  One generation Global GC cycle: concurrent mark-sweep operations, optionally followed by a compact operation <code>optthruput</code> One area: flat  One generation Global GC cycle: STW mark-sweep operations, optionally followed by a compact operation <code>metronome</code> Multiple regions by size class  One generation Global GC cycle: incremental STW mark-sweep operation in small interruptible steps <code>nogc</code> One area: flat No GC cycles <p> Note: All OpenJ9 GC policies support compressed references on 64-bit platforms, which compresses heap pointers to 32 bits if the total heap size does not exceed the theoretical upper bound of 64 GB. Applications that require more heap space can select any heap size within the bounds imposed by the operating system and available system RAM, without using compressed references. For more information, see compressed references.</p>"},{"location":"gc/#policy-selection-and-tuning","title":"Policy selection and tuning","text":"<p>The default policy is the Generational Concurrent (<code>gencon</code>) GC policy, which suits a broad spectrum of applications. Choosing a different GC policy should be guided by the application dynamics and an observation of how the application interacts with the heap during startup and at steady state. To help with this analysis, all OpenJ9 GC policies are instrumented to collect a wide range of GC-related metric data for reporting in a GC log file.</p> <p>To enable GC logging for the OpenJ9 Java runtime, include the <code>-verbose:gc</code> option on the command line. By default, this option prints output to <code>stderr</code> but you can send the output to a log file by using <code>-Xverbosegclog</code>. You can then visualize the output by loading the GC log into the Garbage Collector and Memory Visualizer (GCMV) plugin for the Eclipse IDE. OpenJ9 Java GC logs can also be analyzed by some online services, such as GCEasy.</p> <p>The following sections provide more information about each policy and when you might choose it for your application. To select a GC policy other than <code>gencon</code>, specify the <code>-Xgcpolicy</code> option on the command line. To adjust the initial and maximum size of the Java heap, use the <code>-Xms</code> and <code>-Xmx</code> command line options. For generational GC policies, you can also set the <code>-Xmn</code>, <code>-Xmns</code>, and <code>-Xmnx</code> options.</p>"},{"location":"gc/#gencon-policy-default","title":"<code>gencon</code> policy (default)","text":"<p>The Generational Concurrent GC policy (<code>-Xgcpolicy:gencon</code>) is probably best suited if you have a transactional application, with many short-lived objects. This policy aims to minimize GC pause times without compromising throughput. This is the default policy employed by the VM, so if you want to use it you don't need to specify it on the command line when you start your application.</p> <p>If your application requires the allocation of objects of very different sizes and liveness on the Java heap, you might experience heap fragmentation, which in turn might lead to global heap compaction. In these circumstances, the Balanced GC policy might be more appropriate.</p>"},{"location":"gc/#gc-processing","title":"GC processing","text":"<p>With the <code>gencon</code> policy, the Java heap is divided into two main areas, the nursery area, where new objects are created and the tenure area, where objects are moved if they have reached tenure age.</p> <p>The nursery area is subdivided into two further areas, the allocate space and the survivor space. A partial GC cycle that involves a GC scavenge operation is used to reclaim memory from the nursery area. This process is illustrated in the following diagram, which shows a sequence of four main events:</p> <p></p> <ol> <li>Objects are created in the allocate space.</li> <li>The allocate space is full.</li> <li>A local GC scavenge process runs and reachable objects are either evacuated (copied) into the survivor space or into the tenure area if they have reached tenure age. Any objects that can't be reached are left untouched and subsequently cleared.</li> <li>The allocate and survivor spaces swap roles. The original survivor space becomes the allocate space where new objects are created, and the original allocate space becomes the survivor space ready for the next local GC scavenge process.</li> </ol> <p>The relative sizes of the allocate and survivor spaces are dynamically adjusted by a technique called tilting. When the nursery area is first created, it is evenly divided between the allocate and survivor spaces. If, after a GC scavenge operation runs, the amount of space required for the survivor area is comparatively small, the boundary between the two spaces is adjusted by tilting. For example, if the survivor space requires only 10% of the nursery area, the tilt ratio is adjusted to give 90% of the nursery area to the allocate space. With more space available for new objects, the frequency of scavenge cycles is reduced.</p> <p>The tenure age of an object is determined by the VM and reflects the number of times that an object has been copied between the allocate space and the survivor space. The age is in the range 1 - 14 and is adjusted dynamically by the VM depending on the object survival rate at particular ages. For example, if an object has a tenure age of <code>5</code>, it has been copied backwards and forwards between allocate and survivor spaces five times. If the VM sets a tenure age of <code>5</code> based on the percentage of space remaining in the nursery area, the next scavenge moves the object from the nursery to the tenure area. You can set an initial tenure age with the <code>-Xgc:scvTenureAge</code> option. You can also prevent the VM dynamically adjusting the tenure age by setting the <code>Xgc:scvNoAdaptiveTenure</code> option so that the initial age is maintained throughout the run time of the VM.</p> <p>Within the tenure area, new objects are allocated into the small object area (SOA), which is illustrated in the earlier diagram (see item 3). A large object area (LOA) is set aside for objects greater than 64 KB that cannot be allocated into the SOA to minimize fragmentation. The LOA is allocated by default but is reduced and removed after a few GC cycles if it isn't populated. To prevent the creation of an LOA, you can specify the <code>-Xnoloa</code> option on the command line when you start your application. When the tenure area is close to full a global GC cycle is triggered.</p> <p>The partial GC cycle (scavenge) reduces pause times by frequently reclaiming memory in the nursery area which, for a transactional application with many short-lived objects, has the most recyclable space. While most of the objects stay in the nursery area after the scavenge operation is complete, a small fraction are moved to the tenure area. Over time the tenure area might become full. So, whilst a partial GC cycle is operating on the nursery area, a concurrent global GC cycle also runs alongside normal program execution to mark and remove unreachable objects from the tenure area. These two GC approaches combine to provide a good trade-off between shorter pause times and consistent throughput.</p>"},{"location":"gc/#concurrent-scavenge","title":"Concurrent Scavenge","text":"<p>A special mode of the <code>gencon</code> policy is known as Concurrent Scavenge. This mode aims to further reduce the average time spent in STW pauses by collecting garbage from the nursery area in parallel with running application threads. Whilst aiming to reduce the average time, this mode does not improve the worst case pause time when compared to running <code>gencon</code> without Concurrent Scavenge enabled.</p> <p>To enable Concurrent Scavenge, see -Xgc:concurrentScavenge.</p> <p>This mode can be enabled with hardware-based support and software-based support:</p> <ul> <li> <p>Hardware-based support: (Linux on IBM Z\u00ae and z/OS\u00ae) This mode works on the IBM z14\u2122 and later mainframe system with the Guarded Storage (GS) Facility. The GS Facility provides hardware-based support to detect when potentially stale references to objects are accessed by an application. This means that the garbage collector can start processing objects in parts of the heap without halting an application because the GS Facility is on hand to spot accesses to an object and send a notification. The object that was ready to be swept away can be moved, and references to it can be reset.</p> </li> <li> <p>Software-based support: (64-bit: Linux on (x86-64, POWER, IBM Z\u00ae), AIX\u00ae, macOS\u00ae, and z/OS\u00ae) With software-based support, Concurrent Scavenge can be enabled without any pre-requisite hardware although the performance throughput is not as good as hardware-based support.</p> </li> </ul> <p>More information about Concurrent Scavenge mode can be found in the blog post Concurrent Scavenge Garbage Collection Policy.</p>"},{"location":"gc/#balanced-policy","title":"<code>balanced</code> policy","text":"<p>(64-bit only)</p> <p>The Balanced GC policy (<code>-Xgcpolicy:balanced</code>) evens out pause times and reduces the overhead of some of the costlier operations that are typically associated with garbage collection, such as compaction and class unloading. The Java heap is divided into a large number of regions (1,000 - 2,000), which are managed individually by an incremental generational collector to reduce the maximum pause time on large heaps and increase the efficiency of garbage collection. The aim of the policy is to avoid global garbage collections by matching object allocation and survival rates.</p>"},{"location":"gc/#when-to-use","title":"When to use","text":"<p>The Balanced policy might be a good alternative for applications that experience unacceptable pause times with <code>gencon</code>.</p> <ul> <li> <p>If you have problems with application pause times that are caused by global garbage collections, particularly compactions, this policy might improve application performance.</p> </li> <li> <p>If you are using large systems that have Non-Uniform Memory Architecture (NUMA) characteristics (x86 and POWER\u2122 platforms only), the Balanced policy might further improve application throughput.</p> </li> </ul> <p>However, even though pause times are typically evened out across GC operations, actual pause times are affected by object allocation rates, object survival rates, and fragmentation levels within the heap, and cannot therefore be bound to a certain maximum nor can a certain utilization level be guaranteed.</p>"},{"location":"gc/#gc-processing_1","title":"GC processing","text":"<p>During VM startup, the GC divides the heap memory into regions of equal size. These regions remain static for the lifetime of the VM and are the basic unit of garbage collection and allocation operations. For example, when the heap is expanded or contracted, the memory committed or released corresponds to a certain number of regions. Although the Java heap is a contiguous range of memory addresses, any region within that range can be committed or released from a pool as required. This enables the Balanced GC to contract the heap more dynamically and aggressively than other garbage collectors, which typically require the committed portion of the heap to be contiguous.</p> <p>Regions impose a maximum object size. Objects are always allocated within the bounds of a single region and are never permitted to span regions. The region size is always a power of two; for example, 512 KB, 1 MB, and so on (where KB is 2<sup>10</sup> bytes and MB is 2<sup>20</sup> bytes). The region size is selected at startup based on the maximum heap size. The collector chooses the smallest power of two which will result in less than 2048 regions, with a minimum region size of 512 KB. Except for small heaps (less than about 512 MB) the VM aims to have between 1024 and 2047 regions.</p> <p>Object ages are tracked for each region with a maximum of 24 possible generations. The following diagram illustrates the structure of the object heap:</p> <p></p> <p>The eden space is a set of regions of age 0, which contain the newest objects allocated. The size of the eden space is determined by the number of regions that it contains. When the region count for the eden space reaches a predetermined  threshold (taxation threshold), a partial GC cycle runs to reduce the number of used regions, typically by using a copy forward operation. Empty regions can then be assigned to the eden space from the pool. In specific cases, mark and compact operations might be used, for example, when there are not enough free survivor regions available. The partial GC cycle is a STW operation that always includes the eden space, but might include older regions. Objects from collectible regions of age N are moved into another region of the same age N or to an empty region that is assigned an age of N. Then, the ages of all regions across the heap are incremented by 1, except for the maximum age 24 regions. Regions of age 24 are included in partial GC collection sets in order to defragment them.</p> <p>Partial GC cycles work to reclaim free regions in the heap for allocating new objects. Because some objects from eden regions always survive, a partial GC cycle can reclaim only about 90% of this memory. To keep up with object allocation, partial GC cycles also reclaim free regions by defragmenting older regions. For example, a partial GC cycle that moves objects from 5 fragmented older regions into 2 empty regions, reclaims 3 regions for new object allocation. However, over time the overall amount of fragmented memory decreases and records about object liveness in older regions become less accurate. Eventually, the work done by partial GC cycles to reclaim memory cannot keep pace with memory consumption. Free regions become so scarce that a global mark operation (GMP), which is triggered by another taxation threshold, is required to build a new record of object liveness across the heap. A sweep operation uses this record to measure the amount of free memory in fragmented older regions, which later partial GC cycles can act upon to move objects and reclaim free regions.</p> <p>A global sweep operation also runs to reclaim memory so that it can create empty regions. The global sweep operation, while logically associated with the global mark operation, runs in the same STW increment as the first partial GC cycle after the mark operation completes. Because the GC cycle responsible for the global mark operation runs concurrently, it might overlap and interleave with a few partial GC cycles.</p> <p>With the <code>balanced</code> policy, a global GC cycle is sometimes required in addition to the global mark operations and partial GC cycle. This global GC cycle is rare, occurring only in very tight memory conditions when other GC cycles cannot free enough memory on the heap.</p> <p>Most objects are easily contained within the minimum region size of 512 KB. However, to support large arrays, which cannot be contained in a region, the <code>balanced</code> GC policy uses an arraylet representation in the heap. For more information about structure and layout, see Arraylets.</p> <p> Note: With arraylets, JNI access to array data might involve reconstituting arraylets as contiguous arrays, which can significantly slow down processing.</p> <p>To learn about the default heap size and the tuning options that can be used with the <code>balanced</code> policy, see <code>-Xgcpolicy:balanced</code>.</p>"},{"location":"gc/#optavgpause-policy","title":"<code>optavgpause</code> policy","text":"<p>The optimize for pause time policy (<code>-Xgcpolicy:optavgpause</code>) uses a global GC to manage a flat heap comprised of a single area and to compact the heap if the heap becomes fragmented. The global GC cycle starts preemptively so that the cycle finishes before the heap is exhausted. By anticipating global collections and initiating some mark operations ahead of collection, the <code>optavgpause</code> policy reduces GC pause times when compared to <code>optthruput</code>. However, the reduction in pause time comes at the expense of some performance throughput.</p>"},{"location":"gc/#when-to-use_1","title":"When to use","text":"<p>Consider using this policy if you have a large heap size (available on 64-bit platforms), because this policy limits the effect of increasing heap size on the length of the GC pause.</p> <p>Although <code>optavgpause</code> uses a write barrier to support concurrent mark operations, it does not use a generational write barrier. For some application workloads, such as those that frequently change large and old reference arrays, this strategy might be of greater benefit. However, in many situations, the default <code>gencon</code> policy offers better performance.</p> <p>By using a flat heap, <code>optavgpause</code> avoids potential issues with very large objects. With <code>gencon</code>, the heap is divided into areas (nursery and tenure) in order to manage generations of objects. Although there might be sufficient free space on the overall Java heap for a very large object, it might not fit into the nursery area. If the allocator does succeed in allocating a very large object, further GC cycles might be required to create enough contiguous free space.</p> <p>Overall, <code>optavgpause</code>, along with <code>optthruput</code>, is best suited to short-lived applications and to long-running services that involve concurrent sessions with short lifespans. Short-lived applications with adequate heap sizes usually complete without compaction. The flat heap fragments more slowly when session-bound objects are allocated and drop out of the live set in short overlapping clusters.</p>"},{"location":"gc/#gc-processing_2","title":"GC processing","text":"<p>The <code>optavgpause</code> policy requires a flat Java heap. A global GC cycle runs concurrent mark-sweep operations, optionally followed by compact operations. By running most operations concurrently with application threads, this strategy aims to reduce GC pause times as much as possible.</p>"},{"location":"gc/#optthruput-policy","title":"<code>optthruput</code> policy","text":"<p>The optimize for throughput policy (<code>-Xgcpolicy:optthruput</code>) uses a global GC cycle to manage a flat heap that is comprised of a single area and to compact the heap if the heap becomes fragmented. The global collector runs mark and sweep operations that are triggered by an allocation failure when the heap is exhausted. As a result, applications stop for long pauses while garbage collection takes place.</p>"},{"location":"gc/#when-to-use_2","title":"When to use","text":"<p>You might consider using this policy when a large heap application can tolerate longer GC pauses to obtain better overall throughput. Unlike <code>gencon</code>, the <code>optthruput</code> policy does not use object access barriers. In some workloads, the cost of these barriers might be high enough to make <code>optthruput</code> preferable. However, in many situations, the default <code>gencon</code> policy offers better performance.</p> <p>By using a flat heap, <code>optthruput</code> avoids potential issues with very large objects. With <code>gencon</code>, the heap is divided into areas (nursery and tenure) in order to manage generations of objects. Although there might be sufficient free space on the overall Java heap for a very large object, it might not fit into the nursery area. If the allocator does succeed in allocating a very large object, further GC cycles might be required to create enough contiguous free space.</p> <p>Overall, <code>optthruput</code>, along with <code>optavgpause</code>, is best suited to short-lived applications and to long-running services that involve concurrent sessions with short lifespans. Short-lived applications with adequate heap sizes usually complete without compaction. The flat heap fragments more slowly when session-bound objects are allocated and drop out of the live set in short overlapping clusters.</p>"},{"location":"gc/#gc-processing_3","title":"GC processing","text":"<p>The <code>optthruput</code> policy requires a flat Java heap. A  global GC cycle runs mark-sweep operations, optionally followed by compact operations. The cycle requires exclusive access to the heap, causing application threads to halt while operations take place. As such, long pauses can occur.</p>"},{"location":"gc/#metronome-policy","title":"<code>metronome</code> policy","text":"<p>(Linux on x86-64 and AIX platforms only)</p> <p>The metronome policy (<code>-Xgcpolicy:metronome</code>) is an incremental, deterministic garbage collector with short pause times. Applications that are dependent on precise response times can take advantage of this technology by avoiding potentially long delays from GC activity.</p>"},{"location":"gc/#when-to-use_3","title":"When to use","text":"<p><code>metronome</code> is designed for applications that require a precise upper bound on collection pause times as well as specified application utilization: the proportion of time that the application is permitted to use, with the remainder being devoted to GC. The <code>metronome</code> GC runs in short interruptible bursts to avoid long STW pauses.</p>"},{"location":"gc/#gc-processing_4","title":"GC processing","text":"<p>The Java heap is allocated as a contiguous range of memory, partitioned into small regions of equal size (~64 KB). The <code>metronome</code> policy does not dynamically resize the heap; the heap is always fully expanded, even if <code>-Xms</code> is not set to <code>-Xmx</code>.</p> <p>Each region of the heap is either empty, or contains only objects in one of 16 size classes. The heap also supports Arraylets for dealing with large arrays. This organization improves the use of available heap space, reducing the need for heap compaction and defragmentation, and providing more precise control over the incremental sweep operation.</p> <p> Note: With arraylets, JNI access to array data might involve reconstituting arraylets as contiguous arrays, which can significantly slow down processing.</p> <p>Although high application utilization is desirable for optimal throughput, the GC must be able to keep up with the application's memory allocation rate.</p> <p>A higher utilization typically requires a larger heap because the GC isn't allowed to run as much as a lower utilization would permit. The relationship between utilization and heap size is highly application dependent, and striking an appropriate balance requires iterative experimentation with the application and VM parameters. You might need to adjust heap size or pause time or target utilization to achieve an acceptable runtime configuration.</p> <p>To learn about default options and tuning options that can be used with the <code>metronome</code> policy, see <code>-Xgcpolicy:metronome</code>.</p>"},{"location":"gc/#nogc-policy","title":"<code>nogc</code> policy","text":"<p><code>-Xgcpolicy:nogc</code> handles only memory allocation and heap expansion, but doesn't reclaim any memory. The GC impact on runtime performance is therefore minimized, but if the available Java heap becomes exhausted, an <code>OutOfMemoryError</code> exception is triggered and the VM stops.</p>"},{"location":"gc/#when-to-use_4","title":"When to use","text":"<p>This policy is not suited to the majority of Java applications. However, the following use cases apply:</p> <ul> <li> <p>Testing during development</p> <ul> <li> <p>GC performance: Use <code>nogc</code> as a baseline when testing the performance of other GC policies, including the provision of a low-latency baseline.</p> </li> <li> <p>Application memory: Use <code>nogc</code> to test your settings for allocated memory. If you use <code>-Xmx</code> to set the heap size that should not be exceeded, your application terminates with a heap dump if it tries to exceed your memory limit.</p> </li> </ul> </li> <li> <p>Running applications with minimal or no GC requirements</p> <ul> <li> <p>You might use <code>nogc</code> when an application is so short-lived that allocated memory is never exhausted and running a full GC cycle is therefore a waste of resources.</p> </li> <li> <p>Similarly, when memory application is well understood or where there is rarely memory to be reclaimed, you might prefer to avoid unnecessary GC cycles and rely on a failover mechanism to occasionally restart the VM.</p> </li> </ul> </li> </ul> <p> Note: You should be especially careful when using any of the following techniques with <code>nogc</code> because memory is never released under this policy:</p> <ul> <li>Finalization  </li> <li>Direct memory access  </li> <li>Weak, soft, and phantom references</li> </ul>"},{"location":"gc/#troubleshooting","title":"Troubleshooting","text":"<p>You can diagnose problems with garbage collection operations by turning on verbose GC logging. By default, the information is printed to STDERR but can be redirected to a file by specifying the <code>-Xverbosegclog</code> option. The log files contain detailed information about all operations, including initialization, STW processing, finalization, reference processing, and allocation failures. For more information, see Verbose GC logs.</p> <p>If verbose logs do not provide enough information to help you diagnose GC problems, you can use GC trace to analyze operations at a more granular level. For more information, see -Xtgc.</p>"},{"location":"gc_overview/","title":"Garbage Collection (GC)","text":""},{"location":"gc_overview/#garbage-collection","title":"Garbage collection","text":"<p>To prevent applications running out of memory, objects in the Java heap that are no longer required must be reclaimed. This process is known as garbage collection (GC). When garbage is collected, the garbage collector must obtain exclusive access to the heap, which causes an application to pause while the cleanup is done. This pause is often referred to as a stop-the-world (STW) pause because an application must halt until the process completes. In general, the first step in the GC process is to mark the objects that are reachable, which means they are still in use. The next step is to sweep away the unmarked objects to reclaim memory. The final step is to compact the heap if the heap is badly fragmented.</p> <p>A GC cycle is a repeatable process that involves a set of GC operations. These operations process all or parts of the Java heap. When operating on the whole of the Java heap, the cycle is referred to as a global GC cycle; When operating on part of the heap, the cycle is referred to as a partial GC cycle.</p> <p>A global GC cycle can be triggered explicitly or implicitly according to the following rules:</p> <ul> <li>A global GC cycle is triggered implicitly if it occurs because of internal mechanisms, such as an allocation failure or a taxation threshold being reached.</li> <li>A global GC cycle is triggered explicitly if it is started directly by an application calling <code>System.gc()</code> or indirectly, for example when requesting a heap dump.</li> </ul> <p>Partial GC cycles are triggered only implicitly under the control of a particular GC policy. For more information about the GC policies available with Eclipse OpenJ9\u2122, see Garbage collection policies.</p> <p>The GC process is designed to operate without intervention from an application. Developers should not attempt to predict GC behavior, for example, by making calls to <code>System.gc()</code> to trigger a cycle or by using finalizers to clean up objects in memory. Such actions might degrade the performance of an application.</p>"},{"location":"gc_overview/#gc-operations","title":"GC operations","text":"<p>GC operations run discrete functions on the Java heap. For example, a mark operation traces all objects in the heap to determine which ones are reachable. A sweep operation runs to clear away unreachable objects. Together, a mark and sweep operation are capable of reclaiming used memory as part of a GC cycle. Not all GC cycles include operations to reclaim memory. For example, the <code>balanced</code> GC policy involves a global cycle that includes only a mark operation; reclaiming the memory with a sweep operation occurs as part of a separate partial GC cycle that evacuates younger regions and defragments older regions.</p> <p>A GC operation might complete in one step, or it might involve multiple steps. For example, a mark operation consists of three steps, as described in the following section.</p>"},{"location":"gc_overview/#gc-mark-operation","title":"GC mark operation","text":"<p>A mark operation identifies which objects on the Java heap are reachable from outside of the heap and which objects are unreachable. Reachable objects are in use and must be retained, whereas unreachable objects are not in use and can be cleared away as garbage.</p> <p>The process of marking involves a bit array called a mark map that is allocated by the VM at startup, based on the maximum heap size setting. Each bit in the mark map corresponds to 8 bytes of heap space. When an object is marked, its location in the heap is recorded by setting the appropriate bit in the mark map.</p> <p>A mark operation can be broken down into the following steps:</p> <ol> <li> <p>Initial</p> <p>A root object is an object that is accessible from outside of the heap such as a stack, class static field, or JNI reference. For other objects in the heap to be reachable, they must retain a connection from a root object. In the initial step, tracing identifies all root objects by running a root scan. Root objects are pushed onto a work stack for processing in the next step.</p> </li> <li> <p>Main</p> <p>The list of reachable root objects in the work stack is recursively traced for references to other objects in the heap. Objects that are not marked are new objects and these are added to the work stack. If an object is reachable, the appropriate bit is set in the mark map.</p> </li> <li> <p>Final</p> <p>The final step processes weakly reachable roots such as finalizable objects, weak references, monitor sets, and string sets. For more information about the processing of soft, weak, and phantom references, see Weak reference processing.</p> </li> </ol> <p>In general, helper threads are used in parallel to speed up mark operations on the heap. The helper threads share the work stack with the application thread and are involved in identifying root objects, tracing objects in the heap, and updating the mark map. By default, the number of helper threads is based on the number of CPUs reported by the operating system. You can control the number of helper threads available by specifying the -Xgcthreads command line option when starting your application.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"mark\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#concurrent-mark-processing","title":"Concurrent mark processing","text":"<p>A mark operation can run with exclusive access to the heap, which requires application threads to pause while processing takes place. Alternatively, it can run concurrently with application threads to avoid pauses in application processing.</p> <p>With concurrent mark, the process of root scanning is handed over to application stack threads, which populate the work stack with root objects in their stack. The root objects in the work stack are then traced by a background thread and by each application thread during a heap lock allocation to find reachable objects and update the mark map. Because the mark operation runs concurrently with application threads, any changes to objects that are already traced must be updated. This process works by using a write barrier that can flag the update and trigger a further scan of part of the heap.</p> <p>To track updates to objects, concurrent mark operations use single-byte cards in a card table. Each card corresponds to a 512-byte section of the Java heap. When an object is updated, the start address for the object in the heap is marked on the appropriate card. These cards are used to determine what must be retraced later in the GC cycle.</p> <p>A GC cycle that includes concurrent mark operations aims to trace all reachable objects and complete processing at the same time as the heap is exhausted. Continuous adjustments are made to the start time of each cycle to get as close to heap exhaustion as possible. When the heap is exhausted a sweep operation is able to reclaim memory. This operation requires a STW pause. Before sweep operations start, the root objects are rescanned and the cards are checked to determine which areas of memory must be retraced.</p> <p>An advantage of concurrent mark operations over STW mark operations is reduced pause times, because the garbage collector is able to identify garbage without halting application threads. Pause times are also more consistent because the collector is able to tune start times to maximize heap usage.</p> <p>Disadvantages of concurrent mark operations include the additional CPU for operating the write barrier and additional work for application threads to trace objects when requesting a heap lock.</p> <p>Concurrent mark operations are used by the <code>gencon</code> GC policy and the <code>optavgpause</code> GC policy.</p>"},{"location":"gc_overview/#incremental-concurrent-mark-processing","title":"Incremental concurrent mark processing","text":"<p>Incremental concurrent mark processing evens out pause times by avoiding global STW garbage collections. This type of marking is also known as the global mark phase, whereby mark operations take place incrementally across the entire heap. The global mark operations are interleaved with a partial GC cycle that is responsible for moving objects and clearing unreachable objects in the heap.</p> <p>These operations also use mark map in a card table to manage updates to objects that occur whilst mark operations are in progress. However, unlike the concurrent mark operations used by other policies, application threads are not involved in tracing objects; only background threads are used to trace objects and update the mark map.</p> <p>Incremental concurrent mark operations are used by the <code>balanced GC policy</code>.</p>"},{"location":"gc_overview/#gc-sweep-operation","title":"GC sweep operation","text":"<p>The purpose of a sweep operation is to identify memory that can be reclaimed for object allocation and update a central record, known as the freelist.</p> <p>sweep operations occur in 2 steps:</p> <ol> <li> <p>Initial</p> <p>This step analyzes the mark map for free memory.</p> </li> <li> <p>Final</p> <p>Based on the analysis, the sections of the heap are connected to the freelist.</p> </li> </ol> <p>As with mark operations, multiple helper threads can be used to sweep the Java heap in parallel to speed up processing times. Because these helper threads are the same ones that are used for parallel mark operations, the number of threads can be controlled by using the -Xgcthreads option.</p> <p>Parallel sweep operations run on 256 KB sections of the heap. Each helper thread scans a section at a time. The results are stored and used to generate a freelist of empty regions.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"sweep\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#concurrent-sweep-processing","title":"Concurrent sweep processing","text":"<p>Concurrent sweep processing works in tandem with concurrent mark processing and uses the same mark map. Concurrent sweep operations start after a STW collection and complete a section of the heap before concurrent mark operations continue.</p> <p>Concurrent sweep is used by the <code>optavgpause</code> GC policy.</p>"},{"location":"gc_overview/#gc-scavenge-operation","title":"GC scavenge operation","text":"<p>A GC scavenge operation is triggered by an allocation failure in the nursery area of the heap. The operation occurs in the following 3 steps:</p> <ol> <li> <p>Initial</p> <p>A root object is an object that is accessible from outside of the heap such as a stack, class static field, or JNI reference. For other objects in the heap to be reachable, they must retain a connection from a root object. In the initial step, tracing identifies all root objects by running a root scan. Root objects are pushed onto a work stack for processing in the next step.</p> </li> <li> <p>Main</p> <p>The list of reachable root objects in the work stack is recursively traced for references to other objects in the heap by using the hierarchical scan ordering mode (<code>-Xgc:hierarchicalScanOrdering</code>). If new objects are found, they are added to the work stack. If an object is reachable, it is copied from the allocate space to the survivor space in the nursery area or to the tenure area if the object has reached a particular age.</p> </li> <li> <p>Final</p> <p>The final step processes weakly reachable roots such as finalizable objects, weak references, monitor sets, and string sets. For more information about the processing of soft, weak, and phantom references, see Weak reference processing.</p> </li> </ol> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"scavenge\"&gt;</code> XML element. For more information, see Verbose GC logs.</p> <p>The scavenge operation is used by the <code>gencon</code> GC policy.</p>"},{"location":"gc_overview/#gc-copy-forward-operation","title":"GC copy forward operation","text":"<p>A GC copy forward operation is similar to a scavenge operation but is triggered by a taxation threshold being reached. The operation occurs in the following 3 steps:</p> <ol> <li> <p>Initial</p> <p>A root object is an object that is accessible from outside of the heap such as a stack, class static field, or JNI reference. For other objects in the heap to be reachable, they must retain a connection from a root object. In the initial step, tracing identifies all root objects by running a root scan. Root objects are pushed onto a work stack for processing in the next step.</p> </li> <li> <p>Main</p> <p>The list of reachable root objects in the work stack is recursively traced for references to other objects in the heap by using dynamic breadth first scan ordering mode (<code>-Xgc:dynamicBreadthFirstScanOrdering</code>). If new objects are found, they are added to the work stack. If an object is reachable, it is moved to another region of the same age or to an empty region of the same age in the heap. The age of all regions in the heap is then incremented by 1, except for the oldest region (age 24).</p> </li> <li> <p>Final</p> <p>The final step processes weakly reachable roots such as finalizable objects, weak references, monitor sets, and string sets. For more information about the processing of soft, weak, and phantom references, see Weak reference processing.</p> </li> </ol> <p>The operation aims to empty or evacuate fragmented regions that can then be reclaimed for new object allocation.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"copy forward\"&gt;</code> XML element. For more information, see Verbose GC logs.</p> <p>The copy forward operation is used by the <code>balanced GC policy</code>.</p>"},{"location":"gc_overview/#gc-classunloading-operation","title":"GC classunloading operation","text":"<p>The classunloading operation is single threaded, not parallel threaded.</p> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"classunload\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#gc-compact-operation","title":"GC compact operation","text":"<p>Compaction of the heap is an expensive operation because when objects are moved to defragment the heap, the references to each object change. Therefore, compact operations do not occur by default but only when the following triggers occur:</p> <ul> <li>The <code>-Xcompactgc</code> option is specified on the command line.</li> <li>After sweeping the heap, there is not enough free space available to satisfy an allocation request.</li> <li>A <code>System.gc()</code> is requested and the last allocation failure that triggered a global GC cycle did not compact or <code>-Xcompactexplicitgc</code> is specified.</li> <li>At least half the previously available memory has been consumed by TLH allocations (ensuring an accurate sample) and the average TLH size falls to less than 1024 bytes.</li> <li>The largest object that the <code>gencon</code> GC policy failed to move to the tenure area in the most recent scavenge operation is bigger than the largest free slot in the tenure area.</li> <li>The heap is fully expanded and less than 4% of the tenure area is free.</li> <li>Less than 128 KB of the heap is free.</li> </ul> <p>The following two options can be used to control compaction:</p> <ul> <li><code>-Xcompactgc</code> forces compaction of the heap.</li> <li><code>-Xnocompactgc</code> avoids compaction of the heap as a result of all the triggers shown in the preceding list. However a compaction can still occur in rare circumstances.</li> </ul> <p>In a verbose GC log, this operation is shown by the <code>&lt;gc-op type=\"compact\"&gt;</code> XML element. For more information, see Verbose GC logs.</p>"},{"location":"gc_overview/#weak-reference-processing","title":"Weak reference processing","text":"<p>Weak reference processing includes soft references, weak references, and phantom references. These references are created by the user for specific use cases and allow some level of interaction with the garbage collector. For example, a soft reference to an object allows that object to persist in memory for a longer period of time before being cleared. For example, a software cache. The garbage collector handles the reference types in the order shown and with the behavior detailed in the following table:</p> Reference type Class Garbage collector behavior soft <code>java.lang.ref.SoftReference</code> A soft reference is cleared only when its referent is not marked for a number of GC cycles or if space on the heap is likely to cause an out of memory error. Use the -Xsoftrefthreshold option to control the collection of soft reference objects. weak <code>java.lang.ref.WeakReference</code> A weak reference is cleared as soon as its referent is not marked by a GC cycle. phantom <code>java.lang.ref.PhantomReference</code> A phantom reference is cleared automatically as soon as its referent is not marked by a GC cycle. The cleared reference is then added to the associated reference queue at the same time or later. <p>If your application uses the Java Native Interface (JNI) to interact with other application types, you can also create weak JNI object references. These references have a similar life cycle to a weak Java reference. The garbage collector processes weak JNI references after all other Java reference types.</p>"},{"location":"interface_dtfj/","title":"DTFJ","text":""},{"location":"interface_dtfj/#diagnostic-tool-framework-for-java","title":"Diagnostic Tool Framework for Java","text":"<p>The Diagnostic Tool Framework for Java\u2122 (DTFJ) is a Java application programming interface (API) that is used to support the building of Java diagnostic tools. DTFJ works with data from a system dump or a Java dump.</p> <p>On Linux and AIX\u00ae operating systems, you can get more information from a system dump if you also have copies of executable files and libraries. You can run the <code>jpackcore</code> utility to collect these files into a single archive for use in subsequent problem diagnosis. For more information, see Dump extractor.</p> <p>The DTFJ API helps diagnostic tools access the following information:  </p> <ul> <li>Memory locations stored in the dump (System dumps only)</li> <li>Relationships between memory locations and Java internals (System dumps only)</li> <li>Java threads running in the VM</li> <li>Native threads held in the dump (System dumps only)</li> <li>Java classes and their class loaders that were present</li> <li>Java objects that were present in the heap (System dumps only)</li> <li>Java monitors and the objects and threads they are associated with</li> <li>Details of the workstation on which the dump was produced (System dumps only)</li> <li>Details of the Java version that was being used</li> <li>The command line that launched the VM</li> </ul> <p>If your DTFJ application requests information that is not available in the Java dump, the API will return null or throw a <code>DataUnavailable</code> exception. You might need to adapt DTFJ applications written to process system dumps to make them work with Java dumps.</p> <p>DTFJ is implemented in pure Java and tools written using DTFJ can be cross-platform. Therefore, you can analyze a dump taken from one workstation on another (remote and more convenient) machine. For example, a dump produced on an AIX\u00ae Power\u00ae system can be analyzed on a Windows laptop.</p> <p>See the DTFJ API documentation. </p> <p> Note: If the code that loads DTFJ is in a module, the module must require the <code>openj9.dtfj</code> module. For example:</p> <pre><code>module MyModule {\n  requires openj9.dtfj;\n}\n</code></pre>"},{"location":"interface_dtfj/#using-the-dtfj-interface","title":"Using the DTFJ interface","text":"<p>To create applications that use DTFJ, you must use the DTFJ interface. Implementations of this interface have been written that work with system dumps and Java dumps.</p> <p>The diagram that follows illustrates the DTFJ interface. The starting point for working with a dump is to obtain an <code>Image</code> instance by using the <code>ImageFactory</code> class supplied with the concrete implementation of the API.</p>"},{"location":"interface_dtfj/#working-with-a-system-dump","title":"Working with a system dump","text":"<p>The following example shows how to work with a system dump. In this example, the only section of code that ties the dump to a particular implementation of DTFJ is the generation of the factory class. Change the factory if you want to use a different implementation.</p> <p>If there is a problem with the file that is passed to the <code>getImage()</code> method, an <code>IOException</code> is thrown and an appropriate message is issued. If a missing file is passed to the example shown, the following output is produced:</p> <pre><code>Could not find/use required file(s)\njava.io.FileNotFoundException: core_file.xml (The system cannot find the file specified.)\n        at java.io.FileInputStream.open(Native Method)\n        at java.io.FileInputStream.&lt;init&gt;(FileInputStream.java:135)\n        at com.ibm.dtfj.image.j9.ImageFactory.getImage(ImageFactory.java:47)\n        at com.ibm.dtfj.image.j9.ImageFactory.getImage(ImageFactory.java:35)\n        at DTFJEX1.main(DTFJEX1.java:23)Copy\n</code></pre> <p>In this case, the DTFJ implementation is expecting a dump file to exist. Different errors are caught if the file existed but was not recognized as a valid dump file.</p> Example of working with a system dump <pre><code>import java.io.File;\nimport java.util.Iterator;\nimport java.io.IOException;\n\nimport com.ibm.dtfj.image.CorruptData;\nimport com.ibm.dtfj.image.Image;\nimport com.ibm.dtfj.image.ImageFactory;\n\npublic class DTFJEX1 {\n    public static void main(String[] args) {\n        Image image = null;\n        if (args.length &gt; 0) {\n            File f = new File(args[0]);\n            try {\n                Class factoryClass = Class.forName(\"com.ibm.dtfj.image.j9.ImageFactory\");\n                ImageFactory factory = (ImageFactory) factoryClass.newInstance();\n                image = factory.getImage(f);\n            } catch (ClassNotFoundException e) {\n                System.err.println(\"Could not find DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IllegalAccessException e) {\n                System.err.println(\"IllegalAccessException for DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (InstantiationException e) {\n                System.err.println(\"Could not instantiate DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IOException e) {\n                System.err.println(\"Could not find/use required file(s)\");\n                e.printStackTrace(System.err);\n            }\n        } else {\n            System.err.println(\"No filename specified\");\n        }\n        if (image == null) {\n            return;\n        }\n\n        Iterator asIt = image.getAddressSpaces();\n        int count = 0;\n        while (asIt.hasNext()) {\n            Object tempObj = asIt.next();\n            if (tempObj instanceof CorruptData) {\n                System.err.println(\"Address Space object is corrupt: \"\n                        + (CorruptData) tempObj);\n            } else {\n                count++;\n            }\n        }\n        System.out.println(\"The number of address spaces is: \" + count);\n    }\n}\n</code></pre>"},{"location":"interface_dtfj/#working-with-a-java-dump","title":"Working with a Java dump","text":"<p>To work with a Java dump, change the factory class to <code>com.ibm.dtfj.image.javacore.JCImageFactory</code> and pass the Java dump file to the <code>getImage()</code> method.</p> Example of working with a Java dump <pre><code>import java.io.File;\nimport java.util.Iterator;\nimport java.io.IOException;\n\nimport com.ibm.dtfj.image.CorruptData;\nimport com.ibm.dtfj.image.Image;\nimport com.ibm.dtfj.image.ImageFactory;\n\npublic class DTFJEX2 {\n    public static void main(String[] args) {\n        Image image=null;\n\n        if (args.length &gt; 0) {\n            File javacoreFile = new File(args[0]);\n\n            try {\n                Class factoryClass = Class.forName(\"com.ibm.dtfj.image.javacore.JCImageFactory\");\n                ImageFactory factory = (ImageFactory) factoryClass.newInstance();\n                image = factory.getImage(javacoreFile);\n            } catch (ClassNotFoundException e) {\n                System.err.println(\"Could not find DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IllegalAccessException e) {\n                System.err.println(\"IllegalAccessException for DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (InstantiationException e) {\n                System.err.println(\"Could not instantiate DTFJ factory class\");\n                e.printStackTrace(System.err);\n            } catch (IOException e) {\n                System.err.println(\"Could not find/use required file(s)\");\n                e.printStackTrace(System.err);\n            }\n        } else {\n            System.err.println(\"No filename specified\");\n        }\n        if (image == null) {\n            return;\n        }\n\n        Iterator asIt = image.getAddressSpaces();\n        int count = 0;\n        while (asIt.hasNext()) {\n            Object tempObj = asIt.next();\n            if (tempObj instanceof CorruptData) {\n                System.err.println(\"Address Space object is corrupt: \"\n                        + (CorruptData) tempObj);\n            } else {\n                count++;\n            }\n        }\n        System.out.println(\"The number of address spaces is: \" + count);\n    }\n}\n</code></pre>"},{"location":"interface_dtfj/#analyze-the-dump","title":"Analyze the dump","text":"<p>After you have obtained an <code>Image</code> instance, you can begin analyzing the dump. The <code>Image</code> instance is the second instance in the class hierarchy for DTFJ illustrated by the following diagram:</p> <p></p> <p>Some things to note from the diagram:</p> <ul> <li>The DTFJ interface is separated into two parts: classes with names that start with <code>Image</code> (the dump, a sequence of bytes with different contents on different platforms) and classes with names that start with <code>Java</code> (the Java internal knowledge).</li> <li><code>Image</code> and <code>Java</code> classes are linked using a <code>ManagedRuntime</code> class (which is extended by <code>JavaRuntime</code>).</li> <li>An <code>Image</code> object contains one <code>ImageAddressSpace</code> object (or, on z/OS\u00ae, possibly more).</li> <li>An <code>ImageAddressSpace</code> object contains one <code>ImageProcess</code> object (or, on z/OS, possibly more).</li> <li>Conceptually, you can apply the <code>Image</code> model to any program running with the <code>ImageProcess</code>. For the purposes of this document discussion is limited to the Eclipse OpenJ9\u2122 virtual machine implementations.</li> <li>There is a link from a <code>JavaThread</code> object to its corresponding <code>ImageThread</code> object. Use this link to find out about native code associated with a Java thread, for example JNI functions that have been called from Java.</li> <li>If a <code>JavaThread</code> was not running Java code when the dump was taken, the <code>JavaThread</code> object has no <code>JavaStackFrame</code> objects. In these cases, use the link to the corresponding <code>ImageThread</code> object to find out what native code was running in that thread. This situation is typically the case with the JIT compilation thread and Garbage Collection threads.</li> <li>The DTFJ interface enables you to obtain information about native memory. Native memory is memory requested from the operating system using library functions such as <code>malloc()</code> and <code>mmap()</code>. When the Java runtime allocates native memory, the memory is associated with a high-level memory category. For more information about native memory detailed in a Java dump, see Java dump: <code>NATIVEMEMINFO</code></li> </ul>"},{"location":"interface_dtfj/#dtfj-example-application","title":"DTFJ example application","text":"<p>This example is a fully working DTFJ application. Many DTFJ applications will follow a similar model.</p> Sample DTFJ application <pre><code>import java.io.File;\nimport java.util.Iterator;\nimport com.ibm.dtfj.image.CorruptData;\nimport com.ibm.dtfj.image.CorruptDataException;\nimport com.ibm.dtfj.image.DataUnavailable;\nimport com.ibm.dtfj.image.Image;\nimport com.ibm.dtfj.image.ImageAddressSpace;\nimport com.ibm.dtfj.image.ImageFactory;\nimport com.ibm.dtfj.image.ImageProcess;\nimport com.ibm.dtfj.java.JavaRuntime;\nimport com.ibm.dtfj.java.JavaThread;\nimport com.ibm.dtfj.image.ImageThread;\n\npublic class DTFJEX2\n{\n   public static void main( String[] args )\n   {\n      Image image = null;\n      if ( args.length &gt; 0 )\n      {\n         File f = new File( args[0] );\n         try\n         {\n            Class factoryClass = Class\n                  .forName( \"com.ibm.dtfj.image.j9.ImageFactory\" );\n            ImageFactory factory = (ImageFactory) factoryClass.newInstance( );\n            image = factory.getImage( f );\n         }\n         catch ( Exception ex )\n         { /*\n             * Should use the error handling as shown in DTFJEX1.\n             */\n            System.err.println( \"Error in DTFJEX2\" );\n            ex.printStackTrace( System.err );\n         }\n      }\n      else\n      {\n         System.err.println( \"No filename specified\" );\n      }\n\n      if ( null == image )\n      {\n         return;\n      }\n\n      MatchingThreads( image );\n   }\n\n   public static void MatchingThreads( Image image )\n   {\n      ImageThread imgThread = null;\n\n      Iterator asIt = image.getAddressSpaces( );\n      while ( asIt.hasNext( ) )\n      {\n         System.out.println( \"Found ImageAddressSpace...\" );\n\n         ImageAddressSpace as = (ImageAddressSpace) asIt.next( );\n\n         Iterator prIt = as.getProcesses( );\n\n         while ( prIt.hasNext( ) )\n         {\n            System.out.println( \"Found ImageProcess...\" );\n\n            ImageProcess process = (ImageProcess) prIt.next( );\n\n            Iterator runTimesIt = process.getRuntimes( );\n            while ( runTimesIt.hasNext( ) )\n            {\n               System.out.println( \"Found Runtime...\" );\n               JavaRuntime javaRT = (JavaRuntime) runTimesIt.next( );\n\n               Iterator javaThreadIt = javaRT.getThreads( );\n\n               while ( javaThreadIt.hasNext( ) )\n               {\n                  Object tempObj = javaThreadIt.next( );\n                  /*\n                   * Should use CorruptData handling for all iterators\n                   */\n                  if ( tempObj instanceof CorruptData )\n                  {\n                     System.out.println( \"We have some corrupt data\" );\n                  }\n                  else\n                  {\n                     JavaThread javaThread = (JavaThread) tempObj;\n                     System.out.println( \"Found JavaThread...\" );\n                     try\n                     {\n                        imgThread = (ImageThread) javaThread.getImageThread( );\n\n                        // Now we have a Java thread we can iterator\n                        // through the image threads\n                        Iterator imgThreadIt = process.getThreads( );\n\n                        while ( imgThreadIt.hasNext( ) )\n                        {\n                           ImageThread imgThread2 = (ImageThread) imgThreadIt\n                                 .next( );\n                           if ( imgThread.equals( imgThread2 ) )\n                           {\n                              System.out.println( \"Found a match:\" );\n                              System.out.println( \"\\tjavaThread \"\n                                    + javaThread.getName( )\n                                    + \" is the same as \" + imgThread2.getID( ) );\n                           }\n                        }\n                     }\n                     catch ( CorruptDataException e )\n                     {\n                        System.err.println( \"ImageThread was corrupt: \"\n                              + e.getMessage( ) );\n                     }\n                     catch ( DataUnavailable e )\n                     {\n                        System.out.println( \"DataUnavailable: \"\n                              + e.getMessage( ) );\n                     }\n                  }\n               }\n            }\n         }\n      }\n   }\n}\n</code></pre> <p>For clarity, the example does not perform full error checking when constructing the main Image object and does not perform <code>CorruptData</code> handling in all of the iterators. In a production environment, you use the techniques illustrated in the previous examples under Working with a system dump and Working with a Java dump.</p> <p>In the example, the program iterates through every available Java thread and checks whether it is equal to any of the available image threads. When they are found to be equal, the program displays the following message: \"Found a match\".</p> <p>The example demonstrates:</p> <ul> <li>How to iterate down through the class hierarchy.</li> <li>How to handle <code>CorruptData</code> objects from the iterators.</li> <li>The use of the <code>.equals</code> method for testing equality between objects.</li> </ul>"},{"location":"interface_jvmti/","title":"JVMTI","text":""},{"location":"interface_jvmti/#java-virtual-machine-tool-interface","title":"Java Virtual Machine Tool Interface","text":"<p>The Java\u2122 Virtual Machine Tool Interface (JVMTI) is a two-way interface that allows communication between the VM and a native agent. It replaces both the Java Virtual Machine Debug Interface (JVMDI) and Java Virtual Machine Profiler Interface (JVMPI).</p>"},{"location":"interface_jvmti/#overview","title":"Overview","text":"<p>The JVMTI allows third parties to develop debugging, profiling, and monitoring tools for the VM. The interface contains mechanisms for the agent to notify the VM about the kinds of information it requires, and also provides a means of receiving relevant notifications.</p> <p>Several agents can be attached to a VM at any one time.</p> <p>JVMTI agents can be loaded at startup using short or long forms of the command-line option:</p> <pre><code>-agentlib:&lt;agent-lib-name&gt;=&lt;options&gt;\n</code></pre> <p>or</p> <pre><code>-agentpath:&lt;path-to-agent&gt;=&lt;options&gt;\n</code></pre> <p>In the example that follows (see Sample JVMTI agent), the directory containing the <code>jdwp</code> library is assumed to  be on the library path. If you require a specific library, such as <code>jdwp</code>, with your JVMTI agent, you can specify the path at startup, for example:</p> <pre><code>-agentlib:jdwp=&lt;options&gt;\n</code></pre> <p>For more information about JVMTI, see https://docs.oracle.com/javase/8/docs/technotes/guides/management/index.html.</p> <p>For a guide about writing a JVMTI agent, see http://www.oracle.com/technetwork/articles/javase/jvmti-136367.html.</p>"},{"location":"interface_jvmti/#eclipse-openj9-extensions","title":"Eclipse OpenJ9 extensions","text":"<p>Eclipse OpenJ9\u2122 extensions to the JVMTI allow a JVMTI agent to query or automatically trigger operations in the VM, including the following tasks:</p> Task OpenJ9 extensions Get the OS thread ID <code>GetOSThreadID</code> Query, set, and reset the VM dump options <code>QueryVmDump</code>, <code>SetVmDump</code>, <code>ResetVmDump</code> Trigger a VM dump, and monitor JVMTI event functions when VM dumps start and end <code>TriggerVmDump</code>, <code>VMDumpStart</code>, <code>VMDumpEnd</code> Set VM trace options <code>SetVmTrace</code> Subscribe to and unsubscribe from VM tracepoints <code>RegisterTracePointSubscriber</code>, <code>DeregisterTracePointSubscriber</code> Query runtime environment native memory categories <code>GetMemoryCategories</code> Query and set VM log options <code>QueryVmLogOptions</code>, <code>SetVmLogOptions</code> Search for and remove a shared classes cache <code>IterateSharedCaches</code>, <code>DestroySharedCache</code> Subscribe to and unsubscribe from verbose garbage collection (GC) data logging <code>RegisterVerboseGCSubscriber</code>, <code>DeregisterVerboseGCSubscriber</code> <p>The definitions that you need when you write a JVMTI agent are provided in the header files <code>jvmti.h</code> and <code>ibmjvmti.h</code>, in the  <code>include</code> directory.</p>"},{"location":"interface_jvmti/#sample-jvmti-agent","title":"Sample JVMTI agent","text":"<p>The following sample shows you how to write a simple JVMTI agent that uses OpenJ9 extensions to the JVMTI.</p> Sample JVMTI agent written in C/C++, which uses the OpenJ9 extensions <pre><code>/*\n * tiSample.c\n *\n * Sample JVMTI agent to demonstrate the OpenJ9 JVMTI dump extensions\n */\n\n#include \"jvmti.h\"\n#include \"ibmjvmti.h\"\n\n/* Forward declarations for JVMTI callback functions */\nvoid JNICALL VMInitCallback(jvmtiEnv *jvmti_env, JNIEnv* jni_env, jthread thread);\nvoid JNICALL DumpStartCallback(jvmtiEnv *jvmti_env, char* label, char* event, char* detail, ...);\n\n\n/*\n * Agent_Onload()\n *\n * JVMTI agent initialisation function, invoked as agent is loaded by the VM\n */\nJNIEXPORT jint JNICALL Agent_OnLoad(JavaVM *jvm, char *options, void *reserved) {\n\n  jvmtiEnv *jvmti = NULL;\n  jvmtiError rc;\n  jint extensionEventCount = 0;\n  jvmtiExtensionEventInfo *extensionEvents = NULL;\n  jint extensionFunctionCount = 0;\n  jvmtiExtensionFunctionInfo *extensionFunctions = NULL;\n  int i = 0, j = 0;\n\n  printf(\"tiSample: Loading JVMTI sample agent\\n\");\n\n    /* Get access to JVMTI */\n    (*jvm)-&gt;GetEnv(jvm, (void **)&amp;jvmti, JVMTI_VERSION_1_0);\n\n     /* Look up all the JVMTI extension events and functions */\n   (*jvmti)-&gt;GetExtensionEvents(jvmti, &amp;extensionEventCount, &amp;extensionEvents);\n   (*jvmti)-&gt;GetExtensionFunctions(jvmti, &amp;extensionFunctionCount, &amp;extensionFunctions);\n\n    printf(\"tiSample: Found %i JVMTI extension events, %i extension functions\\n\", extensionEventCount, extensionFunctionCount);\n\n   /* Find the JVMTI extension event we want */\n   while (i++ &lt; extensionEventCount) {\n\n        if (strcmp(extensionEvents-&gt;id, COM_IBM_VM_DUMP_START) == 0) {\n            /* Found the dump start extension event, now set up a callback for it */\n            rc = (*jvmti)-&gt;SetExtensionEventCallback(jvmti, extensionEvents-&gt;extension_event_index, &amp;DumpStartCallback);\n            printf(\"tiSample: Setting JVMTI event callback %s, rc=%i\\n\", COM_IBM_VM_DUMP_START, rc);\n            break;\n        }\n        extensionEvents++; /* move on to the next extension event */\n    }\n\n    /* Find the JVMTI extension function we want */\n    while (j++ &lt; extensionFunctionCount) {\n        jvmtiExtensionFunction function = extensionFunctions-&gt;func;\n\n        if (strcmp(extensionFunctions-&gt;id, COM_IBM_SET_VM_DUMP) == 0) {\n            /* Found the set dump extension function, now set a dump option to generate javadumps on\n          thread starts */\n            rc = function(jvmti, \"java:events=thrstart\");\n            printf(\"tiSample: Calling JVMTI extension %s, rc=%i\\n\", COM_IBM_SET_VM_DUMP, rc);\n            break;\n        }\n        extensionFunctions++; /* move on to the next extension function */\n     }\n\n     return JNI_OK;\n}\n\n\n/*\n * DumpStartCallback()\n * JVMTI callback for dump start event (IBM JVMTI extension)  */\nvoid JNICALL\nDumpStartCallback(jvmtiEnv *jvmti_env, char* label, char* event, char* detail, ...) {\n      printf(\"tiSample: Received JVMTI event callback, for event %s\\n\", event);\n}\n</code></pre> <p>The sample JVMTI agent consists of two functions, <code>Agent_OnLoad()</code> and <code>DumpStartCallback()</code>:</p>"},{"location":"interface_jvmti/#agent_onload","title":"<code>Agent_OnLoad()</code>","text":"<p>This function is called by the VM when the agent is loaded at VM startup, which allows the JVMTI agent to modify VM behavior before initialization is complete. The sample agent obtains access to the JVMTI interface by using the JNI Invocation API function <code>GetEnv()</code>. The agent calls the APIs <code>GetExtensionEvents()</code> and <code>GetExtensionFunctions()</code> to find the JVMTI extensions that are supported by the VM. These APIs provide access to the list of extensions available in the <code>jvmtiExtensionEventInfo</code> and <code>jvmtiExtensionFunctionInfo</code> structures. The sample uses an extension event and an extension function in the following way:</p> <p>Extension event: The sample JVMTI agent searches for the extension event <code>VmDumpStart</code> in the list of <code>jvmtiExtensionEventInfo</code> structures, by using the identifier <code>COM_IBM_VM_DUMP_START</code> provided in <code>ibmjvmti.h</code>. When the event is found, the JVMTI agent calls the JVMTI interface <code>SetExtensionEventCallback()</code> to enable the event, providing a function <code>DumpStartCallback()</code> that is called when the event is triggered.</p> <p>Extension function: Next, the sample JVMTI agent searches for the extension function <code>SetVMDump</code> in the list of <code>jvmtiExtensionFunctionInfo</code> structures, by using the identifier <code>COM_IBM_SET_VM_DUMP</code> provided in <code>ibmjvmti.h</code>. The JVMTI agent calls the function by using the <code>jvmtiExtensionFunction</code> pointer to set a VM dump option <code>java:events=thrstart</code>. This option requests the VM to trigger a Java dump every time a VM thread is started.</p>"},{"location":"interface_jvmti/#dumpstartcallback","title":"<code>DumpStartCallback()</code>","text":"<p>This callback function issues a message when the associated extension event is called. In the sample code, <code>DumpStartCallback()</code> is used when the <code>VmDumpStart</code> event is triggered.</p>"},{"location":"interface_jvmti/#using-the-sample-jvmti-agent","title":"Using the sample JVMTI agent","text":"<ul> <li> <p>Build the sample JVMTI agent:</p> <p>Windows:</p> <pre><code>cl /I&lt;jre_path&gt;\\include /MD /FetiSample.dll tiSample.c /link /DLL\n</code></pre> <p>Linux, AIX\u00ae, and z/OS\u00ae:</p> <pre><code>gcc -I&lt;jre_path&gt;/include -o libtiSample.so -shared tiSample.c\n</code></pre> <p>where <code>&lt;jre_path&gt;</code> is the path to your Java runtime environment installation.</p> </li> <li> <p>To run the sample JVMTI agent, use the command:</p> <pre><code>java -agentlib:tiSample -version\n</code></pre> <p>When the sample JVMTI agent loads, messages are generated. When the JVMTI agent initiates a Java dump, the message <code>JVMDUMP010</code> is issued.</p> </li> </ul>"},{"location":"interface_jvmti/#api-reference","title":"API reference","text":"<p>The following sections provide reference information for the OpenJ9 extensions to the JVMTI.</p>"},{"location":"interface_jvmti/#getosthreadid","title":"<code>GetOSThreadID</code>","text":"<p>You can get the OS thread ID by using the <code>GetOSThreadID()</code> API:</p> <pre><code>jvmtiError GetOSThreadID(jvmtiEnv* jvmti_env, jthread thread, jlong * threadid_ptr);\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>thread</code>: The thread for which the ID is required.</li> <li><code>threadid_ptr</code>: A pointer to a variable, used to return the thread ID that corresponds to the thread specified by the <code>thread</code> parameter.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>threadid_ptr</code> parameter is null. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_INVALID_THREAD</code>: The thread is not valid. <code>JVMTI_ERROR_THREAD_NOT_ALIVE</code>: The VM state of the thread is not started or has died. <code>JVMTI_ERROR_UNATTACHED_THREAD</code>: The current thread is not attached to the VM. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI start or live phase.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.GetOSThreadID</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_GET_OS_THREAD_ID</code></p>"},{"location":"interface_jvmti/#queryvmdump","title":"<code>QueryVmDump</code>","text":"<p>You can query the VM dump options that are set for a VM by using the <code>QueryVmDump()</code> API:</p> <pre><code>jvmtiError QueryVmDump(jvmtiEnv* jvmti_env, jint buffer_size, void* options_buffer, jint* data_size_ptr)\n</code></pre> <p>This extension returns a set of dump option specifications as ASCII strings. The syntax of the option string is the same as the <code>-Xdump</code> command-line option, with the initial <code>-Xdump:</code> omitted. See -Xdump. The option strings are separated by newline characters. If the memory buffer is too small to contain the current VM dump option strings, you can expect the following results:</p> <ul> <li>The error message <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code> is returned.</li> <li>The variable for <code>data_size_ptr</code> is set to the required buffer size.</li> </ul> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>buffer_size</code>: The size of the supplied memory buffer in bytes.</li> <li><code>options_buffer</code>: A pointer to the supplied memory buffer.</li> <li><code>data_size_ptr</code>: A pointer to a variable, used to return the total size of the option strings.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>options_buffer</code> or <code>data_size_ptr</code> parameters are null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The supplied memory buffer in <code>options_buffer</code> is too small.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.QueryVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_QUERY_VM_DUMP</code></p>"},{"location":"interface_jvmti/#setvmdump","title":"<code>SetVmDump</code>","text":"<p>You can set VM dump options by using the <code>SetVmDump()</code> API:</p> <pre><code>jvmtiError SetVmDump(jvmtiEnv* jvmti_env, char* option)\n</code></pre> <p>The dump option is passed in as an ASCII character string. Use the same syntax as the <code>-Xdump</code> command-line option, with the initial <code>-Xdump:</code> omitted. See -Xdump.</p> <p>When dumps are in progress, the dump configuration is locked, and calls to <code>SetVmDump()</code> fail with a return value of <code>JVMTI_ERROR_NOT_AVAILABLE</code>.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>option</code>: The VM dump option string. Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The parameter option is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The parameter option contains an invalid <code>-Xdump</code> string.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.SetVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_SET_VM_DUMP</code></p>"},{"location":"interface_jvmti/#triggervmdump","title":"<code>TriggerVmDump</code>","text":"<p>You can trigger a VM dump and specify the type of dump you want by using the <code>TriggerVmDump()</code> API:</p> <pre><code>jvmtiError TriggerVmDump(jvmtiEnv* jvmti_env, char* option)\n</code></pre> <p>Choose the type of dump required by specifying an ASCII string that contains one of the supported dump agent types. See -Xdump. JVMTI events are provided at the start and end of the dump.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li> <p><code>option</code>: A pointer to the dump type string, which can be one of the following types:  </p> <p><code>stack</code> <code>java</code> <code>system</code> <code>console</code> <code>tool</code> <code>heap</code> <code>snap</code> <code>ceedump</code> (z/OS only)  </p> <p> Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.</p> </li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The option parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.TriggerVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_TRIGGER_VM_DUMP</code></p>"},{"location":"interface_jvmti/#resetvmdump","title":"<code>ResetVmDump</code>","text":"<p>You can reset VM dump options to the values at VM initialization by using the <code>ResetVmDump()</code> API:</p> <pre><code>jvmtiError ResetVmDump(jvmtiEnv* jvmti_env)\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: The JVMTI environment pointer.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The dump configuration is locked because a dump is in progress.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.ResetVmDump</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_RESET_VM_DUMP</code></p>"},{"location":"interface_jvmti/#vmdumpstart","title":"<code>VMDumpStart</code>","text":"<p>The following JVMTI event function is called when a VM dump starts:</p> <pre><code>void JNICALL VMDumpStart(jvmtiEnv *jvmti_env, JNIEnv* jni_env, char* label, char* event, char* detail)\n</code></pre> <p>The event function provides the dump file name, the name of the JVMTI event, and the detail string from the dump event. The detail string provides additional information about the event that triggered the dump. This information is the same as the information detailed in the <code>JVMDUMP039I</code> message. For example:</p> <pre><code>JVMDUMP039I Processing dump event \"systhrow\", detail \"java/lang/OutOfMemoryError\" at 2014/10/17 13:31:03 - please wait.\"\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: JVMTI environment pointer.</li> <li><code>jni_env</code>: JNI environment pointer for the thread on which the event occurred.</li> <li><code>label</code>: The dump file name, including directory path.</li> <li><code>event</code>: The extension event name, such as <code>com.ibm.VmDumpStart</code>.</li> <li><code>detail</code>: The dump event detail string. The string can be empty.</li> </ul> <p>Returns</p> <p>None</p>"},{"location":"interface_jvmti/#vmdumpend","title":"<code>VMDumpEnd</code>","text":"<p>The following JVMTI event function is called when a VM dump ends:</p> <pre><code>void JNICALL VMDumpEnd(jvmtiEnv *jvmti_env, JNIEnv* jni_env, char* label, char* event, char* detail)\n</code></pre> <p>The event function provides the dump file name, the name of the JVMTI event, and the detail string from the dump event. The detail string provides additional information about the event that triggered the dump. This information is the same as the information detailed in the <code>JVMDUMP039I</code> message. For example:</p> <pre><code>JVMDUMP039I Processing dump event \"systhrow\", detail \"java/lang/OutOfMemoryError\" at 2014/10/17 13:31:03 - please wait.\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: JVMTI environment pointer.  </li> <li><code>jni_env</code>: JNI environment pointer for the thread on which the event occurred.  </li> <li><code>label</code>: The dump file name, including directory path.  </li> <li><code>event</code>: The extension event name <code>com.ibm.VmDumpEnd</code>.  </li> <li><code>detail</code>: The dump event detail string. The string can be empty.  </li> </ul> <p>Returns</p> <p>None</p>"},{"location":"interface_jvmti/#setvmtrace","title":"<code>SetVmTrace</code>","text":"<p>You can set VM trace options by using the <code>SetVmTrace()</code> API:</p> <pre><code>jvmtiError SetVmTrace(jvmtiEnv* jvmti_env, char* option)\n</code></pre> <p>The trace option is passed in as an ASCII character string. Use the same syntax as the <code>-Xtrace</code> command-line option, with the initial <code>-Xtrace:</code> omitted. See -Xtrace.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: JVMTI environment pointer.</li> <li><code>option</code>: Enter the VM trace option string. Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The option parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The option parameter contains an invalid <code>-Xtrace</code> string.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.SetVmTrace</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_SET_VM_TRACE</code></p>"},{"location":"interface_jvmti/#registertracepointsubscriber","title":"<code>RegisterTracePointSubscriber</code>","text":"<p>You can subscribe to VM tracepoints by using the <code>RegisterTracePointSubscriber()</code> API:</p> <pre><code>jvmtiError RegisterTracePointSubscriber(jvmtiEnv* jvmti_env, char *description, jvmtiTraceSubscriber subscriber, jvmtiTraceAlarm alarm, void *userData, void **subscriptionID)\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>description</code>: An ASCII character string that describes the subscriber.</li> <li><code>subscriber</code>: A function of type <code>jvmtiTraceSubscriber</code>.</li> <li><code>alarm</code>: A function pointer of type <code>jvmtiTraceAlarm</code>.</li> <li><code>user_data</code>: A pointer to user data. This pointer is passed to the subscriber and alarm functions each time these functions are called. This pointer can be a null value.</li> <li><code>subscription_id</code>: A pointer to a subscription identifier. This pointer is returned by the <code>RegisterTracePointSubscriber</code> call if successful. The value must be supplied to a future call to the <code>DeregisterTracePointSubscriber</code> API, which is used to unsubscribe from the VM tracepoint.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: One of the supplied parameters is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: VM trace is not available. <code>JVMTI_ERROR_INTERNAL</code>: An internal error occurred.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.RegisterTracePointSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_REGISTER_TRACEPOINT_SUBSCRIBER</code></p>"},{"location":"interface_jvmti/#jvmtitracesubscriber-function","title":"<code>jvmtiTraceSubscriber</code> function","text":"<p>The subscriber function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiTraceSubscriber)(jvmtiEnv *jvmti_env, void *record, jlong length, void *user_data);\n</code></pre> <p>The subscriber function must be of type <code>jvmtiTraceSubscriber</code>, which is declared in <code>ibmjvmti.h</code>.</p> <p>This function is called with each tracepoint record that is selected through the <code>-Xtrace:external</code> option.</p> <p>The tracepoint record that is supplied to the subscriber function is valid only for the duration of the function. If the subscriber wants to save the data, the data must be copied elsewhere.</p> <p>If the subscriber function returns an error, the alarm function is called, the subscription is disconnected, and no further tracepoints are sent to the subscriber.</p> <p>Subscriber function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>record</code>: A UTF-8 string that contains a tracepoint record.</li> <li><code>length</code>: The number of UTF-8 characters in the tracepoint record.</li> <li><code>user_data</code>: User data that is supplied when the subscriber is registered.</li> </ul>"},{"location":"interface_jvmti/#jvmtitracealarm-function","title":"<code>jvmtiTraceAlarm</code> function","text":"<p>The alarm function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiTraceAlarm)(jvmtiEnv *jvmti_env, void *subscription_id, void *user_data);\n</code></pre> <p>The alarm function must be of type <code>jvmtiTraceAlarm</code>, which is declared in <code>ibmjvmti.h</code>. This function is called if the subscriber function returns an error.</p> <p>Alarm function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>subscription_id</code>: The subscription identifier.</li> <li><code>user_data</code>: User data that is supplied when the subscriber is registered.</li> </ul>"},{"location":"interface_jvmti/#deregistertracepointsubscriber","title":"<code>DeregisterTracePointSubscriber</code>","text":"<p>You can unsubscribe from VM tracepoints by using the <code>DeregisterTracePointSubscriber()</code> API:</p> <pre><code>jvmtiError DeregisterTracePointSubscriber(jvmtiEnv* jvmti_env, void *userData, void *subscription_id)\n</code></pre> <p>After the <code>DeregisterTracePointSubscriber()</code> API is called, no further calls are made to the subscriber function.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>subscription_id</code>: The subscription identifier that is returned by the call to the RegisterTracePointSubscriber API.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>subscription_id</code> parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.DeregisterTracePointSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_DEREGISTER_TRACEPOINT_SUBSCRIBER</code></p>"},{"location":"interface_jvmti/#getmemorycategories","title":"<code>GetMemoryCategories</code>","text":"<p>You can query runtime environment native memory categories by using the <code>GetMemoryCategories()</code> API:</p> <pre><code>jvmtiError GetMemoryCategories(jvmtiEnv* env, jint version, jint max_categories, jvmtiMemoryCategory * categories_buffer, jint * written_count_ptr, jint * total_categories_ptr);\n</code></pre> <p>You can query the total native memory consumption of the runtime environment for each memory category by using this API. Native memory is memory requested from the operating system using library functions such as <code>malloc()</code> and <code>mmap()</code>. Runtime environment native memory use is grouped under high-level memory categories, as described in the <code>NATIVEMEMINFO</code> section of the Java dump topic. The data returned by the <code>GetMemoryCategories()</code> API is consistent with this format. See Java dump: NATIVEMEMINFO.</p> <p>The extension writes native memory information to a memory buffer specified by the user. Each memory category is recorded as a <code>jvmtiMemoryCategory</code> structure, whose format is defined in <code>ibmjvmti.h</code>.</p> <p>You can use the <code>GetMemoryCategories()</code> API to work out the buffer size you must allocate to hold all memory categories defined inside the VM. To calculate the size, call the API with a null <code>categories_buffer</code> argument and a non-null <code>total_categories_ptr</code> argument.</p> <p>Parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment.</li> <li><code>version</code>: The version of the <code>jvmtiMemoryCategory</code> structure that you are using. Use <code>COM_IBM_GET_MEMORY_CATEGORIES_VERSION_1</code> for this argument, unless you must work with an obsolete version of the <code>jvmtiMemoryCategory</code> structure.</li> <li><code>max_categories</code>: The number of <code>jvmtiMemoryCategory</code> structures that can fit in the <code>categories_buffer</code> memory buffer.</li> <li><code>categories_buffer</code>: A pointer to the memory buffer for holding the result of the <code>GetMemoryCategories()</code> call. The number of <code>jvmtiMemoryCategory</code> slots available in the <code>categories_buffer</code> memory buffer must be accurately specified with <code>max_categories</code>, otherwise <code>GetMemoryCategories()</code> can overflow the memory buffer. The value can be null.</li> <li><code>written_count_ptr</code>: A pointer to <code>jint</code> to store the number of <code>jvmtiMemoryCategory</code> structures to be written to the <code>categories_buffer</code> memory buffer. The value can be null.</li> <li><code>total_categories_ptr</code>: A pointer to <code>jint</code> to store the total number of memory categories declared in the VM. The value can be null.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_UNSUPPORTED_VERSION</code>: Unrecognized value passed for version. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: Illegal argument; <code>categories_buffer</code>, <code>count_ptr</code>, and <code>total_categories_ptr</code> all have null values. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>env</code> parameter is invalid. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: Memory category data is truncated because <code>max_categories</code> is not large enough.  </p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.GetMemoryCategories</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_GET_MEMORY_CATEGORIES</code></p>"},{"location":"interface_jvmti/#queryvmlogoptions","title":"<code>QueryVmLogOptions</code>","text":"<p>You can query VM log options by using the <code>QueryVmLogOptions()</code> API:</p> <pre><code>jvmtiError QueryVmLogOptions(jvmtiEnv* jvmti_env, jint buffer_size, void* options, jint* data_size_ptr)\n</code></pre> <p>This extension returns the current log options as an ASCII string. The syntax of the string is the same as the <code>-Xsyslog</code> command-line option, with the initial <code>-Xsyslog:</code> omitted. For example, the string \"error,warn\" indicates that the VM is set to log error and warning messages only. For more information, see <code>-Xsyslog</code>.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.  </li> <li><code>buffer_size</code>: The size of the supplied memory buffer in bytes. If the memory buffer is too small to contain the current VM log option string, the <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code> error message is returned.  </li> <li><code>options_buffer</code>: A pointer to the supplied memory buffer.  </li> <li><code>data_size_ptr</code>: A pointer to a variable, used to return the total size of the option string.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>options</code> or <code>data_size_ptr</code> parameters are null. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The supplied memory buffer is too small.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.QueryVmLogOptions</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_QUERY_VM_LOG_OPTIONS</code></p>"},{"location":"interface_jvmti/#setvmlogoptions","title":"<code>SetVmLogOptions</code>","text":"<p>You can set VM log options by using the <code>SetVmLogOptions()</code> API:</p> <pre><code>jvmtiError SetVmLogOptions(jvmtiEnv* jvmti_env, char* options_buffer)\n</code></pre> <p>The log option is passed in as an ASCII character string. Use the same syntax as the <code>-Xsyslog</code> command-line option, with the initial <code>-Xsyslog:</code> omitted. For example, to set the VM to log error and warning messages, pass in a string containing \"error,warn\". For more information, see <code>-Xsyslog</code>.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>options_buffer</code>: A pointer to memory containing the log option.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The parameter option is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is invalid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The parameter option contains an invalid <code>-Xsyslog</code> string.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.SetVmLogOptions</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_SET_VM_LOG_OPTIONS</code></p>"},{"location":"interface_jvmti/#iteratesharedcaches","title":"<code>IterateSharedCaches</code>","text":"<p>You can search for shared classes caches that exist in a specified cache directory by using the <code>IterateSharedCaches()</code> API:</p> <pre><code>jvmtiError IterateSharedCaches(jvmtiEnv* env, jint version, const char *cacheDir, jint flags, jboolean useCommandLineValues, jvmtiIterateSharedCachesCallback callback, void *user_data);\n</code></pre> <p>Information about the caches is returned in a structure that is populated by a user-specified callback function. You can specify the search directory in two ways:</p> <ul> <li>Set the value of <code>useCommandLineValues</code> to <code>true</code> and specify the directory on the command line. If the directory is not specified on the command line, the default location for the platform is used.</li> <li>Set the value of <code>useCommandLineValues</code> to <code>false</code> and use the <code>cacheDir</code> parameter. To accept the default location for the platform, specify <code>cacheDir</code> with a <code>null</code> value.</li> </ul> <p>Parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment.</li> <li><code>version</code>: Version information for <code>IterateSharedCaches</code>, which describes the <code>jvmtiSharedCacheInfo</code> structure passed to the <code>jvmtiIterateSharedCachesCallback</code> function. The values allowed are:<ul> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_1</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_2</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_3</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_4</code></li> <li><code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_5</code></li> </ul> </li> <li><code>cacheDir</code>: When the value of <code>useCommandLineValues</code> is <code>false</code>, specify the absolute path of the directory for the shared classes cache. If the value is <code>null</code>, the platform-dependent default is used.</li> <li><code>flags</code>: Reserved for future use. The only value allowed is <code>COM_IBM_ITERATE_SHARED_CACHES_NO_FLAGS</code>.</li> <li><code>useCommandLineValues</code>: Set this value to <code>true</code> when you want to specify the cache directory on the command line. Set this value to <code>false</code> when you want to use the <code>cacheDir</code> parameter.</li> <li><code>callback</code>: A function pointer to a user provided callback routine <code>jvmtiIterateSharedCachesCallback</code>.</li> <li><code>user_data</code>: User supplied data, passed as an argument to the callback function.  <pre><code>jint (JNICALL *jvmtiIterateSharedCachesCallback)(jvmtiEnv *env,jvmtiSharedCacheInfo *cache_info, void *user_data);\n</code></pre> </li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_UNSUPPORTED_VERSION</code>: The <code>version</code> parameter is not valid. <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>callback</code> parameter is null. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The shared classes feature is not enabled in the VM. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The <code>flags</code> parameter is not valid. <code>JVMTI_ERROR_INTERNAL</code>: This error is returned when the <code>jvmtiIterateSharedCachesCallback</code> returns <code>JNI_ERR</code>.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.IterateSharedCaches</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_ITERATE_SHARED_CACHES</code></p>"},{"location":"interface_jvmti/#jvmtiiteratesharedcachescallback-function","title":"<code>jvmtiIterateSharedCachesCallback</code> function","text":"<p>Callback function parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment when calling <code>COM_IBM_ITERATE_SHARED_CACHES</code>.</li> <li><code>cache_info</code>: A <code>jvmtiSharedCacheInfo</code> structure containing information about a shared cache.</li> <li><code>user_data</code>: User-supplied data, passed as an argument to <code>IterateSharedCaches</code>.</li> </ul> <p>Callback function returns</p> <p><code>JNI_OK</code>: Continue iterating. <code>JNI_ERR</code>: Stop iterating, which causes <code>IterateSharedCaches</code> to return <code>JVMTI_ERROR_INTERNAL</code></p>"},{"location":"interface_jvmti/#jvmtisharedcacheinfo-structure","title":"<code>jvmtiSharedCacheInfo</code> structure","text":"<p>The structure of <code>jvmtiSharedCacheInfo</code></p> <pre><code>typedef struct jvmtiSharedCacheInfo {\nconst char *name;      // the name of the shared cache\njboolean isCompatible; // if the shared cache is compatible with this VM\njboolean isPersistent; // true if the shared cache is persistent, false if its non-persistent\njint os_shmid;         // the OS shared memory ID associated with a non-persistent cache, -1 otherwise\njint os_semid;         // the OS shared semaphore ID associated with a non-persistent cache, -1 otherwise\njint modLevel;         // one of:\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA5\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA6\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA7\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA8\n                       //   COM_IBM_SHARED_CACHE_MODLEVEL_JAVA9\n                       //   from Java 10: the version number of the Java level on which the shared cache is created\njint addrMode;         // the address mode of the VM creating the shared cache: includes additional\n                       // information on whether it is a 64-bit compressedRefs cache when\n                       // COM_IBM_ITERATE_SHARED_CACHES_VERSION_3 or later is specified.\njboolean isCorrupt;    // if the cache is corrupted\njlong cacheSize;       // the total usable shared classes cache size, or -1 when isCompatible is false\njlong freeBytes;       // the number of free bytes in the shared classes cache, or -1 when isCompatible is false\njlong lastDetach;      // the last detach time specified in milliseconds since 00:00:00 on 1 January 1970 UTC,\n                       // or -1 when the last detach time is not available\njint cacheType;        // the type of the cache\njlong softMaxBytes;    // the soft limit for the available space in the cache\njint layer;            // the shared cache layer number\n} jvmtiSharedCacheInfo;\n</code></pre> <p> Notes:</p> <ul> <li> <p>The field <code>cacheType</code> is included when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_2</code> or later is specified.</p> </li> <li> <p><code>jvmtiSharedCacheInfo.addrMode</code> encodes both address mode and the compressed reference mode when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_3</code> or later is specified. In this case, use the following set of macros to access the address mode and compressed reference mode:</p> </li> </ul> <p>To get the address mode, use:</p> <pre><code>COM_IBM_ITERATE_SHARED_CACHES_GET_ADDR_MODE(jvmtiSharedCacheInfo.addrMode)\n</code></pre> <p>This macro returns one of the following values: <code>COM_IBM_SHARED_CACHE_ADDRMODE_32</code> <code>COM_IBM_SHARED_CACHE_ADDRMODE_64</code> </p> <p>To get the compressed references mode, use:</p> <pre><code>COM_IBM_ITERATE_SHARED_CACHES_GET_CMPRSSREF_MODE(jvmtiSharedCacheInfo.addrMode)\n</code></pre> <p>This macro returns one of the following values: <code>COM_IBM_ITERATE_SHARED_CACHES_UNKNOWN_COMPRESSED_POINTERS_MODE</code> <code>COM_IBM_ITERATE_SHARED_CACHES_COMPRESSED_POINTERS_MODE</code> <code>COM_IBM_ITERATE_SHARED_CACHES_NON_COMPRESSED_POINTERS_MODE</code> </p> <ul> <li> <p>The field <code>softMaxBytes</code> is included when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_4</code> or later is specified.</p> </li> <li> <p>The field <code>layer</code> is included when <code>COM_IBM_ITERATE_SHARED_CACHES_VERSION_5</code> or later is specified. If the shared cache does not have a layer number, the value for <code>layer</code> is <code>-1</code>.</p> </li> </ul>"},{"location":"interface_jvmti/#destroysharedcache","title":"<code>DestroySharedCache</code>","text":"<p>You can remove a shared classes cache by using the <code>DestroySharedCache()</code> API:</p> <pre><code>jvmtiError DestroySharedCache(jvmtiEnv *env, const char *cacheDir, const char *name, jint persistence, jboolean useCommandLineValues, jint *internalErrorCode);\n</code></pre> <p>This extension removes a named shared classes cache of a given persistence type, in a given directory. You can specify the cache name, persistence type, and directory in one of these ways:</p> <ul> <li> <p>Set <code>useCommandLineValues</code> to <code>true</code> and specify the values on the command line. If a value is not available, the default values for the platform are used.</p> </li> <li> <p>Set <code>useCommandLineValues</code> to <code>false</code> and use the <code>cacheDir</code>, <code>persistence</code> and <code>cacheName</code> parameters to identify the cache to be removed. To accept the default value for <code>cacheDir</code> or <code>cacheName</code>, specify the parameter with a <code>null</code> value.</p> </li> </ul> <p>Parameters</p> <ul> <li><code>env</code>: A pointer to the JVMTI environment.</li> <li><code>cacheDir</code>: When the value of <code>useCommandLineValues</code> is <code>false</code>, specify the absolute path of the directory for the shared classes cache. If the value is <code>null</code>, the platform-dependent default is used.</li> <li><code>cacheName</code>: When the value of <code>useCommandLineValues</code> is <code>false</code>, specify the name of the cache to be removed. If the value is <code>null</code>, the platform-dependent default is used.</li> <li><code>persistence</code>: When the value of <code>useCommandLineValues</code> is false, specify the type of cache to remove. This parameter must have one of the following values: <code>PERSISTENCE_DEFAULT</code> (The default value for the platform). <code>PERSISTENT</code> <code>NONPERSISTENT</code> </li> <li><code>useCommandLineValues</code>: Set this value to <code>true</code> when you want to specify the shared classes cache name, persistence type, and directory on the command line. Set this value to <code>false</code> when you want to use the <code>cacheDir</code>, <code>persistence</code>, and <code>cacheName</code> parameters instead.</li> <li><code>internalErrorCode</code>: If not <code>null</code>, this value is set to one of the following constants when <code>JVMTI_ERROR_INTERNAL</code> is returned:  <ul> <li><code>COM_IBM_DESTROYED_ALL_CACHE</code>: Set when <code>JVMTI_ERROR_NONE is</code> returned.</li> <li><code>COM_IBM_DESTROYED_NONE</code>: Set when the function fails to remove any caches.  </li> <li><code>COM_IBM_DESTROY_FAILED_CURRENT_GEN_CACHE</code>: Set when the function fails to remove the existing current generation cache, irrespective of the state of older generation caches.  </li> <li><code>COM_IBM_DESTROY_FAILED_OLDER_GEN_CACHE</code>: Set when the function fails to remove any older generation caches. The current generation cache does not exist or is successfully removed.</li> </ul> </li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. No cache exists or all existing caches of all generations are removed. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: The shared classes feature is not enabled in the VM. <code>JVMTI_ERROR_ILLEGAL_ARGUMENT</code>: The <code>persistence</code> parameter is not valid. <code>JVMTI_ERROR_INTERNAL</code>: Failed to remove any existing cache with the given name. See the value of the <code>internalErrorCode</code> parameter for more information about the failure.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.DestroySharedCache</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_DESTROY_SHARED_CACHE</code></p>"},{"location":"interface_jvmti/#registerverbosegcsubscriber","title":"<code>RegisterVerboseGCSubscriber</code>","text":"<p>You can subscribe to verbose garbage collection (GC) data logging by using the <code>RegisterVerboseGCSubscriber()</code> API:</p> <pre><code>jvmtiError RegisterVerboseGCSubscriber(jvmtiEnv* jvmti_env, char *description, jvmtiVerboseGCSubscriber subscriber, jvmtiVerboseGCAlarm alarm, void *user_data, void **subscription_id)\n</code></pre> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>description</code>: An ASCII character string that describes the subscriber.</li> <li><code>subscriber</code>: A function of type <code>jvmtiVerboseGCSubscriber</code>.</li> <li><code>alarm</code>: A function pointer of type <code>jvmtiVerboseGCAlarm</code>.</li> <li><code>user_data</code>: A pointer to user data. This pointer is passed to the subscriber and alarm functions each time these functions are called. This pointer can be a null value.</li> <li><code>subscription_id</code>: A pointer to a subscription identifier. This pointer is returned by the <code>RegisterVerboseGCSubscriber</code> call if successful. The value must be supplied to a future call to <code>DeregisterVerboseGCSubscriber</code> API, which is used to unsubscribe from verbose GC data logging.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: One of the supplied parameters is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase. <code>JVMTI_ERROR_NOT_AVAILABLE</code>: GC verbose logging is not available. <code>JVMTI_ERROR_INTERNAL</code>: An internal error has occurred.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.RegisterVerboseGCSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_REGISTER_VERBOSEGC_SUBSCRIBER</code></p>"},{"location":"interface_jvmti/#jvmtiverbosegcsubscriber-function","title":"<code>jvmtiVerboseGCSubscriber</code> function","text":"<p>The subscriber function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiVerboseGCSubscriber)(jvmtiEnv *jvmti_env, const char *record, jlong length, void *user_data);\n</code></pre> <p>The subscriber function must be of type <code>jvmtiVerboseGCSubscriber</code>, which is declared in <code>ibmjvmti.h</code>.</p> <p>This function is called with each record of verbose logging data produced by the VM.</p> <p>This function runs under the same restrictions as the <code>GarbageCollectionStart</code> and <code>GarbageCollectionFinish</code> events in the standard JVMTI specification. For more information about these events, see the JVMTI Event Index for your OpenJDK version.</p> <p>The verbose logging record supplied to the subscriber function is valid only for the duration of the function. If the subscriber wants to save the data, the data must be copied elsewhere.</p> <p>If the subscriber function returns an error, the alarm function is called, and the subscription is deregistered.</p> <p>Subscriber function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>record</code>: An ASCII string that contains a verbose log record.</li> <li><code>length</code>: The number of ASCII characters in the verbose log record.</li> <li><code>user_data</code>: User data supplied when the subscriber is registered.</li> </ul>"},{"location":"interface_jvmti/#jvmtiverbosegcalarm-function","title":"<code>jvmtiVerboseGCAlarm</code> function","text":"<p>The alarm function type is defined as follows:</p> <pre><code>typedef jvmtiError (*jvmtiVerboseGCAlarm)(jvmtiEnv *jvmti_env, void *subscription_id, void *user_data);\n</code></pre> <p>The alarm function must be of type <code>jvmtiVerboseGCAlarm</code>, which is declared in <code>ibmjvmti.h</code>. This function is called if the subscriber function returns an error.</p> <p>This function runs under the same restrictions as the <code>GarbageCollectionStart</code> and <code>GarbageCollectionFinish</code> events in the standard JVMTI specification. For more information about these events, see the JVMTI Event Index for your OpenJDK version.</p> <p>Alarm function parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>user_data</code>: User data supplied when the subscriber is registered.</li> <li><code>subscription_id</code>: The subscription identifier.</li> </ul>"},{"location":"interface_jvmti/#deregisterverbosegcsubscriber","title":"<code>DeregisterVerboseGCSubscriber</code>","text":"<p>You can unsubscribe from verbose Garbage Collection (GC) data logging by using the <code>DeregisterVerboseGCSubscriber()</code> API:</p> <pre><code>jvmtiError DeregisterVerboseGCSubscriber(jvmtiEnv* jvmti_env, void *userData, void *subscription_id)\n</code></pre> <p>After the <code>DeregisterVerboseGCSubscriber()</code> API is called, no further calls are made to the previously registered subscriber function.</p> <p>Parameters</p> <ul> <li><code>jvmti_env</code>: A pointer to the JVMTI environment.</li> <li><code>subscription_id</code>: The subscription identifier that is returned by the call to the RegisterVerboseGCSubscriber() API.</li> </ul> <p>Returns</p> <p><code>JVMTI_ERROR_NONE</code>: Success. <code>JVMTI_ERROR_NULL_POINTER</code>: The <code>subscription_id</code> parameter is null. <code>JVMTI_ERROR_OUT_OF_MEMORY</code>: There is insufficient system memory to process the request. <code>JVMTI_ERROR_INVALID_ENVIRONMENT</code>: The <code>jvmti_env</code> parameter is not valid. <code>JVMTI_ERROR_WRONG_PHASE</code>: The extension has been called outside the JVMTI live phase.</p> <p>Identifiers</p> <p>JVMTI Extension Function identifier: <code>com.ibm.DeregisterVerboseGCSubscriber</code> Macro declaration in the <code>ibmjvmti.h</code> file: <code>COM_IBM_DEREGISTER_VERBOSEGC_SUBSCRIBER</code></p>"},{"location":"interface_lang_management/","title":"Language Management","text":""},{"location":"interface_lang_management/#language-management-interface","title":"Language management interface","text":"<p>Eclipse OpenJ9\u2122 provides MXBean extensions to the standard <code>java.lang.management</code> API, which can be used to monitor and manage the Java\u2122 virtual machine. These extensions provide access to information about the state of the OpenJ9 VM and the environment in which it is running. The following tables list the MXBeans by package and describe the monitoring or management capabilities.</p> <p>Package: <code>com.ibm.lang.management</code></p> MXBean Description <code>GarbageCollectorMXBean</code> Discovers Garbage Collection (GC) operations (collection times, compactions, heap memory usage, and freed memory). <code>JvmCpuMonitorMXBean</code> Discovers CPU consumption by category (GC, JIT, or other threads). <code>MemoryMXBean</code> Discovers memory usage (minimum and maximum heap sizes, and shared classes cache sizes). <code>MemoryPoolMXBean</code> Discovers memory pool usage for specific GC policies. <code>OperatingSystemMXBean</code> Discovers information about the operating system (memory, CPU capacity/utilization). <code>RuntimeMXBean</code> Discovers information about the runtime environment (CPU load, Java process ID, and VM state) <code>ThreadMXBean</code> Discovers information about native thread IDs. <code>UnixOperatingSystemMXBean</code> Discovers information for Unix operating systems (memory, file descriptors, processors, processor usage, and hardware) <p>Package: <code>com.ibm.virtualization.management</code></p> MXBean Description <code>GuestOSMXBean</code> Discovers CPU and memory statistics of a virtual machine or logical partition as seen by the Hypervisor. <code>HypervisorMXBean</code> Discovers whether the operating system is running on a hypervisor and provides information about the hypervisor. <p>Package: <code>openj9.lang.management</code></p> MXBean Description <code>OpenJ9DiagnosticsMXBean</code> Configures and dynamically triggers dump agents. <p>For more information about using these MXBeans, read the API documentation. For Java 8, see the OpenJ9 Language Management API documentation. </p>"},{"location":"introduction/","title":"Getting started","text":""},{"location":"introduction/#getting-started-with-eclipse-openj9","title":"Getting started with Eclipse OpenJ9","text":"<p>Eclipse OpenJ9\u2122 is a high performance, scalable, Java\u2122 virtual machine (VM) implementation that is fully compliant with the Java Virtual Machine Specification.</p> <p>At run time, the VM interprets the Java bytecode that is compiled by the Java compiler. The VM acts as a translator between the language and the underlying operating system and hardware. A Java program requires a specific VM to run on a particular platform, such as Linux\u00ae, z/OS\u00ae, or Windows\u2122.</p> <p>This material provides information about the VM configuration and tuning options, together with the default settings. Follow the links provided for more detailed information.</p>"},{"location":"introduction/#configuring-your-system","title":"Configuring your system","text":"<p>Most Java applications should run on an OpenJDK that contains the OpenJ9 VM without changing anything on the underlying system. However, to get the most out of your system you might want to consider some configuration options. Read Configuring your system to learn more about the following options:</p> <ul> <li>Setting operating system environment variables, such as PATH and CLASSPATH.</li> <li>Increasing resource limits for running Java applications.</li> <li>Configuring large page memory allocation.</li> <li>Configuring Dynamic LPAR support on AIX\u00ae systems.</li> </ul>"},{"location":"introduction/#performance-tuning","title":"Performance tuning","text":"<p>OpenJ9 is configured to start with a set of default options that provide the optimal runtime environment for Java applications with typical workloads. However, if your application is atypical, you can improve performance by tuning the OpenJ9 VM. You can also improve performance by enabling hardware features or using specific APIs in your application code.</p>"},{"location":"introduction/#garbage-collection-policies","title":"Garbage collection policies","text":"<p>OpenJ9 includes several garbage collection policies. To learn more about these policies and the types of application workload that can benefit from them, see Garbage collection policies.</p>"},{"location":"introduction/#class-data-sharing","title":"Class data sharing","text":"<p>You can share class data between running VMs, which can reduce the startup time for a VM after the cache has been created. For more information, see Introduction to class data sharing.</p>"},{"location":"introduction/#native-data-operations","title":"Native data operations","text":"<p>If your Java application manipulates native data, consider writing your application to take advantage of methods in the Data Access Accelerator (DAA) API.</p> <p>The following functions are provided:</p> <ul> <li>Arithmetic, comparison, shifting, and validation operations for packed decimal data.</li> <li>Conversion operations between different binary coded decimal and Java binary types.</li> <li>Marshalling operations: marshalling and unmarshalling Java binary types, such as <code>short</code>, <code>int</code>, <code>long</code>, <code>float</code>, and <code>double</code>, to and from byte arrays.</li> </ul> <p>You can gain a number of benefits by using the APIs provided:</p> <ul> <li>Improved application performance by avoiding object creation and intermediate processing, which can also put pressure on the Java heap.</li> <li>Hardware acceleration by automatically exploiting available hardware features on specific platforms.</li> <li>Platform independence for applications that are developed to take advantage of Data Access Acceleration.</li> </ul> <p>For more information, see the API documentation.</p>"},{"location":"introduction/#cloud-optimizations","title":"Cloud optimizations","text":"<p>To improve the performance of applications that run in containers, try setting the following tuning options:</p> <ul> <li> <p>Use a shared classes cache (<code>-Xshareclasses -XX:SharedCacheHardLimit=200m -Xscmx60m</code>) with Ahead-Of-Time (AOT) compilation to improve your startup time. For persistence, store the cache in a volume that you map to your container. For more information, see Introduction to class data sharing and AOT Compiler.</p> </li> <li> <p>Use the -Xtune:virtualized option, which configures OpenJ9 for typical cloud deployments where VM guests are provisioned with a small number of virtual CPUs to maximize the number of applications that can be run. When enabled, OpenJ9 adapts its internal processes to reduce the amount of CPU consumed and trim down the memory footprint. These changes come at the expense of only a small loss in throughput.</p> </li> <li> <p>Provide access to the <code>/proc</code> file system for container detection on Linux systems since the detection code requires access to the <code>/proc/1/cgroup</code> and <code>/proc/1/sched</code> files. If you mount the <code>/proc</code> file system with the <code>hidepid=2</code> option on Linux systems and the VM does not have root privileges, it cannot access the <code>/proc</code> file system and the container detection fails. Even though the container detection fails, the VM does start with a warning message. For example:</p> <p><code>JVMPORT050W Failed to identify if the JVM is running inside a container; error message: fopen failed to open /proc/1/cgroup file with errno=2.</code></p> <p>Although the VM starts after the container detection fails, the VM assumes that it is running outside a container. Therefore, if the VM is running in a container, the VM cannot adapt to the container's limitations and might use an undesirable amount of resources. You can evaluate the impact on performance because of the container detection failure and take steps to resolve the performance issue, if so required. Some of the steps that you can take are as follows:</p> <ul> <li> <p>Remount the <code>/proc</code> file system with the <code>hidepid=0</code> option: You can use this option to allow the VM to access the <code>/proc</code> file system. This action allows all processes access to <code>/proc</code> not just the VM.</p> <pre><code># Remount /proc with hidepid=0 to read the contents of /proc/&lt;PID&gt;\nmount -o remount,rw,hidepid=0 /proc\n\n# Apply the change to /proc persistently by editing /etc/fstab\nproc            /proc           proc    rw,nosuid,nodev,noexec,relatime,hidepid=0   0 0\n</code></pre> </li> <li> <p>Remount the <code>/proc</code> file system with the <code>gid</code> and <code>hidepid=2</code> options: You can use this option to allow only certain processes to access the <code>/proc</code> file system. You can add the processes in a group and provide access to that group with the <code>gid</code> option.</p> <pre><code># Create a group to allow certain users to read the contents of /proc/&lt;PID&gt;\ngroupadd -g 1000 procaccess\n\n# Add a user to the group procaccess\nusermod -a -G procaccess &lt;USER&gt;\n\n# Remount /proc with the gid option to allow users in group procaccess to access /proc\nmount -o remount,rw,hidepid=2,gid=1000 /proc\n\n# Apply the change to /proc persistently by editing /etc/fstab\nproc            /proc           proc    rw,nosuid,nodev,noexec,relatime,hidepid=2,gid=1000   0 0\n</code></pre> </li> </ul> </li> </ul> <p>The OpenJ9 VM automatically detects when it is running in a docker container and uses a mechanism to detect when the VM is idle. When an idle state is detected, OpenJ9 runs a garbage collection cycle and releases free memory pages back to the operating system. The object heap is also compacted to make best use of the available memory for further application processing. Compaction is triggered by internal heuristics that look into the number of fragmented pages. Typically there is no need to force a compaction.</p> <p>For cloud services that charge based on memory usage, maintaining a small footprint can generate cost savings. For more information about tuning options that control this process, see <code>-XX:IdleTuningMinIdleWaitTime</code>.</p>"},{"location":"introduction/#cryptographic-operations","title":"Cryptographic operations","text":"<p>OpenJDK uses the in-built Java cryptographic implementation by default. However, native cryptographic implementations typically provide better performance. OpenSSL is a native open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which is well established and used with many enterprise applications. For more information, see OpenSSL.</p>"},{"location":"introduction/#exploiting-gpus","title":"Exploiting GPUs","text":"<p>OpenJ9 provides both the CUDA4J API  and the GPU API,  which enables you to develop applications that can take advantage of graphics processing unit (GPU) processing for suitable functions, such as sorting arrays. You can also enable the JIT compiler to offload certain processing tasks to a GPU by specifying the <code>-Xjit:enableGPU</code> option on the command line. When enabled, the JIT compiler determines when to offload tasks based on performance heuristics.</p> <p>GPU processing is supported only on Linux little-endian systems, such as x86-64 and IBM Power LE, and Windows x86-64 systems. For more information about enabling GPU processing, see Exploiting graphics processing units.</p> <p>Special consideration is needed when using the WDDM driver model for GPUs on Windows. Using the WDDM driver model means the GPU is also used as a display device and as such is subject to the Timeout Detection and Recovery (TDR) mechanism of Windows. If you are running demanding GPU workloads, you should increase the timeout from the default 2 seconds. More detail may be found in NVIDIA's Installation Guide for Windows.</p>"},{"location":"introduction/#hardware-acceleration","title":"Hardware acceleration","text":"<p>On AIX\u00ae systems that contain the Nest accelerator (NX) co-processor, OpenJ9 can take advantage of the <code>zlibNX</code> library. This library is an enhanced version of the <code>zlib</code> compression library that supports hardware-accelerated data compression and decompression. The <code>zlibNX</code> library is supported on AIX version 7.2 TL4 and later and must be installed on the system. The Nest accelerator (NX) co-processor is available on IBM POWER9\u00ae systems. To learn more about <code>zlibNX</code>, see Data compression by using the zlibNX library.</p>"},{"location":"introduction/#runtime-options","title":"Runtime options","text":"<p>Runtime options are specified on the command line and include system properties, standard options, nonstandard (-X) options, and -XX options. For a detailed list of runtime options, see OpenJ9 command-line options</p>"},{"location":"introduction/#default-settings","title":"Default settings","text":"<p>If you do not specify any options on the command line at run time, the OpenJ9 VM starts with default settings that define how it operates. For more information about these settings, see Default settings for the OpenJ9 VM.</p>"},{"location":"introduction/#using-jlink","title":"Using jlink","text":"<p>On Java 11 and later, you can use the <code>jlink</code> utility to create a custom OpenJ9 runtime image, which allows you to optimize image size. If you do not require translations from the English language, the translation files can be removed to further optimize the size. You can achieve this by specifying the <code>--exclude-files=**java_**.properties</code> option when you run <code>jlink</code>. The default English <code>java.properties</code> file is unaffected.</p>"},{"location":"introduction/#using-jpackage","title":"Using jpackage","text":"<p>(Linux, macOS, and Windows only)</p> <p>You can use the <code>jpackage</code> utility to package a Java application into a platform-specific package that includes all of the necessary dependencies. Full details of the tool are available at JEP 392: Packaging Tool. Instructions for using it and the various options available, are documented in the Oracle Tool Specifications: The jpackage Command.</p>"},{"location":"introduction/#troubleshooting","title":"Troubleshooting","text":"<p>The OpenJ9 diagnostic component contains extensive features to assist with problem determination. Diagnostic data is produced under default conditions, but can also be controlled by starting the VM with the -Xdump option or using the <code>com.ibm.jvm.Dump</code> API. You can also trace Java applications, methods, and VM operations by using the -Xtrace option.</p> <p>To get started, read Diagnostic tools and data.</p>"},{"location":"jit/","title":"JIT Compiler","text":""},{"location":"jit/#the-jit-compiler","title":"The JIT compiler","text":"<p>The Just-In-Time (JIT) compiler is a key component of the Eclipse OpenJ9\u2122 VM that improves the performance of Java applications by compiling platform-neutral Java bytecode into native machine code at run time. Without the JIT, the VM has to interpret the bytecodes itself - a process that requires extra CPU and memory.</p> <p>The JIT compiler doesn't compile every method that gets called because thousands of methods can be called at startup. Instead, OpenJ9 records the number of times a method is called. When the count reaches a pre-defined invocation threshold, JIT compilation is triggered. Once a method has been compiled by the JIT, the VM can call the compiled method rather than interpreting it.</p>"},{"location":"jit/#optimization-levels","title":"Optimization levels","text":"<p>The JIT compiler can compile a method at different optimization levels: cold, warm, hot, very hot (with profiling), or scorching. The hotter the optimization level, the better the expected performance, but the higher the cost in terms of CPU and memory.</p> <ul> <li>cold is used during startup processing for large applications where the goal is to achieve the best compiled code speed for as many methods as possible.</li> <li>warm is the workhorse; after start-up, most methods are compiled when they reach the invocation threshold.</li> </ul> <p>For higher optimization levels, the VM uses a sampling thread to identify methods that continue to take a lot of time. Methods that consume more than 1% are compiled at hot. Methods that consume more than 12.5% are scheduled for a scorching compilation. However, before that happens the methods are compiled at very hot with profiling to collect detailed profile data that is used by the scorching compilation.</p> <p>The higher optimization levels use special techniques such as escape analysis and partial redundancy elimination, or loop through certain optimization sequences more times. Although these techniques use more CPU and memory, the improved performance that is delivered by the optimizations can make the tradeoff worthwhile.</p>"},{"location":"jit/#troubleshooting","title":"Troubleshooting","text":"<p>The JIT compiler is enabled by default to optimize performance. However, if you experience a problem running your application, temporarily turning off the JIT will tell you whether the JIT is at fault.</p> <p>Because JIT starts at the same time as the VM, you can only modify JIT behavior at startup.</p> <p>There are a number of ways to disable the JIT:</p> <ul> <li>Specify <code>-Djava.compiler=NONE</code> on the command line.</li> <li>Specify <code>-Xint</code> on the command line, which turns off the JIT and AOT compiler. To eliminate problems with one or the other you can turn these compilers off selectively with the <code>-Xnojit</code> and <code>-Xnoaot</code> options.</li> <li>Call the <code>java.lang.Compiler</code> API programmatically.</li> </ul> <p> Note: <code>java.lang.Compiler</code> is deprecated for removal in Java SE 9.</p> <p>If turning off the JIT solves your problem, you can investigate JIT operations in more detail by using a number of options to control behavior.</p> <p>Turning on verbose logging with the <code>verbose</code> suboption causes the JIT to record all compiler operations. However, the log file can be difficult to read because there are so many complex operations occuring in rapid succession. Follow these steps to simplify operations, which helps you pinpoint the root cause:</p> Turn off multiple compilation threads <p>The JIT compiler can use more than one compilation thread, which typically improves startup performance. The number of threads is determined by the VM, depending on the system configuration. You can turn off multiple threads by using the <code>-XcompilationThreads</code> option, which simplifies the output in the verbose log.</p> Lower the invocation threshold <p>When the invocation count is set to <code>0</code>, the JIT compiles every method and your application will fail immediately when the method causing the problem is reached. You can alter the threshold with the <code>count</code> suboption.</p> Turn off inlining <p>Inlining is a complex process that generates larger and more complex code. To eliminate errors caused by these operations, use the <code>disableInlining</code> suboption.</p> Decrease the optimization levels <p>Use the <code>optlevel</code> suboption to gradually decrease the compiler optimization levels to see whether you can isolate the level at which your problem occurs.</p> <p>More information about these suboptions and the command line syntax is covered in -Xjit.</p>"},{"location":"jit/#understanding-jit-verbose-logs","title":"Understanding JIT verbose logs","text":"<p>At first glance, a JIT verbose log can look very complex. To help you understand the log we'll look at JIT compiler operations when you run the <code>java -version</code> command.</p> <p>The following option turns on verbose logging and directs output to a log file called <code>vlogfile</code>:</p> <pre><code>java -Xjit:verbose,vlog=vlogfile -version\n</code></pre> <p>The first section of the log includes lines that start with <code>#INFO:</code>, which provides information about the environment that the JIT is operating in. You can determine the version of the JIT and VM that you are using, and the type and number of processors that the JIT has access to.</p> <pre><code>#INFO:  _______________________________________\n#INFO:  Version Information:\n#INFO:       JIT Level  - e24e8aa9\n#INFO:       JVM Level  - 20180315_120\n#INFO:       GC Level   - e24e8aa9\n#INFO:  \n#INFO:  Processor Information:\n#INFO:       Platform Info:X86 Intel P6\n#INFO:       Vendor:GenuineIntel\n#INFO:       numProc=1\n#INFO:  \n#INFO:  _______________________________________\n#INFO:  AOT\n#INFO:  options specified:\n#INFO:       samplingFrequency=2\n#INFO:  \n#INFO:  options in effect:\n#INFO:       verbose=1\n#INFO:       vlog=vlogfile\n#INFO:       compressedRefs shiftAmount=0\n#INFO:       compressedRefs isLowMemHeap=1\n#INFO:  _______________________________________\n#INFO:  JIT\n#INFO:  options specified:\n#INFO:       verbose,vlog=vlogfile\n#INFO:  \n#INFO:  options in effect:\n#INFO:       verbose=1\n#INFO:       vlog=vlogfile\n#INFO:       compressedRefs shiftAmount=0\n#INFO:       compressedRefs isLowMemHeap=1\n#INFO:  StartTime: Apr 23 09:49:10 2018\n#INFO:  Free Physical Memory: 996188 KB\n#INFO:  CPU entitlement = 100.00\n</code></pre> <p>This section also shows the AOT and JIT options that are in force. The last few lines detail the start time of the compilation activity, how much free physical memory is available to the process, and the CPU entitlement.</p> <p>The information section is followed by a sequence of lines that describe the methods that are being compiled, as well as other events significant to the operation of the JIT compiler.</p> <p>Here is a typical line from the verbose log:</p> <pre><code>+ (cold) sun/reflect/Reflection.getCallerClass()Ljava/lang/Class; @ 00007FCACED1303C-00007FCACED13182 OrdinaryMethod - Q_SZ=0 Q_SZI=0 QW=1 j9m=00000000011E7EA8 bcsz=2 JNI compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <p>In this example:</p> <ul> <li>The method compiled is <code>sun/reflect/Reflection.getCallerClass()Ljava/lang/Class</code>.</li> <li>The <code>+</code> indicates that this method is successfully compiled. Failed compilations are marked by a <code>!</code>.</li> <li><code>(cold)</code> tells you the optimization level that was applied. Other examples might be <code>(warm)</code> or <code>(scorching)</code>.</li> <li><code>00007FCACED1303C-00007FCACED13182</code> is the code range where the compiled code was generated.</li> <li><code>Q</code> values provide information about the state of the compilation queues when the compilation occurred.</li> <li><code>bcsz</code> shows the bytecode size. In this case it is small because this is a native method, so the JIT is simply providing an accelerated JNI transition into the native <code>getCallerClass</code> method.</li> </ul> <p>Each line of output represents a method that is compiled.</p> <p>The following example requests information about the performance of JIT compiler threads, with output written to <code>vlogfile</code>.</p> <pre><code>java -Xjit:verbose={compilePerformance},vlog=vlogfile -version\n</code></pre> <p>The output generated by using this command adds the values <code>time</code> and <code>mem</code> into each line, as shown in the following example:</p> <pre><code>+ (cold) java/lang/System.getEncoding(I)Ljava/lang/String; @ 00007F29183A921C-00007F29183A936D OrdinaryMethod - Q_SZ=0 Q_SZI=0 QW=1 j9m=0000000000F13A70 bcsz=3 JNI time=311us mem=[region=704 system=16384]KB compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <ul> <li>time=311us reflects the amount of time taken to do the compilation.</li> <li>mem=[region=704 system=16384]KB reflects the amount of memory that was allocated during the compilation.</li> </ul> <p>The following example can be used to create verbose output that includes lines to show when compilation for a method starts and ends, and any methods that are inlined during the compilation.</p> <pre><code>java '-Xjit:verbose={compileStart|compileEnd|inlining},count=5,vlog=vlogfile' -XcompilationThreads1 -version\n</code></pre> <p> Note: The suboptions <code>count</code> and <code>-XcompilationThreads1</code> are included only to simplify the output for this example and are not recommended for production.</p> <p>The following section is taken from the output and describes the compilation and inlining of one method <code>java/lang/String.equals</code>:</p> <pre><code>(warm) Compiling java/lang/String.equals(Ljava/lang/Object;)Z  OrdinaryMethod j9m=0000000001300B30 t=90 compThread=0 memLimit=262144 KB freePhysicalMemory=969 MB\n#INL: 7 methods inlined into 4dce72bd java/lang/String.equals(Ljava/lang/Object;)Z @ 00007F53190A3E40\n#INL: #0: 4dce72bd #-1 inlined 4dce72bd@22 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #1: 4dce72bd #-1 inlined 4dce72bd@28 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #2: 4dce72bd #-1 inlined 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n#INL: #3: 4dce72bd #2 inlined bf62dcaf@121 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #4: 4dce72bd #2 inlined bf62dcaf@131 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #5: 4dce72bd #2 inlined bf62dcaf@156 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #6: 4dce72bd #2 inlined bf62dcaf@166 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: 4dce72bd called 4dce72bd@120 -&gt; f734b49c bcsz=233 java/lang/String.deduplicateStrings(Ljava/lang/String;Ljava/lang/String;)V\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n+ (warm) java/lang/String.equals(Ljava/lang/Object;)Z @ 00007F53190A3E40-00007F53190A40D0 OrdinaryMethod - Q_SZ=277 Q_SZI=277 QW=1667 j9m=0000000001300B30 bcsz=127 GCR compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <p>The first line is included as a result of setting the <code>compileStart</code> suboption and shows the start of the warm method compilation:</p> <pre><code>(warm) Compiling java/lang/String.equals(Ljava/lang/Object;)Z OrdinaryMethod j9m=0000000001300B30 t=90 compThread=0 memLimit=262144 KB freePhysicalMemory=969 MB\n</code></pre> <p>Similarly, the last line shows the successful compilation of this method, as denoted by the <code>+</code>:</p> <pre><code>+ (warm) java/lang/String.equals(Ljava/lang/Object;)Z @ 00007F53190A3E40-00007F53190A40D0 OrdinaryMethod - Q_SZ=277 Q_SZI=277 QW=1667 j9m=0000000001300B30 bcsz=127 GCR compThread=0 CpuLoad=2%(2%avg) JvmCpu=0%\n</code></pre> <p>The lines inbetween that start with <code>#INL</code> describe the inlining operations that took place. A total of 7 methods were inlined into <code>java/lang/String.equals</code>:</p> <p>The first three methods (<code>#0</code>, <code>#1</code>, <code>#2</code>) are inlined into the top level method, denoted as <code>#-1</code>:</p> <pre><code>#INL: #0: 4dce72bd #-1 inlined 4dce72bd@22 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #1: 4dce72bd #-1 inlined 4dce72bd@28 -&gt; 81670d20 bcsz=37 java/lang/String.lengthInternal()I\n#INL: #2: 4dce72bd #-1 inlined 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n</code></pre> <p>The next four methods (<code>#3</code>, <code>#4</code>, <code>#5</code>, <code>#6</code>) are inlined into the method denoted by <code>#2</code>.</p> <pre><code>#INL: #3: 4dce72bd #2 inlined bf62dcaf@121 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #4: 4dce72bd #2 inlined bf62dcaf@131 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #5: 4dce72bd #2 inlined bf62dcaf@156 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n#INL: #6: 4dce72bd #2 inlined bf62dcaf@166 -&gt; bbb5af92 bcsz=39 java/lang/String.charAtInternal(I[C)C\n</code></pre> <p>Here's how to interpret the line for <code>#INL: #0:</code>:</p> <p>The method is inlined into <code>4dce72bd</code>, where <code>4dce72bd</code> is an internal pointer that corresponds to this method (in this case, <code>java/lang/String.equals(Ljava/lang/Object;)Z</code>). The value <code>@22</code> at the end of the pointer is a bytecode index, which describes the bytecode index of the call that is being inlined. The call is <code>81670d20 bcsz=37 java/lang/String.lengthInternal()I</code>, which shows the corresponding internal pointer, bytecode size (bcsz) and the name of the method that got inlined. Going through the <code>#INL</code> output line by line then:</p> <pre><code>java/lang/String.lengthInternal()I got inlined into its caller 4dce72bd at bytecode index @22.\njava/lang/String.lengthInternal()I also got inlined into its caller 4dce72bd at bytecode index @28.\njava/lang/String.regionMatchesInternal(...) got inlined at call reference 4dce72bd at bytecode index @104.\n</code></pre> <p>Then 4 distinct calls to <code>java/lang/String.charAtInternal(I[C)C</code> were also inlined into <code>java/lang/String.regionMatchesInternal(...)</code> :</p> <pre><code>#3 at bytecode index @121 of regionMatchesInternal\n#4 at bytecode index @131 of regionMatchesInternal\n#5 at bytecode index @156 of regionMatchesInternal\n#6 at bytecode index @166 of regionMatchesInternal\n</code></pre> <p>These were all the calls that the inliner decided to inline into the method being compiled. There is some additional output that describes calls to methods that weren't inlined:</p> <pre><code>#INL: 4dce72bd called 4dce72bd@120 -&gt; f734b49c bcsz=233 java/lang/String.deduplicateStrings(Ljava/lang/String;Ljava/lang/String;)V\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n#INL: 4dce72bd coldCalled 4dce72bd@104 -&gt; bf62dcaf bcsz=182 java/lang/String.regionMatchesInternal(Ljava/lang/String;Ljava/lang/String;[C[CIII)Z\n</code></pre> <p>While the output does not specifically say why these methods were not inlined, the relatively larger bytecode size (<code>bcsz=233</code>) probably prevented the first method from being inlined. It's possible that, at a higher optimization level than cold, this <code>deduplicateStrings</code> method may get inlined. The <code>coldCalled</code> label on the last two lines, however, indicate that these calls are located in a part of the method that has not ever been executed, so the JIT decided that inlining those last two methods will probably increase compile time without much promise that it will improve performance.</p> <p>By reading the log in this way you can reconstruct the tree of inlines that are taking place as the compilation proceeds. You can see which methods are being inlined and which methods are not being inlined.</p>"},{"location":"jit/#see-also","title":"See also","text":"<ul> <li>Diagnosing a JIT or AOT problem</li> </ul>"},{"location":"jitserver/","title":"JITServer technology","text":""},{"location":"jitserver/#jitserver-technology","title":"JITServer technology","text":"<p>Linux\u00ae on x86, Linux on IBM Power\u00ae systems, and Linux on IBM Z\u00ae systems (64-bit only)</p> <p>JITServer technology decouples the JIT compiler from the VM and lets the JIT compiler run remotely in its own process. This mechanism prevents your Java\u2122 application suffering possible negative effects due to CPU and memory consumption caused by JIT compilation.</p> <p>This technology can improve quality of service, robustness, and performance of Java applications. You might want to try this technology if the following criteria are met:</p> <ul> <li>Your Java application is required to compile many methods using JIT in a relatively short time.</li> <li>The application is running in an environment with limited CPU or memory, which can worsen interference from the JIT compiler.</li> <li>The network latency between JITServer and client VM is relatively low.</li> </ul> <p>For more details about JITServer technology, including its advantages and disadvantages and when best to use it, see blog posts such as the following:</p> <ul> <li>Free your JVM from the JIT with JITServer Technology</li> <li>JITServer - Optimize your Java cloud-native applications</li> </ul> <p>For a more in-depth description of the JITServer design and implementation, see the following research paper:</p> <ul> <li>JITServer: Disaggregated Caching JIT Compiler for the JVM in the Cloud</li> </ul>"},{"location":"jitserver/#using-jitserver-technology","title":"Using JITServer technology","text":"<p>JITServer technology is not enabled by default: you must explicitly invoke it. Running OpenJ9 without either of the following options launches it as a regular VM with embedded JIT compilation.</p>"},{"location":"jitserver/#launch-eclipse-openj9-in-client-mode","title":"Launch Eclipse OpenJ9 in client mode","text":"<p>Use the following command-line option to launch Eclipse OpenJ9\u2122 in client mode. In this mode, the VM sends compilation requests to an available JITServer. The client operates as a regular VM with its own JIT compiler if a server is not available.</p> <pre><code> -XX:+UseJITServer\n</code></pre>"},{"location":"jitserver/#launch-openj9-in-server-mode","title":"Launch OpenJ9 in server mode","text":"<p>Use the following command to start a JITServer process that listens for incoming compilation requests:</p> <pre><code>jitserver\n</code></pre>"},{"location":"jitserver/#configuring-jitserver-technology","title":"Configuring JITServer technology","text":"<p>You can use command line options to further configure the JITServer and the client VM processes. For example:</p> <ul> <li><code>-XX:JITServerPort=&lt;port&gt;</code>: Specifies the port the server listens to for compilation requests</li> <li><code>-XX:JITServerAddress=&lt;address&gt;</code>: Specifies the name or IP of the server</li> <li><code>-XX:JITServerTimeout=&lt;timeout&gt;</code>: Specifies a timeout value in milliseconds for socket operations</li> <li><code>-XX:[+|-]JITServerShareROMClasses</code>: Specifies whether the server shares cached ROM classes between clients</li> <li><code>-XX:[+|-]JITServerLocalSyncCompiles</code>: Improves performance for real-time applications by compiling synchronous JIT compilations locally, with a remote asynchronous recompilation scheduled at a later point</li> <li><code>-XX:[+|-]JITServerLogConnections</code>: Enables logging of connection/disconnection events between the server and the client</li> <li><code>-XX:[+|-]JITServerMetrics</code>: Specifies whether the JITServer custom metrics exporter is enabled or disabled</li> <li><code>-XX:JITServerMetricsPort=&lt;port&gt;</code>: Specifies the port number on which the JITServer metrics are provided to a monitoring agent</li> <li><code>-XX:JITServerAOTCacheName=&lt;cache_name&gt;</code>: Specifies the name of the server-side AOT cache to use</li> <li><code>-XX:[+|-]JITServerUseAOTCache</code>: Specifies whether the server caches AOT-compiled methods</li> <li><code>-XX:JITServerAOTmx=&lt;size&gt;</code>: Specifies the maximum amount of memory that can be used by the JITServer AOT cache</li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code>: Specifies whether the JITServer server allows other JITServer instances to reuse AOT caches</li> <li><code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code>: Specifies the directory to be used for saving and loading JITServer AOT cache files</li> </ul> <p>If a JITServer server crashes, the client is forced to perform compilations locally. You can change this behavior by using the <code>-XX:[+|-]RequireJITServer</code> option so that the client crashes with an assert when it detects that the server is unavailable. This feature is useful when you are running a test suite with JITServer enabled and you want the server crash to cause the test to fail.</p>"},{"location":"jitserver/#security","title":"Security","text":"<p>You can encrypt network communication between the client VM and JITServer by using OpenSSL 1.0.x, 1.1.x, or 3.x. To enable encryption, you specify the private key and the certificate at the server and use the certificate at the client. For more information, see -XX:JITServerSSLCert / -XX:JITServerSSLKey / -XX:JITServerSSLRootCerts.</p>"},{"location":"jitserver/#tuning-jitserver","title":"Tuning JITServer","text":"<p>For best practices regarding JITServer configuration and tuning, see the document JITServer tuning and practical considerations.</p>"},{"location":"jitserver/#building-a-jdk-with-jitserver-technology","title":"Building a JDK with JITServer technology","text":"<p>If you want to build a JDK with JITServer technology, see Appendix A of Free your JVM from the JIT with JITServer Technology.</p>"},{"location":"jitserver/#see-also","title":"See also","text":"<ul> <li>The JIT compiler</li> </ul>"},{"location":"jitserver_tuning/","title":"JITServer tuning","text":""},{"location":"jitserver_tuning/#jitserver-tuning-and-practical-considerations","title":"JITServer tuning and practical considerations","text":""},{"location":"jitserver_tuning/#server-caches","title":"Server caches","text":""},{"location":"jitserver_tuning/#client-session-caches","title":"Client-session caches","text":"<p>Multiple client JVMs can be connected at the same time to a single JIT server. For each client, the server maintains a client-session cache with information about the environment the client is running in (Java classes, class hierarchy, profiling information, JVM options, etc.). Typically, the information in these caches is kept separately, per client. However, if you specify the <code>-XX:+JITServerShareROMClasses</code> option, the read-only part of the Java classes (ROMClasses in Eclipse OpenJ9\u2122 parlance) is shared between the different clients. This option can generate memory savings at the server when the connected clients run identical or similar Java applications.</p> <p>The client-session caches are deleted when the clients terminate, but this can happen only if the clients are shutdown gracefully, giving them the opportunity to send a termination message to the server. To address the scenario of clients ending abruptly, the server also deletes the cache for a client that hasn\u2019t issued a compilation request for 1000 minutes, or 5 minutes under memory pressure. If needed, you can change these values with the following options:</p> <pre><code>-Xjit:oldAge=&lt;time-in-ms&gt;,oldAgeUnderLowMemory=&lt;time-in-ms&gt;\n</code></pre>"},{"location":"jitserver_tuning/#jitserver-aot-cache","title":"JITServer AOT cache","text":"<p>The JITServer technology can cache AOT compiled methods at the server.  The JITServer can, therefore, avoid carrying out an AOT compilation when a compatible AOT method body already exists in the cache, thereby saving CPU resource and improving remote compilation latency. This mechanism works in conjunction with the dynamic AOT technology at the client and therefore the client needs to have the shared classes cache (SCC) enabled (the SCC is the repository for the AOT code).</p> <p>When the JITServer receives an AOT compilation request, it checks its AOT cache for a compatible compiled method body. If one is not found, the server performs the AOT compilation, sends the response to the client JVM, then serializes the compiled method and stores it in its local AOT cache, for future use. If a compatible compiled method is found, the server sends the client the serialized compiled method from its cache, thus avoiding a compilation. The client deserializes the response, stores the result in its local SCC, and loads the compiled method as a regular dynamic AOT code.</p> <p>To enable this feature, specify the <code>-XX:+JITServerUseAOTCache</code> command line option, both at the server and at the client JVM.</p> <p>A JITServer instance can have several AOT caches, each with its own name. This addresses the situation when client JVMs with significantly different profiles of execution use the same JITServer instance. A client JVM can indicate a specific AOT cache it wants to use by providing its name with the following command-line option <code>-XX:JITServerAOTCacheName=&lt;cache_name&gt;</code>. If the client doesn't specify a name for the AOT cache, the server uses a cache named <code>default</code>.</p> <p>The maximum amount of memory that all the AOT cache instances combined can use at the server is 300 MB, by default. You can change this value by using the <code>-XX:JITServerAOTmx=&lt;size&gt;</code> option. When the cache size reaches the specified limit, new clients cannot create new AOT cache instances or add new compiled methods to the existing AOT cache instances.</p> <p>Typically, each JITServer server populates its own AOT caches independently of other existing servers. To help with JITServer auto-scaling, and in particular with scaling down to zero, JITServer instances can save their AOT caches to files by setting the <code>-XX:+JITServerAOTCachePersistence</code> command-line option. Other JITServer instances that are started later can load the existing AOT cache files into their memory, and then continue to gradually add new AOT compiled methods. Saving an AOT cache to a file is performed periodically based on the following conditions:</p> <ul> <li>The number of extra AOT methods added to the in-memory cache since the last save operation is equal to or more than the value specified by the <code>-Xjit:aotCachePersistenceMinDeltaMethods=&lt;number_of_methods&gt;</code> option (default value - 200 methods), and</li> <li>The time passed since the last AOT cache save is equal to or later than the time specified by the <code>-Xjit:aotCachePersistenceMinPeriodMs=&lt;milliseconds&gt;</code> option (default time gap - 10000 milliseconds).</li> </ul> <p>If the JITServer AOT cache feature and the <code>-Xshareclasses:readonly</code> option are both enabled at the same time at a JITServer client, the shared classes cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p> <p>Current limitation:</p> <ul> <li>Caching works only for AOT compilation requests. For this reason, when JITServer AOT caching is enabled, the client JVM will attempt to generate as many AOT requests as possible.</li> </ul>"},{"location":"jitserver_tuning/#number-of-concurrent-clients","title":"Number of concurrent clients","text":"<p>The amount of CPU and memory resources consumed by the server is expected to increase with the number of connected clients. Finding the appropriate number of clients to connect to a server is a tricky proposition that depends on many factors: number of methods that need to be compiled by the clients, optimization levels for these compilations, how clients are started (staggered or not), how clients are shutdown (gracefully or not), etc.</p> <p>As a rule of thumb, you should have 10-20 JVMs simultaneously connected to a server with 1-2 GB of memory. With respect to CPU resources, in Kubernetes you might want to set a low \"request\" value at the server (1-2 vCPUs) and a larger \"limit\" value (4-8 vCPUs) in order to soak all those idle cycles. It is possible to connect even more clients to one server instance if memory and CPU resources are increased, but in general, two medium-sized server instances placed on different nodes are better than a single, larger server.</p>"},{"location":"jitserver_tuning/#alleviating-cpu-congestion-at-the-server","title":"Alleviating CPU congestion at the server","text":"<p>When too many clients connect to the server, the server can become flooded with compilation requests, leading to increased compilation times and slower start-up/ramp-up for applications. It should be noted that a client JVM issues most of its compilation requests during the start-up phase and ramp-up phase of an application, when load is first applied to it. Thus, from the CPU consumption point of view what matters is the number of clients that start-up or ramp-up concurrently. To alleviate the CPU strain on the server, you can start the client JVMs in a staggered fashion, rather than all at the same time. Sometimes the staggering happens naturally; for instance, when using Kubernetes horizontal pod auto-scaling, additional application instances are launched gradually as the load increases.</p> <p>Another idea is to use the <code>-Xjit:enableJITServerHeuristics</code> command line option at the clients. When this option is present, the client JVMs share some of the compilation burden by performing the cheap compilations locally and send only expensive compilations to the server. What constitutes a cheap compilation is determined by JIT heuristics that look at the method size, optimization level and the amount of CPU and memory available to the JVM.</p>"},{"location":"jitserver_tuning/#avoiding-memory-shortages-at-the-server","title":"Avoiding memory shortages at the server","text":"<p>Roughly speaking, the server uses two types of memory: 1. \"Scratch\" memory. This is allocated during a compilation (for JIT internal data structures) and released to the operating system at the end of the compilation. 2. \"Persistent\" memory. This is used for client-session caches and gets deleted only when a client terminates gracefully (or when the JITServer purging mechanism is triggered).</p> <p>The total amount of scratch memory at any given moment depends on how many compilations are in progress and how expensive those compilations are. To reduce this amount, you can start the clients in a staggered fashion as suggested previously, or reduce the number of compilation threads per client. Note that the latter already happens automatically: when the server senses that it is about to run out of memory, it provides feedback to the connected clients to reduce their number of active compilation threads.</p> <p>To reduce the amount of persistent memory, you can use the techniques described in section Server caches.</p>"},{"location":"jitserver_tuning/#traffic-encryption","title":"Traffic encryption","text":"<p>Enabling network encryption can increase the CPU overhead, both at the client and at the server. For this reason, you should turn on encryption only if needed. Note that some technologies like Istio, Weave, Linkerd, Calico, Cilium already encrypt all network traffic, so using JITServer encryption might be redundant.</p>"},{"location":"jitserver_tuning/#minimizing-application-stalls","title":"Minimizing application stalls","text":"<p>Usually, the compilation threads in OpenJ9 JVM execute in parallel with Java application threads. However, for correctness reasons a small number of compilations are performed synchronously, meaning that Java application threads have to wait for the compilation result before being allowed to execute the method being compiled. Since remote compilations typically take longer to complete due to network latency, application stalls caused by synchronous compilations can be more severe in a JITServer setting. If this becomes a problem, you should add the following command line option at the client:</p> <pre><code>-XX:+JITServerLocalSyncCompiles\n</code></pre> <p>This option instructs the client JVM to perform the synchronous compilations locally, at a low optimization level (thus the compilation is relatively quick), and to follow-on with remote asynchronous recompilations at a higher optimization level to avoid any performance loss.</p>"},{"location":"jitserver_tuning/#session-affinity","title":"Session affinity","text":"<p>For technical reasons, a client JVM must use a single JITServer at a time. In a Kubernetes environment, where a JITServer service can be backed up by several server instances, you can satisfy this requirement by using session affinity. Note that if a server crashes (or gets terminated by the Kubernetes controller) the clients can connect to another server instance. This scenario imposes some performance penalty because the client-session caches that the server maintains need to be built anew. Following is an example of a Kubernetes service definition that uses sessionAffinity:</p> <pre><code>apiVersion: v1\nkind: Service\nmetadata:\n  name: jitserver\nspec:\n  type: ClusterIP\nselector:\n    app: jitserver\n  ports:\n    - protocol: TCP\n      port: 38400\n      targetPort: 38400\n  sessionAffinity: ClientIP\n  sessionAffinityConfig:\n    clientIP:\n      timeoutSeconds: 86400\n</code></pre>"},{"location":"jitserver_tuning/#resilience","title":"Resilience","text":"<p>If the client JVM does not find a compatible server to connect to, compilations are performed locally, by the client itself. To account for the case where the server is temporarily unavailable (for example, server crash followed by Kubernetes launching another server instance), from time to time the client retries to connect to a server at the indicated address and port. The retry mechanism uses an exponential back-off where the retry interval is doubled with each unsuccessful attempt.</p>"},{"location":"jitserver_tuning/#monitoring","title":"Monitoring","text":""},{"location":"jitserver_tuning/#performance-metrics","title":"Performance metrics","text":"<p>You can enable the provision of performance metrics by specifying the <code>-XX:+JITServerMetrics</code> command line option. After enabling this option, you can use a monitoring tool that follows the OpenMetrics standard, such as Prometheus, to collect the data by issuing an HTTP <code>GET</code> request to the following url: <code>http://&lt;jitserveraddress&gt;:&lt;port&gt;/metrics</code>.</p> <p> Note: There is a limit of four concurrent <code>GET</code> requests at any given time.</p> <p>You can use the <code>-XX:JITServerMetricsSSLKey</code> and <code>-XX:JITServerMetricsSSLCert</code> options to encrypt the data with TLS or SSL.</p> <p>For more information, including the types of metrics that are provided, see the <code>-XX:[+|-]JITServerMetrics</code> topic.</p>"},{"location":"jitserver_tuning/#verbose-logging","title":"Verbose logging","text":"<p>You can inspect the behavior of a JITServer instance by using the OpenJ9 verbose logging facility. Note that if the name of the verbose log is not specified, the relevant information is printed to stderr. When you use the <code>-XX:+JITServerLogConnections</code> command line option, the server prints a message to the verbose log every time a new client JVM connects to it or disconnects from it. This is an easy way to determine that the clients are able to reach the server. Example of output:</p> <pre><code>#JITServer: t= 74232 A new client (clientUID=14692403771747196083) connected. Server allocated a new client session.\n#JITServer: t= 74282 A new client (clientUID=2599593246759846167) connected. Server allocated a new client session.\n#JITServer: t= 86281 Client (clientUID=14692403771747196083) disconnected. Client session deleted\n</code></pre> <p>The server has a heart-beat thread that periodically prints to the verbose log information related to the number of clients connected, the number of active compilation threads, the amount of CPU used, the amount of available memory and the number of times the internal server caches have been cleared. This last bit of information is important for diagnosing performance problems. The heart-beat information is enabled with the following option:</p> <pre><code>-Xjit:statisticsFrequency=&lt;period-in-ms&gt;\n</code></pre> <p>Example of output:</p> <pre><code>#JITServer: CurrentTime: Aug 06 17:25:15 2021\n#JITServer: Compilation Queue Size: 0\n#JITServer: Number of clients : 2\n#JITServer: Total compilation threads : 63\n#JITServer: Active compilation threads : 2\n#JITServer: Physical memory available: 14299 MB\n#JITServer: CpuLoad 206% (AvgUsage 25%) JvmCpu 113%\n...\n</code></pre> <p>A value greater than 0 for the <code>Compilation Queue Size</code> is a sign that the server is overloaded. Compilation requests that wait in the compilation queue face greater delays and run the risk of exceeding network timeouts. To avoid this scenario, you can reduce the number of connected clients, use the techniques described in section Alleviating CPU congestion at the server, or increase the number of compilation threads at the server by using the <code>-XcompilationThreads</code> option.</p> <p>Increasing the maximum number of client threads can improve performance in high network latency settings because there can be more in-progress concurrent compilation requests. Increasing the number of threads at the server can improve performance if the server has many CPU cores available and serves a large number of clients concurrently.</p> <p>More detailed diagnostics can be obtained with the option <code>-Xjit:verbose={JITServer},verbose={compilePerformance}</code>, which is typically used for debugging server behavior.</p>"},{"location":"legal/","title":"Legal","text":""},{"location":"legal/#legal","title":"Legal","text":"<p>License agreement, notices, copyright, and trademark information for the user documentation.</p>"},{"location":"legal/#license-agreement","title":"License agreement","text":"<p>See License</p>"},{"location":"legal/#notices","title":"Notices","text":"<p>See Notices</p>"},{"location":"legal/#copyright-information","title":"Copyright information","text":"<p>Eclipse OpenJ9\u2122 documentation is subject to the following copyright:</p> <pre><code>Copyright (c) 2017, 2023 IBM Corp.\n</code></pre>"},{"location":"legal/#trademarks","title":"Trademarks","text":"<p>IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at \"Copyright and trademark information\" here.</p> <p>Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.</p> <p>Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.</p> <p>Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.</p>"},{"location":"messages_intro/","title":"OpenJ9 messages","text":""},{"location":"messages_intro/#eclipse-openj9-vm-messages","title":"Eclipse OpenJ9 VM messages","text":"<p>Messages are issued by the Eclipse OpenJ9\u2122 virtual machine (VM) in response to certain conditions. Understanding what the messages mean can help you with problem determination.</p>"},{"location":"messages_intro/#message-categories","title":"Message categories","text":"<p>There are three main categories of message:</p> Information Information messages provide information about VM processing. For example, a dump information message is typically issued when a dump agent requests a dump. Warning Warning messages are issued by the VM to indicate conditions that might need user intervention. Error Error messages are issued by the VM when normal processing cannot proceed, because of unexpected conditions. <p>OpenJ9 virtual machine messages have the following format:</p> <pre><code>    JVM&lt;type&gt;&lt;number&gt;&lt;code&gt;\n</code></pre> <p>where:</p> <ul> <li><code>JVM</code> is a standard prefix.</li> <li><code>&lt;type&gt;</code> refers to the VM subcomponent that issued the message.</li> <li><code>&lt;number&gt;</code> is a unique numerical number.</li> <li><code>&lt;code&gt;</code> is one of the following codes:<ul> <li><code>I</code> - Information message</li> <li><code>W</code> - Warning message</li> <li><code>E</code> - Error message</li> </ul> </li> </ul> <p>These messages can help you with problem determination.</p> <p>By default, all error and some information messages are routed to the system log and also written to <code>stderr</code> or <code>stdout</code>. The specific information messages are <code>JVMDUMP039I</code>, <code>JVMDUMP032I</code>, and <code>JVMDUMP033I</code>, which provide valuable additional information about dumps produced by the VM. To route additional message types to the system log, or turn off message logging to the system log, use the <code>-Xsyslog</code> option. The <code>-Xsyslog</code> option does not affect messages written to the standard error stream (stderr). See OpenJ9 command-line options.</p> <p> Note: The <code>-Xsyslog</code> option replaces the <code>-Xlog</code> option in OpenJ9 version 0.24.0.</p>"},{"location":"messages_intro/#finding-logged-messages","title":"Finding logged messages","text":"<p>Logged messages can be found in different locations, according to platform.</p>"},{"location":"messages_intro/#finding-aix-messages","title":"Finding AIX messages","text":"<p>On AIX\u00ae, messages are logged by the syslog daemon (<code>/usr/sbin/syslogd</code>). Logged messages are written to the syslog file that is configured in <code>/etc/syslog.conf</code>. If the syslog daemon is not running, logged messages are lost.</p> <p>You can redirect messages from the syslog daemon to the AIX error log facility by performing the following configuration steps:</p> <ol> <li>Set up a redirect in the file <code>syslog.conf</code> so that syslog messages are sent to the error log, by adding the following line:</li> </ol> <pre><code>        user.debug errlog\n</code></pre> <ol> <li>If syslogd is already running, reload the updated configuration by running the following command:</li> </ol> <pre><code>        refresh -s syslogd\n</code></pre> <ol> <li>The updated configuration is used each time syslogd starts. 4.  Use the AIX errpt command or the System Management Interface Tool (SMIT) to read the messages sent to the error log.</li> </ol> <p>For more information about AIX logging, see: Error-logging overview.</p>"},{"location":"messages_intro/#finding-linux-messages","title":"Finding Linux messages","text":"<p>On Linux\u00ae, messages are logged by the syslog daemon. To find where messages are logged, check the syslog configuration file.</p>"},{"location":"messages_intro/#finding-macos-messages","title":"Finding macOS messages","text":"<p>On macOS\u00ae, messages are logged by the syslog daemon. However, on Sierra and High Sierra, syslog does not work. If <code>/var/log/system.log</code> is not available, <code>Console.app</code> can be used instead.</p>"},{"location":"messages_intro/#finding-windows-messages","title":"Finding Windows messages","text":"<p>On Windows\u2122, messages are logged in the application events section of the event viewer.</p>"},{"location":"messages_intro/#finding-zos-messages","title":"Finding z/OS messages","text":"<p>On z/OS\u00ae, messages are sent to the operator console. To see the messages, go from the ispf panel to the sdsf panel, then open the log panel.</p>"},{"location":"messages_intro/#obtaining-detailed-message-descriptions","title":"Obtaining detailed message descriptions","text":"<p>Detailed message information is available to help with problem diagnosis.</p> <p>Understanding the warning or error message issued by the VM can help you diagnose problems. All warning and error messages issued by the VM are listed by type in the messages guide: IBM\u00ae VM messages.</p> <p>The messages, error codes, and exit codes in this guide apply to multiple versions of the VM.</p> <p> Note: If the VM fills all available memory, the message number might be produced without a description for the error that caused the problem. Look for the message number in the relevant section of the J9 VM  Messages guide to see the message description and the additional information provided.</p>"},{"location":"migrating11to17/","title":"Migrating from Java 11 to Java 17","text":""},{"location":"migrating11to17/#migrating-from-java-11-to-java-17","title":"Migrating from Java 11 to Java 17","text":"<p>Support for OpenJDK 17 was added in Eclipse OpenJ9\u2122 version 0.29.1.</p> <p>The following new OpenJ9 changes apply when OpenJ9 is built with Java SE 17 class libraries. This information exists elsewhere in the documentation but is summarized here for convenience.</p>"},{"location":"migrating11to17/#support-for-jdk-enhancement-proposals-jep","title":"Support for JDK enhancement proposals (JEP)","text":"<p>The new JEPs that are supported are listed in the following topics:</p> <ul> <li>JDK 12: What's new in version 0.13.0</li> <li>JDK 13: What's new in version 0.16.0</li> <li>JDK 14: What's new in version 0.19.0</li> <li>JDK 15: What's new in version 0.22.0</li> <li>JDK 16: What's new in version 0.25.0</li> <li>JDK 17: What's new in version 0.29.1</li> </ul>"},{"location":"migrating11to17/#new-openj9-features-and-changes","title":"New OpenJ9 features and changes","text":"<p>The following table lists the new OpenJ9 features and notable changes with the OpenJ9 release in which they were added:</p> Features and changes OpenJ9 release Linux builds for all platforms use gcc 10.3 instead of gcc 7.5. See the list of build environments. 0.33.0 The default operating system stack size on x64 platforms is increased from 256 KB to 512 KB to accommodate vector support. You can change the operating system stack size by using the -Xmso option. 0.33.0"},{"location":"migrating8to11/","title":"Migrating from Java 8 to Java 11","text":""},{"location":"migrating8to11/#migrating-from-java-8-to-java-11","title":"Migrating from Java 8 to Java 11","text":"<p>Support for OpenJDK 11 was added in Eclipse OpenJ9\u2122 version 0.10.0.</p> <p>The following new OpenJ9 features and notable changes apply when OpenJ9 is built with Java SE 11 class libraries. This information exists elsewhere in the documentation but is summarized here for convenience.</p>"},{"location":"migrating8to11/#support-for-jdk-enhancement-proposals-jep","title":"Support for JDK enhancement proposals (JEP)","text":"<p>The new JEPs that are supported are listed in the following topics:</p> <ul> <li>JDK 9: What's new in version 0.9.0</li> <li>JDK 10: What's new in version 0.9.0</li> <li>JDK 11: What's new in version 0.10.0</li> </ul>"},{"location":"migrating8to11/#new-openj9-features-and-changes","title":"New OpenJ9 features and changes","text":"<p>The following table lists the new OpenJ9 features and notable changes with the OpenJ9 release in which they were added:</p> Features and changes OpenJ9 release The path that is specified by the default <code>-Xoptionsfile</code> value is the <code>&lt;java_home&gt;/lib</code> directory, where <code>&lt;java_home&gt;</code> is the directory for your runtime environment. For Java 8, the path is the VM directory that is listed in Directory conventions. First release Low-overhead heap profiling is supported. JEP 331 provides a mechanism for sampling Java heap allocations with a low overhead via the JVM Tool Interface (JVMTI). Restrictions: JEP 331 is implemented for OpenJ9 with the following limitations:<ul><li>The <code>balanced</code> and <code>metronome</code> garbage collection policies are not supported.</li><li>The JEP331 JVMTI agent and the Health Center agent both set a sampling interval, which by default is different. If both agents are used at the same time the Health Center agent will get incorrect results, unless the sampling intervals are adjusted to use the same value.</li></ul> 0.15.0 OpenSSL support for the ChaCha20 and ChaCha20-Poly1305 algorithms is available. The version of OpenSSL must be version 1.1.x or later. For more information, see <code>-Djdk.nativeChaCha20</code>. 0.15.0 The <code>-verbose:module</code> option, which writes information to stderr for each module that is loaded and unloaded, is now supported. 0.25.0 The default value of the <code>-XX:MaxDirectMemorySize</code> option, which limits the amount of heap memory that is used for direct byte buffers, is the same as the maximum heap size. For JDK 8, the VM default value is 87.5% of the maximum heap size. 0.32.0 OpenSSL support is added for the following algorithms:<ul><li><code>-Djdk.nativeXDHKeyAgreement</code></li><li><code>-Djdk.nativeXDHKeyGen</code></li></ul>The version of OpenSSL must be version 1.1.1 or later for the <code>-Djdk.nativeXDHKeyAgreement</code> and <code>-Djdk.nativeXDHKeyGen</code> algorithms. 0.40.0"},{"location":"openj9_defaults/","title":"Default settings","text":""},{"location":"openj9_defaults/#default-settings-for-the-eclipse-openj9-vm","title":"Default settings for the Eclipse OpenJ9\u2122 VM","text":"<p>The following tables provide a quick reference to the default settings for the VM when it is first installed.</p> <p>The last 2 columns show whether the default setting can be changed by a command-line parameter or an environment variable. Note that if both are set, the command-line parameter always takes precedence.</p> VM setting Default Command line Env. variable Javadump Enabled yes yes Heapdump Disabled yes yes System dump Enabled yes yes Snap traces Enabled yes yes JIT dump Enabled yes yes Verbose output Disabled yes no Compressed references (See Note 1) yes yes Boot classpath search Disabled yes no JNI checks Disabled yes no Remote debugging Disabled yes no Strict conformance checks Disabled yes no Quickstart Disabled yes no Remote debug info server Disabled yes no Reduced signaling Disabled yes no Signal handler chaining Enabled yes no Classpath Not set yes yes Class data sharing Disabled yes no Accessibility support Enabled no yes JIT compiler Enabled yes yes AOT compiler (See Note 2) Enabled yes no JIT debug options Disabled yes no Java2D max size of fonts with algorithmic bold 14 point no yes Java2D use rendered bitmaps in scalable fonts Enabled no yes Java2D freetype font rasterizing Enabled no yes Java2D use AWT fonts Disabled no yes <p> Notes:</p> <ol> <li> <p>On AIX\u00ae, Linux\u00ae, macOS\u00ae x86, and Windows\u2122: Enabled for -Xmx values \u2264 57 GB, otherwise disabled.</p> <p>On z/OS\u00ae: Enabled for -Xmx values \u2264 25 GB, otherwise disabled. With APAR OA49416, enabled for -Xmx values \u2264 57 GB.</p> <p>On macOS AArch64 (Apple silicon): Disabled.</p> </li> <li> <p>AOT is not used by the VM unless shared classes are also enabled.</p> </li> </ol> VM setting AIX Linux macOS Windows z/OS Command line Env. variable Default locale None None None N/A None no yes Time to wait before starting plug-in N/A Zero N/A N/A N/A no yes Temporary directory <code>/tmp</code> <code>/tmp</code> <code>/tmp</code> <code>c:\\temp</code> <code>/tmp</code> no yes Plug-in redirection None None None N/A None no yes IM switching Disabled Disabled Disabled N/A Disabled no yes IM modifiers Disabled Disabled Disabled N/A Disabled no yes Thread model N/A N/A N/A N/A Native no yes Initial stack size for Java Threads (32/64-bit). Use <code>-Xiss&lt;size&gt;</code> 2 KB 2 KB 2 KB 2 KB 2 KB yes no Maximum stack size for Java Threads (32-bit). Use <code>-Xss&lt;size&gt;</code> 320 KB 320 KB N/A 320 KB 320 KB yes no Maximum stack size for Java Threads (64-bit). Use <code>-Xss&lt;size&gt;</code> 1024 KB 1024 KB 1024 KB 1024 KB 1024 KB yes no Stack size for OS Threads (32-bit). Use <code>-Xmso&lt;size&gt;</code> 256 KB 256 KB N/A 32 KB 256 KB yes no Stack size for OS Threads (64-bit). Use <code>-Xmso&lt;size&gt;</code> 512 KB  512 KB (256 KB on IBM Z\u00ae) Earlier Java versions: 256 KB (512 KB on PPC)  Architecture: x86: 512 KB, AArch64 (Apple silicon): 256 KB Earlier Java versions: 256 KB  512 KB Earlier Java versions: 256 KB 1 MB yes no Initial heap size. Use <code>-Xms&lt;size&gt;</code> 8 MB 8 MB 8 MB 8 MB 8 MB yes no Maximum Java heap size. Use <code>-Xmx&lt;size&gt;</code> See Notes See Notes See Notes See Notes See Notes yes no Page size for the Java object heap and code cache (For restrictions, see the <code>-Xlp:codecache</code> and <code>-Xlp:objectheap</code> options). Operating system default Architecture: x86: 2 MB, IBM Z: 1 MB, Other architectures: Operating system default Architecture: x86: 4 KB, AArch64 (Apple silicon): 16 KB Operating system default 1M pageable yes no <p> Notes:</p> <p>The default value of <code>-Xmx</code> :</p> <ul> <li> <p>The value is 25% of the available memory with a maximum of 25 GB. However, where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB.</p> </li> <li> <p>On Linux\u00ae sytems, if the VM is running in a container and <code>-XX:+UseContainerSupport</code> is enabled, the value is 75% of the container memory limit, with a maximum of 25 GB. However, if the container memory limit is less than 1 GB, the value is 50% of the container memory limit. If the container memory limit is between 1GB and 2GB, the value is the container memory limit minus 512 MB.</p> </li> <li> <p>The default value is capped at 25 GB, which is the limit of heap size for 3-bit shift of compressed references (see <code>-Xcompressedrefs</code>), to prevent silent switching to 4-bit shift of compressed references, which has possible performance penalties. You can use the <code>-Xmx</code> option to overwrite the 25 GB limit.</p> </li> <li> <p> If you have set the <code>-XX:+OriginalJDK8HeapSizeCompatibilityMode</code> option for compatibility with earlier releases, the value is half the available memory with a minimum of 16 MB and a maximum of 512 MB. </p> </li> </ul> <p>Available memory is defined as being the smallest of two values: The real or physical memory or the RLIMIT_AS value.</p>"},{"location":"openj9_directories/","title":"Directory conventions","text":""},{"location":"openj9_directories/#directory-conventions","title":"Directory conventions","text":"<p>The following tables provide a quick reference to the Eclipse OpenJ9\u2122 VM directory location on different Java\u2122 versions and different platform architectures. Some pages refer to the VM directory location as <code>&lt;vm_dir&gt;</code>.</p> Operating system Java 8 Java 11 and later AIX\u00ae <code>&lt;install_dir&gt;/jre/lib/ppc[64]/default</code> <code>&lt;install_dir&gt;/</code> Linux\u00ae <code>&lt;install_dir&gt;/jre/lib/&lt;arch&gt;/default</code> <code>&lt;install_dir&gt;/</code> macOS\u00ae <code>&lt;install_dir&gt;/jre/lib/default</code> <code>&lt;install_dir&gt;/</code> Windows\u2122 <code>&lt;install_dir&gt;\\jre\\bin\\default</code> <code>&lt;install_dir&gt;\\</code> z/OS\u00ae <code>&lt;install_dir&gt;/jre/lib/s390[x]/default</code> <code>&lt;install_dir&gt;/</code> <p>Where:</p> <ul> <li><code>&lt;install_dir&gt;</code> is your JDK installation directory.</li> <li><code>&lt;arch&gt;</code> depends on the architecture your Linux distribution is running on. See the following table for possible values:</li> </ul> Architecture Value of <code>&lt;arch&gt;</code> x86 32-bit <code>i386</code> x86 64-bit <code>x86-64</code> IBM POWER\u00ae 32-bit (Big Endian) <code>ppc</code> IBM POWER 64-bit (Big Endian) <code>ppc64</code> IBM POWER 64-bit (Little Endian) <code>ppc64le</code> IBM Z\u00ae 31-bit <code>s390</code> IBM Z 64-bit <code>s390x</code>"},{"location":"openj9_newuser/","title":"New to OpenJ9?","text":""},{"location":"openj9_newuser/#new-to-eclipse-openj9","title":"New to Eclipse OpenJ9?","text":"<p>The Eclipse OpenJ9\u2122 virtual machine (VM) implements the Java Virtual Machine Specification. Most Java applications should run on an OpenJDK that contains the OpenJ9 VM without changing anything. However, because it is an independent implementation there are some differences compared to the HotSpot VM, which is the default OpenJDK VM and is also included in an Oracle JDK.</p>"},{"location":"openj9_newuser/#command-line-options","title":"Command-line options","text":"<p>Although OpenJ9 implements its own command-line interface, many HotSpot options are recognized and accepted by the VM for compatibility. Any <code>-XX:</code> options that are not recognized by the VM are ignored by default, which prevents an application failing to start. You can turn off this behavior with the -XX:-IgnoreUnrecognizedXXColonOptions option.</p> <p>For a list of compatible options, equivalent options, and options that need to be set for compatibility, see Switching to OpenJ9.</p>"},{"location":"openj9_newuser/#garbage-collection-policies","title":"Garbage collection policies","text":"<p>Eclipse OpenJ9 has a number of garbage collection (GC) policies designed around different types of applications and workloads. By default, OpenJ9 uses the Generational Concurrent (<code>gencon</code>) GC policy, which is best suited for transactional applications that have many short-lived objects. The policy aims to minimize GC pause times without compromising throughput. If you are using Java 8, the <code>gencon</code> policy is similar to the HotSpot CMS (concurrent mark sweep). If you are using Java 11, the OpenJ9 balanced (<code>balanced</code>) policy is most similar to the default HotSpot policy.</p> <p>If you have a different type of workload, you might want to select a different GC policy. For details about the available policies and when to choose them, see Garbage collection.</p>"},{"location":"openj9_newuser/#operational-tooling","title":"Operational tooling","text":"<p>If you are a Java application developer or you are responsible for managing large server or desktop deployments of a Java runtime environment, you probably use a number of tools for monitoring, management, and troubleshooting. Because OpenJ9 is an independent implementation, it has evolved with its own approach for these areas and, in some cases, its own unique tools.</p> <p>In other cases, tools have been added for compatibility with the reference implementation, but these tools might differ in behavior from equivalent tools in HotSpot. For a list of these tools, see Switching to OpenJ9 in the Tools section.</p>"},{"location":"openj9_newuser/#dumps-logs-and-trace-files","title":"Dumps, logs, and trace files","text":"<p>OpenJ9 contains extensive trace and debugging capabilities to help identify, isolate, and solve run time problems.</p> <ul> <li>Dump files: Various types of dump are produced by default in response to certain events and can also be triggered for a whole range of events by using the <code>com.ibm.jvm.Dump</code> API or by specifying <code>-Xdump</code> options on the command line. Dumps include Java dumps, heap dumps, system dumps, JIT dumps, stack dumps, and snap dumps (tracepoint data). For more information, see the <code>-Xdump</code> option.</li> <li>Verbose log files: Some components of OpenJ9 can also produce verbose output or log files to assist with problem determination, including class data sharing, garbage collection, and the JIT compiler.</li> <li>Trace files: The OpenJ9 implementation contains extensive tracepoints used to log information and exceptional conditions, with minimal impact on performance. Some tracepoints are enabled by default; others can be enabled on demand. For more information, see the <code>-Xtrace</code> option for tracing Java applications and the VM, and the <code>-Xtgc</code> option for tracing garbage collection.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, you probably make use of the monitoring and diagnostic tools that are provided with the VM. OpenJ9 has implemented a different approach to providing similar data; rather than running a number of different tools to obtain a different piece of information, the Java dump file provides a comprehensive set of information in one place. You can find the following information in an OpenJ9 Java dump:</p> <ul> <li>The system the VM is running on and the resources available.</li> <li>The Java execution environment, including the options set from the command line.</li> <li>The native memory used by the VM, broken down by VM component.</li> <li>Memory usage in the VM for the object heap and internal VM structures, such as the JIT code cache.</li> <li>Lock operations that protect shared resources during runtime.</li> <li>Java threads, native threads, and stack traces.</li> <li>Hook interfaces, for performance analysis.</li> <li>Details about the shared classes cache, if used.</li> <li>Detailed information about classloaders, together with a list of libraries and classes that are loaded.</li> </ul> <p>For more information, see Java dump.</p>"},{"location":"openj9_newuser/#tools","title":"Tools","text":"<p>OpenJ9 provides support for a number of monitoring and diagnostic tools that can be found in the Eclipse marketplace. Each tool provides a graphical user interface to help you visualize data and, in some cases, can provide tuning or debugging recommendations.</p> <ul> <li>Health Center: Provides real-time monitoring of running applications with minimal overhead over the network. You can monitor a whole range of operations including, class loading, CPU usage, GC heap and pause times, I/O activity, lock contention, method trace, native memory usage, profiling, and live threads. For more information, read the Health Center documentation.</li> <li>Garbage Collection Memory Vizualizer (GCMV): Plots GC and native memory data over time. You can view and save data as a report, raw log, tabulated data, or in graphical format. The tool helps to diagnose problems such as memory leaks with data presented in various visual formats for analysis. Tuning recommendations are also provided. For more information, read the GCMV documentation.</li> <li>Eclipse Memory Analyzer\u2122: Examines the Java object heap to help find memory leaks or reduce memory consumption. Support is available for OpenJ9 via the DTFJ interface (Install from the Eclipse Help menu; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and Diagnostic Tools &gt; Diagnostic Tool Framework for Java). More information about Eclipse MAT can be found on the project website page.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, the Java VisualVM utility is functionally similar to Health Center. Most of the other tools provided with HotSpot are not officially supported, but equivalent functionality is available in OpenJ9 through command-line options, dump agents, and AttachAPI.</p>"},{"location":"openj9_newuser/#interfaces","title":"Interfaces","text":"<p>OpenJ9 provides the following interfaces, which can be used for monitoring and diagnostic purposes:</p> <ul> <li>JVMTI: OpenJ9 supports the Java Virtual Machine Tool Interface (JVMTI) and provides extensions that allow JVMTI tools to obtain diagnostic information or trigger diagnostic operations in the VM. For more information about this interface, see Java Virtual Machine Tool Interface.</li> <li>DTFJ interface: The Diagnostic Tool Framework for Java (DTFJ) API allows custom applications to be written that can access a wide range of information in a system dump or a Java dump. DTFJ can be used with the Eclipse Memory Analyzer Toolkit (MAT) to examine the Java object heap for memory leaks and to reduce memory consumption. For more information about DTFJ, see Diagnostic Tool Framework for Java.</li> <li>java.lang.management API: OpenJ9 provides MXBean additions and extensions to this standard API, which enables you to use tools such as JConsole to monitor and manage your Java applications. For more information, see Language management interface.</li> </ul> <p>If you are familiar with using HotSpot as part of an Oracle JDK or OpenJDK, you might make use of certain <code>com.sun.management</code> interfaces. Although OpenJ9 implements some of these interfaces, a few are specific to the HotSpot VM. The following table indicates alternative classes or mechanisms that you can use for equivalent function in OpenJ9:</p> HotSpot-specific classes Alternatives for OpenJ9 <code>HotSpotDiagnosticMXBean</code> <code>OpenJ9DiagnosticsMXBean</code> (for heap dumps) <code>MissionControl</code> Use Health Center <code>MissionControlMXBean</code> Use Health Center <code>ThreadMXBean</code> <code>JvmCpuMonitorMXBean</code> (for thread time) <code>VMOption</code> OpenJ9 Java dump (option <code>-Xdump:java</code>) <code>DiagnosticCommandMBean</code> None <p> Note: OpenJ9 implements the following <code>com.sun.management</code> interfaces: <code>GarbageCollectorMXBean</code>, <code>GarbageCollectionNotificationInfo</code>, <code>GcInfo</code>, <code>OperatingSystemMXBean</code>, <code>UnixOperatingSystemMXBean</code>.</p> <p>For information about OpenJ9 application programming interfaces, see API documentation.</p>"},{"location":"openj9_newuser/#other-differences","title":"Other differences","text":"<p>This topic describes the differences between the HotSpot VM and the Eclipse OpenJ9 VM. Therefore, if you are currently using an OpenJDK with the default HotSpot VM and you want to switch to using an OpenJDK with the OpenJ9 VM, these are the only differences you might be concerned about. If however, you are using an Oracle JDK, you might want to learn about differences between other components that make up an Oracle JDK or an OpenJDK from the AdoptOpenJDK community. For more information, read the Migration guide.</p>"},{"location":"openj9_releases/","title":"Overview","text":""},{"location":"openj9_releases/#overview","title":"Overview","text":"<p>New releases of Eclipse OpenJ9\u2122 are set to coincide with critical patch updates and new versions of the Java\u2122 SE class libraries. To learn more about when these releases take place, and the OpenJ9 support lifecycle, see Supported environments.</p> <p>If you are interested in the content of future releases, plans are published in the Eclipse OpenJ9 project page.</p> <p>High level information about the features and changes in final releases of OpenJ9 can be found in the topics that follow.</p>"},{"location":"openj9_signals/","title":"Signal handling","text":""},{"location":"openj9_signals/#signal-handling","title":"Signal handling","text":"<p>Signals used by the Eclipse OpenJ9\u2122 VM include the following types:</p> <ul> <li>Exceptions (Exc): Raised synchronously by the operating system whenever an unrecoverable condition occurs (not applicable on Windows\u2122 systems).</li> <li>Errors (Err): Raised by the OpenJ9 VM when an unrecoverable condition occurs.</li> <li>Interrupts (Int): Raised asynchronously from outside a VM process to request a VM exit.</li> <li>Controls (Con): Other signals that are used by the VM for control purposes.</li> </ul> <p>For exceptions and errors, if the VM cannot handle the condition and recover, dumps are produced and a controlled shut down sequence takes place. Interrupts also cause the VM to enter a controlled shut down sequence, but without generating dumps. The shutdown sequence is equivalent to calling <code>System.exit()</code>, which results in the following steps:</p> <ol> <li>The VM calls the equivalent application signal handler.</li> <li>The VM calls any hooks installed by the application (unexpected shutdown hooks for exceptions or errors, shutdown or exit hooks for interrupts).</li> <li>The VM does any final clean up.</li> </ol> <p>Control signals are used for internal control purposes and do not cause the VM to end.</p> <p>The VM takes control of any signals for Java\u2122 threads. For non-Java threads, the VM passes control to an application handler, if one is installed. If the application does not install a signal handler, or signal chaining is turned off, the signal is either ignored or the default action is taken. Signal chaining is controlled by the <code>-Xsigchain</code> / <code>-Xnosigchain</code> command-line option.</p> <p>The signals relevant to each platform are detailed in the sections that follow.</p> <p>When reading each table, a number supplied after the signal name is the standard numerical value for that signal.</p> <p>Note that certain signals on VM threads cause OpenJ9 to shutdown. An application signal handler should not attempt to recover from these signals unless it no longer requires the VM.</p>"},{"location":"openj9_signals/#signals-on-linux","title":"Signals on Linux","text":"Signal Type Description Option to disable signal <code>SIGBUS (7)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (6)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (12)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (3)</code> Con Quit signal from a terminal, which triggers a Java dump by default <code>-Xrs</code> <code>SIGTRAP (5)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGRTMIN (34)</code> Con Used by the VM for thread introspection - <code>SIGRTMIN +1 (35)</code> Con Used by the VM for Runtime Instrumentation (Linux for IBM Z\u00ae systems only) - <code>SIGRTMAX -2 (62)</code> Con Used by the <code>java.net</code> class library code - <code>SIGCHLD (17)</code> Con Used by the <code>java.lang.Process</code> implementation - <p> Notes:</p> <ul> <li>The use of <code>SIGRTMIN</code> is configurable with the <code>-Xdump:suspendwith=&lt;num&gt;</code> option.</li> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signals-on-macos","title":"Signals on macOS","text":"Signal Type Description Option to disable signal <code>SIGBUS (10)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction)) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (6)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (31)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (3)</code> Con Quit signal from a terminal, which triggers a Java dump by default <code>-Xrs</code> <code>SIGTRAP (5)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGCHLD (20)</code> Con Used by the <code>java.lang.Process</code> implementation - <code>SIGUSR1 (30)</code> Con Used by the VM for thread introspection - <code>SIGIO (23)</code> Con Used by the <code>java.net</code> class library code - <p> Note:</p> <ul> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signals-on-windows","title":"Signals on Windows","text":"Signal Type Description Option to disable signal <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGBREAK</code> Con A break signal from a terminal. By default, this triggers a Java dump <code>-Xrs</code> <p> Notes:</p> <p>The following mechanisms are used by OpenJ9 for signal handling:</p> <ul> <li>structured exception handling (32-bit VM only)</li> <li><code>AddVectoredExceptionHandler()</code> API (64-bit JVM only)</li> <li><code>SetConsoleCtrlHandler()</code> applicable</li> </ul> <p>All mechanisms can be disabled by using the <code>-Xrs</code> option. However, only structured exception handling and the use of the <code>AddVectoredExceptionHandler()</code> API can be disabled  by using the <code>-Xrs:sync</code> option. The option <code>-Xnosigchain</code>, which turns off signal handler chaining, is ignored on Windows systems.</p>"},{"location":"openj9_signals/#signals-on-zos","title":"Signals on z/OS","text":"Signal Type Description Option to disable signal <code>SIGBUS (10)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction)) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (3)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (17)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (24)</code> Con Quit signal from a terminal, triggers a Java dump by default <code>-Xrs</code> <code>SIGTRAP (26)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGCHLD (20)</code> Con Used by the <code>java.lang.Process</code> implementation - <code>SIGUSR1 (16)</code> Con Used by the <code>java.net</code> class library code - <p> Note:</p> <ul> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signals-on-aix","title":"Signals on AIX","text":"Signal Type Description Option to disable signal <code>SIGBUS (10)</code> Exc Incorrect memory access (data misalignment) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGSEGV (11)</code> Exc Incorrect memory access (write to inaccessible area) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGILL (4)</code> Exc Illegal instruction (attempt to call unknown machine instruction)) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGFPE (8)</code> Exc Floating point exception (divide by zero) <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGABRT (6)</code> Err Abnormal termination, raised by the VM when a VM fault is detected <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGINT (2)</code> Int Interactive attention (CTRL-C), VM exits normally <code>-Xrs</code> <code>SIGTERM (15)</code> Int Termination request, VM exits normally <code>-Xrs</code> <code>SIGHUP (1)</code> Int Hang up, VM exits normally <code>-Xrs</code> <code>SIGUSR2 (31)</code> Int User-defined signal for triggering a dump agent <code>-Xrs</code> <code>SIGQUIT (3)</code> Con Triggers a Java dump by default <code>-Xrs</code> <code>No Name (40)</code> Con Used by the VM for control purposes <code>-Xrs</code> <code>SIGRECONFIG (58)</code> Con Reserved to detect changes to resources (CPUs, processing capacity, or physical memory) <code>-Xrs</code> <code>SIGTRAP (5)</code> Con Used by the JIT <code>-Xrs</code> or <code>-Xrs:sync</code> <code>SIGRTMIN (50)</code> Con Used by the VM for thread introspection - <code>SIGRTMAX -1 (56)</code> Con Used by the <code>java.net</code> class library code - <code>SIGCHLD (20)</code> Con Used by the <code>java.lang.Process</code> implementation - <p> Notes:</p> <ul> <li>VM performance is affected if you install a signal handler for SIGTRAP (5) or SIGRECONFIG (58) because these signals are used for internal control purposes.</li> <li>If you want to generate floating point exceptions, use the following call in your code to generate a <code>SIGFPE</code> signal: <code>fp_trap( P_TRAP_SYNC)</code>. Although you can use the C compiler <code>-qflttrap</code> setting to generate <code>SIGTRAP</code> signals to trap floating point exceptions, this mechanism can affect the JIT compiler.</li> <li>The handling of <code>SIGABRT</code> is configurable with the <code>-XX:[+|-]HandleSIGABRT</code> option.</li> <li>The handling of <code>SIGUSR2</code> is configurable with the <code>-XX:[+|-]HandleSIGUSR2</code> option.</li> </ul>"},{"location":"openj9_signals/#signal-chaining","title":"Signal chaining","text":"<p>Signal chaining allows application code to interoperate with VM signal handling. By linking and loading a shared library, certain calls can be intercepted so that the application handlers do not replace the VM signal handlers already installed by the VM. Instead, the application handlers are chained behind the VM handlers. If signals that are raised do not target the VM, the application handlers take over. Signals that can be chained include <code>signal()</code>, <code>sigset()</code>, and <code>sigaction()</code>.</p> <p>The following table shows the shared library that must be linked with the application that creates or embeds a VM, and the command line syntax to use with the compiler, where available:</p> Operating system Shared library Method for linking Linux\u00ae, macOS\u00ae, and z/OS\u00ae <code>libjsig.so</code> <code>gcc -L$JAVA_HOME/bin -ljsig -L$JAVA_HOME/lib/j9vm -ljvm &lt;java_application&gt;.c</code> Windows <code>jsig.dll</code> Link the DLL with the application that creates or embeds a VM AIX <code>libjsig.so</code> <code>cc_r [-q64] &lt;other_compile/link_parameter&gt; -L&lt;java_install_dir&gt; -ljsig -L&lt;java_install_dir&gt;/lib/j9vm -ljvm &lt;java_application&gt;.c</code> <p>In the absence of signal chaining, the VM does not allow application signal handlers for certain signals that are used internally by the VM, including the <code>SIGUSR2</code> signal. You can use the <code>-XX:-HandleSIGUSR2</code> option instead, whereby the VM signal handler is not installed on VM startup. Therefore, the application signal handler, if available, takes over the handling of the <code>SIGUSR2</code> signal. If there is no application signal handler, then the operating system's default signal handler is used.</p> <p>For more information about this option that affects the handling of the <code>SIGUSR2</code> signal, see <code>-XX:[+|-]HandleSIGUSR2</code>.</p> <p> Note: On Linux, macOS, and z/OS systems, you can use the <code>LD_PRELOAD</code> environment variable as an alternative method to the command line for linking the shared library as shown in the following list:</p> <ul> <li>bash and ksh shells: <code>export LD_PRELOAD=$JAVA_HOME/lib/libjsig.so; &lt;java_application&gt;</code></li> <li>csh shell: <code>setenv LD_PRELOAD=$JAVA_HOME/lib/libjsig.so; &lt;java_application&gt;</code></li> </ul>"},{"location":"openj9_signals/#see-also","title":"See also","text":"<ul> <li>-Xrs</li> <li>-Xsigcatch</li> <li>-Xsigchain</li> <li>-Xsignal (z/OS only)</li> </ul>"},{"location":"openj9_support/","title":"Supported environments","text":""},{"location":"openj9_support/#supported-environments","title":"Supported environments","text":"<p>The Eclipse OpenJ9\u2122 project source code can be built against multiple JDK levels starting with JDK8, so the question of support has a more complicated answer than at OpenJDK. Our community is committed to supporting JDK levels as long as they are supported at the OpenJDK open source project with a significant user base. Currently, Eclipse OpenJ9 produces a new release every quarter that can build against all JDK levels that are currently supported by the OpenJDK community. We are committed to accepting problem reports when using Eclipse OpenJ9 against a supported OpenJDK level, with fixes being delivered in each release of Eclipse OpenJ9.</p> <p>In order to track the OpenJDK 6-month release cadence, OpenJ9 also produces two releases a year that support only a single JDK level. These releases will occur in March and September with the intention of supporting only the corresponding new OpenJDK feature release.</p> <p>The following table summarizes which JDK levels are expected to be supported by which Eclipse OpenJ9 releases, along with projected release dates. All future dates and support expectations are predictions that might change depending on how the OpenJDK and OpenJ9 projects evolve over time. To keep this table concise, some rows and columns will be removed over time.</p>"},{"location":"openj9_support/#eclipse-openj9-releases","title":"Eclipse OpenJ9 releases","text":"OpenJ9 release Release date JDK8 (LTS) JDK11 (LTS) JDK17 (LTS) JDK20 JDK21 (LTS) 0.38.0 Apr 2023 yes yes yes 0.39.0 Jun 2023 (2) no no no yes 0.40.0 Jul 2023 yes yes yes yes 0.41.0 Oct 2023 yes yes yes no 0.42.0 Dec 2023 (1, 3) no no no no yes 0.43.0 Jan 2024 (1) yes yes yes no yes <p> Notes:</p> <ol> <li>These future OpenJ9 releases are expected, in line with our support statement.</li> <li>These OpenJ9 releases are feature releases that support a new OpenJDK release only.</li> <li>These OpenJ9 releases support a new LTS OpenJDK release only.</li> </ol> <p>For any issues or limitations of an Eclipse OpenJ9 release, read the release notes.</p>"},{"location":"openj9_support/#platform-support","title":"Platform support","text":"<p>The Eclipse OpenJ9 project is open to supporting any hardware or operating system platforms provided that we have community members available to maintain them. For practical reasons the Eclipse OpenJ9 JVM does not currently run on every platform.</p>"},{"location":"openj9_support/#openjdk-8","title":"OpenJDK 8","text":"<p>OpenJDK 8 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux\u00ae AArch64 x32 x64 ppc64le Z31 Z64 CentOS 6.10 no  yes yes no  no  no  CentOS 7.9 yes yes yes yes no  no  CentOS Stream 8 yes no yes yes no  no  Red Hat Enterprise Linux (RHEL) 6.10 no  yes yes no  no  no  RHEL 7.8 yes yes yes yes no yes RHEL 8.6 yes no yes yes no yes RHEL 9.0 no no yes yes no yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes yes yes Ubuntu 20.04 yes no yes yes no  yes Ubuntu 22.04 no no yes yes no  yes <p> Notes:</p> <ul> <li> <p>Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.12 (x) or 2.17 (others)</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> </li> <li> <p>Support for OpenJ9 on CentOS 6.10 might be available even though CentOS 6 is no longer supported by the CentOS project. However, this support is deprecated and will be removed in a future release. With the removal of support, the minimum glibc version (x) will be increased from 2.12 to 2.17.</p> </li> </ul> Windows\u2122 x32 x64 Windows 10 yes yes Windows 11 yes yes Windows Server 2016 yes yes Windows Server 2019 yes yes Windows Server 2022 yes yes macOS\u00ae x64 OS X\u00ae 10.10.0+ yes macOS 11 yes macOS 12 yes macOS 13 yes AIX\u00ae ppc32 ppc64 AIX 7.2 TL5 yes yes <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#openjdk-11","title":"OpenJDK 11","text":"<p>OpenJDK 11 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux (Note 1) AArch64 x64 ppc64le Z64 CentOS 6.10 no  yes no  no  CentOS 7.9 yes yes yes no  CentOS Stream 8 yes yes yes no  Red Hat Enterprise Linux (RHEL) 6.10 no  yes no  no  RHEL 7.8 yes yes yes yes RHEL 8.6 yes yes yes yes RHEL 9.0 no yes yes yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes Ubuntu 20.04 yes yes yes yes Ubuntu 22.04 no yes yes yes <p> Notes:</p> <ul> <li> <p>Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.12 (x) or 2.17 (others)</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> </li> <li> <p>Support for OpenJ9 on CentOS 6.10 might be available even though CentOS 6 is no longer supported by the CentOS project. However, this support is deprecated and will be removed in a future release. With the removal of support, the minimum glibc version (x) will be increased from 2.12 to 2.17.</p> </li> </ul> Windows x64 Windows 10 yes Windows 11 yes Windows Server 2016 yes Windows Server 2019 yes Windows Server 2022 yes macOS x64 AArch64 (Apple silicon) OS X 10.11+ yes no macOS 11 yes yes macOS 12 yes yes macOS 13 yes yes AIX ppc64 AIX 7.2 TL5 yes <p> Important: AIX OpenJ9 builds require the XL C++ Runtime 16.1.0.7 or later.</p> <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#openjdk-17","title":"OpenJDK 17","text":"<p>OpenJDK 17 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux (Note 1) AArch64 x64 ppc64le Z64 CentOS 7.9 yes yes yes no  CentOS Stream 8 yes yes yes no  RHEL 7.8 yes yes yes yes RHEL 8.6 yes yes yes yes RHEL 9.0 no yes yes yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes Ubuntu 20.04 yes yes yes yes Ubuntu 22.04 no yes yes yes <p> Note: Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.17</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> Windows x64 Windows 10 yes Windows 11 yes Windows Server 2016 yes Windows Server 2019 yes Windows Server 2022 yes macOS x64 AArch64 (Apple silicon) macOS 10.14+ yes no macOS 11 yes yes macOS 12 yes yes macOS 13 yes yes AIX ppc64 AIX 7.2 TL5 yes <p> Important: AIX OpenJ9 builds require the XL C++ Runtime 16.1.0.7 or later.</p> <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#openjdk-21","title":"OpenJDK 21","text":"<p>OpenJDK 21 binaries are expected to function on the minimum operating system levels shown in the following tables:</p> Linux (Note 1) AArch64 x64 ppc64le Z64 CentOS 7.9 yes yes yes no  CentOS Stream 8 yes yes yes no  RHEL 7.8 yes yes yes yes RHEL 8.6 yes yes yes yes RHEL 9.0 no yes yes yes SUSE Linux Enterprise Server (SLES) 12 SP5 no  yes yes yes Ubuntu 20.04 yes yes yes yes Ubuntu 22.04 no yes yes yes <p> Note: Not all of these distributions are tested, but the following distributions are expected to function without problems:</p> <ul> <li>Linux distributions that have a minimum glibc version 2.17</li> <li>RHEL 9.0 and Ubuntu 22.04 distributions on AArch64 architecture</li> </ul> Windows x64 Windows 10 yes Windows 11 yes Windows Server 2016 yes Windows Server 2019 yes Windows Server 2022 yes macOS x64 AArch64 (Apple silicon) macOS 11 yes yes macOS 12 yes yes macOS 13 yes yes AIX ppc64 AIX 7.2 TL5 yes <p> Important: AIX OpenJ9 builds require the XL C++ Runtime 16.1.0.7 or later.</p> <p>When public support for an operating system version ends, OpenJ9 can no longer be supported on that level.</p>"},{"location":"openj9_support/#build-environments","title":"Build environments","text":"<p>The project builds and tests OpenJDK with OpenJ9 on a number of platforms. The operating system and compiler levels for the build systems are shown in the following tables.</p>"},{"location":"openj9_support/#openjdk-8_1","title":"OpenJDK 8","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 6.10 gcc 7.5 Linux on POWER\u00ae LE 64-bit CentOS 7.9 gcc 7.5 Linux on IBM Z\u00ae 64-bit RHEL 7.9 gcc 7.5 Linux AArch64 64-bit CentOS 7.9 gcc 7.5 Windows x86 32-bit Windows Server 2019 Microsoft Visual Studio 2019 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2019 macOS x86 64-bit OSX 10.15.7 xcode 12.4 and clang 12.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 13.1.3"},{"location":"openj9_support/#openjdk-11_1","title":"OpenJDK 11","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 6.10 gcc 7.5 Linux on POWER LE 64-bit CentOS 7.9 gcc 7.5 Linux on IBM Z 64-bit RHEL 7.9 gcc 7.5 Linux AArch64 64-bit CentOS 7.9 gcc 7.5 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2019 macOS x86 64-bit macOS 10.15.7 xcode 12.4 and clang 12.0.0 macOS AArch64 macOS 11.5.2 xcode 13.0 and clang 13.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 16.1.0.11"},{"location":"openj9_support/#openjdk-17_1","title":"OpenJDK 17","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 7.9 gcc 10.3 Linux on POWER LE 64-bit CentOS 7.9 gcc 10.3 Linux on IBM Z 64-bit RHEL 7.9 gcc 10.3 Linux AArch64 64-bit CentOS 7.9 gcc 10.3 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2019 macOS x86 64-bit macOS 10.15.7 xcode 12.4 and clang 12.0.0 macOS AArch64 macOS 11.5.2 xcode 13.0 and clang 13.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 16.1.0.11"},{"location":"openj9_support/#openjdk-21-and-later","title":"OpenJDK 21 and later","text":"Platform Operating system Compiler Linux x86 64-bit CentOS 7.9 gcc 11.2 Linux on POWER LE 64-bit CentOS 7.9 gcc 11.2 Linux on IBM Z 64-bit RHEL 7.9 gcc 11.2 Linux AArch64 64-bit CentOS 7.9 gcc 10.3 Windows x86 64-bit Windows Server 2019 Microsoft Visual Studio 2022 macOS x86 64-bit macOS 10.15.7 xcode 12.4 and clang 12.0.0 macOS AArch64 macOS 11.5.2 xcode 13.0 and clang 13.0.0 AIX POWER BE 64-bit AIX 7.2 TL5 xlc/C++ 16.1.0.11"},{"location":"openssl/","title":"OpenSSL","text":""},{"location":"openssl/#openssl","title":"OpenSSL","text":"<p>OpenJDK uses the in-built Java\u2122 cryptographic implementation by default but Eclipse OpenJ9\u2122 also provides some support for the OpenSSL cryptographic library. OpenSSL is an open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which is well established and used with many enterprise applications. Because it is a native library, OpenSSL might provide better performance. To use OpenSSL cryptographic acceleration, install OpenSSL 1.0.x, 1.1.x, or 3.x on your system. The OpenSSL V1.0.x, V1.1.x, and V3.x implementations are currently supported for the Digest, CBC, GCM, RSA, ECDH key agreement, and EC key generation algorithms. The OpenSSL V1.1.x and V3.x implementations are also supported for the ChaCha20 and ChaCha20-Poly1305 algorithms. The OpenSSL V1.1.1 onwards implementations are supported for the XDH key agreement and XDH key generation algorithms.</p> <p>On Linux\u00ae and AIX\u00ae operating systems, the OpenSSL 1.0.x, 1.1.x, or 3.x library is expected to be found on the system path. If you use a package manager to install OpenSSL, the system path will be updated automatically. On Windows\u2122 and MacOS\u00ae the OpenSSL 3.x library is bundled. Later levels of some Linux operating systems also bundle OpenSSL 3.x.</p> <p>If you have multiple versions of OpenSSL on your system, the OpenJ9 VM uses the latest version.</p> <p> Note: OpenSSL 3.x does not support initialization vector (IV) sizes above 16 Bytes for the GCM algorithm. (In earlier OpenSSL versions, you can use such sizes but they might cause unpredictable behavior.) If you need to use a larger size, disable OpenSSL support for the GCM algorithm.</p> <p>OpenSSL support is enabled by default for all supported algorithms. If you want to limit support to specific algorithms, a number of system properties are available for tuning the implementation.</p> <p>Each algorithm can be disabled individually by setting the following system properties on the command line:</p> <ul> <li>To turn off Digest, set <code>-Djdk.nativeDigest=false</code></li> <li>To turn off ChaCha20 and ChaCha20-Poly1305, set <code>-Djdk.nativeChaCha20=false</code>.  Note:  These algorithms are not supported on Java 8 </li> <li>To turn off CBC, set <code>-Djdk.nativeCBC=false</code></li> <li>To turn off GCM, set <code>-Djdk.nativeGCM=false</code></li> <li>To turn off RSA, set <code>-Djdk.nativeRSA=false</code></li> <li>To turn off ECDH key agreement, set <code>-Djdk.nativeEC=false</code></li> <li>To turn off EC key generation, set <code>-Djdk.nativeECKeyGen=false</code></li> <li> To turn off XDH key agreement, set <code>-Djdk.nativeXDHKeyAgreement=false</code></li> <li>To turn off XDH key generation, set <code>-Djdk.nativeXDHKeyGen=false</code> </li> </ul> <p>You can turn off all the algorithms by setting the following system property on the command line:</p> <pre><code>-Djdk.nativeCrypto=false\n</code></pre> <p>To build a version of OpenJDK with OpenJ9 that includes OpenSSL support, follow the steps in our detailed build instructions:</p> <ul> <li>OpenJDK 8 with OpenJ9.</li> <li>OpenJDK 11 with OpenJ9.</li> <li>OpenJDK 17 with OpenJ9.</li> </ul> <p> Note: If you obtain an OpenJDK with OpenJ9 build that includes OpenSSL or build a version yourself that includes OpenSSL support, the following acknowledgments apply in accordance with the license terms:</p> <ul> <li>This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/).</li> <li>This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).</li> </ul>"},{"location":"shrc/","title":"Introduction","text":""},{"location":"shrc/#introduction-to-class-data-sharing","title":"Introduction to class data sharing","text":"<p>Sharing class data between Eclipse OpenJ9\u2122 VMs improves start up performance and reduces memory footprint. Consider the following outcomes for two VMs that are running similar Java applications but sharing class data:</p> <ul> <li> <p>Start up performance is improved by placing classes that each application needs when initializing into a shared classes cache. The next time the application runs, it takes less time to start because the classes are already available.</p> </li> <li> <p>Memory footprint is reduced by sharing common classes between the applications.</p> </li> </ul> <p>When class data sharing is enabled, OpenJ9 automatically creates shared memory that stores and shares the classes in memory between processes. This shared classes cache is updated dynamically; when an application loads new classes, the VM automatically stores them in the cache without any user intervention. By default, class data sharing is enabled for bootstrap classes, as described in Enabling class data sharing.</p> <p>When class data sharing is enabled, Ahead-of-time (AOT) compilation is also enabled by default, which dynamically compiles certain methods into AOT code at runtime. By using these features in combination, startup performance is further improved because the cached AOT code can be used to quickly enable native code performance for subsequent runs of your application. For more information about AOT, see AOT Compiler. Further performance improvements are gained by storing JIT data and profiles in the shared classes cache.</p> <p>The contents of a shared classes cache can include the following artifacts:</p> <ul> <li>Bootstrap classes</li> <li>Application classes</li> <li>Metadata that describes the classes</li> <li>AOT-compiled code</li> <li>JIT data</li> <li>GC hints (for initial Java heap size)</li> <li> Bootstrap <code>jar</code> file indexes</li> </ul>"},{"location":"shrc/#cache-utilities","title":"Cache utilities","text":"<p>Active caches can be managed by a set of cache utilities, which are invoked by specifying <code>-Xshareclasses</code> suboptions. These utilities control the following types of operations:</p> <ul> <li>Displaying information about the caches on a system.</li> <li>Adjusting the size of a cache and the amount of space that is reserved for AOT code or JIT data.</li> <li>Creating a snapshot of a non-persistent cache to save to disk and restoring the cache from disk.</li> <li>Troubleshooting cache problems.</li> <li>Removing unwanted caches on a system.</li> </ul> <p>These cache utilities are discussed in more detail in the sections that follow.</p>"},{"location":"shrc/#enabling-class-data-sharing","title":"Enabling class data sharing","text":"<p>Class data sharing is enabled by default for bootstrap classes, unless your application is running in a container. Default behavior includes the following characteristics:</p> <ul> <li>On Windows\u00ae, the cache is created in the user's <code>C:\\Users\\&lt;username&gt;\\AppData\\Local\\javasharedresources</code> directory. On z/OS\u00ae, the default cache directory is <code>/tmp/javasharedresources</code>. On other systems, the cache is created in the <code>.cache/javasharedresources</code> directory in the user's home directory, unless the <code>groupAccess</code> parameter is specified, in which case it is created in <code>/tmp/javasharedresources</code>. Please do not set the home directory on a NFS mount or shared mount across systems or LPARs.</li> <li>The cache name is <code>sharedcc_%u</code>, where <code>%u</code> is the current user name.</li> <li>If class data sharing fails, the VM still starts without printing any errors.</li> </ul> <p>Shared class behavior is controlled by specifying the -Xshareclasses option on the command line when you start your application. The default settings are equivalent to specifying the following suboptions:</p> <pre><code>-Xshareclasses:bootClassesOnly,nonFatal,silent\n</code></pre> <p>You can enable class data sharing for non-bootstrap classes as well as bootstrap classes, by omitting the <code>bootClassesOnly</code> suboption. You can also disable all class data sharing by using the <code>none</code> suboption.</p> <p>Further suboptions are available to configure a cache at startup, including name, location, and startup size. You can also use cache utilities to manage a shared classes cache after it is initialized and in use.</p> <p>A shared classes cache can be persistent or non-persistent according to the following definition:</p> <ul> <li>persistent caches are written to memory-mapped files and remain in place, even after a system is rebooted.</li> <li>non-persistent caches exist in shared memory and are automatically removed when the operating system is restarted.</li> </ul> <p>By default, a shared classes cache is persistent, except on the z/OS\u00ae platform, where persistent caches are not supported. If you are using a non-persistent cache, you can use a cache utility to create a snapshot of the cache, which can be reinitialized after a reboot. For more information see Saving a non-persistent shared classes cache.</p> <p>If you have multiple VMs and you do not change the default shared classes behavior, the VMs share a single default cache, assuming that the VMs are from a single Java installation. If the VMs are from different Java installations, the cache might be deleted and re-created.</p> <p>For a set of best practices when using class data sharing, see Creating a shared classes cache.</p>"},{"location":"shrc/#class-data-sharing-operations","title":"Class data sharing operations","text":"<p>When a VM loads a class and the class loader is enabled for class sharing, the VM looks in the shared classes cache to see if the class is already present. If the class is present and the classpath or URL to load the class is a match, the VM loads the class from the cache. Otherwise, it loads the class from the file system and writes it into the cache.</p> <p>The VM detects file system updates by storing timestamp values into the cache and comparing the cached values with actual values. In this way, the VM detects when a class might be invalidated and can mark the class as stale. These operations happen transparently when classes are loaded, so users can modify and update as many classes as they like during the lifetime of a shared classes cache, knowing that the correct classes are always loaded. Stale classes are redeemed if the same class is subsequently fetched by the class loader from another VM and checked against the stale class in the cache.</p> <p>Occasionally, caches that are created from one version of the VM might not be compatible with caches that are created from a different version. This situation typically occurs when an update is made in OpenJ9 that changes the internal cache data structure. If a VM detects an incompatible cache at start up, it creates a new cache that can coexist, even if it has the same name. The VM detects a conflict by checking an internal shared classes cache generation number.</p> <p>Caches are not compatible between VMs that are using different object storage modes. For example, a 64-bit VM that uses compressed references to store 64-bit objects in a 32-bit representation, cannot share a cache with a 64-bit VM that is not using compressed references. For more information about object storage options, see Compressed references.</p> <p>In the OpenJ9 implementation of <code>java.net.URLClassLoader</code>, classes are read from and written to the cache using the public Helper API. Therefore, any class loader that extends <code>java.net.URLClassLoader</code> gets class sharing support for free provided that it continues to use the methods in <code>java.net.URLClassLoader</code> to load classes. Custom class loaders that do not extend <code>java.net.URLClassLoader</code> must be adapted to share class data as described in Support for custom class loaders.</p>"},{"location":"shrc/#aot-code-and-jit-data","title":"AOT code and JIT data","text":"<p>OpenJ9 can automatically store small amounts of AOT code and JIT data, which helps improve performance in the following ways:</p> <ul> <li>The JIT compiler dynamically compiles certain methods into AOT code at runtime. Subsequent VMs that attach to the cache can take advantage of the compiled code to start faster.</li> <li>The JIT compiler stores profiling data and various compilation hints into the shared classes cache. This data enables subsequent VMs that attach to the cache to start faster, run faster, or both.</li> </ul> <p>The default settings provide significant performance benefits. However, you can specify options on the command line to configure AOT code storage or JIT data storage in the shared classes cache, as shown in the following table:</p> Component Setting a minimum storage value Setting a maximum storage value Turning off storage AOT code <code>-Xscminaot&lt;size&gt;</code> <code>-Xscmaxaot&lt;size&gt;</code> <code>-Xshareclasses:noaot</code> JIT data <code>-Xscminjitdata&lt;size&gt;</code> <code>-Xscmaxjitdata&lt;size&gt;</code> <code>-Xshareclasses:nojitdata</code> <p>The following cache utilities are available to adjust the storage values when a cache is active:</p> Component Adjusting the minimum storage value Adjusting the maximum storage value AOT code <code>-Xshareclasses:adjustminaot</code> <code>-Xshareclasses:adjustmaxaot</code> JIT code <code>-Xshareclasses:adjustminjit</code> <code>-Xshareclasses:adjustmaxjit</code> <p>You can also use the <code>-Xshareclasses:findAotMethods</code> cache utility to list the AOT methods in a cache that match a method specification. This utility helps you identify methods that are causing a failure in an application. You can then invalidate the method without destroying the cache by using the <code>-Xshareclasses:invalidateAotMethods</code> cache utility. You can also revalidate an AOT method with the <code>-Xshareclasses:revalidateAotMethods</code> cache utility. To troubleshoot AOT problems, use the <code>-Xshareclasses:verboseAOT</code> suboption on the command line, which generates output about AOT code that is found or stored in the cache. For more information see <code>-Xshareclasses</code>.</p>"},{"location":"shrc/#creating-a-shared-classes-cache","title":"Creating a shared classes cache","text":"<p>The -Xshareclasses option is highly configurable, allowing you to specify where to create the cache, how much space to allocate, and more. The following best practices apply to using class data sharing:</p> <ul> <li> <p>Before starting your application, use the <code>-Xshareclasses:listAllCaches</code> cache utility to review and maintain the existing caches on your system.</p> <p>This option lists all the caches that exist in the default directory, including compatible and incompatible caches. You can also specify the <code>cacheDir</code> suboption to look for caches in a specified directory. Remove any obsolete caches, as described in Housekeeping.</p> </li> <li> <p>If you are creating a new cache, set an application-specific cache name (<code>-Xshareclasses:name=&lt;name&gt;</code>).</p> <p>If a cache with the specified name doesn't already exist, a new cache is created.</p> <p>This avoids sharing your application cache with a cache that is enabled by default or with another application that doesn't set a name, and ensures that the size of your application cache can be set appropriately and that cache space is used exclusively for your application.</p> <p> Note: You cannot change the size of a default cache that already exists by using the <code>-Xscmx</code> option, as that option has no effect on a pre-existing cache.</p> </li> <li> <p>Set a specific cache directory (<code>-Xshareclasses:cacheDir=&lt;directory&gt;</code>).</p> <p>Set a cache directory that is specific to your application, to  avoid sharing the default cache directory with the default cache, or other application caches that don't set a cache directory. Your application will be unaffected by a user running <code>java -Xshareclasses:destroyAll</code>. Please do not set the cache directory on a NFS mount or a shared mount across systems or LPARs.</p> <p>In addition, if you have VMs from different Java installations, of the same Java release and installed by the same user, each VM checks whether the existing default shared cache in the cache directory is from the same Java installation as the VM. If not, the VM deletes that shared cache, then creates a new one. Specifying a different cache directory for each Java installation avoids this situation.</p> </li> <li> <p>Ensure that the cache directory permissions are set appropriately (<code>-Xshareclasses:cacheDirPerm</code>).</p> <p>It is good practice to explicitly set permissions for the cache directory when the defaults are not appropriate. Access is controlled by operating system permissions and Java security permissions; read/write access is the default only for the current user. On Unix systems, you can use the <code>-Xshareclasses:groupAccess</code> suboption to allow read/write permissions for groups as well as users.</p> <p>On z/OS, a cache can be accessed only by a VM that is running in the same storage key as the VM that created the cache. If the keys do not match, permission to access the cache is denied.</p> </li> <li> <p>Set the <code>-Xshareclasses:nonfatal</code> option.</p> <p>In most cases, setting this option allows your application to start even if there is a problem opening or creating the shared cache. The VM will continue to start without class data sharing.</p> </li> <li> <p>Set a soft maximum size for the cache by specifying the -Xscmx option with the <code>-XX:SharedCacheHardLimit</code> option.</p> <p>For example, you might create a 64 MB shared cache and set a smaller value, such as 16 MB, for the <code>-Xscmx</code> option, to limit the data stored in the cache (<code>-XX:SharedCacheHardLimit=64m -Xscmx16m</code>). You can then adjust the soft maximum size by using the <code>-Xshareclasses:adjustsoftmx</code> cache utility or the  <code>MemoryMXBean.setSharedClassCacheSoftmxBytes()</code> method in the <code>com.ibm.lang.management</code> API. For more information, see Setting a soft maximum size.</p> </li> </ul>"},{"location":"shrc/#creating-layer-caches","title":"Creating layer caches","text":"<p>Creating a layered cache might be useful when you are building a Docker image.</p> <p>Normally, writing to an existing shared cache in a lower image layer results in Docker duplicating the shared cache to the top layer (following the Docker copy-on-write strategy). With a layered cache, you can instead write into a new cache in the top layer. The new cache builds on the existing cache, so space is saved in the image.</p> The following example shows a Docker container with four layers: <p></p> <ol> <li>The lowest layer is a Ubuntu Docker image.</li> <li> <p>The next layer is an OpenJ9 Docker image that is built on the Ubuntu image. As part of this image, the <code>-Xshareclasses:name=MyCache</code> suboption is used to create a cache called <code>MyCache</code>. The layer number assigned to this cache is <code>0</code>. The <code>listAllCaches</code> suboption shows the cache and the layer number:</p> <pre><code>java -Xshareclasses:listAllCaches\n...\nCache name              level         cache-type      feature         layer       OS shmid       OS semid       last detach time\n\nCompatible shared caches\nMyCache                 Java8 64-bit  persistent      cr              0                                         Mon Sep 23 11:41:04 2019\n</code></pre> </li> <li> <p>The next Docker layer up is a middleware image that is built on the OpenJ9 image. As part of this image, the <code>-Xshareclasses:name=MyCache,layer=1</code> suboption is used to create another cache called <code>MyCache</code>. Because the <code>layer=1</code> suboption is specified, this new cache is a layered cache, which builds on <code>MyCache</code> in the previous container layer. (Open Liberty starts two VMs, so if you instead use the <code>createLayer</code> suboption here, two layered caches are created, with layer numbers of 1 and 2.) Note that cache layers are different from, and independent of, container layers.</p> </li> <li> <p>In the same way, another Docker layer is added for an application, and another layered cache is created to add to <code>MyCache</code>. The <code>listAllCaches</code> suboption now shows all the caches and their layers:</p> <pre><code>java -Xshareclasses:listAllCaches\n...\nCache name              level         cache-type      feature         layer       OS shmid       OS semid       last detach time\n\nCompatible shared caches\nMyCache                 Java8 64-bit  persistent      cr              0                                         Mon Sep 23 11:41:04 2019\nMyCache                 Java8 64-bit  persistent      cr              1                                         Mon Sep 23 11:46:25 2019\nMyCache                 Java8 64-bit  persistent      cr              2                                         In use\n</code></pre> </li> </ol> <p>The caches are created in the same directory.</p> <p>When you use the <code>-Xshareclasses:name=MyCache</code> suboption in future Java commands, all the caches are started. The top-layer cache is started in read/write mode, and lower-layer caches are started in read-only mode. Modifying a lower-layer cache will invalidate all the caches in the layers above.</p> <p>The following options and cache utilities are available for creating, managing, and removing layered caches:</p> <ul> <li><code>-Xshareclasses:createLayer</code></li> <li><code>-Xshareclasses:layer</code></li> <li><code>-Xshareclasses:printTopLayerStats</code> (for example output, see printTopLayerStats)</li> <li><code>-Xshareclasses:destroyAllLayers</code></li> </ul>"},{"location":"shrc/#saving-a-non-persistent-shared-classes-cache","title":"Saving a non-persistent shared classes cache","text":"<p>As described in an earlier section, a shared classes cache can be persistent or non-persistent; persistent caches are memory-mapped files. By default, a cache is persistent on all platforms, except z/OS. Non-persistent caches are stored in shared memory and are removed when a system is rebooted. If you want to save a non-persistent cache beyond a reboot, you might want to consider taking a cache snapshot.</p> <p>To create a snapshot of a non-persistent shared classes cache, use the <code>-Xshareclasses:snapshotCache</code> cache utility. The snapshot has the same name and location as the shared cache, as specified by the <code>name</code> and <code>cacheDir</code> suboptions. The shared cache can be in use when the snapshot is taken, but VMs are blocked when they try to write to the shared cache while the cache data is copied to the file.</p> <p>Typically, after a system is reinitialized, the snapshot file is used to restore the copy of the non-persistent cache into shared memory, by using the <code>-Xshareclasses:restoreFromSnapshot</code> cache utility. Because this process removes all non-persistent caches from shared memory, restoring the cache from the snapshot file can result in better VM startup performance, because the contents of the shared cache, including classes and AOT code, do not have to be re-created.</p> <p>The <code>-Xshareclasses:listAllCaches</code> cache utility can be used to identify snapshots on a system.</p> <p>A snapshot can be created only if the user has sufficient permissions to create the destination snapshot file. If a snapshot of the same name exists already, it is overwritten. On platforms that support persistent caches, the <code>nonpersistent</code> suboption must be specified in order to create a snapshot. For information about removing snapshot files, see the <code>destroySnapshot</code> and <code>destroyAllSnapshots</code> cache utilities in Housekeeping.</p> <p> Notes:</p> <ul> <li>Persistent caches are not supported on z/OS.</li> <li>The <code>snapshotCache</code> and <code>restoreFromCache</code> cache utilities cannot be used on Windows systems.</li> </ul>"},{"location":"shrc/#housekeeping","title":"Housekeeping","text":"<p>Caches can be deleted if they contain many stale classes or if the cache is full and you want to create a bigger cache. Use one of the following utilities to remove unwanted caches:</p> <ul> <li><code>-Xshareclasses:destroy</code>: Removes specific caches when used with the <code>name</code>, <code>cacheDir</code>, and <code>nonpersistent</code> suboptions.</li> <li><code>-Xshareclasses:destroyAll</code>: Removes all the caches that are specified by the <code>cacheDir</code> and <code>nonpersistent</code> suboptions.</li> <li><code>-Xshareclasses:destroySnapshot</code>: Removes a cache snapshot from disk that is specified by <code>name</code> and <code>cacheDir</code> suboptions.</li> <li><code>-Xshareclasses:destroyAllSnapshots</code>: Removes all cache snapshots from disk that are found by specifying the <code>cacheDir</code> suboption.</li> <li><code>-Xshareclasses:destroyAllLayers</code>: Removes all shared cache layers that are specified by the <code>name</code> and <code>cacheDir</code> suboptions.</li> </ul> <p> Note: You must always use the utilities to remove non-persistent caches correctly from shared memory.</p> <p>Caches can also be removed if they are unused for a specified amount of time. To configure time-based housekeeping, use the -Xshareclasses:expire option.</p> <p>If you want to remove a cache but allow it to be re-created when the VM restarts, use the <code>-Xshareclasses:reset</code> option.</p>"},{"location":"shrc/#support-for-custom-class-loaders","title":"Support for custom class loaders","text":"<p>Classes are shared by the bootstrap class loader internally in the VM. The OpenJ9 implementation of <code>java.net.URLClassLoader</code> is modified to use <code>SharedClassURLClasspathHelper</code> and any class loaders that extend <code>java.net.URLClassLoader</code> can inherit this behavior. If you are using a custom class loader that does not extend <code>java.net.URLClassLoader</code>, you can use the Java Helper API to find and store classes in a shared classes cache.</p> <p>If a running application uses its own class loader and you are using a <code>SecurityManager</code>, you must grant the class loader permission to <code>SharedCachePermission</code> before they can share classes. To grant permission, add shared class permissions to the <code>java.policy</code> file by specifying the <code>ClassLoader</code> class name. Permissions can be set for <code>read</code>, <code>write</code>, or <code>read,write</code>. For example:</p> <pre><code>permission com.ibm.oti.shared.SharedClassPermission\n        \"com.abc.customclassloaders.*\", \"read,write\";\n</code></pre> <p>If a running application is calling the <code>com.ibm.oti.shared.SharedClassUtilities</code> APIs <code>getSharedCacheInfo()</code> or <code>destroySharedCache()</code>, you must also grant the code calling these APIs the appropriate <code>SharedClassesNamedPermission</code>. For example:</p> <pre><code>permission com.ibm.oti.shared.SharedClassesNamedPermission \"getSharedCacheInfo\";\npermission com.ibm.oti.shared.SharedClassesNamedPermission \"destroySharedCache\";\n</code></pre>"},{"location":"shrc/#the-java-shared-classes-helper-api","title":"The Java shared classes Helper API","text":"<p>The Java Helper API classes can be found in the <code>com.ibm.oti.shared</code> package.</p> <p>Each class loader that wants to share classes must get a <code>SharedClassHelper</code> object from a <code>SharedClassHelperFactory</code>. The <code>SharedClassHelper</code>, when created, has a one to one relationship with the class loader. That is, it belongs to the class loader that requested it and can only store classes defined by that class loader. The <code>SharedClassHelper</code> gives the class loader a simple API for finding and storing classes in the class cache to which the VM is connected. If the class loader is garbage collected, its <code>SharedClassHelper</code> is also garbage collected.</p> <p>The following main functions are available from the <code>SharedClassHelper</code> API:</p> <ul> <li><code>findSharedClass</code>: Used to check whether a class is already in the cache before looking for the class on the file system.</li> <li><code>storeSharedClass</code>: Used to store a class in the cache.</li> <li><code>setSharingFilter</code>: A filter that can be used to decide which classes are found and stored in the cache. This filter can be applied to a particular package by implementing the <code>SharedClassFilter</code> interface. To apply a filter to all non-bootstrap class loaders that share classes, specify the <code>-Dcom.ibm.oti.shared.SharedClassGlobalFilterClass</code> system property on the command line.</li> </ul> <p>You can also define partitions in a cache to store sets of classes separately from one another. For more information see <code>SharedClassHelper</code> cache partitions.</p> <p>Each class loader that wants to share data must get a <code>SharedDataHelper</code> object from a <code>SharedDataHelperFactory</code>. A <code>SharedDataHelperFactory</code> provides an interface that can be used to create <code>SharedDataHelpers</code>, which are used for storing Java byte array data. A <code>SharedDataHelper</code> also has a one to one relationship with a class loader, although a class loader can exist without a <code>SharedDataHelper</code>.</p>"},{"location":"shrc/#the-java-shared-classes-utility-api","title":"The Java shared classes utility API","text":"<p>The following APIs are available for obtaining information about a shared classes cache:</p> <ul> <li><code>com.ibm.oti.shared.SharedClassStatistics</code>: Obtains information about cache size, including free space, soft maximum limit, and the limits enforced for AOT and JIT data.</li> <li><code>com.ibm.oti.shared.SharedClassUtilities</code>: Obtains detailed information about a shared classes cache, including its size, name, type, and status.</li> <li><code>com.ibm.oti.shared.SharedClassCacheInfo</code>: Stores information about a shared classes cache and provides API methods to retrieve the information and remove caches. You can also use the <code>IterateSharedCaches</code> and <code>DestroySharedCache</code> JVMTI extensions.</li> </ul>"},{"location":"shrc/#support-for-bytecode-instrumentation","title":"Support for bytecode instrumentation","text":"<p>Modifying the bytecode of a set of classes at runtime is a useful mechanism for adding functions to a program, such as profiling or debugging. The JVM Tools Interface (JVMTI) includes hooks that allow you to instrument the byte code in this way. Alternatively, you can write your own Java agent that uses the <code>java.lang.instrument</code> API. Sharing classes that are changed before they are loaded adds complexity to the class sharing process.</p> <p>By default, if OpenJ9 detects that a JVMTI agent or <code>java.lang.instrument</code> agent has registered to modify class bytes, modified classes are not stored in the cache. Instead, the VM stores original class byte data in the cache, which allows classes to be retransformed.</p> <p>If you turn off bytecode instrumentation support by specifying <code>-Xshareclasses:disableBCI</code> and do not use a modification context to share modified classes safely, all bytecode is loaded from the file system for the agent to modify. When passed to the cache for storing, the VM compares the bytes with known classes of the same name. If a match is found, the class is reused. However, if a match is not found, the potentially modified class is stored in the cache in a way that prevents other VMs from loading it. In this situation, performance can be affected because the bytecode is always loaded from the file system and compared with existing classes in the cache. When bytecode instrumentation is turned off, classes loaded from the shared cache cannot be retransformed. For more information about using a modification context, see Sharing modified bytecode.</p>"},{"location":"shrc/#redefined-and-retransformed-classes","title":"Redefined and retransformed classes","text":"<p>The following rules exist for classes that are redefined or retransformed by JVMTI or <code>java.lang.instrument</code> agents:</p> <ul> <li> <p>Redefined classes contain replacement bytecode that is provided by an agent at run time by using the JVMTI <code>RedefineClasses</code> or <code>Instrumentation.redefineClasses</code> function. A typical use case is for debugging, where function is added for log output. These classes are never stored in the cache.</p> </li> <li> <p>Retransformed classes contain bytecode that can be changed without any reference to the original bytecode by using the JVMTI <code>RetransformClasses</code> or <code>Instrumentation.retransformClasses</code> functions. A typical use case is a profiling agent that adds or removes profiling calls with each retransformation. These classes can be modified multiple times and are not stored in the cache by default. If you want to store these modified classes for reuse, you can do so by setting the <code>-Xshareclasses:cacheRetransformed</code> suboption when you start your application. This option turns off bytecode instrumentation support, forcing cache creation into <code>-Xshareclasses:disableBCI</code> mode.</p> </li> </ul>"},{"location":"shrc/#sharing-modified-bytecode","title":"Sharing modified bytecode","text":"<p>Sharing modified bytecode can be advantageous for applications that use the same modifications because the transformation process needs to happen only once. OpenJ9 allows multiple VMs that are using the same or different types of class modifications to safely share the cache. However, when a class is modified and cached, it cannot be modified (retransformed) further.</p> <p>Modified bytecode can be shared safely by using a modification context. Use the <code>-Xshareclasses:disableBCI</code> and <code>-Xshareclasses:modified=&lt;modified_context&gt;</code> suboptions when you start your application, where <code>&lt;modified_context&gt;</code> is a user-defined description. The cache is structured so that any VM that is started with the same modification context can share the classes in a private area. The following outcomes apply to VMs that do not want to share the modified classes:</p> <ul> <li>A VM that is started without specifying a modification context shares classes outside of that area as normal.</li> <li>A VM that is started with a different modification context, shares classes in its own private area.</li> </ul>"},{"location":"shrc/#sharedclasshelper-cache-partitions","title":"<code>SharedClassHelper</code> cache partitions","text":"<p>Another method of structuring and protecting classes in the shared classes cache can be implemented by using the <code>SharedClassHelper</code> API with a custom class loader. This mechanism creates partitions by using a string key to identify a set of classes, which can be stored and retrieved by the class loader. A use case for this mechanism is Aspect Oriented Programming (AOP) where aspects are woven in to bytecode when a class is loaded into the VM. Being able to partition the cache provides a suitable level of granularity when you want to use different aspect paths.</p> <p>Although it is possible to combine partitions and modification contexts, this practice is not recommended because the cache will contain partitions within partitions.</p> <p> Note: Partitions are not supported by the bootstrap class loader or the default application class loader.</p>"},{"location":"shrc/#see-also","title":"See also","text":"<ul> <li>AOT compiler</li> <li>Class sharing article</li> <li>Diagnosing problems with class data sharing</li> </ul>"},{"location":"shrc_diag_util/","title":"Diagnosing problems","text":""},{"location":"shrc_diag_util/#diagnosing-problems-with-class-data-sharing","title":"Diagnosing problems with class data sharing","text":"<p>If you encounter problems with class data sharing, VM messages are typically generated that point to an underlying cause. In some situations, a cache might fail to initialize correctly. In other situations classes might not be found or stored in the shared classes cache. To provide more information about a problem, you can generate verbose output, use diagnostic cache utilities, or use the Eclipse OpenJ9\u2122 trace facility.</p>"},{"location":"shrc_diag_util/#initialization-problems","title":"Initialization problems","text":"<p>If you do not specify a directory for the shared classes cache by using the <code>cacheDir</code> suboption, the cache is created in the <code>javasharedresources</code> directory in the following default location:</p> <ul> <li>On Windows\u00ae systems, this directory is created in the user's <code>C:\\Users\\&lt;username&gt;\\AppData\\Local\\</code> directory.</li> <li>On z/OS\u00ae systems, this directory is created in the <code>/tmp</code> directory.</li> <li>On other systems, this directory is located in the <code>.cache</code> directory in the user's home directory. Do not set the user's home directory on an NFS mount or a shared mount across systems or LPARs.</li> </ul> <p>Initialization problems can occur on systems other than Windows because caches are created with read/write access for the user only and subsequent users do not have permission to write to the home directory. If you specify the <code>-Xshareclasses:groupAccess</code> suboption, the cache is created in the <code>/tmp</code> directory instead where all users have permission to write to the cache.</p> <p>For a persistent cache, initialization problems can also occur if there is insufficient disk space available or if you are attempting to locate the cache on a remote networked file system, which is not supported.</p> <p>For a non-persistent cache, a shared memory area is required. Check that your system is configured with sufficient resources as described in Setting shared memory values. If initialization problems persist, try deleting the cache by using the <code>-Xshareclasses:destroyAll</code> cache utility, which removes all known shared memory areas and semaphores for caches in the <code>cacheDir</code> specified or the default directory. These actions force the VM to re-create the cache.</p>"},{"location":"shrc_diag_util/#problems-finding-or-storing-classes","title":"Problems finding or storing classes","text":"<p>The most common cause for classes not being stored in the cache is due to space constraints. Make sure that you set an appropriate size for the cache, as described in Creating a shared classes cache. Setting a soft maximum size is recommended, because you can adjust the soft maximum size that is set for the cache after it is created. See Setting a soft maximum size.</p> <p>Storing classes can also be a problem if the cache is opened read-only or if the class does not exist on the file system because it is sourced from a URL location.</p> <p>If you are attempting to share modified bytecode, you must use a modification context, as described in Sharing modified bytecode. Otherwise, classes are stored in a private area that is not accessible to other VMs.</p> <p>If you are using a custom class loader, class path entries in the <code>SharedClassURLClasspathHelper</code> must be confirmed before classes can be found for these entries. More information about confirmed entries is available in the <code>SharedClassURLClasspathHelper</code> interface in the <code>com.ibm.oti.shared</code> API documentation.</p> <p>If you are instrumenting bytecode by using a JVMTI agent or <code>java.lang.instrument</code> agent, the following rules apply:</p> <ul> <li>Redefined classes are never stored in the cache.</li> <li>Retransformed classes are stored only if you specify the <code>-Xshareclasses:cacheRetransformed</code> suboption when you start your application.</li> </ul> <p>If a running application uses its own class loader and you are using a <code>SecurityManager</code>, you must grant the class loader permission to <code>SharedCachePermission</code> before they can share classes. For more information, see Support for custom class loaders.</p> <p>In very rare cases, problems with finding or storing classes might be due to cache corruption. If the VM detects that a cache is corrupt, it attempts to destroy the cache and re-create it. If the VM cannot re-create the cache, it starts only if the <code>-Xshareclasses:nonfatal</code> suboption is specified on the command line, but without using the shared cache. Try using the <code>-Xshareclasses:destroy</code> cache utility to remove the specific cache and re-create it. You might need to specify the <code>cacheDir=&lt;directory&gt;</code> and <code>name=&lt;cache_name&gt;</code> suboptions if the cache is not using the default settings.</p>"},{"location":"shrc_diag_util/#generating-verbose-output","title":"Generating verbose output","text":"<p>A number of <code>-Xshareclasses</code> suboptions are available for generating verbose output during class data sharing operations, which can help you identify the root cause of a problem.</p>"},{"location":"shrc_diag_util/#verbose","title":"<code>verbose</code>","text":"<p>The <code>-Xshareclasses:verbose</code> suboption provides basic output on cache usage. In the following example, a persistent cache is opened and attached to the VM for class sharing. Information is provided about the size of the cache, the unstored bytes due to the setting of a soft maximum size, and maximum AOT and JIT data size.</p> <pre><code>java -Xshareclasses:name=myCache,verbose HelloWorld\n[-Xshareclasses persistent cache enabled]\n[-Xshareclasses verbose output enabled]\nJVMSHRC237I Opened shared classes persistent cache myCache\nJVMSHRC246I Attached shared classes persistent cache myCache\nJVMSHRC765I Memory page protection on runtime data, string read-write data and partially filled pages is successfully enabled\nHello World\nJVMSHRC168I Total shared class bytes read=2532416. Total bytes stored=268156\nJVMSHRC818I Total unstored bytes due to the setting of shared cache soft max is 0. Unstored AOT bytes due to the setting of -Xscmaxaot is 0. Unstored JIT bytes due to the setting of -Xscmaxjitdata is 0.\n\n</code></pre>"},{"location":"shrc_diag_util/#verboseio","title":"<code>verboseIO</code>","text":"<p>The <code>-Xshareclasses:verboseIO</code> suboption provides more detailed information about class sharing operations. In the following example, some classes are found when the cache is accessed. However, class <code>openj9/internal/tools/attach/target/CommonDirectory</code> is not found and is therefore stored for sharing.</p> <pre><code>java -Xshareclasses:name=myCache,verboseIO HelloWorld\n[-Xshareclasses verbose I/O output enabled]\nFound class java/lang/Object in shared cache for class-loader id 0.\nFound class java/lang/J9VMInternals in shared cache for class-loader id 0.\nFound class com/ibm/oti/vm/VM in shared cache for class-loader id 0.\nFound class java/lang/J9VMInternals$ClassInitializationLock in shared cache for class-loader id 0.\n...\nFailed to find class openj9/internal/tools/attach/target/CommonDirectory in shared cache for class-loader id 0.\nStored class openj9/internal/tools/attach/target/CommonDirectory in shared cache for class-loader id 0 with URL /root/sdk/jre/lib/amd64/compressedrefs/jclSC180/vm.jar (index 0).\n...\n</code></pre> <p>The bootstrap class loader has an ID of <code>0</code>; other class loaders are given a unique ID. Class loaders follow the class loader hierarchy by asking the parent class loader for a class. If a parent fails to find the class in the cache, the child class loader stores the class in the cache.</p> <p>In some situations, verbose output might not show classes being found. For example, classes are typically not found if the class is stale, as described in Class data sharing operations. Stale classes are redeemed if the same class is subsequently fetched by the class loader from another VM and checked against the stale class in the cache.</p>"},{"location":"shrc_diag_util/#verboseaot","title":"<code>verboseAOT</code>","text":"<p>To troubleshoot AOT problems, use the <code>-Xshareclasses:verboseAOT</code> suboption on the command line, which generates output about AOT code that is found or stored in the cache.</p> <p>In the following example output, a populated cache is being accessed to look for compiled AOT code. Some AOT code is found, which can be shared, and some AOT code is stored for reuse.</p> <pre><code>java -Xshareclasses:name=myCache,verboseAOT HelloWorld\n[-Xshareclasses AOT verbose output enabled]\nFound AOT code for ROMMethod 0x00007F658005C180 in shared cache.\nFound AOT code for ROMMethod 0x00007F65800723EC in shared cache.\nFound AOT code for ROMMethod 0x00007F6580071D14 in shared cache.\nStored AOT code for ROMMethod 0x00007F65801847B8 in shared cache.\nStored AOT code for ROMMethod 0x00007F65800D38A4 in shared cache.\nStored AOT code for ROMMethod 0x00007F65800723CC in shared cache.\nFound AOT code for ROMMethod 0x00007F65800D38A4 in shared cache.\nStored AOT code for ROMMethod 0x00007F65800724C4 in shared cache.\n...\n</code></pre>"},{"location":"shrc_diag_util/#verbosehelper","title":"<code>verboseHelper</code>","text":"<p>To troubleshoot problems with custom class loaders that use the Java <code>SharedClassHelper</code> API, specify the <code>-Xshareclasses:verboseHelper</code> suboption. Information messages and error messages are generated in the output, which can help you diagnose problems with finding or storing classes in the shared cache.</p> <p>The following example output shows only information messages:</p> <pre><code>java -Xshareclasses:name=myCache,verboseHelper HelloWorld\n[-Xshareclasses Helper API verbose output enabled]\nInfo for SharedClassURLClasspathHelper id 1: Verbose output enabled for SharedClassURLClasspathHelper id 1\nInfo for SharedClassURLClasspathHelper id 1: Created SharedClassURLClasspathHelper with id 1\nInfo for SharedClassURLClasspathHelper id 2: Verbose output enabled for SharedClassURLClasspathHelper id 2\nInfo for SharedClassURLClasspathHelper id 2: Created SharedClassURLClasspathHelper with id 2\nInfo for SharedClassURLClasspathHelper id 1: There are no confirmed elements in the classpath. Returning null.\nInfo for SharedClassURLClasspathHelper id 2: There are no confirmed elements in the classpath. Returning null.\nInfo for SharedClassURLClasspathHelper id 2: setClasspath() updated classpath. No invalid URLs found\nInfo for SharedClassURLClasspathHelper id 2: Number of confirmed entries is now 1\nHello World\n</code></pre>"},{"location":"shrc_diag_util/#diagnostic-cache-utilities","title":"Diagnostic cache utilities","text":"<p>These utilities display information about the contents of a shared classes cache. Run the utilities by specifying them as suboptions of <code>-Xshareclasses</code>. The utilities run on the default cache unless you specify a cache by adding the <code>name=&lt;cache_name&gt;</code> and <code>cacheDir=&lt;directory&gt;</code> suboptions.</p>"},{"location":"shrc_diag_util/#printstats","title":"<code>printStats</code>","text":"<pre><code>-Xshareclasses:printStats\n-Xshareclasses:printStats,name=&lt;cache_name&gt;\n-Xshareclasses:printStats=&lt;data_type1&gt;[+&lt;data_type2&gt;][...],name=&lt;cache_name&gt;\n</code></pre> <p>Displays summary information about the cache. For layered caches, <code>-Xshareclasses:printStats</code> shows some information for the top layer cache, and summary information (bytes and counts only) for all layers combined. To see information for the top layer cache only, use <code>printTopLayerStats</code>.</p> <p>You can request more detail about items of a specific data type that are stored in the shared cache by using <code>printStats=&lt;data_type&gt;</code>. Use the plus symbol (+) to separate the data types. For example, use <code>printStats=romclass+url,name=myCache</code> to see information about <code>ROMClass</code> and <code>URL</code> items in all the layer caches of the cache called <code>Cache1</code>. The valid data types are as follows (case insensitive):</p> <ul> <li><code>help</code> (displays the list of valid data types)</li> <li><code>all</code> (equivalent to <code>printAllStats</code>)</li> <li><code>classpath</code></li> <li><code>url</code></li> <li><code>token</code></li> <li><code>romclass</code></li> <li><code>rommethod</code></li> <li><code>aot</code></li> <li><code>jitprofile</code></li> <li><code>jithint</code></li> <li><code>zipcache</code></li> <li><code>stale</code></li> <li><code>startuphint</code></li> </ul> <p>Example output for a traditional cache (no cache layers: <code>cache layer = 0</code>), with summary information only:</p> <pre><code>Current statistics for cache \"Cache1\":\n\nCache created with:\n        -Xnolinenumbers                      = false\n        BCI Enabled                          = true\n        Restrict Classpaths                  = false\n        Feature                              = cr\n\nCache contains only classes with line numbers\n\nbase address                         = 0x00007F60B807A000\nend address                          = 0x00007F60B905E000\nallocation pointer                   = 0x00007F60B81BE3A8\n\ncache layer                          = 0\ncache size                           = 16776608\nsoftmx bytes                         = 16776608\nfree bytes                           = 12740572\nReserved space for AOT bytes         = -1\nMaximum space for AOT bytes          = -1\nReserved space for JIT data bytes    = -1\nMaximum space for JIT data bytes     = -1\nMetadata bytes                       = 30440\nMetadata % used                      = 0%\nClass debug area size                = 1331200\nClass debug area used bytes          = 189358\nClass debug area % used              = 14%\n\nROMClass bytes                       = 1328040\nAOT bytes                            = 98404\nJIT data bytes                       = 168\nZip cache bytes                      = 1133704\nStartup hint bytes                   = 0\nData bytes                           = 114080\n\n# ROMClasses                         = 452\n# AOT Methods                        = 2\n# Classpaths                         = 1\n# URLs                               = 0\n# Tokens                             = 0\n# Zip caches                         = 21\n# Startup hints                      = 0\n# Stale classes                      = 0\n% Stale classes                      = 0%\n\n\nCache is 24% full\n\nCache is accessible to current user = true\n</code></pre> <p>Example output for a cache with 2 layers (<code>cache layer = 1</code>), with summary information only:</p> <pre><code>Current statistics for top layer of cache \"Cache1\":\n\nCache created with:\n        -Xnolinenumbers                      = false\n        BCI Enabled                          = true\n        Restrict Classpaths                  = false\n        Feature                              = cr\n\n\nbase address                         = 0x00007FCAB2766000\nend address                          = 0x00007FCAB374A000\nallocation pointer                   = 0x00007FCAB2766000\n\ncache layer                          = 1\ncache size                           = 16776608\nsoftmx bytes                         = 16776608\nfree bytes                           = 15299372\nReserved space for AOT bytes         = -1\nMaximum space for AOT bytes          = -1\nReserved space for JIT data bytes    = -1\nMaximum space for JIT data bytes     = -1\nClass debug area size                = 1331200\nClass debug area used bytes          = 0\nClass debug area % used              = 0%\n\nCache is 8% full\n\nCache is accessible to current user = true\n---------------------------------------------------------\n\nCurrent statistics for all layers of cache \"Cache1\":\n\nROMClass bytes                       = 1328040\nAOT bytes                            = 128924\nJIT data bytes                       = 812\nZip cache bytes                      = 1133704\nStartup hint bytes                   = 0\nData bytes                           = 114080\n\n# ROMClasses                         = 452\n# AOT Methods                        = 20\n# Classpaths                         = 1\n# URLs                               = 0\n# Tokens                             = 0\n# Zip caches                         = 21\n# Startup hints                      = 0\n# Stale classes                      = 0\n% Stale classes                      = 0%\n</code></pre> <p>The <code>Cache created with</code> section indicates the options that were used when the cache was created. <code>BCI Enabled</code> relates to the <code>-Xshareclasses:enableBCI</code> option (enabled by default) and <code>Restrict Classpaths</code> relates to the <code>-Xshareclasses:restrictClasspaths</code> option. <code>Feature = cr</code> indicates that the cache is a 64-bit compressed references cache.</p> <p>Line number information for classes in the cache is then shown with one of the following messages:</p> <ul> <li><code>Cache contains only classes with line numbers</code> : VM line number processing was enabled for all the classes that were stored in this shared cache (the <code>-Xlinenumbers</code> option is enabled by default). All classes in the cache contain line numbers if the original classes contained line number data.</li> <li><code>Cache contains only classes without line numbers</code> : The <code>-Xnolinenumbers</code> option was used to disable VM line number processing for all the classes that were stored in this shared cache, so none of the classes contain line numbers.</li> <li><code>Cache contains classes with line numbers and classes without line numbers</code> : VM line number processing was enabled for some classes and disabled for others (the <code>-Xnolinenumbers</code> option was specified when some of the classes were added to the cache).</li> </ul> <p>The following summary data is displayed:</p> <ul> <li><code>baseAddress</code> and <code>endAddress</code><ul> <li>The boundary addresses of the shared memory area that contains the classes. These addresses vary from run to run, depending on where the operating system allocates the memory.</li> </ul> </li> <li><code>allocation pointer</code><ul> <li>The address where <code>ROMClass</code> data is currently being allocated in the cache.</li> </ul> </li> <li><code>cache layer</code><ul> <li>The layer number that the cache stats relate to.</li> </ul> </li> <li><code>cache size</code> and <code>free bytes</code><ul> <li><code>cache size</code> shows the total size of the shared memory area in bytes</li> <li><code>free bytes</code> shows the free bytes that remain. The free space is not necessarily all available for storing new classes. The cache contains separate areas for different data, and can reserve space for AOT and JIT data, as shown by subsequent summary data.</li> </ul> </li> <li><code>softmx bytes</code><ul> <li>The soft maximum size for the cache. For more information, see <code>-Xscmx</code>.</li> </ul> </li> <li><code>ROMClass bytes</code><ul> <li>The number of bytes of class data in the cache, which does not include data that is stored in the class debug area (see separate output for the class debug area).</li> </ul> </li> <li><code>AOT bytes</code><ul> <li>The number of bytes of AOT-compiled code in the cache.</li> </ul> </li> <li><code>Reserved space for AOT bytes</code><ul> <li>The number of bytes reserved for AOT-compiled code in the cache.</li> </ul> </li> <li><code>Maximum space for AOT bytes</code><ul> <li>The maximum number of bytes of AOT-compiled code that can be stored in the cache.</li> </ul> </li> <li><code>JIT data bytes</code><ul> <li>The number of bytes of JIT-related data stored in the cache.</li> </ul> </li> <li><code>Reserved space for JIT data bytes</code><ul> <li>The number of bytes reserved for JIT-related data in the cache.</li> </ul> </li> <li><code>Maximum space for JIT data bytes</code><ul> <li>The maximum number of bytes of JIT-related data that can be stored in the cache.</li> </ul> </li> <li><code>Zip cache bytes</code><ul> <li>The number of zip entry cache bytes stored in the cache. On Java 11 and later, this value is zero unless a <code>jar</code> file is added to the boot classpath.</li> </ul> </li> <li><code>Startup hint bytes</code><ul> <li>The number of bytes of data stored to describe startup hints.</li> </ul> </li> <li><code>Data bytes</code><ul> <li>The number of bytes of non-class data stored by the VM.</li> </ul> </li> <li><code>Metadata bytes</code><ul> <li>The number of bytes of data stored to describe the cached classes.  Note: This field is available only in the top layer cache output or when a cache is not layered.</li> </ul> </li> <li><code>Metadata % used</code><ul> <li>The proportion of metadata bytes to class bytes, which indicates how efficiently cache space is being used. The value shown does consider the <code>Class debug area size</code>.</li> </ul> </li> <li><code>Class debug area size</code><ul> <li>The size in bytes of the class debug area. This area is reserved to store <code>LineNumberTable</code> and <code>LocalVariableTable</code> class attribute information.</li> </ul> </li> <li><code>Class debug area bytes used</code><ul> <li>The size in bytes of the Class Debug Area that contains data.</li> </ul> </li> <li><code>Class debug area % used</code><ul> <li>The percentage of the Class Debug Area that contains data.</li> </ul> </li> <li><code>ROMClasses</code><ul> <li>The number of classes in the cache. The cache stores <code>ROMClasses</code> (the class data itself, which is read-only) and information about the location from which the classes were loaded. This information is stored in different ways, depending on the Java <code>SharedClassHelper</code> API that was used to store the classes. For more information, see Support for custom class loaders.</li> </ul> </li> <li><code>AOT methods</code><ul> <li>Optionally, <code>ROMClass</code> methods can be compiled and the AOT code stored in the cache. The <code>AOT methods</code> information shows the total number of methods in the cache that have AOT code compiled for them. This number includes AOT code for stale classes.</li> </ul> </li> <li><code>Classpaths</code>, <code>URLs</code>, and <code>Tokens</code><ul> <li>The number of class paths, URLs, and tokens in the cache. Classes stored from a <code>SharedClassURLClasspathHelper</code> are stored with a Classpath. Classes stored using a <code>SharedClassURLHelper</code> are stored with a URL. Classes stored using a <code>SharedClassTokenHelper</code> are stored with a Token. Most class loaders, including the bootstrap and application class loaders, use a <code>SharedClassURLClasspathHelper</code>. The result is that it is most common to see class paths in the cache.</li> <li>The number of Classpaths, URLs, and Tokens stored is determined by a number of factors. For example, every time an element of a Classpath is updated, such as when a <code>.jar</code> file is rebuilt, a new Classpath is added to the cache. Additionally, if partitions or modification contexts are used, they are associated with the Classpath, URL, or Token. A Classpath, URL, or Token is stored for each unique combination of partition and modification context. For more information, see Sharing modified bytecode and <code>SharedClassHelper</code> cache partitions.</li> </ul> </li> <li><code>Zip caches</code><ul> <li>The number of <code>.zip</code> files that have entry caches stored in the shared cache. On Java 11 and later, this value is zero unless a <code>jar</code> file is added to the boot classpath.</li> </ul> </li> <li><code>Startup hints</code><ul> <li>The number of startup hints stored in the cache. There can be a startup hint for each unique set of command line options used to start the VM.</li> </ul> </li> <li><code>Stale classes</code><ul> <li>The number of classes that have been marked as \"potentially stale\" by the cache code, because of a VM or Java application update. See Class data sharing operations.</li> </ul> </li> <li><code>% Stale classes</code><ul> <li>The percentage of classes in the cache that are stale.</li> </ul> </li> <li><code>Cache is XXX% full</code><ul> <li>The percentage of the cache that is currently used. This line is displayed only if the soft maximum size is not set. This value is calculated as follows:<ul> <li><code>% Full = (('Cache Size' - 'Free Bytes') * 100) / ('Cache Size')</code></li> </ul> </li> </ul> </li> <li><code>Cache is XXX% soft full</code><ul> <li>The percentage of the soft maximum size that is currently used. This line is displayed only if the soft maximum size is set. The <code>free bytes</code> in the cache statistics means the free bytes within the soft maximum limit. This value is calculated as follows:<ul> <li><code>% soft Full = (('Soft max bytes' - 'Free Bytes') * 100) / ('Soft max  bytes')</code></li> </ul> </li> <li>For more information about the soft maximum size, see <code>-Xscmx</code>.</li> </ul> </li> <li><code>Cache is accessible to current user</code><ul> <li>Whether the current user can access the cache.</li> </ul> </li> </ul>"},{"location":"shrc_diag_util/#printallstats","title":"<code>printAllStats</code>","text":"<pre><code>-Xshareclasses:printAllStats\n-Xshareclasses:printAllStats,name=&lt;cache_name&gt;\n</code></pre> <p>Displays the contents of the cache in chronological order. You can use this output to see the history of updates that were made to the cache. For layered caches, some information is shown for the top layer cache only, and some is shown for all layers combined. To see information for the top layer cache only, use <code>printTopLayerStats=all</code>.</p> <p>Each entry in the output starts with a VM ID, so you can see which VM wrote the associated data. Here are example entries for various types of cache data, with explanations:</p>"},{"location":"shrc_diag_util/#class-paths","title":"Class paths","text":"<p>The following example shows one class path with 4 entries:</p> <pre><code>    1: 0x2234FA6C CLASSPATH\n            /myVM/Apps/application1.jar\n            /myVM/Apps/application2.jar\n            /myVM/Apps/application3.jar\n            /myVM/Apps/application4.jar\n</code></pre> <ul> <li><code>1</code>: the ID of the VM that wrote this data.</li> <li><code>0x2234FA6C</code>: the address where this data is stored.</li> <li><code>CLASSPATH</code>: the type of data that was written.</li> </ul>"},{"location":"shrc_diag_util/#romclasses","title":"ROMClasses","text":"<p>This example shows an entry for a single <code>ROMClass</code>:</p> <pre><code>    1: 0x2234F7DC ROMCLASS: java/lang/Runnable at 0x213684A8\n            Index 1 in class path 0x2234FA6C\n</code></pre> <ul> <li><code>1</code>: the ID of the VM that wrote this data.</li> <li><code>0x2234F7DC</code>: the address where the metadata about the class is stored.</li> <li><code>ROMCLASS</code>: the type of data that was stored.</li> <li><code>java/lang/Runnable</code>: the name of the class.</li> <li><code>0x213684A8</code>: the address where the class was stored.</li> <li><code>Index 1</code>: the index in the class path where the class was loaded from.</li> <li><code>0x2234FA6C</code>: the address of the class path against which this class is stored.</li> </ul> <p>Stale classes are marked with <code>!STALE!</code>. Any partition or modification context that is used when the class is stored is also shown.</p>"},{"location":"shrc_diag_util/#aot-methods","title":"AOT methods","text":"<p>This example shows an entry for one AOT-compiled method:</p> <pre><code>    1: 0x00007F841A800554 AOT: hashCode Signature: ()I Address: 0x00007F83F6859280\n            for ROMClass java/lang/Object at 0x00007F83F6859000.\n</code></pre> <ul> <li><code>1</code>: the ID of the VM that wrote this data.</li> <li><code>0x00007F841A800554</code>: the address where the data is stored.</li> <li><code>AOT</code>: the type of data that was stored.</li> <li><code>hashCode</code>: the method for which AOT-compiled code is stored.</li> <li><code>()I</code>: the signature of the ROM method.</li> <li><code>0x00007F83F6859280</code>: the ROM method address.</li> <li><code>java/lang/Object</code>: the class that contains the method.</li> <li><code>0x00007F83F6859000</code>: the address of the class that contains the method.</li> </ul> <p>Stale methods are marked with <code>!STALE!</code>.</p>"},{"location":"shrc_diag_util/#urls-and-tokens","title":"URLs and tokens","text":"<p>The output for these data types has the same format as that for class paths, but with a single entry. A <code>Token</code> is a string that is passed to the Java <code>SharedClassHelper</code> API.</p>"},{"location":"shrc_diag_util/#zip-entry-caches","title":"Zip entry caches","text":"<p>The following example shows 4 separate entries for zip entry caches:</p> <pre><code>    1: 0x042FE07C ZIPCACHE: luni-kernel.jar_347075_1272300300_1 Address: 0x042FE094 Size: 7898\n    1: 0x042FA878 ZIPCACHE: luni.jar_598904_1272300546_1 Address: 0x042FA890 Size: 14195\n    1: 0x042F71F8 ZIPCACHE: nio.jar_405359_1272300546_1 Address: 0x042F7210 Size: 13808\n    1: 0x042F6D58 ZIPCACHE: annotation.jar_13417_1272300554_1 Address: 0x042F6D70 Size: 1023\n</code></pre> <ul> <li><code>1</code> : the ID of the VM that wrote this data.</li> <li><code>0x042FE07C</code> : the address where the metadata for the zip entry cache is stored.</li> <li><code>ZIPCACHE</code> : the type of data that was stored.</li> <li><code>luni-kernel.jar_347075_1272300300_1</code> : the name of the zip entry cache.</li> <li><code>0x042FE094</code> : the address where the data is stored.</li> <li><code>7898</code> : the size of the stored data, in bytes.</li> </ul>"},{"location":"shrc_diag_util/#jit-data","title":"JIT data","text":"<p>Information about JIT data is shown in <code>JITPROFILE</code> and <code>JITHINT</code> entries. For example:</p> <pre><code>    1: 0xD6290368 JITPROFILE: getKeyHash Signature: ()I Address: 0xD55118C0\n    for ROMClass java/util/Hashtable$Entry at 0xD5511640.\n    2: 0xD6283848 JITHINT: loadClass Signature: (Ljava/lang/String;)Ljava/lang/Class; Address: 0xD5558F98\n    for ROMClass com/ibm/oti/vm/BootstrapClassLoader at 0xD5558AE0.\n</code></pre>"},{"location":"shrc_diag_util/#startup-hints","title":"Startup hints","text":"<p>Information about startup hints is shown in <code>STARTUP HINTS KEY</code> and <code>STARTUP HINTS DETAIL</code>. For example:</p> <pre><code>    1: 0x000000002237C6E0 STARTUP HINTS KEY: -Xoptionsfile=jre\\bin\\compressedrefs\\options.default -Xlockword:mode=default -Xjcl:jclse29 -Dcom.ibm.oti.vm.bootstrap.library.path=jre\\bin\\compressedrefs;jre\\bin -Djava.home=jre -Djava.ext.dirs=jre\\lib\\ext -Duser.dir=bin -Djava.class.path=. -Dsun.java.launcher=SUN_STANDARD Address: 0x000000002237C700 Size: 96\n    STARTUP HINTS DETAIL Flags: 1 DATA1: 1677721 DATA2: 5033165\n</code></pre>"},{"location":"shrc_diag_util/#printtoplayerstats","title":"<code>printTopLayerStats</code>","text":"<p>Use this utility with a layered cache. This utility works in the same way as <code>printStats</code>. By default, this utility shows information for the top layer cache. To view statistics for a specific layer, use the <code>layer=&lt;number&gt;</code> option. For example, to show statistics for the second layer in a 2-layer cache, run <code>printTopLayerStats,layer=1</code>.</p> <p>Example output:</p> <pre><code>Current statistics for cache \"Cache1\":\n\nCache created with:\n        -Xnolinenumbers                      = false\n        BCI Enabled                          = true\n        Restrict Classpaths                  = false\n        Feature                              = cr\n\n\nbase address                         = 0x00007F234C054000\nend address                          = 0x00007F234D038000\nallocation pointer                   = 0x00007F234C054000\n\ncache layer                          = 1\ncache size                           = 16776608\nsoftmx bytes                         = 16776608\nfree bytes                           = 15299372\nReserved space for AOT bytes         = -1\nMaximum space for AOT bytes          = -1\nReserved space for JIT data bytes    = -1\nMaximum space for JIT data bytes     = -1\nMetadata bytes                       = 792\nMetadata % used                      = 0%\nClass debug area size                = 1331200\nClass debug area used bytes          = 0\nClass debug area % used              = 0%\n\nROMClass bytes                       = 0\nAOT bytes                            = 30520\nJIT data bytes                       = 644\nZip cache bytes                      = 0\nStartup hint bytes                   = 0\nData bytes                           = 114080\n\n# ROMClasses                         = 0\n# AOT Methods                        = 18\n# Classpaths                         = 0\n# URLs                               = 0\n# Tokens                             = 0\n# Zip caches                         = 0\n# Startup hints                      = 0\n# Stale classes                      = 0\n% Stale classes                      = 0%\n\n\nCache is 8% full\n\nCache is accessible to current user = true\n</code></pre>"},{"location":"shrc_diag_util/#using-the-trace-facility","title":"Using the trace facility","text":"<p>Trace output contains very detailed information that might be used by a VM developer to diagnose complex problems with class data sharing. Trace is configured by using the <code>-Xtrace</code> option and the binary output of the trace facility must be processed by the Trace formatter into a human-readable format.</p> <p>The trace component for class data sharing is <code>j9shr</code>. Five levels of trace are available, starting from basic initialization and runtime information in level 1 up to the most detailed trace output in level 5.</p> <p>To trace memory-mapped files, shared memory, and shared semaphores, include the <code>j9prt</code> trace component.</p> <p>To trace operations with Java Helper API methods, include the <code>j9jcl</code> trace component.</p>"},{"location":"tool_builder/","title":"Option builder","text":""},{"location":"tool_builder/#option-builder-tools","title":"Option builder tools","text":"<p>You can modify many of the command-line options by specifying a number of parameters.</p> <p>Several of the options have many available parameters that you can combine in numerous ways to achieve the effect you want.</p> <p>Tools are available for the following options to help you select these parameters correctly, achieve the correct combinations, and avoid conflicts:</p> <ul> <li> <p>-Xdump</p> </li> <li> <p>-Xtrace</p> </li> </ul>"},{"location":"tool_jcmd/","title":"Java command (jcmd) tool","text":""},{"location":"tool_jcmd/#java-diagnostic-command-jcmd-tool","title":"Java diagnostic command (<code>jcmd</code>) tool","text":"<p>Use the <code>jcmd</code> tool to run diagnostic commands on a specified VM.</p> <p> Note: Running diagnostic commands can significantly affect the performance of the target VM.</p> <p>The command syntax is as follows:</p> <pre><code>jcmd [&lt;options&gt;] [&lt;vmid&gt; &lt;arguments&gt;]\n</code></pre> <p>Where:</p> <ul> <li> <p>The available <code>&lt;options&gt;</code> are:    </p> <ul> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jcmd</code> command. You can use multiple <code>-J</code> options, for example: <code>jcmd -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-h</code>: prints the <code>jcmd</code> help</li> </ul> </li> <li> <p><code>&lt;vmid&gt;</code> is the Attach API virtual machine identifier for the Java\u2122 VM process. This ID is often, but not always, the same as the operating system process ID. One example where the ID might be different is if you specified the system property <code>-Dcom.ibm.tools.attach.id</code> when you started the process. You can use the <code>jps</code> command to find the VMID.</p> </li> <li> <p>The available <code>arguments</code> are:</p> <ul> <li><code>help</code>: shows the diagnostic commands that are available for this VM. This list of commands can vary between VMs.</li> <li><code>help &lt;command&gt;</code>: shows help information for the specified diagnostic command</li> <li><code>&lt;command&gt; [&lt;command_arguments&gt;]</code>: runs the specified diagnostic command, with optional command arguments</li> </ul> </li> </ul> <p>Examples:</p> <pre><code>jcmd 31452 Thread.print\njcmd 31452 help Dump.heap\njcmd 31452 Dump.heap myHeapDump\n</code></pre> <p> Restrictions: This tool is not supported and is subject to change or removal in future releases. Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to Eclipse OpenJ9\u2122. For information about the differences between these two implementations, see Switching to OpenJ9.</p> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations.</li> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jdmpview/","title":"Dump viewer","text":""},{"location":"tool_jdmpview/#dump-viewer-jdmpview","title":"Dump viewer (<code>jdmpview</code>)","text":"<p>The dump viewer is a command-line tool that allows you to examine the contents of system dumps produced from the Eclipse OpenJ9\u2122 VM. The dump viewer allows you to view both Java\u2122 and native information from the time the dump was produced. You can run the dump viewer on one platform to work with dumps from another platform.</p> <p>For long running tasks, the dump viewer can also be run in batch mode.</p> <p>The dump viewer is useful for diagnosing <code>OutOfMemoryError</code> exceptions in Java\u2122 applications. For problems like general protection faults (GPFs), system abends, and SIGSEGVs, a system debugger such as gdb (Linux) provides more information.</p>"},{"location":"tool_jdmpview/#syntax","title":"Syntax","text":""},{"location":"tool_jdmpview/#starting-the-dump-viewer","title":"Starting the dump viewer","text":"<p><code>jdmpview [-J&lt;vm option&gt;] (-core &lt;core file&gt; | -zip &lt;zip file&gt;) [-notemp]</code></p> Input option Explanation <code>-core &lt;core file&gt;</code> Specifies a dump file. <code>-zip &lt;zip file&gt;</code> Specifies a compressed file containing the core file (produced by the dump extractor (<code>jpackcore</code>) tool on AIX\u00ae, Linux\u00ae, and macOS\u00ae systems). <code>-notemp</code> By default, when you specify a file by using the <code>-zip</code> option, the contents are extracted to a temporary directory before processing. Use the <code>-notemp</code> option to prevent this extraction step, and run all subsequent commands in memory. <code>-J-Dcom.ibm.j9ddr.path.mapping=&lt;mappings&gt;</code> The variable <code>&lt;mappings&gt;</code> is a list of native library mappings of the form <code>old-path=new-path</code>, using the usual path separator (a semi-colon (';') on Windows, and a colon (':') on other platforms). <code>-J-Dcom.ibm.j9ddr.library.path=&lt;path&gt;</code> The variable <code>&lt;path&gt;</code> is a list of paths to search for native libraries, using the usual path separator (a semi-colon (';') on Windows, and a colon (':') on other platforms). <p> Note: The <code>-core</code> option can be used with the <code>-zip</code> option to specify the core file in the compressed file. With these options, <code>jdmpview</code> shows multiple contexts, one for each source file that it identified in the compressed file.</p> <p> Note: On AIX and Linux, some <code>jdmpview</code> commands must locate the executable and the native libraries that are referenced by the core. For example, commands that relate to call-sites. A common scenario involves using <code>jdmpview</code> to examine core files that originate on different systems. However, if the executable and the libraries are in their original locations, <code>jdmpview</code> might not consider them. Therefore, first check the executable and the list of native libraries by running <code>jdmpview</code> on a core with the <code>info mod</code> command.</p> <ul> <li> <p>One way to assist <code>jdmpview</code> to locate those files is by specifying on the command line one or both of the path mapping option (<code>-J-Dcom.ibm.j9ddr.path.mapping=&lt;mappings&gt;</code>) and the library path option (<code>-J-Dcom.ibm.j9ddr.library.path=&lt;path&gt;</code>).</p> </li> <li> <p>Alternatively, on the system where the core file was produced, you can use <code>jpackcore</code> to collect all the relevant files into a single zip archive. That archive can be unpacked, possibly on another system, into a new, empty directory. Running <code>jdmpview</code> in that new directory (where the core file will be located) should enable it to find all the data it needs, including information that might not be included in the core file itself, such as symbols or sections. When you use an archive produced by <code>jpackcore</code>, setting the path or library mapping system properties should not be necessary.</p> </li> </ul> <p>On z/OS\u00ae, you can copy the dump to an HFS file and supply that as input to <code>jdmpview</code>, or you can supply a fully qualified MVS\u2122 data set name. For example:</p> <pre><code>&gt; jdmpview -core USER1.JVM.TDUMP.SSHD6.D070430.T092211\nDTFJView version 4.29.5, using DTFJ version 1.12.29003\nLoading image from DTFJ...\n</code></pre> <p>MVS data set names may contain the dollar sign ($). Names that contain a dollar sign must be enclosed by single quotation marks ('). For example:</p> <pre><code>&gt; jdmpview -core 'USER1.JVM.$TDUMP.SSH$D7.D141211.T045506'\n</code></pre> <p>After <code>jdmpview</code> processes the dump files, a session starts, showing this message:</p> <pre><code>For a list of commands, type \"help\"; for how to use \"help\", type \"help help\"\n&gt;\n</code></pre> <p>If you run the <code>jdmpview</code> tool on a compressed file that contains multiple dumps, the tool detects and shows all the dump files, whether these are system dumps, Java dumps, or heap dumps. Because of this behavior, more than one context might be displayed when you start <code>jdmpview</code>. To switch context, type <code>context &lt;n&gt;</code>, where <code>&lt;n&gt;</code> is the context value for the dump you want to investigate.</p> <p>On z/OS, a system dump can contain multiple address spaces and an address space can contain multiple VM instances. In this case, the context allows you to select the address space and VM instance within the dump file. The following z/OS example shows address spaces (<code>ASID</code>), with two JVMs occupying address space <code>0x73</code> (context 5 and 6). The current context is 5 (<code>CTX:5&gt;</code>), shown with an asterisk. To view the JVM in context 6, you can switch by specifying <code>context 6</code>.  </p> <pre><code>CTX:5&gt; context\nAvailable contexts (* = currently selected context) :\n\n0 : ASID: 0x1 : No JRE : No JRE\n1 : ASID: 0x3 : No JRE : No JRE\n2 : ASID: 0x4 : No JRE : No JRE\n3 : ASID: 0x6 : No JRE : No JRE\n4 : ASID: 0x7 : No JRE : No JRE\n*5 : ASID: 0x73 EDB: 0x83d2053a0 : JRE 1.8.0 z/OS s390x-64 build 20181117_128845 (pmz6480-20181120_01)\n6 : ASID: 0x73 EDB: 0x8004053a0 : JRE 1.8.0 z/OS s390x-64 build 20181117_128845 (pmz6480-20181120_01)\n7 : ASID: 0x73 EDB: 0x4a7bd9e8 : No JRE\n8 : ASID: 0xffff : No JRE : No JRE\n</code></pre> <p>If you are using <code>jdmpview</code> to view Java dumps and heap dumps, some options do not produce any output. For example, a heap dump doesn't contain the information requested by the <code>info system</code> command, but does contain information requested by the <code>info class</code> command.</p> <p>If you are viewing a dump where there are a large number of objects on the heap, you can speed up the performance of <code>jdmpview</code> by ensuring that your system has enough memory available and does not need to page memory to disk. To achieve this, start <code>jdmpview</code> with a larger heap size by specifying the <code>-Xmx</code> option. Use the <code>-J</code> option to pass the <code>-Xmx</code> command line option to the JVM. For example:</p> <pre><code>jdmpview -J-Xmx&lt;n&gt; -core &lt;core file&gt;\n</code></pre> <p>The options available to the dump viewer session are shown under Session parameters</p>"},{"location":"tool_jdmpview/#starting-in-batch-mode","title":"Starting in batch mode","text":"<p>For long running or routine jobs, <code>jdmpview</code> can be used in batch mode.</p> <p>You can run a single command without specifying a command file by appending the command to the end of the <code>jdmpview</code> command line. For example:</p> <pre><code>jdmpview -core mycore.dmp info class\n</code></pre> <p>When specifying jdmpview commands that accept a wildcard parameter, you must replace the wildcard symbol with <code>ALL</code> to prevent the shell interpreting the wildcard symbol. For example, in interactive mode, the command <code>info thread *</code> must be specified in the following way:</p> <pre><code>jdmpview -core mycore.dmp info thread ALL\n</code></pre> <p>Batch mode is controlled with the following command line options:</p> Option Explanation -cmdfile &lt;path to command file&gt; A file that contains a series of jdmpview commands, which are read and run sequentially. -charset &lt;character set name&gt; The character set for the commands specified in -cmdfile (name must be a supported charset as defined in java.nio.charset.Charset. For example, US-ASCII) -outfile &lt;path to output file&gt; The file to record any output generated by commands. -overwrite If the file specified in -outfile exists, this option overwrites the file. -append If the file specified in -outfile exists, new output messages are appended to the end of that file. The -append and -overwrite options cannot be used at the same time. <p>The command file can have empty lines that contain spaces, or comment lines that start with // or #. These lines are ignored by jdmpview. Example command file:</p> <pre><code>// commands.txt\ninfo system\ninfo proc\n</code></pre> <p>To run jdmpview in batch mode, using this command file, specify:</p> <pre><code>jdmpview -outfile out.txt [-overwrite|-append] -cmdfile commands.txt -core &lt;path to core file&gt;\n</code></pre> <p>When the output file exists, you need to specify either the <code>-overwrite</code> option or the <code>-append</code> option. If you do not, an error message is generated.</p>"},{"location":"tool_jdmpview/#processing-output","title":"Processing output","text":"<p>You can redirect command output to a file, or pipe the command output to another command.</p> <p>To redirect jdmpview command output to a file, use one of the following formats:</p> <pre><code>command &gt; &lt;target_file&gt;\n</code></pre> <p>If the target file exists, this redirection overwrites the content within it.</p> <pre><code>command &gt;&gt; &lt;target_file&gt;\n</code></pre> <p>If the target file exists, this redirection appends the output to it.</p> <p>Where <code>&lt;target_file&gt;</code> is the file name, which can include the full path to the file.</p> <p>To pipe <code>jdmpview</code> command output to another command, use the vertical bar (|) character. For example:</p> <pre><code>command | grep string\n</code></pre> <p>You can chain more than two commands together by using multiple vertical bar characters.</p> <p>The following commands can be used to interrogate the output:</p> <ul> <li><code>charsFrom</code></li> <li><code>charsTo</code></li> <li><code>grep</code></li> <li><code>tokens</code></li> </ul>"},{"location":"tool_jdmpview/#using-charsfrom","title":"Using <code>CharsFrom</code>","text":"<p>Use the <code>charsFrom</code> command after the vertical bar character to exclude all characters that come before a specified pattern in a resulting line.</p> <pre><code>charsFrom &lt;options&gt; pattern\n</code></pre> <p>Where <code>&lt;options&gt;</code>:</p> <ul> <li><code>-e</code> or <code>-exclude</code> : Exclude the matched pattern from the resulting line. By default, the matched pattern is included in the resulting line.</li> <li><code>-keep</code> : Keep lines that do not contain a match to the pattern. By default, lines that do not contain a match are excluded from the results.</li> <li><code>-i</code> or <code>-ignoreCase</code> : Ignore case.</li> </ul> <p>For example, the following command displays resulting lines that contain the pattern <code>jre</code>, and trims each line to exclude all characters that come before this pattern:</p> <pre><code>&gt; info mod | charsFrom jre\njre/lib/ppc64/libzip.so @ 0x0, sections:\njre/lib/ppc64/libdbgwrapper80.so @ 0x0, sections:\njre/lib/ppc64/libverify.so @ 0x0, sections:\njre/lib/ppc64/libjava.so @ 0x0, sections:\njre/lib/ppc64/compressedrefs/libjclse7b_28.so @ 0x0, sections:\n</code></pre>"},{"location":"tool_jdmpview/#using-charsto","title":"Using <code>CharsTo</code>","text":"<p>Use the <code>CharsTo</code> command after the vertical bar character to include the characters in a resulting line until a specific pattern is found.</p> <pre><code>charsTo &lt;options&gt; pattern\n</code></pre> <p>Where <code>&lt;options&gt;</code>:</p> <ul> <li><code>-include</code> : Include the matched pattern in the resulting line. By default, the matched pattern is excluded from the resulting line.</li> <li><code>-keep</code> : Keep lines that do not contain a match to the pattern. By default, lines that do not contain a match are excluded from the results.</li> <li><code>-i</code> or <code>-ignoreCase</code> : Ignore case.</li> </ul> <p>For example, the following command displays lines that contain the pattern <code>@</code>, and trims each line to exclude all characters from <code>@</code> onwards:</p> <pre><code>&gt; info mod | charsTo @\nbin/java\n/usr/lib64/gconv/UTF-16.so\n/test/sdk/lib/ppc64le/libnet.so\n/test/sdk/lib/ppc64le/libnio.so\n/test/sdk/lib/ppc64le/libzip.so\n/test/sdk/lib/ppc64le/libjsig.so\nlibjsig.so\n</code></pre> <p>You can also use <code>charsFrom</code> and <code>charsTo</code> together, separated by a vertical bar character. For example, the following command displays lines that contain the pattern <code>lib</code>, and trims each line to exclude all characters that come before this pattern, as well as all characters from the pattern <code>@</code> :</p> <pre><code>&gt; info mod | charsFrom lib | charsTo @\nlib/ppc64le/libzip.so\nlib/ppc64le/libjsig.so\nlib/ppc64le/libverify.so\nlib/ppc64le/libjava.so\nlib/ppc64le/compressedrefs/libj9jit29.so\n</code></pre> <p> Note: The line will not be displayed if the <code>charsFrom</code> and <code>charsTo</code> are used together, but only one of the patterns are matched in a line. Furthermore, the line will not be displayed if both patterns are matched in a line, but the <code>charsTo</code> pattern appears before, and not after, the <code>charsFrom</code> pattern.</p>"},{"location":"tool_jdmpview/#using-grep","title":"Using <code>grep</code>","text":"<p>Use the <code>grep</code> command after the vertical bar character to show which lines match a specified pattern.</p> <pre><code>grep &lt;options&gt; pattern\n</code></pre> <p>Where <code>&lt;options&gt;</code>:</p> <ul> <li><code>-i</code> : Ignore case.</li> <li><code>-r</code>, <code>-G</code>, or <code>--regex</code>: Use a regular expression as defined in the Java documentation of the java.utils.regex.Pattern class.</li> <li><code>-b</code> or <code>--block</code> : Show blocks of lines where at least one of the lines matches the pattern. Blocks of lines are separated by empty lines.</li> <li><code>-A</code> &lt;NUM&gt; or +&lt;NUM&gt; : Show at most &lt;NUM&gt; lines after the matching line. For example <code>grep -A 2 &lt;pattern&gt;</code> or <code>grep +2 &lt;pattern&gt;</code>.</li> <li><code>-B</code> &lt;NUM&gt; or -&lt;NUM&gt; : Show at most &lt;NUM&gt; lines before the matching line.</li> <li><code>-C</code> &lt;NUM&gt; or +-&lt;NUM&gt; : Show at most &lt;NUM&gt; lines before and after the matching line.</li> <li><code>-v</code> or <code>--invert-match</code> : Use with the grep command to show lines that do not match the pattern. These options are equivalent to the <code>grep</code> command.</li> <li><code>-F</code> or <code>--fixed-strings</code> : Do not treat the asterisk (*) as a wildcard character. Use these options with the <code>-r</code>, <code>-G</code>, or <code>--regex</code> options.</li> </ul> <p>Pattern rules:</p> <ul> <li>An asterisk (*) in a pattern is treated as a wildcard character unless you specify the <code>-F</code> or <code>--fixed-strings</code> options.</li> <li>If a pattern contains spaces, enclose the pattern in a pair of double quotation marks (\").</li> <li>If a pattern contains double quotation marks, enclose the pattern in a pair of single quotation marks (').</li> <li> <p>You can specify multiple sub-patterns to match by using the following format, but only if you do not use the <code>-r</code>, <code>-G</code>, or <code>--regex</code> options:</p> <p><code>\"[pattern1|pattern2|...|patternN]\"</code> </p> <p>The initial and trailing double quotation marks and brackets ([ ]) are required. Use a vertical bar character to separate the sub-patterns. Quotation marks and the vertical bar are not allowed in a sub-pattern. Spaces are allowed in the middle of a sub-pattern, but leading and trailing spaces will be trimmed.</p> </li> <li> <p>Use the <code>grep</code> command to show lines that do not match the pattern.</p> </li> </ul> <p>In the following example, the command displays the number of instances and total heap size for the <code>java/lang/String</code> class:</p> <pre><code>&gt; info class | grep java/lang/String\n94 7688 [Ljava/lang/String;\n1822 58304 java/lang/String               \n1 16 java/lang/String$CaseInsensitiveComparator              \n0 0 java/lang/String$UnsafeHelpers\n</code></pre> <p>In the following example, the command uses two pipes in combination to display the number of instances and total heap size for the <code>java/lang/StringCoding.StringDecoder</code> class:</p> <pre><code>&gt; info class | grep java/lang/String | grep -i decoder\n1 48 java/lang/StringCoding$StringDecoder\n</code></pre>"},{"location":"tool_jdmpview/#using-tokens","title":"Using <code>tokens</code>","text":"<p>Use the <code>tokens</code> command after the vertical bar character to isolate specified tokens in the resulting lines.</p> <pre><code>tokens [options] range[,range][..range]\n</code></pre> <p>You can define range in the following formats:</p> <ul> <li><code>x</code></li> <li><code>x,y</code></li> <li><code>x..y</code></li> </ul> <p>A set of rules applies to these formats:</p> <ul> <li><code>x</code> or <code>y</code> can be prefixed with <code>-</code>. This means that <code>x</code> or <code>y</code> are counting backwards from the end of a list. For example, a <code>y</code> value of <code>-1</code> represents the last token in a list, while -2 represents the penultimate token in a list.</li> <li><code>x</code> must represent a token that either precedes or is at the same position as <code>y</code>.</li> </ul> <p>In this format, if <code>x</code> is omitted, it is assumed to be <code>1</code>. If <code>y</code> is omitted, it is assumed to be <code>-1</code>.</p> <p>For example, the following command displays the first and second token for each resulting line:</p> <pre><code>&gt; info mmap | grep -r ^0x | tokens 1,2\n0x0000000000012fff 0x000000000000d000\n0x0000000000017fff 0x0000000000004000\n0x00000000009dafff 0x0000000000018000\n0x00000000009fffff 0x000000000001f000\n0x0000000000cbefff 0x0000000000002000\n0x0000000000d76fff 0x0000000000001000\n0x0000000003145fff 0x0000000000071000\n0x0000000003b93fff 0x0000000000003000\n</code></pre>"},{"location":"tool_jdmpview/#session-parameters","title":"Session parameters","text":"<p>When <code>jdmpview</code> is started, many parameters can be used during the session to interrogate the system dump data, which are divided into general and expert parameters. The general parameters are documented in this section. To see a list of expert parameters, use the <code>!j9help</code> option.</p>"},{"location":"tool_jdmpview/#j9help","title":"!j9help","text":"<pre><code>    !j9help\n</code></pre> Lists all expert parameters that can be used in a session, with a brief description. <p> Note: The expert parameters are subject to change and not intended as a supported interface.</p>"},{"location":"tool_jdmpview/#cd","title":"cd","text":"<pre><code>    cd &lt;directory_name&gt;\n</code></pre> Changes the working directory to <code>&lt;directory_name&gt;</code>. The working directory is used for log files. Logging is controlled by the <code>set logging</code> command. Use the <code>pwd</code> command to query the current working directory."},{"location":"tool_jdmpview/#cmdfile","title":"cmdfile","text":"<pre><code>    cmdfile &lt;directory_name&gt;\n</code></pre> Runs all of the commands in a file. The commands are read line by line and run sequentially. Empty lines, and lines that start with // or #, are ignored. Use the option charset to identify the character set that is used in the chosen file. The character set must be supported, as defined in <code>java.nio.charset.Charset</code>, such as <code>US-ASCII</code>."},{"location":"tool_jdmpview/#deadlock","title":"deadlock","text":"<p>This command detects deadlock situations in the Java application that was running when the system dump was produced. Example output:</p> <pre><code>deadlock loop:\nthread: Thread-2 (monitor object: 0x9e32c8) waiting for =&gt;\nthread: Thread-3 (monitor object: 0x9e3300) waiting for =&gt;\nthread: Thread-2 (monitor object: 0x9e32c8)\n</code></pre> <p>In this example, the deadlock analysis shows that <code>Thread-2</code> is waiting for a lock held by <code>Thread-3</code>, which is in turn waiting for a lock held earlier by <code>Thread-2</code>.</p> <p>Threads are identified by their Java thread name, whereas object monitors are identified by the address of the object in the Java heap. You can obtain further information about the threads using the <code>info thread *</code> command. You can obtain further information about the monitors using the <code>x/J &lt;0xaddr&gt;</code> command.</p>"},{"location":"tool_jdmpview/#find","title":"find","text":"<pre><code>    find &lt;pattern&gt;,&lt;start_address&gt;,&lt;end_address&gt;,&lt;memory_boundary&gt;, &lt;bytes_to_print&gt;,&lt;matches_to_display&gt;\n</code></pre> <p>This command searches for <code>&lt;pattern&gt;</code> in the memory segment from <code>&lt;start_address&gt;</code> to <code>&lt;end_address&gt;</code> (both inclusive), and shows the number of matching addresses you specify with <code>&lt;matches_to_display&gt;</code>. You can also display the next <code>&lt;bytes_to_print&gt;</code> bytes for the last match.</p> <p>By default, the <code>find</code> command searches for the pattern at every byte in the range. If you know the pattern is aligned to a particular byte boundary, you can specify <code>&lt;memory_boundary&gt;</code> to search every <code>&lt;memory_boundary&gt;</code> bytes. For example, if you specify a <code>&lt;memory_boundary&gt;</code> of \"4\", the command searches for the pattern every 4 bytes.</p>"},{"location":"tool_jdmpview/#findnext","title":"findnext","text":"Finds the next instance of the last string passed to <code>find</code> or <code>findptr</code>. It repeats the previous <code>find</code> or <code>findptr</code> command, depending on which one was issued last, starting from the last match."},{"location":"tool_jdmpview/#findptr","title":"findptr","text":"<pre><code>    findptr &lt;pattern&gt;,&lt;start_address&gt;,&lt;end_address&gt;,&lt;memory_boundary&gt;,&lt;bytes_to_print&gt;,&lt;matches_to_display&gt;\n</code></pre> <p>Searches memory for the given pointer. <code>findptr</code> searches for <code>&lt;pattern&gt;</code> as a pointer in the memory segment from <code>&lt;start_address&gt;</code> to <code>&lt;end_address&gt;</code> (both inclusive), and shows the number of matching addresses you specify with <code>&lt;matches_to_display&gt;</code>. You can also display the next <code>&lt;bytes_to_print&gt;</code> bytes for the last match.</p> <p>By default, the <code>findptr</code> command searches for the pattern at every byte in the range. If you know the pattern is aligned to a particular byte boundary, you can specify <code>&lt;memory_boundary&gt;</code> to search every <code>&lt;memory_boundary&gt;</code> bytes. For example, if you specify a <code>&lt;memory_boundary&gt;</code> of \"4\", the command searches for the pattern every 4 bytes.</p>"},{"location":"tool_jdmpview/#help","title":"help","text":"<pre><code>    help [&lt;command_name&gt;]\n</code></pre> Shows information for a specific command. If you supply no parameters, help shows the complete list of supported commands."},{"location":"tool_jdmpview/#history","title":"history","text":"<pre><code>    history|his [-r][&lt;N&gt;]\n</code></pre> Recalls and displays the history of commands that you have run. The default behavior is to display the 20 most recent commands. If you use the argument <code>&lt;N&gt;</code>, then N commands are displayed. For example, if you run history 35, then the 35 most recent commands are displayed. You can also use the <code>-r</code> option with <code>&lt;N&gt;</code> to run the Nth most recent command in your history. Using the <code>-r</code> option alone runs the most recent command in your history."},{"location":"tool_jdmpview/#info-thread","title":"info thread","text":"<pre><code>    info thread [*|all|&lt;native_thread_ID&gt;|&lt;zos_TCB_address&gt;]\n</code></pre> <p>Displays information about Java and native threads. The following information is displayed for all threads (\"*\"), or the specified thread:</p> <ul> <li>Thread id</li> <li>Registers</li> <li>Stack sections</li> <li>Thread frames: procedure name and base pointer</li> <li>Thread properties: list of native thread properties and their values. For example: thread priority.</li> <li>Associated Java thread, if applicable:<ul> <li>Name of Java thread</li> <li>Address of associated <code>java.lang.Thread</code> object</li> <li>State (shown in JVMTI and <code>java.lang.Thread.State</code> formats)</li> <li>The monitor the thread is waiting for</li> <li>Thread frames: base pointer, method, and filename:line</li> </ul> </li> </ul> <p>If you supply no parameters, the command shows information about the current thread.</p>"},{"location":"tool_jdmpview/#info-system","title":"info system","text":"<p>Displays the following information about the system that produced the core dump:</p> <ul> <li>Amount of memory</li> <li>Operating system</li> <li>Virtual machine or virtual machines present</li> </ul>"},{"location":"tool_jdmpview/#info-class","title":"info class","text":"<pre><code>    info class [&lt;class_name&gt;] [-sort:&lt;name&gt;|&lt;count&gt;|&lt;size&gt;]\n</code></pre> Displays the inheritance chain and other data for a given class. <p>If a class name is passed to info class, the following information is shown about that class:</p> <ul> <li>Name</li> <li>ID</li> <li>Superclass ID</li> <li>Class loader ID</li> <li>Modifiers</li> <li>Number of instances and total size of instances</li> <li>Inheritance chain</li> <li>Fields with modifiers (and values for static fields)</li> <li>Methods with modifiers</li> </ul> <p>If no parameters are passed to <code>info class</code>, the following information is shown:</p> <ul> <li>The number of instances of each class.</li> <li>The total size of all instances of each class.</li> <li>The class name</li> <li>The total number of instances of all classes.</li> <li>The total size of all objects.</li> </ul> <p>The <code>sort</code> option allows the list of classes to be sorted by name (default), by number of instances of each class, or by the total size of instances of each class.</p>"},{"location":"tool_jdmpview/#info-proc","title":"info proc","text":"<p>Displays threads, command-line arguments, environment variables, and shared modules of the current process.</p> <p>To view the shared modules used by a process, use the <code>info sym</code> command.</p>"},{"location":"tool_jdmpview/#info-jitm","title":"info jitm","text":"<p>Displays JIT compiled methods and their addresses:</p> <ul> <li>Method name and signature</li> <li>Method start address</li> <li>Method end address</li> </ul>"},{"location":"tool_jdmpview/#info-lock","title":"info lock","text":"Displays a list of available monitors and locked objects."},{"location":"tool_jdmpview/#info-sym","title":"info sym","text":"Displays a list of available modules. For each process in the address spaces, this command shows a list of module sections for each module, their start and end addresses, names, and sizes."},{"location":"tool_jdmpview/#info-mmap","title":"info mmap","text":"<pre><code>    info mmap [&lt;address&gt;] [-verbose] [-sort:&lt;size&gt;|&lt;address&gt;]\n</code></pre> Displays a summary list of memory sections in the process address space, with start and end address, size, and properties. If an address parameter is specified, the results show details of only the memory section containing the address. If <code>-verbose</code> is specified, full details of the properties of each memory section are displayed. The <code>-sort</code> option allows the list of memory sections to be sorted by size or by start address (default)."},{"location":"tool_jdmpview/#info-mod","title":"info mod","text":"Displays a list of native library modules in the process address space, which includes file paths and other information about each module."},{"location":"tool_jdmpview/#info-heap","title":"info heap","text":"<pre><code>    info heap [*|&lt;heap_name&gt;*]\n</code></pre> <p>If no parameters are passed to this command, the heap names and heap sections are shown.</p> <p>Using either \"*\" or a heap name shows the following information about all heaps or the specified heap:</p> <ul> <li>Heap name</li> <li>(Heap size and occupancy)</li> <li>Heap sections<ul> <li>Section name</li> <li>Section size</li> <li>Whether the section is shared</li> <li>Whether the section is executable</li> <li>Whether the section is read only</li> </ul> </li> </ul>"},{"location":"tool_jdmpview/#heapdump","title":"heapdump","text":"<pre><code>    heapdump [&lt;heaps&gt;]\n</code></pre> Generates a Java heap dump to a file. You can select which Java heaps to dump by listing the heap names, separated by spaces. To see which heaps are available, use the <code>info heap</code> command. By default, all Java heaps are dumped."},{"location":"tool_jdmpview/#hexdump","title":"hexdump","text":"<pre><code>    hexdump &lt;hex_address&gt; &lt;bytes_to_print&gt;\n</code></pre> Displays a section of memory in a hexdump-like format. Displays <code>&lt;bytes_to_print&gt;</code> bytes of memory contents starting from <code>&lt;hex_address&gt;</code>."},{"location":"tool_jdmpview/#_1","title":"+","text":"Displays the next section of memory in hexdump-like format. This command is used with the hexdump command to enable easy scrolling forwards through memory. The previous hexdump command is repeated, starting from the end of the previous one."},{"location":"tool_jdmpview/#-","title":"-","text":"Displays the previous section of memory in hexdump-like format. This command is used with the hexdump command to enable easy scrolling backwards through memory. The previous hexdump command is repeated, starting from a position before the previous one."},{"location":"tool_jdmpview/#pwd","title":"pwd","text":"Displays the current working directory, which is the directory where log files are stored."},{"location":"tool_jdmpview/#quit","title":"quit","text":"Exits the core file viewing tool; any log files that are currently open are closed before exit."},{"location":"tool_jdmpview/#set-heapdump","title":"set heapdump","text":"Configures Heapdump generation settings.<pre><code>set heapdump &lt;options&gt;\n</code></pre> <p>where <code>&lt;options&gt;</code> are:</p> <ul> <li><code>phd</code>: Set the Heapdump format to Portable Heapdump, which is the default.</li> <li><code>txt</code>: Set the Heapdump format to classic.</li> <li><code>file &lt;file&gt;</code>: Set the destination of the Heapdump.</li> <li><code>multiplefiles [on|off]</code>: If multiplefiles is set to on, each Java heap in the system dump is written to a separate file. If multiplefiles is set to off, all Java heaps are written to the same file. The default is off.</li> </ul>"},{"location":"tool_jdmpview/#set-logging","title":"set logging","text":"<pre><code>    set logging &lt;options&gt;\n</code></pre> <p>Configures logging settings, starts logging, or stops logging. This parameter enables the results of commands to be logged to a file, where <code>&lt;options&gt;</code> are:</p> <ul> <li><code>[on|off]</code>: Turns logging on or off. (Default: off)</li> <li><code>file &lt;filename&gt;</code>: Sets the file to log to. The path is relative to the directory returned by the pwd command, unless an absolute path is specified. If the file is set while logging is on, the change takes effect the next time logging is started. Not set by default.</li> <li><code>overwrite [on|off]</code>: Turns overwriting of the specified log file on or off. When overwrite is off, log messages are appended to the log file. When overwrite is on, the log file is overwritten after the set logging command. (Default: off)</li> <li><code>redirect [on|off]</code>: Turns redirecting to file on or off, with off being the default. When logging is set to on:<ul> <li>A value of on for redirect sends non-error output only to the log file.</li> <li>A value of off for redirect sends non-error output to the console and log file.</li> </ul> </li> </ul> <p>Redirect must be turned off before logging can be turned off. (Default: off)</p>"},{"location":"tool_jdmpview/#show-heapdump","title":"show heapdump","text":"<pre><code>    show heapdump &lt;options&gt;\n</code></pre> Displays the current heap dump generation settings."},{"location":"tool_jdmpview/#show-logging","title":"show logging","text":"<pre><code>    show logging &lt;options&gt;\n</code></pre> <p>Displays the current logging settings:</p> <ul> <li>set_logging = [on|off]</li> <li>set_logging_file =</li> <li>set_logging_overwrite = [on|off]</li> <li>set_logging_redirect = [on|off]</li> <li>current_logging_file =</li> </ul> <p>The file that is currently being logged to might be different from set_logging_file, if that value was changed after logging was started.</p>"},{"location":"tool_jdmpview/#whatis-hex_address","title":"whatis <code>&lt;hex_address&gt;</code>","text":"Displays information about <code>whatis</code> stored at the given memory address, <code>&lt;hex_address&gt;</code>. This command examines the memory location at <code>&lt;hex_address&gt;</code> and tries to find out more information about this address. For example:<pre><code>&gt; whatis 0x8e76a8\n\nheap #1 - name: Default@19fce8\n0x8e76a8 is within heap segment: 8b0000 -- cb0000\n0x8e76a8 is start of an object of type java/lang/Thread\n</code></pre>"},{"location":"tool_jdmpview/#x-examine","title":"x/ (examine)","text":"<p>Passes the number of items to display and the unit size, as listed in the following table, to the sub-command. For example, <code>x/12bd</code>.</p> Abbreviation Unit Size b Byte 8-bit h Half word 16-bit w Word 32-bit g Giant word 64-bit <p>This command is similar to the use of the <code>x/</code> command in gdb, including the use of defaults.</p>"},{"location":"tool_jdmpview/#xj-class_name0xaddr","title":"x/J [<code>&lt;class_name&gt;</code>|<code>&lt;0xaddr&gt;</code>]","text":"<p>Displays information about a particular object, or all objects of a class. If <code>&lt;class_name&gt;</code> is supplied, all static fields with their values are shown, followed by all objects of that class with their fields and values. If an object address (in hex) is supplied, static fields for that object's class are not shown; the other fields and values of that object are printed along with its address.</p> <p> Note: This command ignores the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#xd-0xaddr","title":"x/D &lt;<code>0xaddr</code>&gt;","text":"<p>Displays the integer at the specified address, adjusted for the hardware architecture this dump file is from. For example, the file might be from a big-endian architecture.</p> <p> This command uses the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#xx-0xaddr","title":"x/X &lt;<code>0xaddr</code>&gt;","text":"<p>Displays the hex value of the bytes at the specified address, adjusted for the hardware architecture this dump file is from. For example, the file might be from a big-endian architecture.</p> <p> Note: This command uses the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#xk-0xaddr","title":"x/K &lt;<code>0xaddr</code>&gt;","text":"<p>Where the size is defined by the pointer size of the architecture, this parameter shows the value of each section of memory. The output is adjusted for the hardware architecture this dump file is from, starting at the specified address. It also displays a module with a module section and an offset from the start of that module section in memory if the pointer points to that module section. If no symbol is found, it displays a \"*\" and an offset from the current address if the pointer points to an address in 4KB (4096 bytes) of the current address. Although this command can work on an arbitrary section of memory, it is probably more useful on a section of memory that refers to a stack frame. To find the memory section of a thread stack frame, use the info thread command.</p> <p> Note: This command uses the number of items and unit size passed to it by the <code>x/</code> command.</p>"},{"location":"tool_jdmpview/#example","title":"Example","text":"<p>This example session illustrates a selection of the commands available and their use.</p> <p>In the example session, which is generated on a Linux system, some lines have been removed for clarity (and terseness).</p> <p>User input is prefaced by a greater than symbol (&gt;).</p> <pre><code>    test@madras:~/test&gt; sdk/bin/jdmpview -core core.20121116.154147.16838.0001.dmp\n    DTFJView version 4.29.5, using DTFJ version 1.12.29003\n    Loading image from DTFJ...\n\n    For a list of commands, type \"help\"; for how to use \"help\", type \"help help\"\n    Available contexts (* = currently selected context) :\n\n    Source : file:///home/test/core.20121116.154147.16838.0001.dmp\n            *0 : PID: 16867 : JRE 1.8.0 Linux ppc64-64 build 20121115_128521 (pxp6480-20121116_01 )\n\n    &gt; help\n    +                                              displays the next section of memory in hexdump-like format\n    -                                              displays the previous section of memory in hexdump-like format\n    cd                                             changes the current working directory, used for log files\n    close                     [context id]         closes the connection to a core file\n    context                   [ID|asid ID]         switch to the selected context\n    deadlock                                       displays information about deadlocks if there are any\n    exit                                           Exit the application\n    find                                           searches memory for a given string\n    findnext                                       finds the next instance of the last string passed to \"find\"\n    findptr                                        searches memory for the given pointer\n    heapdump                                       generates a PHD or classic format heapdump\n    help                      [command name]       displays list of commands or help for a specific command\n    hexdump                                        outputs a section of memory in a hexdump-like format\n    info                      &lt;component&gt;          Information about the specified component\n    info class                &lt;Java class name&gt;    Provides information about the specified Java class\n    info heap                 [*|heap name]        Displays information about Java heaps\n    info jitm                                      Displays JIT'ed methods and their addresses\n    info lock                                      outputs a list of system monitors and locked objects\n    info mmap                                      Outputs a list of all memory segments in the address space\n    info mod                                       outputs module information\n    info proc                                      shortened form of info process\n    info process                                   displays threads, command line arguments, environment\n    info sym                                       an alias for 'mod'\n    info sys                                       shortened form of info system\n    info system                                    displays information about the system the core dump is from\n    info thread                                    displays information about Java and native threads\n    log                       [name level]         display and control instances of java.util.logging.Logger\n    open                      [path to core or zip] opens the specified core or zip file\n    plugins                                        Plugin management commands\n                         list                      Show the list of loaded plugins for the current context\n                       reload                      Reload plugins for the current context\n                     showpath                      Show the DTFJ View plugin search path for the current context\n                      setpath                      Set the DTFJ View plugin search path for the current context\n    pwd                                            displays the current working directory\n    quit                                           Exit the application\n    set                       [logging|heapdump]   Sets options for the specified command\n    set heapdump                                   configures heapdump format, filename and multiple heap support\n    set logging                                    configures several logging-related parameters, starts/stops logging\n                           on                      turn on logging\n                          off                      turn off logging\n                         file                      turn on logging\n                    overwrite                      controls the overwriting of log files\n    show                      [logging|heapdump]   Displays the current set options for a command\n    show heapdump                                  displays heapdump settings\n    show logging                                   shows the current logging options\n    whatis                    [hex address]        gives information about what is stored at the given memory address\n    x/d                       &lt;hex address&gt;        displays the integer at the specified address\n    x/j                       &lt;object address&gt; [class name] displays information about a particular object or all objects of a class\n    x/k                       &lt;hex address&gt;        displays the specified memory section as if it were a stack frame parameters\n    x/x                       &lt;hex address&gt;        displays the hex value of the bytes at the specified address\n\n    &gt; set logging file log.txt\n    logging turned on; outputting to \"/home/test/log.txt\"\n\n    &gt; info system\n    Machine OS:     Linux\n    Hypervisor:     PowerVM\n    Machine name:   madras\n    Machine IP address(es):\n                    9.20.88.155\n    System memory:  8269201408\n\n    Dump creation time: 2015/08/10 14:44:36:019\n    Dump creation time (nanoseconds): 21314421467539\n\n    Java version:\n    JRE 1.8.0 Linux ppc64-64 build 20121115_128521 (pxp6490-20121116_01)\n\n    JVM start time: 2015/08/10 14:44:05:690\n    JVM start time (nanoseconds): 21284086192267\n\n    &gt; info thread *\n    native threads for address space\n     process id: 16838\n\n      thread id: 16839\n       registers:\n\n       native stack sections:\n       native stack frames:\n       properties:\n       associated Java thread:\n        name:          main\n        Thread object: java/lang/Thread @ 0x2ffd1e08\n        Priority:      5\n        Thread.State:  RUNNABLE\n        JVMTI state:   ALIVE RUNNABLE\n        Java stack frames:\n         bp: 0x0000000000085b28  method: void com/ibm/jvm/Dump.SystemDumpImpl()  (Native Method)\n          objects: &lt;no objects in this frame&gt;\n         bp: 0x0000000000085b40  method: void com/ibm/jvm/Dump.SystemDump()  source: Dump.java:41\n          objects: &lt;no objects in this frame&gt;\n         bp: 0x0000000000085b68  method: void mySystemDump.main(String[])  source: mySystemDump.java:29\n          objects: &lt;no objects in this frame&gt;\n    ===Lines Removed===\n\n        name:          GC Worker\n        id:            16860\n        Thread object: java/lang/Thread @ 0x3001b980\n        Priority:      5\n        Thread.State:  WAITING\n        JVMTI state:   ALIVE WAITING WAITING_INDEFINITELY IN_OBJECT_WAIT\n          waiting to be notified on: \"MM_ParallelDispatcher::workerThread\" with ID 0x1004cbc8 owner name: &lt;unowned&gt;\n        Java stack frames: &lt;no frames to print&gt;\n\n        name:          GC Worker\n        id:            16861\n        Thread object: java/lang/Thread @ 0x3001c180\n        Priority:      5\n        Thread.State:  WAITING\n        JVMTI state:   ALIVE WAITING WAITING_INDEFINITELY IN_OBJECT_WAIT\n          waiting to be notified on: \"MM_ParallelDispatcher::workerThread\" with ID 0x1004cbc8 owner name: &lt;unowned&gt;\n        Java stack frames: &lt;no frames to print&gt;\n\n        name:          Signal Dispatcher\n        id:            16847\n        Thread object: com/ibm/misc/SignalDispatcher @ 0x3000f268\n        Priority:      5\n        Thread.State:  RUNNABLE\n        JVMTI state:   ALIVE RUNNABLE\n        Java stack frames:\n         bp: 0x00000000000df748  method: int com/ibm/misc/SignalDispatcher.waitForSignal()  (Native Method)\n          objects: &lt;no objects in this frame&gt;\n         bp: 0x00000000000df788  method: void com/ibm/misc/SignalDispatcher.run()  source: SignalDispatcher.java:54\n          objects: 0x30015828 0x30015828\n    ===Lines Removed===\n\n\n    &gt; info heap *\n\n             Heap #1:  Generational@fff78303d30\n              Section #1:  Heap extent at 0x100d0000 (0x300000 bytes)\n               Size:        3145728 bytes\n               Shared:      false\n               Executable:  false\n               Read Only:   false\n              Section #2:  Heap extent at 0x2ffd0000 (0x80000 bytes)\n               Size:        524288 bytes\n               Shared:      false\n               Executable:  false\n               Read Only:   false\n              Section #3:  Heap extent at 0x30050000 (0x80000 bytes)\n               Size:        524288 bytes\n               Shared:      false\n               Executable:  false\n               Read Only:   false\n\n    &gt; info class java/lang/String\n    name = java/lang/String\n\n            ID = 0x37c00    superID = 0x30300\n            classLoader = 0x2ffe9b58    modifiers: public final\n\n            number of instances:     2146\n            total size of instances: 51504 bytes\n\n    Inheritance chain....\n            java/lang/Object\n               java/lang/String\n\n    Fields......\n              static fields for \"java/lang/String\"\n                private static final long serialVersionUID = -6849794470754667710 (0xa0f0a4387a3bb342)\n                public static final java.util.Comparator CASE_INSENSITIVE_ORDER = &lt;object&gt; @ 0x2ffd0278\n                private static final char[] ascii = &lt;object&gt; @ 0x2ffd02c8\n                private static String[] stringArray = &lt;object&gt; @ 0x2ffd0298\n                private static final int stringArraySize = 10 (0xa)\n                static boolean enableCopy = false\n                private static int seed = -126504465 (0xfffffffff875b1ef)\n                private static char[] startCombiningAbove = &lt;object&gt; @ 0x100d0c40\n                private static char[] endCombiningAbove = &lt;object&gt; @ 0x100d0cc0\n                private static final char[] upperValues = &lt;object&gt; @ 0x100d0d40\n                private static final java.io.ObjectStreamField[] serialPersistentFields = &lt;object&gt; @ 0x2ffd0920\n\n              non-static fields for \"java/lang/String\"\n                private final char[] value\n                private final int offset\n                private final int count\n                private int hashCode\n                private int hashCode32\n\n    Methods......\n\n    Bytecode range(s): :  private static native int getSeed()\n    Bytecode range(s): fff76d8ce48 -- fff76d8ce5e:  public void &lt;init&gt;()\n    Bytecode range(s): fff76d8ce88 -- fff76d8cecd:  private void &lt;init&gt;(String, char)\n    Bytecode range(s): fff76d8cf10 -- fff76d8cf19:  public void &lt;init&gt;(byte[])\n    Bytecode range(s): fff76d8cf40 -- fff76d8cf4a:  public void &lt;init&gt;(byte[], int)\n    Bytecode range(s): fff76d8cf7c -- fff76d8cfb5:  public void &lt;init&gt;(byte[], int, int)\n    Bytecode range(s): fff76d8cff8 -- fff76d8d065:  public void &lt;init&gt;(byte[], int, int, int)\n    Bytecode range(s): fff76d8d0c4 -- fff76d8d10c:  public void &lt;init&gt;(byte[], int, int, String)\n    ===Lines Removed===\n\n    &gt; whatis  0x2ffd0298\n            heap #1 - name: Generational@fff78303d30\n                    0x2ffd0298 is within heap segment: 2ffd0000 -- 30050000\n                    0x2ffd0298 is the start of an object of type [Ljava/lang/String;\n</code></pre>"},{"location":"tool_jextract/","title":"Dump extractor","text":""},{"location":"tool_jextract/#dump-extractor-jpackcore","title":"Dump extractor (<code>jpackcore</code>)","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae)</p> <p>On some operating systems, copies of executable files and libraries are required for a full analysis of a core dump (you can get some information from the dump without these files, but not as much). Run the <code>jpackcore</code> utility to collect these extra files and package them into an archive file along with the core dump. To analyze the output, use the dump viewer (<code>jdmpview</code>).</p> <p> Note: This tool replaces OpenJ9 <code>jextract</code>, which is deprecated in Eclipse OpenJ9\u2122 version 0.26.0.</p> <p> The OpenJ9 <code>jextract</code> tool is removed from Java 21 and later. </p>"},{"location":"tool_jextract/#syntax","title":"Syntax","text":"<pre><code>jpackcore [-r] [-x] &lt;core file name&gt; [&lt;zip_file&gt;]\n</code></pre> <p>where:</p> <ul> <li><code>-r</code> forces the <code>jpackcore</code> utility to proceed when the system dump is created from an SDK with a different build ID. See Restriction.</li> <li><code>-x</code> causes the <code>jpackcore</code> utility to omit the system dump itself from the archive produced. In its place, the file <code>excluded-files.txt</code> is added which names the excluded file.</li> <li><code>&lt;core file name&gt;</code> is the name of the system dump.</li> <li><code>&lt;zip_file&gt;</code> is the name you want to give to the processed file. If you do not specify a name, output is written to <code>&lt;core file name&gt;.zip</code> by default. The output is written to the same directory as the core file.</li> </ul> <p> Restriction: You should run <code>jpackcore</code> on the same system that produced the system dump in order to collect the correct executables and libraries referenced in the system dump. You should also run <code>jpackcore</code> using the same VM level, to avoid any problems. From Eclipse OpenJ9 V0.24.0, the utility always checks that the build ID of the SDK that created the dump file matches the <code>jpackcore</code> build ID. Where these IDs do not match, the following exception is thrown:</p> <pre><code>J9RAS.buildID is incorrect (found XXX, expecting YYY). This version of jpackcore is incompatible with this dump (use '-r' option to relax this check).\n</code></pre> <p>To continue, despite the mismatch, use the <code>-r</code> option.</p>"},{"location":"tool_jextract/#see-also","title":"See also","text":"<ul> <li>Dump viewer (<code>jdmpview</code>)</li> </ul>"},{"location":"tool_jmap/","title":"Java memory map (jmap) tool","text":""},{"location":"tool_jmap/#java-memory-map-jmap-tool","title":"Java memory map (<code>jmap</code>) tool","text":"<p>Use the <code>jmap</code> tool to get memory information for a particular Java\u2122 process, or list of processes. The tool shows statistics about classes on the heap, including the number of objects and their aggregate size. The command syntax is as follows:</p> <pre><code>jmap [&lt;option&gt;] [&lt;vmid&gt;]\n</code></pre> <p><code>&lt;vmid&gt;</code> is the Attach API virtual machine identifier for the Java process. This ID is typically the same as the operating system process ID, unless you specified the <code>-Dcom.ibm.tools.attach.id</code> system property when you started the process.</p> <p>VMID is shown in <code>jps</code> or other Attach API-based tools. Multiple VMIDs can be specified, separated by a space.</p> <p>If you do not specify a VMID, the command reads input from <code>stdin</code>. You can therefore get information for all processes by piping the output of the <code>jps</code> command to <code>jmap</code>:</p> <p><code>jps -q | jmap -histo</code></p> <p>IDs of dead processes are silently ignored.</p> <p>On its own, <code>jmap</code> prints help information. To obtain memory information, a <code>-histo</code> argument must be supplied, where the available <code>&lt;options&gt;</code> are as follows:</p> <ul> <li><code>-histo</code>: Prints statistics about classes on the heap, including the number of objects and their aggregate size</li> <li><code>-histo:live</code>: Prints statistics for live objects only</li> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jmap</code> command. You can use multiple <code>-J</code> options, for example: <code>jmap -J-Xms2m -J-Xmx10m</code></li> </ul> <p>The output has the following format:</p> <pre><code>num   object count     total size    class name\n-------------------------------------------------\n  1           3354         107328    [C\n  2            717          57360    java.lang.Class\n  3           2427          38832    java.lang.String\n  4             50          13200    [J\n  5            717          11472    java.lang.J9VMInternals$ClassInitializationLock\n  6            342           8208    java.lang.StringBuilder\n  7            151           7248    jdk.internal.org.objectweb.asm.Item\n  8            396           6336    [Ljava.lang.Object;\n</code></pre> <p> Restrictions: This tool is not supported and is subject to change or removal in future releases. Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to Eclipse OpenJ9\u2122.</p> <p>The following tool limitations apply:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations. You can display information for remote processes by  using <code>ssh user@host jmap &lt;options&gt; &lt;pid&gt;</code>.</li> <li>Displaying data from core dumps is not supported; use <code>jdmpview</code> instead.</li> <li>Other options , such as <code>-F</code> (force a dump of an unresponsive process) can be accomplished using <code>kill -QUIT &lt;pid&gt;</code>.</li> </ul> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jps/","title":"Java process status (jps)","text":""},{"location":"tool_jps/#java-process-status-jps-tool","title":"Java process status (<code>jps</code>) tool","text":"<p>Use the <code>jps</code> tool to query running Java\u2122 processes. The tool shows information for every Java process that is owned by the current user ID on the current host. The command syntax is as follows:</p> <pre><code>jps [&lt;options&gt;]\n</code></pre> <p>where the available <code>&lt;options&gt;</code> are as follows:    </p> <ul> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jps</code> command. You can use multiple <code>-J</code> options, for example: <code>jps -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-l</code>: prints the application package name</li> <li><code>-q</code>: prints only the virtual machine identifiers</li> <li><code>-m</code>: prints the application arguments</li> <li><code>-v</code>: prints the Java VM arguments, including those that are produced automatically</li> </ul> <p>The output has the following format:</p> <pre><code>&lt;VMID&gt; [[&lt;class_name&gt;|&lt;jar_name&gt;|\"Unknown\"] [&lt;application_args&gt;][&lt;vm_args&gt;]]\n</code></pre> <p>where <code>VMID</code> is the Attach API virtual machine identifier for the Java process. This ID is often, but not always, the same as the operating system process ID. One example where the ID might be different is if you specified the system property <code>-Dcom.ibm.tools.attach.id</code> when you started the process.</p> <p>For example:</p> <pre><code>$ jps -l\n5462  org.foo.bar.MyApplication\n14332 openj9.tools.attach.diagnostics.Jps\n\n$ jps -q\n5462\n14332\n</code></pre> <p> Restrictions: This tool is not supported and is subject to change or removal in future releases. Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to Eclipse OpenJ9\u2122.</p> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Does not list Java processes on other hosts, to enhance security</li> <li>Does not list Java processes owned by other users</li> <li>Does not list non-OpenJ9 Java processes</li> <li>Does not list processes whose attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jstack/","title":"Java stack (jstack) tool","text":""},{"location":"tool_jstack/#java-stack-jstack-tool","title":"Java stack (<code>jstack</code>) tool","text":"<p>Use the <code>jstack</code> tool to obtain Java stack traces and thread information for processes. The tool is similar to the HotSpot tool of the same name; the Eclipse OpenJ9\u2122 version of <code>jstack</code> is an independent implementation, added for compatibility.</p> <p>The command syntax is as follows:</p> <pre><code>jstack &lt;options&gt;* &lt;pid&gt;*\n</code></pre> <p>Where <code>&lt;pid&gt;*</code> is a list of process IDs. If none are supplied, the process IDs are read from <code>stdin</code>, which allows a user running a Bourne or equivalent shell to query all processes via <code>jps -q | jstack</code>. IDs of inactive processes are silently ignored. The output contains Java stacks and thread information of the specified processes (equivalent to the information provided in <code>java.lang.management.ThreadInfo</code>).</p> <p>The values for <code>&lt;options&gt;*</code> are as follows:</p> <ul> <li><code>-J</code>: supplies arguments to the Java VM that is running the <code>jstack</code> command. You can use multiple <code>-J</code> options, for example: <code>jstack -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-p</code>: prints the system and agent properties of the process</li> <li><code>-l</code>: prints more verbose output, including information about locks</li> <li><code>-h</code>: prints help information</li> </ul> <p> Restrictions:</p> <ul> <li>This tool is not supported and is subject to change or removal in future releases.</li> <li>Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to OpenJ9. For more information about differences, see Switching to OpenJ9.</li> </ul> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations.</li> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_jstat/","title":"Java statistics monitoring (jstat) tool","text":""},{"location":"tool_jstat/#java-statistics-monitoring-jstat-tool","title":"Java statistics monitoring (<code>jstat</code>) tool","text":"<p>Use the <code>jstat</code> tool to obtain Java Virtual Machine (JVM) statistics. The tool is similar to the HotSpot tool of the same name; the Eclipse OpenJ9\u2122 version of <code>jstat</code> is an independent implementation, added for compatibility.</p> <p>The command syntax is as follows:</p> <pre><code>jstat [&lt;option&gt;] [&lt;vmid&gt;]\n</code></pre> <p>where <code>vmid</code> is the Attach API virtual machine identifier for the Java process. This ID is typically the same as the operating system process ID, unless you specified the -Dcom.ibm.tools.attach.id system property when you started the process.</p> <p>VMID is shown in Java process status (jps) tool or other Attach API-based tools.</p> <p>On its own, <code>jstat</code> prints help information. The values for <code>&lt;option&gt;</code> are as follows:</p> <ul> <li><code>-J</code>: supplies arguments to the JVM that is running the <code>jstat</code> command. You can use multiple <code>-J</code> options, for example: <code>jstat -J-Xmx10m -J-Dcom.ibm.tools.attach.enable=yes</code></li> <li><code>-h</code>: prints help information</li> <li><code>-options</code>: lists the available command options</li> <li><code>-class</code>: displays classloading statistics</li> </ul> <p>The output has the following format:</p> <pre><code>Class Loaded    Class Unloaded\n         860                 0\n</code></pre> <p> Restrictions:</p> <ul> <li>This tool is not supported and is subject to change or removal in future releases.</li> <li>Although similar in usage and output to the HotSpot tool of the same name, this tool is a different implementation that is specific to OpenJ9. For more information about differences, see Switching to OpenJ9.</li> </ul> <p>The tool uses the Attach API, and has the following limitations:</p> <ul> <li>Displays information only for local processes that are owned by the current user, due to security considerations.</li> <li>Displays information for OpenJ9 Java processes only</li> <li>Does not show information for processes whose Attach API is disabled.  Note: The Attach API is disabled by default on z/OS.</li> </ul> <p>For more information about the Attach API, including how to enable and secure it, see Java Attach API.</p>"},{"location":"tool_migration/","title":"Switching to OpenJ9","text":""},{"location":"tool_migration/#switching-to-eclipse-openj9","title":"Switching to Eclipse OpenJ9","text":"<p>Eclipse OpenJ9\u2122 provides the following tools, which might differ in behavior from the HotSpot equivalent.</p> <p> Note: For information about HotSpot equivalences and differences for items other than tools, see New to Eclipse OpenJ9?</p>"},{"location":"tool_migration/#java-diagnostic-command-tool-jcmd","title":"Java diagnostic command tool (<code>jcmd</code>)","text":"<p>Runs diagnostic commands on a specified VM. The main difference from the HotSpot <code>jcmd</code> tool is that the following options are not currently supported:</p> <ul> <li>The <code>-f</code> option to read commands from a file.</li> <li>The <code>Perfcounter.print</code> option for displaying performance counters for the target VM.</li> <li>Selecting VMs by main class instead of VMID.</li> <li>Specifying <code>0</code> as a VMID to target all VMs.</li> </ul>"},{"location":"tool_migration/#java-memory-map-tool-jmap","title":"Java memory map tool (<code>jmap</code>)","text":"<p>Displays information about classes on the heap, including the number of objects and their aggregate size. The main differences from the HotSpot <code>jmap</code> tool are as follows:</p> <ul> <li>Uses the Attach API.</li> <li>Displays information only for local processes that are owned by the current user, due to security considerations. You can display information for remote processes by using <code>ssh user@host jmap &lt;option&gt; &lt;vmid&gt;</code>, where <code>&lt;vmid&gt;</code> is the Attach API virtual machine identifier for the Java\u2122 process.</li> <li>Does not support displaying data from core dumps; use Dump viewer instead.</li> <li>Does not include a <code>-F</code> option to force a dump of an unresponsive process. User <code>kill -QUIT &lt;pid&gt;</code> instead, where <code>&lt;pid&gt;</code> is the process identifier.</li> </ul> <p>For more information, see <code>jmap</code>.</p>"},{"location":"tool_migration/#java-process-status-jps","title":"Java process status (<code>jps</code>)","text":"<p>Displays information about running Java processes. The main differences from the HotSpot <code>jps</code> tool are as follows:</p> <ul> <li>Runs on Windows\u00ae, AIX\u00ae, and z/OS\u00ae, as well as Linux\u00ae.</li> <li>Uses the Attach API.</li> <li>Shows processes on the current host only.</li> <li>There is no <code>-V</code> option.</li> </ul> <p>For more information, see <code>Java process status</code>.</p>"},{"location":"tool_migration/#java-stack-jstack-tool","title":"Java stack (<code>jstack</code>) tool","text":"<p>Displays information about Java stack traces and thread information for processes. The main differences from the HotSpot <code>jstack</code> tool are as follows:</p> <ul> <li>In the interests of security, the OpenJ9 implementation of <code>jstack</code> prints only information about local processes that are owned by the current user.</li> <li>Printing data for core dumps is not supported. Use the Dump viewer instead.</li> <li>There is no <code>-m</code> option. Printing data for native stack frames is not supported.</li> <li>There is no <code>-F</code> option to force a dump, although this might be accomplished using <code>kill -QUIT &lt;pid&gt;</code> on some platforms.</li> </ul> <p>For more information, see <code>jstack</code>.</p>"},{"location":"tool_migration/#java-statistics-monitoring-jstat-tool","title":"Java statistics monitoring (<code>jstat</code>) tool","text":"<p>Displays information about Java statistics for processes. The main difference from the HotSpot <code>jstat</code> tool is that this tool only provides the number of classes loaded and the number of class unloaded.</p> <p>For more information, see <code>jstat</code>.</p>"},{"location":"tool_traceformat/","title":"Trace formatter","text":""},{"location":"tool_traceformat/#trace-formatter-traceformat","title":"Trace formatter (<code>traceformat</code>)","text":"<p>The trace formatter is a Java\u2122 program that converts binary trace point data in a trace file to a readable form. The formatter requires the <code>TraceFormat.dat</code> and <code>J9TraceFormat.dat</code> files, which contain the formatting templates. The formatter produces a file that contains header information about the VM that produced the binary trace file, a list of threads for which trace points were produced, and the formatted trace points with their time stamp, thread ID, trace point ID, and trace point data.</p>"},{"location":"tool_traceformat/#syntax","title":"Syntax","text":"<p>To use the trace formatter on a binary trace file type:</p> <pre><code>    traceformat &lt;input_file&gt;  [&lt;output_file&gt;] &lt;parameters&gt;\n</code></pre> <p>Where <code>&lt;input_file&gt;</code> is the name of the binary trace file to be formatted, and <code>&lt;output_file&gt;</code> is the name of the output file. If you do not specify an output file, the output file is called <code>input_file.fmt</code>.</p> <p>The size of the heap that is needed to format the trace is directly proportional to the number of threads present in the trace file. For large numbers of threads the formatter might run out of memory, generating the error <code>OutOfMemoryError</code>. In this case, increase the heap size by using the <code>-Xmx</code> option.</p>"},{"location":"tool_traceformat/#parameters","title":"Parameters","text":"<p>The following <code>&lt;parameters&gt;</code> are available with the trace formatter:</p> Option Explanation <code>-datfile=&lt;file1.dat&gt;[,&lt;file2.dat&gt;]</code> A comma-separated list of trace formatting data files. By default, the following files are used:$JAVA_HOME/lib/J9TraceFormat.dat and $JAVA_HOME/lib/TraceFormat.dat <code>-format_time=yes|no</code> Specifies whether to format the time stamps into human readable form. The default is <code>yes</code>. <code>-help</code> Displays usage information. <code>-indent</code> Indents trace messages at each <code>Entry</code> trace point and outdents trace messages at each <code>Exit</code> trace point. The default is not to indent the messages. <code>-summary</code> Prints summary information to the screen without generating an output file. <code>-threads=&lt;thread id&gt;[,&lt;thread id&gt;]...</code> Filters the output for the given thread IDs only. thread id is the ID of the thread, which can be specified in decimal or hex (0x) format. Any number of thread IDs can be specified, separated by commas. <code>-timezone=+|-HH:MM</code> Specifies the offset from UTC, as positive or negative hours and minutes, to apply when formatting time stamps. <code>-verbose</code> Output detailed warning and error messages, and performance statistics."},{"location":"tool_traceformat/#examples","title":"Examples","text":"<p>The following example shows output from running the trace formatter command:</p> <pre><code>    C:\\test&gt;traceformat sample.trc\n    Writing formatted trace output to file sample.trc.fmt\n    Processing 0.4921875Mb of binary trace data\n    Completed processing of 6983 tracepoints with 0 warnings and 0 errors\n</code></pre> <p>The formatted trace output looks similar to the following extract, which is truncated to show the key areas of information:</p> <pre><code>    Trace Summary\n\n    Service level:\n    JRE 1.8.0 Windows 7 amd64-64 build  (pwa6480sr2-20150624_06(SR2))\n\n    JVM startup options:\n    -Xoptionsfile=c:\\build\\pwa6480sr2-20150624\\sdk\\lib\\compressedrefs\\options.default\n    ....\n\n    Processor information:\n    Arch family:         AMD64\n    Processor Sub-type:  Opteron\n    Num Processors:      8\n    Word size:           64\n\n    Trace activation information::\n    FORMAT=c:\\build\\pwa6480sr2-20150624\\sdk\\lib;.\n    MAXIMAL=all{level1}\n    EXCEPTION=j9mm{gclogger}\n    MAXIMAL=all{level2}\n    output=sample\n\n    Trace file header:\n    JVM start time: 08:58:35.527000000\n    Generations:    1\n    Pointer size:   8\n\n    Active threads\n    ....\n    0x000000000f155f00  Attach API wait loop\n    0x000000000f18b200  Thread-1\n    0x000000000f190200  Thread-3\n\n\n     Trace Formatted Data\n\n    Time (UTC)          Thread ID          Tracepoint ID Type   Tracepoint Data\n    08:58:35.527291919 *0x000000000f010500 j9trc.0       Event  Trace engine initialized for VM = 0x3ad4d0\n    08:58:35.527349836  0x000000000f010500 j9prt.0       Event  Trace engine initialized for module j9port\n    08:58:35.527354040  0x000000000f010500 j9thr.0       Event  Trace engine initialized for module j9thr\n    08:58:35.529409621 *0x000000000f01eb00 j9trc.5       Event  Thread started VMthread = 0xf01eb00, name = (unnamed thread), nativeID = 0x24a798\n    ....\n    08:58:35.536134516  0x000000000f010500 j9vm.1        Entry &gt;Create RAM class from ROM class 0x3cab680 in class loader 0x3042338\n    08:58:35.536136384  0x000000000f010500 j9vm.80       Event  ROM class 0x3cab680 is named java/lang/Object\n    08:58:35.536200373  0x000000000f010500 j9vm.2        Exit  &lt;Created RAM class 0xf03ef00 from ROM class 0x3cab680\n</code></pre>"},{"location":"version0.10/","title":"Version 0.10.0","text":""},{"location":"version0.10/#whats-new-in-version-0100","title":"What's new in version 0.10.0","text":"<p>The following new features and notable changes since v.0.9.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments.</li> <li>Change to the default shared classes cache size for OpenJDK 8 builds</li> <li>New information for the SHARED CLASSES section of a Javadump file</li> <li>Support for OpenJDK HotSpot options</li> <li> New JDK 11 features</li> </ul>"},{"location":"version0.10/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.10/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.10.0 supports OpenJDK 11, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 11</li> </ul> <p>OpenJDK 11 with Eclipse OpenJ9 is a long term support (LTS) release and supersedes OpenJDK 10 with Eclipse OpenJ9.</p> <p>Although it is possible to build an OpenJDK v8 with the OpenJ9 0.10.0 release level, testing at the project is not complete and therefore support is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments</p>"},{"location":"version0.10/#change-to-the-default-shared-classes-cache-size","title":"Change to the default shared classes cache size","text":"<p>For OpenJDK 8 builds, the default shared classes cache size is increased from 16 MB to 300 MB, with a \"soft\" maximum limit for the initial size of the cache set to 64 MB. Certain exceptions apply. For more information, see -Xshareclasses. The new default also applies to OpenJDK 11 builds.</p>"},{"location":"version0.10/#new-information-for-the-shared-classes-section-of-a-java-dump-file","title":"New information for the SHARED CLASSES section of a Java dump file","text":"<p>The value of the soft maximum size (<code>-Xscmx</code>) of the shared classes cache is now recorded in the <code>SHARED CLASSES</code> section of a Java dump file against the string <code>2SCLTEXTSMB</code>. For example output, see Java dump.</p>"},{"location":"version0.10/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li>-XX:HeapDumpPath</li> <li>-XX:[+|-]HeapDumpOnOutOfMemory</li> <li>-XX:ActiveProcessorCount</li> </ul>"},{"location":"version0.10/#new-jdk-11-features","title":"New JDK 11 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 181: Nest-Based Access Control</li> <li>JEP 309: Dynamic Class-File Constants</li> <li>JEP 320: Remove the Java EE and CORBA Modules</li> <li>JEP 321: HTTP Client (Standard)</li> <li>JEP 323: Local-Variable Syntax for Lambda Parameters</li> <li>JEP 324: Key Agreement with Curve25519 and Curve448</li> <li>JEP 329: ChaCha20 and Poly1305 Cryptographic Algorithms</li> <li>JEP 330: Launch Single-File Source-Code Programs</li> <li>JEP 332: Transport Layer Security (TLS) 1.3</li> <li>JEP 335: Deprecate the Nashorn JavaScript Engine</li> <li>JEP 336: Deprecate the Pack200 Tools and API</li> </ul> <p>You can find the full list of features for JDK 11 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.10/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.9.0 and version 0.10.0 releases, see the Release notes.</p>"},{"location":"version0.11/","title":"Version 0.11.0","text":""},{"location":"version0.11/#whats-new-in-version-0110","title":"What's new in version 0.11.0","text":"<p>The following new features and notable changes since version 0.10.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments.</li> <li> OpenSSL is now supported for improved native cryptographic performance</li> <li> Changes to the location of the default shared cache and cache snapshot directory</li> <li>New class data sharing suboptions</li> <li>Container awareness in the Eclipse OpenJ9\u2122 VM is now enabled by default</li> <li>Pause-less garbage collection mode is now available on Linux x86 platforms</li> <li>You can now restrict identity hash codes to non-negative values</li> <li>Support for OpenJDK HotSpot options</li> </ul>"},{"location":"version0.11/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.11/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9 release 0.11.0 provides limited support for the macOS\u00ae platform on OpenJDK 11. Early builds of OpenJDK 11 with OpenJ9 on macOS are available at the AdoptOpenJDK project at the following link:</p> <ul> <li>OpenJDK version 11</li> </ul> <p>Support for macOS on OpenJDK 8 is coming soon.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments</p>"},{"location":"version0.11/#openssl-is-now-supported-for-improved-native-cryptographic-performance","title":"OpenSSL is now supported for improved native cryptographic performance","text":"<p>OpenSSL is a native open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which provides improved cryptographic performance compared to the in-built OpenJDK Java cryptographic implementation. The OpenSSL V1.1.x implementation is enabled by default and  supported for the Digest, CBC, and GCM algorithms. Binaries obtained from AdoptOpenJDK include OpenSSL v1.1.x (see Note). For more information about tuning the OpenSSL implementation, see Performance tuning.</p> <p> Note: Currently, OpenSSL is not bundled as part of the AdoptOpenJDK AIX binary due to an unresolved problem.</p> <p></p>"},{"location":"version0.11/#changes-to-the-location-of-the-default-shared-cache-and-cache-snapshot-directory","title":"Changes to the location of the default shared cache and cache snapshot directory","text":"<p>To increase security, the default shared classes cache directory is changed on non-Windows platforms from <code>/tmp/javasharedresources/</code> to the user's home directory, unless you specify <code>-Xshareclasses:groupAccess</code>. If you use the <code>groupAccess</code> suboption, the default directory is unchanged because some members of the group might not have access to the user home directory.</p> <p> Note: For persistent caches, the shared classes cache directory cannot be on an NFS mount. If your user home directory is on an NFS mount, either move it or use the <code>-Xshareclasses:cacheDir=&lt;directory&gt;</code> suboption to specify a different directory for the cache.</p> <p>In general, caches cannot be shared across different Java releases, so you cannot re-use a cache that was created by a previous level of Java 11; if you use the name and cacheDir suboptions to specify an existing cache, the VM attempts to delete the cache and create a new one. However, on Windows, the cache cannot be deleted if it is in use, in which case the VM continues to use the existing cache.</p> <p>You can find and remove old caches or snapshots by using the following command-line options:</p> <p>For persistent caches: - <code>-Xshareclasses:cacheDir=/tmp/javasharedresources/,listAllCaches</code> to find the cache - <code>-Xshareclasses:cacheDir=/tmp/javasharedresources/,name=&lt;cacheName&gt;,destroy</code> to remove the cache</p> <p>For nonpersistent caches or snapshots: - <code>-Xshareclasses:cacheDir=/tmp,listAllCaches</code> to find the item - <code>-Xshareclasses:cacheDir=/tmp,name=&lt;snapshotName&gt;,destroySnapshot</code> to remove the item</p> <p></p>"},{"location":"version0.11/#new-class-data-sharing-suboptions","title":"New class data sharing suboptions","text":"<p><code>-Xshareclasses:bootClassesOnly</code>: disables caching of classes that are loaded by non-bootstrap class loaders. This suboption also enables the <code>nonfatal</code> suboption, which allows the VM to start even if there was an error creating the shared classes cache.</p> <p><code>-Xshareclasses:fatal</code>: prevents the VM from starting if there was an error creating the shared classes cache. You might want to enable this suboption when using the -Xshareclasses:bootClassesOnly suboption, to troubleshoot problems when creating the cache.</p>"},{"location":"version0.11/#container-awareness-in-the-openj9-vm-is-now-enabled-by-default","title":"Container awareness in the OpenJ9 VM is now enabled by default","text":"<p>When using container technology, applications are typically run on their own and do not need to compete for memory. If the VM detects that it is running in a container environment, and a memory limit for the container is set, the VM automatically adjusts the maximum default Java heap size.</p> <p>In earlier releases, this behavior was enabled by setting the <code>-XX:+UseContainerSupport</code> option. This setting is now the default. For more information about the Java heap size set for a container, see -XX:[+|-]UseContainerSupport.</p>"},{"location":"version0.11/#pause-less-garbage-collection-mode-is-now-available-on-linux-x86-platforms","title":"Pause-less garbage collection mode is now available on Linux x86 platforms","text":"<p>Pause-less garbage collection mode is aimed at large heap, response-time sensitive applications. When enabled, the VM attempts to reduce GC pause times. In earlier releases, pause-less garbage collection mode (<code>-Xgc:concurrentScavenge</code>) was available only on IBM z14 hardware. This mode is now available on 64-bit x86 Linux platforms.</p> <p> Restrictions:</p> <ul> <li>The Generational Concurrent (<code>gencon</code>) garbage collection policy must be used. (This is the default policy.)</li> <li>Compressed references must be used. See <code>-Xcompressedrefs</code>. Compressed references are enabled by default when the maximum heap size (<code>-Xmx</code>) \u2264 57 GB. The concurrent scavenge option is ignored if the maximum heap size is &gt; 57 GB.</li> </ul>"},{"location":"version0.11/#you-can-now-restrict-identity-hash-codes-to-non-negative-values","title":"You can now restrict identity hash codes to non-negative values","text":"<p>OpenJ9 allows both positive and negative identity hashcodes, which can be problematic if your program (incorrectly) assumes hashcodes can only be positive. However, you can now use the -XX:[+|-]PositiveIdentityHash option to limit identity hash codes to non-negative values.</p>"},{"location":"version0.11/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li>-XX:MaxHeapSize</li> <li>-XX:InitialHeapSize</li> </ul>"},{"location":"version0.11/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.10.0 and version 0.11.0 releases, see the Release notes.</p>"},{"location":"version0.12/","title":"Version 0.12.0","text":""},{"location":"version0.12/#whats-new-in-version-012x","title":"What's new in version 0.12.x","text":""},{"location":"version0.12/#version-0120","title":"Version 0.12.0","text":"<p>The following new features and notable changes since version 0.11.0 are included in this release:</p> <ul> <li>Improved flexibility for managing the size of the JIT code cache</li> </ul> <ul> <li>Idle-tuning is enabled by default when Eclipse OpenJ9\u2122 runs in a docker container</li> <li>Changes to default shared classes cache directory permissions (not Windows)</li> <li> OpenSSL is now supported for improved native cryptographic performance</li> <li>Improved support for pause-less garbage collection</li> <li>RSA algorithm support for OpenSSL</li> <li><code>IBM_JAVA_OPTIONS</code> is deprecated</li> </ul> <p> Warning: Following the release of OpenJ9 0.12.0, an intermittent problem was identified with OpenSSL V1.1.x acceleration of the cryptographic Digest algorithm. For more information about the issue, see #4530. You can turn off the Digest algorithm by setting the -Djdk.nativeDigest system property to <code>false</code>. A new release of OpenJ9 (0.12.1) is available that disables the Digest algorithm by default.</p>"},{"location":"version0.12/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.12/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9 release 0.12.0 provides support for OpenJDK 8 with OpenJ9 and OpenJDK 11 with OpenJ9. In this release support is extended to the 64-bit macOS\u00ae platform on OpenJDK with OpenJ9.</p> <p>Builds for all platforms are available from the AdoptOpenJDK project at the following links:</p> <ul> <li>OpenJDK 8 with OpenJ9</li> <li>OpenJDK 11 with OpenJ9</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.12/#improved-flexibility-for-managing-the-size-of-the-jit-code-cache","title":"Improved flexibility for managing the size of the JIT code cache","text":"<p>The JIT code cache stores the native code of compiled Java\u2122 methods. By default, the size of the code cache is 256 MB for a 64-bit VM and 64 MB for a 31/32-bit VM. In earlier releases the size of the code cache could be increased from the default value by using the <code>-Xcodecachetotal</code> command line option. In this release the size can also be decreased by using this option, with a minimum size of 2 MB. The size of the JIT code cache also affects the size of the JIT data cache, which holds metadata about compiled methods. If you use the <code>-Xcodecachetotal</code> option to manage the size of the code cache, the size of the data cache is adjusted by the same proportion. For more information, see <code>-Xcodecachetotal</code>.</p>"},{"location":"version0.12/#idle-tuning-is-enabled-by-default-when-openj9-runs-in-a-docker-container","title":"Idle-tuning is enabled by default when OpenJ9 runs in a docker container","text":"<p>In an earlier release, a set of idle-tuning options were introduced to manage the footprint of the Java heap when the OpenJ9 VM is in an idle state. These options could be set manually on the command line. In this release, the following two options are enabled by default when OpenJ9 is running in a container:</p> <ul> <li><code>-XX:[+|-]IdleTuningGcOnIdle</code>, which runs a garbage collection cycle and releases free memory pages back to the operating system when the VM state is set to idle.</li> <li><code>-XX:[+|-]IdleTuningCompactOnIdle</code>, which compacts the object heap to reduce fragmentation when the VM state is set to idle.</li> </ul> <p>By default, the VM must be idle for 180 seconds before the status is set to idle. To control the wait time before an idle state is set, use the <code>-XX:IdleTuningMinIdleWaitTime</code> option. To turn off idle detection, set the value to <code>0</code>.</p>"},{"location":"version0.12/#changes-to-default-shared-classes-cache-directory-permissions-not-windows","title":"Changes to default shared classes cache directory permissions (not Windows)","text":"<p>If you do not use the <code>cachDirPerm</code> suboption to specify permissions for a shared classes cache directory, and the cache directory is not the <code>/tmp/javasharedresources</code> default, the following changes apply:</p> <ul> <li>When creating a new cache directory, the default permissions are now stricter.</li> <li>If the cache directory already exists, permissions are now unchanged (previously, when a cache was opened using this directory, the permissions would be set to 0777).</li> </ul> <p>For more information, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.12/#openssl-is-now-supported-for-improved-native-cryptographic-performance","title":"OpenSSL is now supported for improved native cryptographic performance","text":"<p>OpenSSL is a native open source cryptographic toolkit for Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols, which provides improved cryptographic performance compared to the in-built OpenJDK Java cryptographic implementation. The OpenSSL V1.1.x implementation is enabled by default and  supported for the Digest, CBC, and GCM algorithms. Binaries obtained from AdoptOpenJDK include OpenSSL v1.1.x (see Note). For more information about tuning the OpenSSL implementation, see Performance tuning.</p> <p> Note: OpenJDK 8 with OpenJ9 includes OpenSSL support since version 0.11.0. Currently, OpenSSL is not bundled as part of the AdoptOpenJDK AIX binaries due to an unresolved problem.</p> <p></p>"},{"location":"version0.12/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Concurrent scavenge mode is now supported on 64-bit Windows operating systems.</p> <p>In Eclipse OpenJ9 version 0.11.0, support was added for <code>-Xgc:concurrentScavenge</code> on Linux x86-64 virtual machines that use compressed references. In this release, support is now available for Linux x86-64 large-heap virtual machines (non-compressed references).</p> <p>For more information, see the <code>-Xgc:concurrentScavenge</code> option.</p>"},{"location":"version0.12/#rsa-algorithm-support-for-openssl","title":"RSA algorithm support for OpenSSL","text":"<p>OpenSSL v1.1 support for the RSA algorithm is added in this release, providing improved cryptographic performance. OpenSSL support is enabled by default. If you want to turn off support for the RSA algorithm, set the <code>-Djdk.nativeRSA</code> system property to <code>false</code>.</p>"},{"location":"version0.12/#ibm_java_options-is-deprecated","title":"<code>IBM_JAVA_OPTIONS</code> is deprecated","text":"<p>The VM environment variable <code>IBM_JAVA_OPTIONS</code> is deprecated and is replaced by <code>OPENJ9_JAVA_OPTIONS</code>. <code>IBM_JAVA_OPTIONS</code> will be removed in a future release. For more information about the use of this variable, see the general options in Environment variables.</p>"},{"location":"version0.12/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.11.0 and version 0.12.0 releases, see the Release notes.</p>"},{"location":"version0.12/#version-0121","title":"Version 0.12.1","text":"<p>The following change is implemented since version 0.12.0:</p> <p>By default, OpenJ9 provides native cryptographic acceleration using OpenSSL version 1.1.x for the Digest, CBC, GCM, and RSA algorithms. Under certain circumstances acceleration of the Digest algorithm was found to cause a segmentation error. Cryptographic acceleration of the Digest algorithm is now turned off by default. The system property <code>-Djdk.nativeDigest</code> cannot be used to turn on support. This property is ignored by the VM.</p>"},{"location":"version0.12/#full-release-information_1","title":"Full release information","text":"<p>Release notes to describe the changes between Eclipse OpenJ9 version 0.12.0 and version 0.12.1 releases, can be found in the OpenJ9 GitHub repository.</p>"},{"location":"version0.13/","title":"Version 0.13.0","text":""},{"location":"version0.13/#whats-new-in-version-0130","title":"What's new in version 0.13.0","text":"<p>The following new features and notable changes since version 0.12.1 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> Support for OpenSSL 1.0.2</li> <li> New Java\u2122 process status tool</li> <li>Writing a Java dump to STDOUT or STDERR</li> <li>Better diagnostic information for Linux systems that implement control groups</li> <li>Improved support for pause-less garbage collection</li> <li> New JDK 12 features</li> </ul>"},{"location":"version0.13/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.13/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.13.0 supports OpenJDK 12, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 12</li> </ul> <p>OpenJDK 12 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.12.0. Features mentioned in these release notes are not available in these builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.13.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.13/#support-for-openssl-102","title":"Support for OpenSSL 1.0.2","text":"<p>OpenSSL cryptographic support is extended to include OpenSSL 1.0.2 for the Digest, CBC, GCM, and RSA algorithms. Support is enabled by default. On Linux and AIX platforms, the OpenSSL libraries are expected to be available on the system path. For more information about cryptographic acceleration with OpenSSL, see Cryptographic operations.</p> <p>In addition, support for the OpenSSL Digest algorithm is re-enabled in this release following the resolution of issue #4530.</p> <p> Warning: Earlier versions of OpenJDK with OpenJ9 from the AdoptOpenJDK project bundle OpenSSL as part of the binary package. On Linux and AIX systems, OpenSSL is no longer bundled and the libraries are expected to be available on the system path.</p> <p></p>"},{"location":"version0.13/#new-java-process-status-tool","title":"New Java process status tool","text":"<p>A Java process status tool (<code>jps</code>) is available for querying running Java processes. For more information, see Java process status.</p> <p></p>"},{"location":"version0.13/#writing-a-java-dump-to-stdout-or-stderr","title":"Writing a Java dump to STDOUT or STDERR","text":"<p>You can now write a Java dump file to STDOUT or STDERR by using the <code>-Xdump</code> command-line option. See Writing to <code>STDOUT</code>/<code>STDERR</code> for details.</p>"},{"location":"version0.13/#better-diagnostic-information-for-linux-systems-that-implement-control-groups","title":"Better diagnostic information for Linux systems that implement control groups","text":"<p>If you use control groups (cgroups) to manage resources on Linux systems, information about CPU and memory limits is now recorded in a Java dump file. This information is particularly important for applications that run in Docker containers, because when resource limits are set inside a container, the Docker Engine relies on cgroups to enforce the settings. If you are getting a Java <code>OutOfMemoryError</code> error because a container limit has been set on the amount of memory available to an application and this allocation is not sufficient, you can diagnose this problem from the Java dump file. You can find the cgroup information in the ENVINFO section. For sample output, see Java dump (ENVINFO).</p>"},{"location":"version0.13/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Concurrent scavenge mode is now supported on the following platforms:</p> <ul> <li>Linux on POWER LE</li> <li>AIX</li> </ul> <p>For more information, see the <code>-Xgc:concurrentScavenge</code> option.</p>"},{"location":"version0.13/#new-jdk-12-features","title":"New JDK 12 features","text":"<p>The following feature is supported by OpenJ9:</p> <ul> <li>JEP 334: JVM Constants API</li> </ul> <p>The following feature is implemented in OpenJDK and available in any builds of OpenJDK 12 with OpenJ9:</p> <ul> <li>JEP 325: Switch Expressions (Preview) </li> </ul> <p>You can find the full list of features for JDK 12 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.13/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.12.1 and version 0.13.0 releases, see the Release notes.</p>"},{"location":"version0.14/","title":"Version 0.14.0","text":""},{"location":"version0.14/#whats-new-in-version-014x","title":"What's new in version 0.14.x","text":""},{"location":"version0.14/#version-0140","title":"Version 0.14.0","text":"<p>The following new features and notable changes since version 0.13.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Support for OpenSSL 1.0.2</li> <li>New option for ignoring or reporting unrecognized -XX: options</li> <li>Improved support for pause-less garbage collection</li> <li>New Java stack (<code>jstack</code>) tool for obtaining stack traces and thread information</li> <li>New Java process status (<code>jps</code>) tool</li> <li>New experimental option to improve the performance of JVMTI watched fields</li> <li>New option to prevent a network query being used to determine host name and IP address</li> <li>Changes to the shared classes cache generation number</li> <li>Change to the default native stack size on 64-bit z/OS\u00ae</li> </ul>"},{"location":"version0.14/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.14/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.14.0 supports OpenJDK 8, 11, and 12. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 12</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.14/#support-for-openssl-102","title":"Support for OpenSSL 1.0.2","text":"<p>OpenJ9 release 0.13.0 introduced support for OpenSSL 1.0.2 for Java 12. In this release, support is extended to Java 8 and Java 11. OpenSSL is enabled by default for the CBC, Digest, GCM, and RSA cryptographic algorithms. On Linux\u00ae and AIX\u00ae platforms, the OpenSSL libraries are expected to be available on the system path. For more information about cryptographic acceleration with OpenSSL, see Cryptographic operations.</p> <p> Note: Support for the OpenSSL Digest algorithm on Java 8 and 11 is re-enabled in this release following the resolution of issue #4530.</p> <p> Warning: Earlier versions of OpenJDK with OpenJ9 from the AdoptOpenJDK project bundle OpenSSL as part of the binary package. On Linux and AIX systems, OpenSSL is no longer bundled and the libraries are expected to be available on the system path.</p>"},{"location":"version0.14/#new-option-for-ignoring-or-reporting-unrecognized-xx-options","title":"New option for ignoring or reporting unrecognized -XX: options","text":"<p>By default, unrecognized <code>-XX:</code> command-line options are ignored, which prevents an application failing to start. You can now use  <code>-XX:-IgnoreUnrecognizedXXColonOptions</code> to turn off this behavior, so that unrecognized <code>-XX:</code> options are reported instead. For more information, see <code>-XX:[+|-]IgnoreUnrecognizedXXColonOptions</code>.</p>"},{"location":"version0.14/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Support for Concurrent scavenge mode is now extended to Linux on POWER\u00ae BE architectures. For more information, see <code>-Xgc:concurrentScavenge</code>.</p>"},{"location":"version0.14/#new-jstack-tool-for-obtaining-stack-traces-and-thread-information","title":"New jstack tool for obtaining stack traces and thread information","text":"<p>For compatibility with the reference implementation, OpenJ9 now includes an independent implementation of the <code>jstack</code> tool. To learn how to use the tool and about any differences compared to the HotSpot tool of the same name, see Java stack tool.</p>"},{"location":"version0.14/#new-jps-tool","title":"New jps tool","text":"<p>OpenJ9 release 0.13.0 introduced support for the <code>jps</code> tool for Java 12. In this release, support is added for Java 8 and 11. The <code>jps</code> tool can be used to  query running Java processes. For more information, see Java process status.</p>"},{"location":"version0.14/#new-experimental-option-to-improve-the-performance-of-jvmti-watched-fields","title":"New experimental option to improve the performance of JVMTI watched fields","text":"<p>The <code>-XX:[+|-]JITInlineWatches</code> option is introduced in this release. When enabled, the option turns on experimental JIT operations that are intended to improve the performance of JVMTI watched fields. This option is currently supported only on x86 platforms (Windows\u00ae, macOS\u00ae, and Linux).</p>"},{"location":"version0.14/#new-option-to-prevent-a-network-query-being-used-to-determine-host-name-and-ip-address","title":"New option to prevent a network query being used to determine host name and IP address","text":"<p>By default, a network query is used to determine the host name and IP address for troubleshooting purposes. To avoid your program waiting to time out if a nameserver cannot be contacted, you can now prevent the query from being performed. For more information, see <code>-XX:[+|-]ReadIPInfoForRAS</code>.</p>"},{"location":"version0.14/#changes-to-the-shared-classes-cache-generation-number","title":"Changes to the shared classes cache generation number","text":"<p>On all platforms, the format of classes that are stored in the shared classes cache is changed, which causes the JVM to create a new shared classes cache, rather than re-creating or reusing an existing cache. To save space, all existing shared caches can be removed unless they are in use by an earlier release. For more information about destroying a shared classes cache, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.14/#change-to-the-default-native-stack-size-on-64-bit-zos","title":"Change to the default native stack size on 64-bit z/OS","text":"<p>The default stack size for operating system threads on 64-bit z/OS is changed from 384 KB to the operating system minimum of 1 MB. For more information about this setting, see <code>-Xmso</code>.</p>"},{"location":"version0.14/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.13.0 and version 0.14.0 releases, see the Release notes.</p>"},{"location":"version0.14/#version-0142","title":"Version 0.14.2","text":"<p>The following new features and notable changes since version 0.14.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Support for OpenSSL 1.0.1</li> <li>OpenSSL Digest algorithm disabled</li> </ul>"},{"location":"version0.14/#features-and-changes_1","title":"Features and changes","text":""},{"location":"version0.14/#binaries-and-supported-environments_1","title":"Binaries and supported environments","text":"<p>OpenJ9 release 0.14.2 supports OpenJDK 8 and 11. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> </ul> <p>The Windows (MSI) installer for OpenJDK v8 (64-bit) can now be used to optionally install the IcedTea-Web package, which provides equivalent functionality to Java Web Start. For more information about the installer, see the AdoptOpenJDK Installation page. For more information about migrating to IcedTea-Web, read the AdoptOpenJDK Migration Guide.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.14/#support-for-openssl-101","title":"Support for OpenSSL 1.0.1","text":"<p>OpenSSL version 1.0.1 support is now enabled; Earlier releases supported only OpenSSL 1.0.2 and 1.1.x. On Linux\u00ae and AIX\u00ae platforms, the OpenSSL libraries are expected to be available on the system path. For more information about cryptographic acceleration with OpenSSL, see Cryptographic operations.</p>"},{"location":"version0.14/#openssl-digest-algorithm-disabled","title":"OpenSSL Digest algorithm disabled","text":"<p>Due to issue #5611, the Digest algorithm is disabled.</p>"},{"location":"version0.15/","title":"Version 0.15.1","text":""},{"location":"version0.15/#whats-new-in-version-0151","title":"What's new in version 0.15.1","text":"<p>The following new features and notable changes since version 0.14.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Performance improvements for JVMTI watched fields</li> <li>Support for pause-less garbage collection on IBM Z systems</li> <li> ChaCha20 algorithm support for OpenSSL</li> <li> OpenSSL Digest algorithm disabled</li> <li>Support for OpenJDK HotSpot options</li> <li>Support for Transparent Huge Pages (THP)</li> <li> Support for low-overhead heap profiling (JEP 331)</li> <li>New Java memory map (jmap) tool</li> <li>Automatically setting an initial heap size</li> <li>Removal of -Xdiagnosticscollector option</li> <li>Change in behaviour of -XX:[+|-]IdleTuningCompactOnIdle</li> <li>Addition of heuristics for compaction during idle GC</li> <li>Change in shared classes behavior for checking timestamps of <code>jar</code> or <code>zip</code> files</li> </ul>"},{"location":"version0.15/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.15/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 0.15.0 and 0.15.1 supports OpenJDK 8, 11, and 12.</p> <p>Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 12</li> </ul> <p> Note: The binaries at AdoptOpenJDK are labeled 0.15.1 due to a missing change.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.15/#performance-improvements-for-jvmti-watched-fields","title":"Performance improvements for JVMTI watched fields","text":"<p>OpenJ9 version 0.14.0 introduced the <code>-XX:[+|-]JITInlineWatches</code> option, which, when enabled, turned on experimental JIT operations to improve the performance of JVMTI watched fields. Following successful results, this option is now enabled by default. This option is now also supported on z/OS\u00ae and Linux for IBM Z\u00ae, in addition to x86 platforms (Windows\u00ae, macOS\u00ae, and Linux).</p>"},{"location":"version0.15/#support-for-pause-less-garbage-collection-on-ibm-z-systems","title":"Support for pause-less garbage collection on IBM Z systems","text":"<p>Support for Concurrent scavenge mode is now extended to Linux on IBM Z\u00ae systems and z/OS\u00ae. For more information, see <code>-Xgc:concurrentScavenge</code>.</p>"},{"location":"version0.15/#chacha20-algorithm-support-for-openssl","title":"ChaCha20 algorithm support for OpenSSL","text":"<p>The ChaCha20 and ChaCha20-Poly1305 algorithms can now use OpenSSL on Java 11. For more information, see <code>-Djdk.nativeChaCha20</code>. </p>"},{"location":"version0.15/#openssl-digest-algorithm-disabled","title":"OpenSSL Digest algorithm disabled","text":"<p>Due to issue #5611, the Digest algorithm is disabled. This algorithm was disabled for Java 8 and 11 in release 0.14.2, which did not support Java 12.</p>"},{"location":"version0.15/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the <code>-XX:OnOutOfMemoryError</code> OpenJDK HotSpot option is now supported by OpenJ9.</p>"},{"location":"version0.15/#support-for-transparent-huge-pages-thp","title":"Support for Transparent Huge Pages (THP)","text":"<p>The VM now supports the allocation of huge pages on Linux when you use the <code>madvise</code> (<code>/sys/kernel/mm/transparent_hugepage/enabled</code>) setting. To enable this feature, set <code>-XX:+TransparentHugePage</code> on the command line when you start your application. This option is currently not enabled by default.</p>"},{"location":"version0.15/#support-for-low-overhead-heap-profiling","title":"Support for low-overhead heap profiling","text":"<p>JEP 331 provides a mechanism for sampling Java heap allocations with a low overhead via the JVM Tool Interface (JVMTI).</p> <p> Restrictions: JEP 331 is implemented for OpenJ9 with the following limitations:</p> <ul> <li>The <code>balanced</code> and <code>metronome</code> garbage collection policies are not supported.</li> <li>The JEP331 JVMTI agent and the Health Center agent both set a sampling interval, which by default is different. If both agents are used at the same time the Health Center agent will get incorrect results, unless the sampling intervals are adjusted to use the same value. </li> </ul>"},{"location":"version0.15/#new-java-memory-map-tool","title":"New Java memory map tool","text":"<p>The Java memory map (jmap) tool is similar to the HotSpot tool of the same name, and can be used to print statistics about classes on the heap, including the number of objects and their aggregate size. For usage information, see Java memory map (jmap) tool.</p>"},{"location":"version0.15/#automatically-setting-an-initial-heap-size","title":"Automatically setting an initial heap size","text":"<p>OpenJ9 can now learn and set an appropriate initial heap size for an application as an alternative to a user manually sizing and setting an <code>-Xms</code> value. The VM records the size of the heap when startup processing ends, writing this data to the shared classes cache. An average value is set over a few restarts, helping to ensure that the value used for the initial heap size is as accurate as possible. The heap size recorded is specific to the application command line, therefore a different hint is stored for every unique command line.</p> <p>To turn on this behavior, set the <code>-XX:+UseGCStartupHints</code> option on the command line when you start your application.</p>"},{"location":"version0.15/#removal-of-xdiagnosticscollector-option","title":"Removal of -Xdiagnosticscollector option","text":"<p>This option was redundant and has now been removed. If you try to use this option on the command line, the VM outputs this error message:</p> <p><code>JVMJ9VM007E Command-line option unrecognised: -Xdiagnosticscollector</code></p>"},{"location":"version0.15/#change-in-behaviour-of-xxidletuningcompactonidle","title":"Change in behaviour of -XX:IdleTuningCompactOnIdle","text":"<p>-XX:[+|-]IdleTuningCompactOnIdle is now no longer effective when -XX:+IdleTuningGcOnIdle is not specified.</p>"},{"location":"version0.15/#heuristics-for-compaction-during-idle-gc","title":"Heuristics for compaction during idle GC","text":"<p>OpenJ9 now automatically compacts the heap when certain triggers are met during idle garbage collection (GC). As a result of this change, <code>-XX:[+|-]IdleTuningCompactOnIdle</code> is deprecated.</p>"},{"location":"version0.15/#change-in-shared-classes-behavior-for-checking-timestamps-of-jar-or-zip-files","title":"Change in shared classes behavior for checking timestamps of <code>jar</code> or <code>zip</code> files","text":"<p>In earlier releases, the shared classes cache checks timestamps of <code>jar</code> or <code>zip</code> files every time a class is loaded and reloads a class if the timestamp has changed. This behavior is now changed; timestamps are checked only when <code>zip</code> or <code>jar</code> files are added to class loaders and used for the first time to look for a class, which can improve class-loading performance. If <code>jar</code> or <code>zip</code> files are updated after a class loader starts loading classes from them, an older version of the class might be loaded from the shared classes cache. To revert to the behavior of earlier releases, set the <code>-Xshareclasses:checkURLTimestamps</code> option on the command line when you start your application.</p> <p> Note: Multiple <code>-Xshareclasses:</code> options are not combined, only the last one is used.</p>"},{"location":"version0.15/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.14.0 and version 0.15.1 releases, see the Release notes.</p>"},{"location":"version0.16/","title":"Version 0.16.0","text":""},{"location":"version0.16/#whats-new-in-version-0160","title":"What's new in version 0.16.0","text":"<p>The following new features and notable changes since version 0.15.1 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Some class data sharing is enabled by default</li> <li>Automatic setting of initial heap size is enabled by default</li> <li>Option to share VM anonymous classes</li> <li>Performance improvements for JVMTI watched fields on Power Systems</li> <li>Linux on x86: Support for Transparent Huge Pages (THP)</li> <li>New Java\u2122 diagnostic command (<code>jcmd</code>) tool</li> <li>Changes to the shared classes cache generation number</li> <li> The <code>-Xverify:none</code> and <code>-noverify</code> options are deprecated</li> <li> New JDK 13 features</li> </ul>"},{"location":"version0.16/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.16/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.16.0 supports OpenJDK 13, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 13</li> </ul> <p>OpenJDK 13 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.15.2. Features mentioned in these release notes are not available in these builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.16.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.16/#some-class-data-sharing-is-enabled-by-default","title":"Some class data sharing is enabled by default","text":"<p>Class data sharing is enabled by default for bootstrap classes, unless your application is running in a container. You can use the <code>-Xshareclasses</code> option to change the default behavior, including using <code>-Xshareclasses:none</code> to disable all class data sharing. For more information, see Introduction to class data sharing.</p>"},{"location":"version0.16/#automatic-setting-of-initial-heap-size-is-enabled-by-default","title":"Automatic setting of initial heap size is enabled by default","text":"<p>OpenJ9 version 0.15.1 introduced the <code>-XX:[+|-]UseGCStartupHints</code> option, which, when enabled, turned on the automatic learning and setting of an appropriate heap size for an application. This option is now enabled by default.</p>"},{"location":"version0.16/#option-to-share-vm-anonymous-classes","title":"Option to share VM anonymous classes","text":"<p>Prior to version 0.16.0, anonymous classes, those created by <code>Unsafe.defineAnonymousClass</code>, were not stored in the shared classes cache. They are now stored there by default, which means they are available for ahead-of-time (AOT) compilation, potentially improving startup performance. A new command, -XX:[+|-]ShareAnonymousClasses, is introduced that enables you to stop anonymous classes being stored in the shared classes cache.</p>"},{"location":"version0.16/#performance-improvements-for-jvmti-watched-fields-on-power-systems","title":"Performance improvements for JVMTI watched fields on Power Systems","text":"<p>OpenJ9 version 0.14.0 introduced the <code>-XX:[+|-]JITInlineWatches</code> option, which turns on JIT operations to improve the performance of JVMTI watched fields. This option, which was enabled by default in version 0.15.1, is now also supported on AIX\u00ae and Linux on Power Systems\u2122.</p>"},{"location":"version0.16/#linux-on-x86-support-for-transparent-huge-pages-thp","title":"Linux\u00ae on x86: Support for Transparent Huge Pages (THP)","text":"<p>When you use the <code>madvise</code> (<code>/sys/kernel/mm/transparent_hugepage/enabled</code>) setting on Linux on x86 systems, THP is now enabled by default. To disable this feature, set <code>-XX:-TransparentHugePage</code> on the command line when you start your application. The THP setting on other systems remains disabled by default when you use <code>madvise</code>, but can be enabled by setting <code>-XX:+TransparentHugePage</code>.</p>"},{"location":"version0.16/#new-jcmd-tool","title":"New jcmd tool","text":"<p>For compatibility with the reference implementation, OpenJ9 now includes an independent implementation of the <code>jcmd</code> tool  for running diagnostic commands on a VM. For more information, see Java diagnostic command tool.</p>"},{"location":"version0.16/#changes-to-the-shared-classes-cache-generation-number","title":"Changes to the shared classes cache generation number","text":"<p>The format of classes that are stored in the shared classes cache is changed, which causes the JVM to create a new shared classes cache rather than re-creating or reusing an existing cache. To save space, you can remove all existing shared caches unless they are in use by an earlier release. As a result of the format change, a <code>layer</code> column now appears in the output of the <code>-Xshareclasses:listAllCaches</code> option. This change is to support a future enhancement.</p> <p>For more information about the <code>-Xshareclasses</code> option, including the <code>destroy</code> options that you can use to remove caches, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.16/#the-xverifynone-and-noverify-options-are-deprecated","title":"The <code>-Xverify:none</code> and <code>-noverify</code> options are deprecated","text":"<p>The option <code>-Xverify:none</code> (and its equivalent <code>-noverify</code>) is deprecated in Java 13. Both options might be removed in a future release. OpenJ9 issues a warning if these options are used in Java 13 and later versions. </p>"},{"location":"version0.16/#new-jdk-13-features","title":"New JDK 13 features","text":"<p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 13 with OpenJ9:</p> <ul> <li>JEP 353: Reimplement the Legacy Socket API</li> <li>JEP 354: Switch Expressions (Preview)</li> <li>JEP 355: Text Blocks (Preview)</li> </ul> <p>You can find the full list of features for JDK 13 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.16/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.15.1 and version 0.16.0 releases, see the Release notes.</p>"},{"location":"version0.17/","title":"Version 0.17.0","text":""},{"location":"version0.17/#whats-new-in-version-0170","title":"What's new in version 0.17.0","text":"<p>The following new features and notable changes since version 0.16.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New shared classes cache suboptions for layered caches</li> <li>New shared classes cache suboption to skip disk space check</li> <li>Option to share 'Unsafe' classes</li> <li>Option to record class relationships in the verifier</li> <li>Support for the IBM z15\u00ae processor</li> <li>Digest algorithm is re-enabled</li> <li>Direct Dump Reader (DDR) VM restriction removed</li> <li>The format of the HOOKS section of a Java dump has changed</li> <li>LUDCL caching disabled by default</li> </ul>"},{"location":"version0.17/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.17/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.17.0 supports OpenJDK 8, 11, and 13. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 13</li> </ul> <p> Note: The Windows\u00ae and macOS\u00ae binaries from the AdoptOpenJDK community for OpenJDK 8, 11, and 13 have been updated to OpenSSL v1.1.1d. Look for the following release names to identify these packages:</p> <ul> <li>OpenJDK 8: <code>jdk8u232-b09.1_openj9-0.17.0</code></li> <li>OpenJDK 11: <code>jdk-11.0.5+10.1_openj9-0.17.0</code></li> <li>OpenjDK 13: <code>jdk-13.0.1+9.1_openj9-0.17.0)</code></li> </ul> <p> Note: The last release of OpenJDK 8 and 11 from AdoptOpenJDK is Eclipse OpenJ9 0.15.1. To read about other features and changes in the VM since 0.15.1, check the Version 0.16.0 release notes too.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.17/#new-shared-classes-cache-suboptions-for-layered-caches","title":"New shared classes cache suboptions for layered caches","text":"<p>(Experimental, 64-bit only)</p> <p>New suboptions are available for creating layered caches, where a cache builds on another cache with the same name. You can use these suboptions to save space when building a Docker container, for example.</p> <p> Note: Because these suboptions are experimental, do not use them in a production environment.</p> <p>The new options are:</p> <ul> <li><code>createLayer</code></li> <li><code>layer=&lt;number&gt;</code> (see this section for more information about layered caches)</li> <li><code>printTopLayerStats</code></li> <li><code>destroyAllLayers</code></li> </ul>"},{"location":"version0.17/#new-shared-classes-cache-suboption-to-skip-disk-space-check","title":"New shared classes cache suboption to skip disk space check","text":"<p>When creating a persistent shared classes cache, the OpenJ9 VM checks that there is sufficient disk space available on the file system. For file systems that do not support the checking of free space, you can set the <code>-Xshareclasses:noPersistentDiskSpaceCheck</code> option, which causes the VM to skip the space checking operation. If there isn't enough disk space available when the cache is written, a SIGBUS or SIGSEGV signal occurs and the VM ends. For more information, see the -Xshareclasses:noPersistentDiskSpaceCheck option.</p>"},{"location":"version0.17/#option-to-share-unsafe-classes","title":"Option to share 'Unsafe' classes","text":"<p>Classes created through <code>Unsafe.defineClass</code> are now stored by default in the shared classes cache. You can use the <code>-XX:-ShareUnsafeClasses</code> option to change the default behavior. For more information, see -XX:[+|-]ShareUnsafeClasses.</p>"},{"location":"version0.17/#option-to-record-class-relationships-in-the-verifier","title":"Option to record class relationships in the verifier","text":"<p>A new command line option <code>-XX:+ClassRelationshipVerifier</code> allows you to record class relationships in the verifier, which avoids unnecessary class loading and reduces VM startup time. This is a new approach to bytecode verification that delays validating the relationships between classes until the classes are required to be loaded for a program's execution thus loading only those classes that are needed. For more information, see -XX:[+|-]ClassRelationshipVerifier.</p>"},{"location":"version0.17/#support-for-the-ibm-z15-processor","title":"Support for the IBM z15 processor","text":"<p>This release adds JIT compiler support for exploiting z15 instructions.</p>"},{"location":"version0.17/#digest-algorithm-is-re-enabled","title":"Digest algorithm is re-enabled","text":"<p>Issue #5611 is fixed, so support for the Digest algorithm is re-enabled. For more information about this support, see Cryptographic operations.</p>"},{"location":"version0.17/#direct-dump-reader-ddr-vm-restriction-removed","title":"Direct Dump Reader (DDR) VM restriction removed","text":"<p>Prior to this version, you had to use a 32-bit VM to look at a 32-bit core, and a 64-bit VM to look at a 64-bit core when using DDR. This restriction has now been removed.</p>"},{"location":"version0.17/#the-format-of-the-hooks-section-of-a-java-dump-has-changed","title":"The format of the HOOKS section of a Java dump has changed","text":"<p>The format of the <code>HOOKS</code> section of a Java dump, which shows internal VM event callbacks, has changed:</p> <ul> <li>Recorded times have been changed from milliseconds to microseconds to provide increased precision.</li> <li>A new field, <code>3HKTOTALTIME</code>, is included, which gives the total duration of previous events.</li> <li>The hook data is now reset after each Java dump.</li> </ul> <p>For more information and an example of the new format, see Java dump: HOOKS</p>"},{"location":"version0.17/#ludcl-caching-disabled-by-default","title":"LUDCL caching disabled by default","text":"<p>By caching the Latest User Defined Class Loader (LUDCL), Java applications that use deserialization extensively can see a performance improvement. This capability is controlled by the -Dcom.ibm.enableClassCaching system property and is now disabled by default due to issue #7332.</p> <p> Note: Versions of the documentation before 0.17.0 incorrectly identified this property as disabled by default when it was actually enabled by default in the VM.</p>"},{"location":"version0.17/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.16 and version 0.17.0 releases, see the Release notes.</p>"},{"location":"version0.18/","title":"Version 0.18.1","text":""},{"location":"version0.18/#whats-new-in-version-0181","title":"What's new in version 0.18.1","text":"<p>The following new features and notable changes since version 0.17.0 are included in this release:</p> <ul> <li>Binaries and supported environments</li> <li>Technical preview of JITServer technology</li> <li><code>jextract</code> now available on macOS\u00ae for OpenJDK version 8</li> <li>New shared-classes cache suboption to turn off timestamp checking</li> <li>Removal of restriction on layered shared cache</li> <li><code>-Xmso</code> 1 MB minimum value on z/OS\u00ae 64-bit</li> <li><code>jstat</code>: new Java\u2122 statistics monitoring tool</li> <li><code>-XX:+TransparentHugePage</code> is enabled by default on more Linux\u00ae systems</li> <li>New exit dump agent and <code>ExitOnOutOfMemoryError</code> option</li> <li>LUDCL caching enabled by default</li> <li>Terabytes suffix support for <code>-X</code> and <code>-XX</code> options that take a size</li> <li>Improved support for pause-less garbage collection</li> <li><code>-Xgc:noConcurrentScavenge</code> option</li> <li>Support for OpenJDK HotSpot options</li> <li>Shared classes cache suboptions for layered caches no longer experimental</li> <li><code>-Djava.lang.string.substring.nocopy</code> option</li> </ul>"},{"location":"version0.18/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.18/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 releases 0.18.0 and 0.18.1 support OpenJDK 8, 11, and 13. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 13</li> </ul> <p> Note: Binaries at AdoptOpenJDK that are labeled 0.18.1 include additional bug fixes. For more information, see the release notes.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.18/#technical-preview-of-jitserver-technology","title":"Technical preview of JITServer technology","text":"<p>A technical preview of JITServer technology is included in this release. It's currently available for OpenJDK 8 and OpenJDK 11 running on Linux on x86-64.</p> <p>JITServer technology decouples the JIT compiler from the VM and lets the JIT compiler run remotely in its own process. This mechanism prevents your Java application suffering possible negative effects due to CPU and memory consumption caused by JIT compilation. This technology can improve quality of service, robustness, and even performance of Java applications. For more information, see JITServer technology.</p>"},{"location":"version0.18/#jextract-now-available-on-macos-for-openjdk-version-8","title":"<code>jextract</code> now available on macOS for OpenJDK version 8","text":"<p>The <code>jextract</code> tool is now available on macOS platforms (as well as AIX\u00ae and Linux) for all current versions of OpenJDK: 8, 11, and 13.</p>"},{"location":"version0.18/#new-shared-classes-cache-suboption-to-turn-off-timestamp-checking","title":"New shared-classes cache suboption to turn off timestamp checking","text":"<p>You can set the <code>-Xshareclasses:noTimestampChecks</code> option to turn off timestamp checking in shared classes. For more information, see the -Xshareclasses:noTimestampChecks option.</p>"},{"location":"version0.18/#removal-of-restriction-on-layered-shared-cache","title":"Removal of restriction on layered shared cache","text":"<p>In the previous release, there is a restriction that the <code>jvmtiSharedCacheInfo.isCorrupt</code> field and the <code>SharedClassCacheInfo.isCacheCorrupt()</code> method cannot detect a corrupted cache that has a layer number other than <code>0</code>. This restriction is now removed. See the Shared classes API documentation. </p>"},{"location":"version0.18/#-xmso-1-mb-minimum-value-on-zos-64-bit","title":"<code>-Xmso</code> 1 MB minimum value on z/OS 64-bit","text":"<p>On z/OS 64-bit, <code>-Xmso</code> has a 1 MB minimum value, to match the minimum stack space provided by the operating system. If you set a value smaller than 1 MB, the value is ignored.</p>"},{"location":"version0.18/#jstat-new-java-statistics-monitoring-tool","title":"<code>jstat</code>: new Java statistics monitoring tool","text":"<p>For compatibility with the HotSpot implementation, OpenJ9 now includes an independent implementation of the <code>jstat</code> tool for retrieving statistics on a VM. For more information, see Java statistics monitoring tool.</p>"},{"location":"version0.18/#-xxtransparenthugepage-is-enabled-by-default-on-more-linux-systems","title":"<code>-XX:+TransparentHugePage</code> is enabled by default on more Linux systems","text":"<p>-XX:+TransparentHugePage is enabled by default on Linux systems for POWER\u00ae and IBM Z\u00ae as well as x86 systems. This option takes affect only when Transparent Huge Pages (THP) is set to <code>madvise</code> on your system. When Transparent Huge Pages are used, your application footprint might increase.</p>"},{"location":"version0.18/#new-exit-dump-agent-and-exitonoutofmemoryerror-option","title":"New exit dump agent and <code>ExitOnOutOfMemoryError</code> option","text":"<p>The new exit dump agent shuts down the VM when the specified event occurs. The exit agent is at priority level 0 and the tool agent has been moved to priority level 1 to aid in mimicking the behavior of HotSpot options. For more information about dump agents, see <code>-Xdump</code>.</p> <p>OpenJ9 now supports the HotSpot option <code>-XX:[+|-]ExitOnOutOfMemoryError</code>. You can set this option to have the VM shut down when a <code>java.lang.OutOfMemory</code> error is thrown by the VM or in Java code. The exit dump agent is used in the implementation of <code>-XX:[+|-]ExitOnOutOfMemoryError</code>.</p>"},{"location":"version0.18/#ludcl-caching-enabled-by-default","title":"LUDCL caching enabled by default","text":"<p>By caching the Latest User Defined Class Loader (LUDCL), Java applications that use deserialization extensively can see a performance improvement. This capability is controlled by the <code>-Dcom.ibm.enableClassCaching</code> system property and is now enabled by default. This feature was disabled for the 0.17.0 release due to issue #7332 which has now been resolved.</p>"},{"location":"version0.18/#terabytes-suffix-support-for-x-and-xx-options-that-take-a-size","title":"Terabytes suffix support for <code>-X</code> and <code>-XX</code> options that take a size","text":"<p>OpenJ9 now supports 't' and 'T' suffixes (indicating terabytes) for <code>-X</code> and <code>-XX</code> options that take a <code>&lt;size&gt;</code> parameter.</p>"},{"location":"version0.18/#improved-support-for-pause-less-garbage-collection","title":"Improved support for pause-less garbage collection","text":"<p>Support for Concurrent scavenge mode is now extended to macOS. For more information, see <code>-Xgc:concurrentScavenge</code>.</p>"},{"location":"version0.18/#-xgcnoconcurrentscavenge-option","title":"<code>-Xgc:noConcurrentScavenge</code> option","text":"<p>The previously undocumented option <code>-Xgc:noConcurrentScavenge</code> disables pause-less garbage collection.</p>"},{"location":"version0.18/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li>-XX:ParallelGCThreads</li> <li>-XX:ConcGCThreads</li> <li>-XX:ParallelCMSThreads</li> </ul>"},{"location":"version0.18/#shared-classes-cache-suboptions-for-layered-caches-no-longer-experimental","title":"Shared classes cache suboptions for layered caches no longer experimental","text":"<p>The suboptions for creating layered caches are no longer marked experimental.</p> <p>The new options are:</p> <ul> <li><code>createLayer</code></li> <li><code>layer=&lt;number&gt;</code> (see this section for more information about layered caches)</li> <li><code>printTopLayerStats</code></li> <li><code>destroyAllLayers</code></li> </ul>"},{"location":"version0.18/#-djavalangstringsubstringnocopy-option","title":"<code>-Djava.lang.string.substring.nocopy</code> option","text":"<p>The previously undocumented Java 8 option <code>-Djava.lang.string.substring.nocopy=true</code> avoids String sharing by String.substring(), which is the same behavior as the Oracle HotSpot VM.</p>"},{"location":"version0.18/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.17.0 and version 0.18.0 releases, see the Release notes.</p>"},{"location":"version0.19/","title":"Version 0.19.0","text":""},{"location":"version0.19/#whats-new-in-version-0190","title":"What's new in version 0.19.0","text":"<p>The following new features and notable changes since version 0.18.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Option to print code cache usage to <code>stderr</code> at VM shutdown</li> <li> <code>StringBuffer</code> and <code>StringBuilder</code> above 1 G grow to the maximum size</li> <li> jpackage packaging tool platform support</li> <li> Extended messages for <code>NullPointerException</code> not yet implemented</li> <li>Compiler changes for Linux</li> <li> New JDK 14 features</li> </ul>"},{"location":"version0.19/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.19/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.19.0 supports OpenJDK 14, which is available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 14</li> </ul> <p>OpenJDK 14 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.18.0. Features mentioned in these release notes are not available in these builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.19.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.19/#option-to-print-code-cache-usage-to-stderr-at-vm-shutdown","title":"Option to print code cache usage to <code>stderr</code> at VM shutdown","text":"<p>A new command line option -XX:+PrintCodeCache allows you to print the code cache memory usage to <code>stderr</code> when the VM shuts down.</p>"},{"location":"version0.19/#stringbuffer-and-stringbuilder-above-1-g-grow-to-the-maximum-size","title":"<code>StringBuffer</code> and <code>StringBuilder</code> above 1 G grow to the maximum size","text":"<p>A 1 G <code>char[]</code> or larger <code>StringBuffer</code> and <code>StringBuilder</code> now immediately grows to the maximum possible size for all current versions of Java, including Java 8. For Java 8 only, you can revert to the previous behavior of growing only as much as necessary to accommodate the <code>String</code> being added, by using the option, <code>-Djava.lang.stringBuffer.growAggressively=false</code>.</p>"},{"location":"version0.19/#jpackage-packaging-tool-platform-support","title":"jpackage packaging tool platform support","text":"<p>The <code>jpackage</code> utility is described in JEP 343 as a tool that \"packages a Java application into a platform-specific package that includes all of the necessary dependencies.\" Full details of the tool are available at JEP 343: Packaging Tool. Be aware that <code>jpackage</code> is supported on only the following OpenJ9 platforms: Linux\u00ae, macOS\u00ae, and Windows\u2122. It is not supported on AIX\u00ae or z/OS\u00ae platforms.</p>"},{"location":"version0.19/#extended-messages-for-nullpointerexception-not-yet-implemented","title":"Extended messages for <code>NullPointerException</code> not yet implemented","text":"<p>JEP 358: Helpful NullPointerExceptions provides extended messages when a <code>NullPointerException</code> is generated by the Java 14 VM and you have enabled the feature. However, be aware that this is not implemented in OpenJ9 at this time.</p>"},{"location":"version0.19/#compiler-changes-for-linux","title":"Compiler changes for Linux","text":"<p>Linux x86 64-bit, Linux on POWER\u00ae LE 64-bit, and Linux on IBM Z\u00ae 64-bit have all moved to the gcc 7.5 compiler. See Supported environments.</p>"},{"location":"version0.19/#new-jdk-14-features","title":"New JDK 14 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 343: Packaging Tool (Incubator) Restrictions: <code>jpackage</code> is supported on only the following OpenJ9 platforms: Linux\u00ae, macOS\u00ae, and Windows\u2122. It is not supported on AIX\u00ae or z/OS\u00ae platforms.</li> <li>JEP 352: Non-Volatile Mapped Byte Buffers</li> <li>JEP 358: Helpful NullPointerExceptions</li> <li>JEP 359: Records (Preview)</li> </ul> <p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 14 with OpenJ9:</p> <ul> <li>JEP 305: Pattern Matching for instanceof (Preview) </li> <li>JEP 361: Switch Expressions (Standard)</li> <li>JEP 367: Remove the Pack200 Tools and API</li> <li>JEP 368: Text Blocks (Second Preview)</li> </ul> <p>You can find the full list of features for JDK 14 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.19/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.18.0 and version 0.19.0 releases, see the Release notes.</p>"},{"location":"version0.20/","title":"Version 0.20.0","text":""},{"location":"version0.20/#whats-new-in-version-0200","title":"What's new in version 0.20.0","text":"<p>The following new features and notable changes since version 0.19.0 are included in this release:</p> <ul> <li>Binaries and supported environments</li> <li> Limited support for 64-bit Linux on ARM</li> <li><code>-XX:[+|-]ExitOnOutOfMemoryError</code> option behavior update</li> <li>New <code>-XX:[+|-]GlobalLockReservation</code> option added</li> <li> Change to default maximum heap size for Java 8</li> <li>Change to <code>jcmd</code> default options</li> </ul>"},{"location":"version0.20/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.20/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.20.0 supports OpenJDK 8, 11, and 14. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 14</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.20/#limited-support-for-64-bit-linux-on-arm","title":"Limited support for 64-bit Linux on ARM","text":"<p>Limited support is available in this release for the 64-bit ARM (AArch64) architecture. An early access build on OpenJDK 11 is available from the AdoptOpenJDK community. See the OpenJ9 release notes for any known issues that are still being worked on before this platform is fully supported.  </p>"},{"location":"version0.20/#-xx-exitonoutofmemoryerror-option-behavior-update","title":"<code>-XX:[+|-]ExitOnOutOfMemoryError</code> option behavior update","text":"<p>The <code>-XX:[+|-]ExitOnOutOfMemoryError</code> option is updated to exit only on VM <code>OutOfMemoryErrors</code> instead of both VM and Java\u2122 thrown errors to match the HotSpot option. See <code>-XX:[+|-]ExitOnOutOfMemoryError</code> for more details about this option.</p>"},{"location":"version0.20/#new-xx-globallockreservation-option-added","title":"New <code>-XX:[+|-]GlobalLockReservation</code> option added","text":"<p>(AIX\u00ae and Linux on Power Systems\u2122 only)</p> <p>Option <code>-XX:[+|-]GlobalLockReservation</code> enables a new optimization targeted towards more efficient handling of locking and unlocking Java  objects. See <code>-XX:[+|-]GlobalLockReservation</code> for more details about this option.</p>"},{"location":"version0.20/#change-to-default-maximum-heap-size-for-java-8","title":"Change to default maximum heap size for Java 8","text":"<p>For consistency with Java 11, the default maximum heap size (<code>-Xmx</code>) is changed to be 25% of the available memory with a maximum of 25 GB. Where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB. If you want to revert to the default setting in earlier releases of OpenJ9, use the -XX:+OriginalJDK8HeapSizeCompatibilityMode option.</p>"},{"location":"version0.20/#change-to-jcmd-default-options","title":"Change to <code>jcmd</code> default options","text":"<p>The Java diagnostic command (<code>jcmd</code>) tool no longer requires a filename when used with the <code>Dump.java</code>, <code>Dump.snap</code>, or <code>Dump.system</code> options. See <code>jcmd</code> for more information about the tool.</p>"},{"location":"version0.20/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.19.0 and version 0.20.0 releases, see the Release notes.</p>"},{"location":"version0.21/","title":"Version 0.21.0","text":""},{"location":"version0.21/#whats-new-in-version-0210","title":"What's new in version 0.21.0","text":"<p>The following new features and notable changes since version 0.20.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Application Programming Interface (API) documentation</li> <li>Performance improvements</li> <li>New <code>-XX:[+|-]HandleSIGABRT</code> option added</li> <li>New <code>-XX:[+|-]PrintFlagsFinal</code> option added</li> <li>Update to <code>NoClassDefFoundError</code> exception message</li> <li>macOS\u00ae shared libraries version updated</li> </ul>"},{"location":"version0.21/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.21/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.21.0 supports OpenJDK 8, 11, and 14. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 14</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.21/#application-programming-interface-api-documentation","title":"Application Programming Interface (API) documentation","text":"<p>API documentation that applies to OpenJ9 can now be found in this user documentation for both JDK 8 and JDK 11. The documentation includes links to Oracle API documentation for information that is not specific to OpenJ9. See API overview.</p>"},{"location":"version0.21/#performance-improvements","title":"Performance improvements","text":"<ul> <li> <p>If the -Xtune:virtualized command line option is used, the default JIT scratch memory limit is now reduced from 256 MB to 16 MB. This reduces the peak from JIT compilation activity, allowing you to size containers more easily, based on the particular application's memory usage.</p> </li> <li> <p>If the JIT is running in a container and no swap space is defined, the JIT dynamically adjusts its scratch memory consumption based on the amount of free physical memory available, to avoid out-of-memory (OOM) occurrences.</p> </li> <li> <p>Several performance features were added to the AArch64 JIT compiler implementation that led to a throughput improvement on multiple applications of at least 20%. The most notable improvements were seen in global register allocation, recompilation (without profiling), CUDA support, concurrent scavenge GC policy, and the inlined code sequence for object allocations.</p> </li> </ul>"},{"location":"version0.21/#new-xx-handlesigabrt-option-added","title":"New <code>-XX:[+|-]HandleSIGABRT</code> option added","text":"<p>This option affects the handling of the operating system signal <code>SIGABRT</code>. For compatibility with the reference implementation, set <code>-XX:-HandleSIGABRT</code>. For more information, see <code>-XX:[+|-]HandleSIGABRT</code>. </p>"},{"location":"version0.21/#new-xx-printflagsfinal-option-added","title":"New <code>-XX:[+|-]PrintFlagsFinal</code> option added","text":"<p>This release provides an initial implementation of the <code>-XX:[+|-]PrintFlagsFinal</code> option. It is currently incomplete and outputs only a subset of parameters. Over time, we expect more options to be added to the output. See <code>-XX:[+|-]PrintFlagsFinal</code> for more details about this option.</p>"},{"location":"version0.21/#update-to-noclassdeffounderror-exception-message","title":"Update to <code>NoClassDefFoundError</code> exception message","text":"<p>The order in which class names are printed in a <code>NoClassDefFoundError</code> exception message now matches the output reported by HotSpot.</p> <p>For example, in the following exception message:</p> <pre><code>java.lang.NoClassDefFoundError: mypackage/Main (wrong name: Main)\n</code></pre> <p><code>mypackage/Main</code> is the class name encountered by the VM in the <code>.class</code> file, but \"wrong name\" <code>Main</code> was the provided class name. Prior to this update to the exception message, the encountered class name and the provided class name were swapped in the <code>NoClassDefFoundError</code> exception message.</p>"},{"location":"version0.21/#macos-shared-libraries-version-updated","title":"macOS shared libraries version updated","text":"<p>The version information for shared libraries on macOS has been updated from 0.0.0 to 1.0.0. If an application has linked against a shared library from a previous OpenJ9 release, it needs to be re-linked against the new release. Failure to re-link causes an error <code>Incompatible library version</code>, <code>requires version 0.0.0</code>.</p>"},{"location":"version0.21/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.20.0 and version 0.21.0 releases, see the Release notes.</p>"},{"location":"version0.22/","title":"Version 0.22.0","text":""},{"location":"version0.22/#whats-new-in-version-0220","title":"What's new in version 0.22.0","text":"<p>The following new features and notable changes since version 0.21.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Performance improvements</li> <li>New <code>-XX:[+|-]PortableSharedCache</code> option added</li> <li>Methods in <code>com.ibm.lang.management.MemoryMXBean</code> deprecated and replaced</li> <li> <code>java.lang.System.mapLibraryName()</code> string suffix</li> <li> New JDK 15 features</li> </ul>"},{"location":"version0.22/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.22/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.22.0 supports OpenJDK 15. Binaries are available from the AdoptOpenJDK community at the following link:</p> <ul> <li>OpenJDK version 15</li> </ul> <p>OpenJDK 15 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>The latest builds of OpenJDK with OpenJ9 for Java 8 and 11 at the AdoptOpenJDK community are for Eclipse OpenJ9 release 0.21.0. Features mentioned in these release notes are not available in these Java 8 and 11 builds. Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 0.22.0, testing at the project is not complete and therefore support for any of these features is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.22/#performance-improvements","title":"Performance improvements","text":"<p>The performance of zero initializing Java heap memory improved on the IBM Z\u00ae platform because of a change to use <code>memset</code> instead of an outdated handcrafted assembly sequence in the JVM.</p>"},{"location":"version0.22/#new-xx-portablesharedcache-option-added","title":"New <code>-XX:[+|-]PortableSharedCache</code> option added","text":"<p>On x86 only, the <code>-XX:[+|-]PortableSharedCache</code> option enables you to choose whether AOT code should be generated using an older processor (Intel\u00ae Sandybridge) feature set, which therefore allows the AOT code to be portable. This feature is particularly relevant for packaging a shared classes cache into a container image (for example, applications deployed on the cloud in the form of Docker containers) because the processor on which the container image is built is likely to be different from the processor on which the container is deployed. For more information, see <code>-XX:[+|-]PortableSharedCache</code>.</p>"},{"location":"version0.22/#methods-in-comibmlangmanagementmemorymxbean-deprecated-and-replaced","title":"Methods in <code>com.ibm.lang.management.MemoryMXBean</code> deprecated and replaced","text":"<p>The methods <code>com.ibm.lang.management.MemoryMXBean.getGCMasterThreadCpuUsed()</code> and <code>com.ibm.lang.management.MemoryMXBean.getGCSlaveThreadsCpuUsed()</code> are deprecated for removal in Java 16. The recommended methods to be used are <code>com.ibm.lang.management.MemoryMXBean.getGCMainThreadCpuUsed()</code> and <code>com.ibm.lang.management.MemoryMXBean.getGCWorkerThreadsCpuUsed()</code> respectively.</p> <p>For more information see Java 8: <code>com.ibm.lang.management.MemoryMXBean</code> and for Java 11: <code>com.ibm.lang.management.MemoryMXBean</code></p>"},{"location":"version0.22/#javalangsystemmaplibraryname-string-suffix","title":"<code>java.lang.System.mapLibraryName()</code> string suffix","text":"<p>On AIX\u00ae systems, <code>java.lang.System.mapLibraryName(libname)</code> returns a representation of a native library in a platform-specific string with a <code>.so</code> suffix.</p>"},{"location":"version0.22/#new-jdk-15-features","title":"New JDK 15 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 360: Sealed Classes (Preview)</li> <li>JEP 371: Hidden Classes</li> <li>JEP 384: Records (Second Preview)</li> </ul> <p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 14 with OpenJ9:</p> <ul> <li>JEP 339: Edwards-Curve Digital Signature Algorithm (EdDSA) </li> <li>JEP 372: Remove the Nashorn JavaScript Engine</li> <li>JEP 373: Reimplement the Legacy DatagramSocket API</li> <li>JEP 375: Pattern Matching for instanceof (Second Preview)</li> <li>JEP 378: Text Blocks</li> <li>JEP 385: Deprecate RMI Activation for Removal</li> </ul> <p>You can find the full list of features for JDK 15 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.22/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.21.0 and version 0.22.0 releases, see the Release notes.</p>"},{"location":"version0.23/","title":"Version 0.23.0","text":""},{"location":"version0.23/#whats-new-in-version-0230","title":"What's new in version 0.23.0","text":"<p>The following new features and notable changes since version 0.22.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li><code>-XX:[+|-]PortableSharedCache</code> option behavior update</li> <li><code>-XX:[+|-]IdleTuningCompactOnIdle</code> option now inactive</li> <li>Support for OpenJDK HotSpot options</li> <li>Extended platform support for the JITServer technology preview</li> </ul>"},{"location":"version0.23/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.23/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.23.0 supports OpenJDK 8, 11, and 15. Binaries are available from the AdoptOpenJDK community at the following links:</p> <ul> <li>OpenJDK version 8</li> <li>OpenJDK version 11</li> <li>OpenJDK version 15</li> </ul> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.23/#-xx-portablesharedcache-option-behavior-update","title":"<code>-XX:[+|-]PortableSharedCache</code> option behavior update","text":"<p>The <code>-XX:[+|-]PortableSharedCache</code> option is updated to improve the portability of AOT-compiled code further. This update allows AOT-compiled code to be portable across OpenJ9 VMs that use compressed references and have a heap size of 1 MB to 28 GB when this option is enabled. This option might introduce a small (1-2%) steady-state throughput penalty when compressed references are used and the heap size is between 1 MB and 3 GB. See <code>-XX:[+|-]PortableSharedCache</code> for more details about this option.</p>"},{"location":"version0.23/#-xx-idletuningcompactonidle-option-now-inactive","title":"<code>-XX:[+|-]IdleTuningCompactOnIdle</code> option now inactive","text":"<p>Setting the <code>-XX:[+|-]IdleTuningCompactOnIdle</code> option now has no effect. A compaction is triggered by internal heuristics that look into the number of fragmented pages. Typically there is no need to force a compaction. This option was deprecated in release 0.15.0, and will be removed in the future. See <code>-XX:[+|-]IdleTuningCompactOnIdle</code> for details about this option.</p>"},{"location":"version0.23/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li><code>-XX:[+|-]AlwaysPreTouch</code></li> </ul>"},{"location":"version0.23/#extended-platform-support-for-the-jitserver-technology-preview","title":"Extended platform support for the JITServer technology preview","text":"<p>Platform support for the JITServer technology preview is now extended to 64-bit Linux\u00ae on IBM Power\u00ae systems, and 64-bit Linux on IBM Z\u00ae systems. JITServer decouples the JIT compiler from the OpenJ9 VM, freeing up CPU and memory for an application. JITServer runs in its own process, either locally or on a remote machine, where resources can be separately managed. This preview was initially introduced in Eclipse OpenJ9 V0.18.1 for Linux on 64-bit x86 systems. For more information, see JITServer technology (technical preview).</p>"},{"location":"version0.23/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.22.0 and version 0.23.0 releases, see the Release notes.</p>"},{"location":"version0.24/","title":"Version 0.24.0","text":""},{"location":"version0.24/#whats-new-in-version-0240","title":"What's new in version 0.24.0","text":"<p>The following new features and notable changes since version 0.23.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Changes to message logging</li> <li>Support for the <code>JAVA_OPTIONS</code> environment variable</li> <li><code>-XX:[+|-]PortableSharedCache</code> option support update</li> <li> <code>-XX:[+|-]ShareAnonymousClasses</code> option behavior update</li> <li>Additional parameters for <code>jcmd Dump</code> commands</li> <li>Change in behavior for the <code>jextract</code> utility</li> <li>New diagnostic suboption for <code>-Xcheck:jni</code> for fatal JNI errors</li> <li>Improved diagnostic information in a Java dump file on processor features</li> <li>Helm chart available for deploying JITServer</li> </ul>"},{"location":"version0.24/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.24/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.24.0 supports OpenJDK 8, 11, and 15.</p> <p>Windows\u00ae builds for Java\u2122 8 are now compiled with Microsoft\u00ae Visual Studio 2013. The Visual Studio redistributable files included with the build are updated to match.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.24/#changes-to-message-logging","title":"Changes to message logging","text":"<p>JEP 158 introduces the <code>-Xlog</code> option as a common logging system for all components of a Java virtual machine. To avoid confusion with the reference implementation, the <code>-Xsyslog</code> option replaces the existing OpenJ9 <code>-Xlog</code> option for message logging. For compatibility with the reference implementation, a limited set of <code>-Xlog</code> suboptions are supported.</p> <p>A new option, <code>-XX:[+|-]LegacyXlogOption</code>, controls how <code>-Xlog</code> is processed when set on the command line.</p> <ul> <li>When <code>-XX:-LegacyXlogOption</code> is set, the <code>-Xlog</code> option is recognized when a form of this option  runs that requests garbage collection (GC) logging.<ul> <li>If any <code>-Xlog</code> GC log requests are set, these options are mapped to the equivalent OpenJ9 verbose GC command line options. For more information, see <code>-Xlog</code>.</li> </ul> </li> <li>Setting <code>-XX:+LegacyXLogOption</code> provides backward compatibility with the legacy <code>-Xlog</code> option, which can be specified on the command line with the parameters documented for the <code>-Xsyslog</code> option. That is, these options can be used interchangeably. If you rely on the legacy <code>-Xlog</code> option and cannot easily migrate to the <code>-Xsyslog</code> option, you must set this option on the command line.</li> </ul>"},{"location":"version0.24/#support-for-the-java_options-environment-variable","title":"Support for the <code>JAVA_OPTIONS</code> environment variable","text":"<p>For compatibility with the reference implementation, OpenJ9 now supports the <code>JAVA_OPTIONS</code> environment variable. This environment variable  can be used to set command line options, as described in OpenJ9 command-line options and Environment variables. Options specified by <code>JAVA_OPTIONS</code> can be overridden by options specified by <code>OPENJ9_JAVA_OPTIONS</code>.</p>"},{"location":"version0.24/#-xx-portablesharedcache-option-support-update","title":"<code>-XX:[+|-]PortableSharedCache</code> option support update","text":"<p>The <code>-XX:[+|-]PortableSharedCache</code> option is now supported on IBM Z\u00ae and POWER\u00ae platforms. AOT-compiled code that is generated with this option is guaranteed to be portable across IBM z10 or newer microarchitectures on IBM Z platforms and IBM POWER8\u00ae or newer microarchitectures on POWER platforms. See <code>-XX:[+|-]PortableSharedCache</code> for more details about this option.</p>"},{"location":"version0.24/#-xx-shareanonymousclasses-option-behavior-update","title":"<code>-XX:[+|-]ShareAnonymousClasses</code> option behavior update","text":"<p>In earlier releases of OpenJ9, the <code>-XX:[+|-]ShareAnonymousClasses</code> option enables and disables the storage of VM anonymous classes in the shared classes cache. From OpenJ9 0.24.0 for OpenJDK 15 binaries, this option also controls the storage of hidden classes. See <code>-XX:[+|-]ShareAnonymousClasses</code> for more details about this option.</p>"},{"location":"version0.24/#additional-parameters-for-jcmd-dump-commands","title":"Additional parameters for <code>jcmd Dump</code> commands","text":"<p>You can now include additional parameters for <code>jcmd Dump</code> commands as indicated in the following list:</p> <ul> <li><code>Dump.system</code>, <code>Dump.heap</code>, <code>Dump.java</code>, and <code>Dump.snap</code> accept an optional <code>request=&lt;requests&gt;</code> parameter.</li> <li><code>Dump.heap</code> accepts an optional <code>opts=&lt;options&gt;</code> parameter.</li> </ul> <p>These parameters, including the <code>&lt;file path&gt;</code> parameter, can be in any order. The default for both system and heap dumps is now: <code>request=exclusive+prepwalk</code>. For further details, refer to the following <code>-Xdump</code> suboptions: <code>request=&lt;requests&gt;</code> and <code>opts=&lt;options&gt;</code>. For more information about <code>jcmd</code>, see Java diagnostic command (jcmd) tool.</p>"},{"location":"version0.24/#change-in-behavior-for-the-jextract-utility","title":"Change in behavior for the <code>jextract</code> utility","text":"<p>The <code>jextract</code> utility gathers relevant files following a system dump to assist with problem determination. It is important that the <code>jextract</code> utility is run from the same SDK that generated the dump. From this release, if the build ID of the <code>jextract</code> utility does not match the build ID of the SDK that is recorded in the system dump, an exception message is generated. To force <code>jextract</code> to continue, a new option, <code>-r</code>, is introduced. For more information, see Dump extractor.</p>"},{"location":"version0.24/#new-diagnostic-suboption-for-xcheckjni-for-fatal-jni-errors","title":"New diagnostic suboption for <code>-Xcheck:jni</code> for fatal JNI errors","text":"<p>A new <code>abortonerror</code> suboption for <code>-Xcheck:jni</code> provides diagnostic data when fatal JNI errors occur. For more information, run <code>-Xcheck:jni:help</code>.</p>"},{"location":"version0.24/#improved-diagnostic-information-in-a-java-dump-file-on-processor-features","title":"Improved diagnostic information in a Java dump file on processor features","text":"<p>The ENVINFO section of a Java dump file now includes further information about processor features. This information helps to diagnose problems associated with JIT and AOT compilations that depend on underlying hardware. For an example that shows the information provided when JIT is enabled, see the CPU Information (<code>2CIJITFEATURE</code>,<code>2CIAOTFEATURE</code>) section in the Java dump topic.</p>"},{"location":"version0.24/#helm-chart-available-for-deploying-jitserver","title":"Helm chart available for deploying JITServer","text":"<p>A Helm Chart is now available for easier deployment of JITServer technology in a Kubernetes or OpenShift cluster. You can find the chart (openj9-jitserver-chart) in the JITServer Helm repository, which contains a complete set of usage instructions. For an introduction to JITServer technology, see JITServer (tech. preview).</p>"},{"location":"version0.24/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.23.0 and version 0.24.0 releases, see the Release notes.</p>"},{"location":"version0.25/","title":"Version 0.25.0","text":""},{"location":"version0.25/#whats-new-in-version-0250","title":"What's new in version 0.25.0","text":"<p>The following new features and notable changes since version 0.24.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> New JDK 16 features</li> <li> Support for the <code>-verbose:module</code> option</li> <li>Enabling <code>zlibNX</code> hardware-accelerated data compression and decompression on AIX</li> <li>z/OS support for the <code>%sysname</code> dump token</li> <li>Single build for compressed references and non-compressed references</li> </ul>"},{"location":"version0.25/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.25/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.25.0 supports OpenJDK 16. OpenJDK 16 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>Although it might be possible to build an OpenJDK 8 or OpenJDK 11 with OpenJ9 release 0.25.0, testing at the project is not complete and therefore support for new features that apply to these Java versions is not available.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.25/#new-jdk-16-features","title":"New JDK 16 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 338: Vector API (incubator)<ul> <li>OpenJ9 adds optimizations for this feature.</li> </ul> </li> <li>JEP 390: Warnings for value-based classes<ul> <li>OpenJ9 adds option <code>-XX:DiagnoseSyncOnValueBasedClasses=&lt;number&gt;</code> for compatibility with the reference implementation.</li> </ul> </li> <li>JEP 395: Records</li> <li>JEP 397: Sealed Classes (second preview)</li> </ul> <p>The following features will be supported by OpenJ9 in a future release:</p> <ul> <li>JEP 389: Foreign linker API (incubator)</li> <li>JEP 393: Foreign-memory access API (third incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any builds of OpenJDK 16 with OpenJ9:</p> <ul> <li>JEP 347: Enable C++ 14 language features</li> <li>JEP 380: Unix-domain socket channels</li> <li>JEP 394: Pattern matching for <code>instanceof</code></li> <li>JEP 396: Strongly encapsulate JDK internals by default</li> <li>JEP 392: Packaging tool<ul> <li>(Linux\u00ae, macOS\u00ae, and Windows\u2122 only) Promoted from incubation to a production-ready feature in this release. See Using <code>jpackage</code> for details.</li> </ul> </li> </ul> <p>You can find the full list of features for JDK 16 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p> <p> Note: Applications might be adversely affected by JEP 396 if they make use of internal APIs. You should update your application to use standard APIs. To temporarily work around this problem, set <code>--illegal-access=permit</code> on the command line, which prints a warning that is similar to the following example when an illegal access call is made:</p> <pre><code>WARNING: An illegal reflective access operation has occurred\nWARNING: Illegal reflective access by org.openj9.test.com.ibm.jit.Test_JITHelpers (file:/home/jenkins/workspace/Test_openjdk11_j9.functional_ppc64_aix_Nightly_testList_1/jvmtest/functional/Java8andUp/GeneralTest.jar) to field java.lang.String.value\nWARNING: Please consider reporting this to the maintainers of org.openj9.test.com.ibm.jit.Test_JITHelpers\nWARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations\nWARNING: All illegal access operations will be denied in a future release\n</code></pre>"},{"location":"version0.25/#support-for-the-verbosemodule-option","title":"Support for the <code>-verbose:module</code> option","text":"<p>The <code>-verbose:module</code> option is now supported for Java 11 and later releases. This option writes information to <code>stderr</code> for each module that is loaded and unloaded.</p>"},{"location":"version0.25/#enabling-zlibnx-hardware-accelerated-data-compression-and-decompression-on-aix","title":"Enabling <code>zlibNX</code> hardware-accelerated data compression and decompression on AIX","text":"<p>By default, AIX\u00ae uses the system <code>zlib</code> library for data compression and decompression.</p> <p>On systems that contain the Nest accelerator (NX) co-processor, OpenJ9 now uses the <code>zlibNX</code> library instead, if it is installed. To learn more about hardware acceleration and the <code>zlibNX</code> library, see Hardware acceleration.</p>"},{"location":"version0.25/#zos-support-for-the-sysname-dump-token","title":"z/OS support for the <code>%sysname</code> dump token","text":"<p>The <code>%sysname</code> dump token is added on z/OS, which equates to the SYSNAME sysparm. See Dump agent tokens.</p>"},{"location":"version0.25/#single-build-for-compressed-references-and-non-compressed-references","title":"Single build for compressed references and non-compressed references","text":"<p>A single build now supports both compressed references and non-compressed references. The object reference mode is selected at run time based on the specified heap size (<code>-Xmx</code>) or by using command-line options that control the selection of compressed references.</p> <p>If you used a large heap build for an earlier release of OpenJ9 because you did not require compressed references, you might need to turn it off if compressed references mode is being selected automatically at run time. Use the <code>-Xnocompressedrefs</code> option when you start your application.</p> <p>The <code>compressedrefs</code> directory is no longer present in the single build.</p> <p>To learn about the benefits of using compressed references, see Compressed references.</p>"},{"location":"version0.25/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.24.0 and version 0.25.0 releases, see the Release notes.</p>"},{"location":"version0.26/","title":"Version 0.26.0","text":""},{"location":"version0.26/#whats-new-in-version-0260","title":"What's new in version 0.26.0","text":"<p>The following new features and notable changes since version 0.25.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Dump extractor tool deprecated</li> </ul>"},{"location":"version0.26/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.26/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.26.0 supports OpenJDK 8, 11, and 16.</p> <p>For OpenJDK 8 and 11 builds that contain OpenJ9, see Version 0.25.0 for additional changes that have now been fully tested for these versions.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.26/#dump-extractor-tool-deprecated","title":"Dump extractor tool deprecated","text":"<p>The dump extractor tool, <code>jextract</code>, is deprecated in this release and replaced with the <code>jpackcore</code> tool. This tool uses the same syntax and parameters as <code>jextract</code> to collect diagnostic files for analysis. The change is necessary because the reference implementation will be introducing a tool in a future release that is also called <code>jextract</code>.</p> <p>For more information, see Dump extractor.</p>"},{"location":"version0.26/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.25.0 and v0.26.0 releases, see the Release notes.</p>"},{"location":"version0.27/","title":"Version 0.27.1","text":""},{"location":"version0.27/#whats-new-in-version-0271","title":"What's new in version 0.27.1","text":"<p>The following new features and notable changes since version 0.26.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New <code>-XX:[+|-]AdaptiveGCThreading</code> option added</li> <li>Improved time zone information added to Java dump files</li> <li>Change in default behavior for the <code>balanced</code> garbage collection policy</li> <li>Stop parsing the JAVA_OPTIONS environment variable</li> <li>Global lock reservation enabled by default</li> <li>Increase in default operating system stack size on PPC64 platforms</li> <li>New <code>-x</code> option added to <code>jpackcore</code> / <code>jextract</code></li> </ul>"},{"location":"version0.27/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.27/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.27.1 supports OpenJDK 8, 11, and 16.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.27/#new-xx-adaptivegcthreading-option-added","title":"New <code>-XX:[+|-]AdaptiveGCThreading</code> option added","text":"<p>Adaptive threading is enabled by default, which automatically tunes the number of active parallel garbage collection (GC) threads. When this feature is enabled, the GC thread count is dynamically adjusted from collection cycle to cycle to account for changes in the the amount of time that parallel threads spend doing useful GC work (such as object graph traversal) compared to time spent synchronizing among themselves. When GC work decreases, fewer threads are used, which reduces the overhead, effectively reducing GC pause times. Resources are freed up for other processing activities.</p> <p>Use the <code>-xgcmaxthreads</code> option with the <code>-XX:+AdaptiveGCThreading</code> option to specify a thread count limit.</p>"},{"location":"version0.27/#improved-time-zone-information-added-to-java-dump-files","title":"Improved time zone information added to Java dump files","text":"<p>To help with troubleshooting, additional time zone information is added to Java\u2122 dump files. Two new fields are included, the date and time in UTC (<code>1TIDATETIMEUTC</code>) and the time zone according to the local system (<code>1TITIMEZONE</code>). For more information, see the Java dump <code>TITLE</code> section.</p>"},{"location":"version0.27/#change-in-default-behavior-for-the-balanced-garbage-collection-gc-policy","title":"Change in default behavior for the <code>balanced</code> garbage collection (GC) policy","text":"<p>In this release, a new scan mode, <code>-Xgc:dynamicBreadthFirstScanOrdering</code>, is used during <code>balanced</code> GC copy forward operations that is expected to improve performance.</p> <p>For more information about this type of operation, see GC copy forward operation.</p> <p>You can revert to the behavior in earlier releases by setting <code>-Xgc:breadthFirstScanOrdering</code> when you start your application.</p>"},{"location":"version0.27/#stop-parsing-the-java_options-environment-variable","title":"Stop parsing the JAVA_OPTIONS environment variable","text":"<p>The 0.24 release started parsing the JAVA_OPTIONS environment variable. This variable was added in error and has been removed. The _JAVA_OPTIONS environment variable (with different behavior) is added for compatibility.</p>"},{"location":"version0.27/#global-lock-reservation-enabled-by-default","title":"Global lock reservation enabled by default","text":"<p>(AIX\u00ae and Linux on Power Systems\u2122 only)</p> <p>Global lock reservation is now enabled by default. This is an optimization targeted towards more efficient handling of locking and unlocking Java objects. The older locking behavior can be restored via the <code>-XX:-GlobalLockReservation</code> option. See -XX:[+|-]GlobalLockReservation for more details.</p>"},{"location":"version0.27/#increase-in-default-operating-system-stack-size-on-ppc64-platforms","title":"Increase in default operating system stack size on PPC64 platforms","text":"<p>The default operating system stack size on AIX and Linux PPC64 is increased from 256KB to 512KB. You can change the operating system stack size by using the -Xmso option.</p>"},{"location":"version0.27/#new-x-option-recognized-by-jpackcore-jextract","title":"New <code>-x</code> option recognized by <code>jpackcore</code> / <code>jextract</code>","text":"<p>The new option, <code>-x</code>, causes the system dump to be omitted from the archive created. In its place, the file <code>excluded-files.txt</code> is added, which names the excluded file. For more information, see Dump extractor.</p>"},{"location":"version0.27/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.26.0 and v0.27.1 releases, see the Release notes.</p>"},{"location":"version0.29.1/","title":"Version 0.29.1","text":""},{"location":"version0.29.1/#whats-new-in-version-0291","title":"What's new in version 0.29.1","text":"<p>The following new features and notable changes since version 0.29.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> New JDK 17 features</li> </ul>"},{"location":"version0.29.1/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.29.1/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.29.1 supports OpenJDK 17.</p> <p>AArch64 Linux is now a fully supported, production-ready target for OpenJDK 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.29.1/#new-jdk-17-features","title":"New JDK 17 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 409: Sealed Classes<ul> <li>Promoted from preview to a production-ready feature in this release.</li> </ul> </li> <li>JEP 411: Deprecate the Security Manager for Removal</li> </ul> <p>The following features will be supported by OpenJ9 in a future release:</p> <ul> <li>JEP 391: macOS/AArch64 Port</li> <li>JEP 412: Foreign Function &amp; Memory API (Incubator)</li> <li>JEP 414: Vector API (Second Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 17 with OpenJ9:</p> <ul> <li> <p>JEP 306: Restore Always-Strict Floating-Point Semantics</p> </li> <li> <p>JEP 356: Enhanced Pseudo-Random Number Generators</p> </li> <li>JEP 382: New macOS Rendering Pipeline</li> <li>JEP 398: Deprecate the Applet API for Removal</li> <li>JEP 403: Strongly Encapsulate JDK Internals</li> <li>JEP 406: Pattern Matching for switch (Preview)</li> <li>JEP 407: Remove RMI Activation</li> <li>JEP 415: Context-Specific Deserialization Filters</li> </ul> <p>You can find the full list of features for JDK 17 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p> <p> Note: Applications might be adversely affected by JEP 403 if they make use of internal APIs. You should update your application to use standard APIs. To temporarily work around this problem, use <code>--add-opens</code>, <code>--add-exports</code> on the command line for each package required.</p>"},{"location":"version0.29.1/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.29.0 and v0.29.1 releases, see the Release notes.</p>"},{"location":"version0.29/","title":"Version 0.29.0","text":""},{"location":"version0.29/#whats-new-in-version-0290","title":"What's new in version 0.29.0","text":"<p>The following new features and notable changes since version 0.27.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>JITServer technology is fully supported on some  systems</li> <li>New <code>-XX:[+|-]UTFCache</code> option added</li> <li><code>-Xsoftmx</code> updates for gencon</li> </ul>"},{"location":"version0.29/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.29/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.29.0 supports OpenJDK 8 and 11.</p> <p>AArch64 Linux is now a fully supported, production-ready target for OpenJDK 8 and 11.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.29/#jitserver-technology-is-fully-supported-on-some-systems","title":"JITServer technology is fully supported on some systems","text":"<p>JITServer technology is now a fully supported feature on Linux\u00ae on x86 and Linux on IBM Power\u00ae systems (64-bit only). This feature remains a technical preview for Linux on IBM Z\u00ae systems (64-bit only). For more information, see JITServer technology.</p>"},{"location":"version0.29/#new-xx-utfcache-option-added","title":"New <code>-XX:[+|-]UTFCache</code> option added","text":"<p>A UTF to String cache is added to enhance reflection performance. The cache is enabled by default but can be disabled using the <code>-XX:[+|-]UTFCache</code> option.</p>"},{"location":"version0.29/#-xsoftmx-updates-for-gencon","title":"<code>-Xsoftmx</code> updates for gencon","text":"<p>When using gencon, the <code>-Xsoftmx</code> limit is proportional to the maximum amount of nursery space specified relative to the <code>-Xmx</code> value.</p>"},{"location":"version0.29/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 v0.27.0 and v0.29.0 releases, see the Release notes.</p>"},{"location":"version0.30.1/","title":"Version 0.30.1","text":""},{"location":"version0.30.1/#whats-new-in-version-0301","title":"What's new in version 0.30.1","text":"<p>The following new features and notable changes since version 0.30.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Creation of system dumps on macOS 12</li> </ul>"},{"location":"version0.30.1/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.30.1/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.30.1 supports OpenJDK 8, 11 and 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.30.1/#creation-of-system-dumps-on-macos-12","title":"Creation of system dumps on macOS 12","text":"<p>Creation of system (core) dumps on macOS 12 or later is now possible.</p>"},{"location":"version0.30.1/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.30.0 and v0.30.1 releases, see the Release notes.</p>"},{"location":"version0.30/","title":"Version 0.30.0","text":""},{"location":"version0.30/#whats-new-in-version-0300","title":"What's new in version 0.30.0","text":"<p>The following new features and notable changes since version 0.29.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Changes to the shared classes cache generation number</li> <li>Ignored options now captured in java dumps</li> <li>New <code>-XX:[+|-]EnsureHashed</code> option added</li> <li>Redesigned heap resizing for the <code>balanced</code> GC policy</li> </ul>"},{"location":"version0.30/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.30/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.30.0 supports OpenJDK 8, 11 and 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.30/#changes-to-the-shared-classes-cache-generation-number","title":"Changes to the shared classes cache generation number","text":"<p>The format of classes that are stored in the shared classes cache is changed, which causes the JVM to create a new shared classes cache rather than re-creating or reusing an existing cache. To save space, you can remove all existing shared caches unless they are in use by an earlier release. For more information about the <code>-Xshareclasses</code> option, including the <code>destroy</code> options that you can use to remove caches, see <code>-Xshareclasses</code>.</p>"},{"location":"version0.30/#ignored-options-captured-in-java-dumps","title":"Ignored options captured in java dumps","text":"<p>For improved compatibility with other Java implementations, OpenJ9 ignores many command-line options. If any were ignored, they are now listed in the java dump files. For example, the command</p> <pre>\njava -Xdump:java:events=vmstop -XX:+UseCompressedOop -XX:CompressedClassSpaceSize=528482304 -version\n</pre> <p>would yield the following in the ENVINFO section after the complete list of all command-line arguments</p> <pre>\n1CIIGNOREDARGS Ignored Args:\n2CIIGNOREDARG            -XX:+UseCompressedOop\n2CIIGNOREDARG            -XX:CompressedClassSpaceSize=528482304\n</pre>"},{"location":"version0.30/#new-xx-ensurehashed-option-added","title":"New <code>-XX:[+|-]EnsureHashed</code> option added","text":"<p>This option specifies the classes whose objects should be assigned hash values or those classes that should be ignored. This option might improve performance for applications that frequently hash objects of a certain type. See -XX:[+|-]EnsureHashed for more details.</p>"},{"location":"version0.30/#redesigned-heap-resizing-for-the-balanced-gc-policy","title":"Redesigned heap resizing for the <code>balanced</code> GC policy","text":"<p>Heap resizing heuristics have been redesigned for the <code>balanced</code> GC policy. This includes both total heap resizing including eden and non-eden components independently, and also balancing between these two components when the heap is fully expanded. The heuristics now combine both the CPU overhead (for Partial GCs as well as Global Mark Phase) and the heap occupancy criteria. The balancing between eden and non-eden for fully expanded heaps is far more dynamic (instead of being mostly fixed in the ratio 1:4).</p> <p>As a consequence, there should typically be less need for heap sizing tuning options, most notably for eden sizing options -Xmn, -Xmns, and -Xmnx.</p> <p>Also, a new soft limit pause target is added for Partial GCs, which defaults to 200ms. This criterion is combined with the PGC CPU overhead criterion for a balanced compromise between minimizing footprint, maximizing throughput, and meeting the paused time target.</p> <p>More details about the new heuristics can be found at:</p> <p>https://blog.openj9.org/2021/09/24/balanced-gc-performance-improvements-eden-heap-sizing-improvements/</p> <p>The heuristics now obey the following existing options that were previously used for the <code>optthruput</code>, <code>optavgpause</code>, and <code>gencon</code> GC policies:</p> <ul> <li>-Xmint/-Xmaxt</li> <li>-Xgc:dnssExpectedTimeRatioMaximum/Minimum</li> </ul> <p>The heuristics also use the -Xgc:targetPausetime option that was previously used only for the <code>metronome</code> GC policy.</p> <p>For more information about GC policies, see Garbage collection policies.</p>"},{"location":"version0.30/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.29.0 and v0.30.0 releases, see the Release notes.</p>"},{"location":"version0.32/","title":"Version 0.32.0","text":""},{"location":"version0.32/#whats-new-in-version-0320","title":"What's new in version 0.32.0","text":"<p>The following new features and notable changes since version 0.30.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Creation of system dumps on macOS 12</li> <li>Support for OpenJDK HotSpot options</li> <li><code>SharedClassStatistics</code> API updated</li> <li>Support for OpenSSL 3.0.x</li> <li>New <code>-XX:[+|-]OpenJ9CommandLineEnv</code> option added</li> <li>JITServer technology support for Linux on IBM Z\u00ae systems</li> <li> Modified default value for <code>-XX:MaxDirectMemorySize</code></li> <li> New JDK 18 features</li> </ul>"},{"location":"version0.32/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.32/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.32.0 supports OpenJDK 8, 11, 17, and 18.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.32/#creation-of-system-dumps-on-macos-12","title":"Creation of system dumps on macOS\u00ae 12","text":"<p>You can now create system (core) dumps on macOS 12 or later.</p>"},{"location":"version0.32/#support-for-openjdk-hotspot-options","title":"Support for OpenJDK HotSpot options","text":"<p>For compatibility, the following OpenJDK HotSpot options are now supported by OpenJ9:</p> <ul> <li><code>-XX:[+|-]ShowHiddenFrames</code>. This option specifies whether generated hidden <code>MethodHandle</code> frames are displayed in a stack trace.</li> </ul>"},{"location":"version0.32/#sharedclassstatistics-api-updated","title":"<code>SharedClassStatistics</code> API updated","text":"<p>You can now use the <code>SharedClassStatistics</code> API to get the name, path, and directory of a shared classes cache. Depending on the operating system, you can also get the number of attached VMs for a non-persistent cache. This information is available through the following new methods: <code>cacheDir()</code>, <code>cacheName()</code>, <code>cachePath()</code>, and <code>numberAttached()</code>. For more information, see the API documentation.</p>"},{"location":"version0.32/#support-for-openssl-30x","title":"Support for OpenSSL 3.0.x","text":"<p>OpenSSL 3.0.x is supported but on Linux only. The JITServer technology feature currently does not support OpenSSL 3.0.x. For more information about OpenSSL support, see <code>Cryptographic operations</code>.</p>"},{"location":"version0.32/#new-xx-openj9commandlineenv-option-added","title":"New <code>-XX:[+|-]OpenJ9CommandLineEnv</code> option added","text":"<p>This option specifies whether the VM captures the command line in the environment variable <code>OPENJ9_JAVA_COMMAND_LINE</code>. For more information, see <code>-XX:[+|-]OpenJ9CommandLineEnv</code>.</p>"},{"location":"version0.32/#jitserver-support-for-linux-on-ibm-z-systems","title":"JITServer support for Linux on IBM Z\u00ae systems","text":"<p>JITServer technology is now a fully supported feature on Linux on IBM Z\u00ae systems (64-bit only). For more information, see JITServer technology.</p>"},{"location":"version0.32/#modified-default-value-for-xxmaxdirectmemorysize","title":"Modified default value for <code>-XX:MaxDirectMemorySize</code>","text":"<p>The default value of the <code>-XX:MaxDirectMemorySize</code> option, which limits the amount of heap memory that is used for direct byte buffers, is now the same as the maximum heap size.</p>"},{"location":"version0.32/#new-jdk-18-features","title":"New JDK 18 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 400: UTF-8 by Default</li> <li>JEP 416: Reimplement Core Reflection with Method Handles</li> <li>JEP 421: Deprecate Finalization for Removal</li> </ul> <p>The following features will be supported by OpenJ9 in a future release:</p> <ul> <li>JEP 391: macOS/AArch64 Port<ul> <li>An early access build is available in this release</li> </ul> </li> <li>JEP 417: Vector API (Third Incubator)</li> <li>JEP 419: Foreign Function &amp; Memory API (Second Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 18 with OpenJ9:</p> <ul> <li>JEP 408: Simple Web Server</li> <li>JEP 413: Code Snippets in Java API Documentation</li> <li>JEP 418: Internet-Address Resolution SPI</li> <li>JEP 420: Pattern Matching for switch (Second Preview)</li> </ul> <p>You can find the full list of features for JDK 18 at the OpenJDK project.</p>"},{"location":"version0.32/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.30.0 and v0.32.0 releases, see the Release notes.</p>"},{"location":"version0.33/","title":"Version 0.33.x","text":""},{"location":"version0.33/#whats-new-in-version-033x","title":"What's new in version 0.33.x","text":"<p>The following new features and notable changes since version 0.32.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>JITServer technology feature updated</li> <li> XL C++ Runtime required on AIX</li> <li> Linux reference compiler updated to gcc 10.3</li> <li>The maximum number of JIT compilation threads is increased</li> <li> Default operating system stack size increased on x64 platforms</li> <li>Control groups v2 support</li> <li>Support for OpenSSL 3.0.x</li> <li>EC key agreement algorithm support for OpenSSL</li> </ul>"},{"location":"version0.33/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.33/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.33.x supports OpenJDK 8, 11, 17, and 18.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 8 are now compiled with Microsoft\u00ae Visual Studio 2017. The Visual Studio redistributable files included with the build are updated to match.</p> <p> Note: Binaries that are labeled 0.33.1 include additional bug fixes. For more information, see the release notes.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.33/#jitserver-technology-feature-updated","title":"JITServer technology feature updated","text":"<p>The JITServer technology feature is updated to provide the following new capabilities, which are disabled by default:</p> <ul> <li>The caching of AOT-compiled methods on the server. The AOT cache improves CPU usage when clients request the compilation of methods that were previously cached. Use the <code>-XX:+JITServerUseAOTCache</code> command line option to enable this feature. Use the <code>-XX:JITServerAOTCacheName</code> option to specify the name of the AOT cache to be used at the JITServer server.</li> <li>The provision of metrics to a monitoring tool that follows the OpenMetrics standard. The following metrics are available for a JITServer server: CPU usage, available memory, number of clients connected, and number of active compilation threads. Use the <code>-XX:+JITServerMetrics</code> command line option to enable this feature.</li> </ul>"},{"location":"version0.33/#xl-c-runtime-required-on-aix","title":"XL C++ Runtime required on AIX","text":"<p>AIX OpenJ9 builds now require version 16.1 of the IBM XL C++ Runtime. This was already required for OpenJDK 17 and is now also required from 11.0.16 to accommodate a security update to the HarfBuzz text shaping library.</p>"},{"location":"version0.33/#linux-reference-compiler-updated-to-gcc-103","title":"Linux reference compiler updated to gcc 10.3","text":"<p>Linux\u00ae builds for all platforms now use gcc 10.3 instead of gcc 7.5. See the list of build environments.</p>"},{"location":"version0.33/#the-maximum-number-of-jit-compilation-threads-is-increased","title":"The maximum number of JIT compilation threads is increased","text":"<p>The maximum number of JIT compilation threads is increased from 7 to 15. If the JITServer feature is enabled, the maximum number of JIT compilation threads is increased further on the server, to 999. You can set the number of compilation threads to be used by specifying the <code>-XcompilationThreads</code> command line option.</p>"},{"location":"version0.33/#default-operating-system-stack-size-increased-on-x64-platforms","title":"Default operating system stack size increased on x64 platforms","text":"<p>The default operating system stack size on Windows x64, macOS\u00ae x64, and Linux x64 platforms is increased from 256 KB to 512 KB to accommodate vector support. You can change the operating system stack size by using the -Xmso option.</p>"},{"location":"version0.33/#control-groups-v2-support","title":"Control groups v2 support","text":"<p>The Linux kernel has two variants of control groups (cgroups): v1 and v2. Many Linux operating systems are gradually transitioning from cgroups v1 to v2 as their default choice. Now, OpenJ9 has added cgroups v2 support, which is identical to the support for cgroups v1.</p>"},{"location":"version0.33/#support-for-openssl-30x","title":"Support for OpenSSL 3.0.x","text":"<p>The JITServer technology feature now supports OpenSSL 3.0.x. For more information about OpenSSL support, see <code>Cryptographic operations</code>.</p>"},{"location":"version0.33/#ec-key-agreement-algorithm-support-for-openssl","title":"EC key agreement algorithm support for OpenSSL","text":"<p>The EC key agreement algorithm can now use the native OpenSSL library. For more information, see <code>-Djdk.nativeEC</code>.</p>"},{"location":"version0.33/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.32.0 and v0.33.x, see the Release notes.</p>"},{"location":"version0.35/","title":"Version 0.35.0","text":""},{"location":"version0.35/#whats-new-in-version-0350","title":"What's new in version 0.35.0","text":"<p>The following new features and notable changes since version 0.33.1 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Java\u2122 dump files contain more information about waiting threads</li> <li>New <code>-XX:[+|-]ShowNativeStackSymbols</code> option added</li> <li>New <code>user2</code> event added for the <code>-Xdump</code> option</li> <li>New <code>-XX:[+|-]PerfTool</code> option added</li> <li>New default options added in the <code>options.default</code> file</li> <li>New options added to encrypt the JITServer exported metrics</li> <li> XL C++ Runtime 16.1.0.7 or later required on AIX</li> <li><code>-XX:[+|-]JITServerLocalSyncCompiles</code> enabled by default</li> <li> Support for changes to the maintenance specifications of JSR 337 in Java 8</li> </ul>"},{"location":"version0.35/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.35/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.35.0 supports OpenJDK 8, 11, and 17.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 11 are now compiled with Microsoft\u00ae Visual Studio 2019. The Visual Studio redistributable files included with the build are updated to match.</p> <p>Apple silicon macOS\u00ae is now a fully supported, production-ready target for OpenJDK 11 and later.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.35/#java-dump-files-contain-more-information-about-waiting-threads","title":"Java dump files contain more information about waiting threads","text":"<p>For threads that are waiting for a class initialization lock, the Java dump output now shows the thread that is currently working to progress the initialization of the class. This thread is indicated by the new <code>Initializing thread: &lt;thread_name&gt;</code> string in the existing <code>3XMTHREADBLOCK</code> line in the Java dump output. For example:</p> <p><code>3XMTHREADBLOCK Waiting on: java/lang/J9VMInternals$ClassInitializationLock@0x00000000FFF5DC90 Owned by: &lt;unowned&gt; Initializing thread: \"Class Initialization Thread 1\"</code></p> <p>For more information, see Threads.</p>"},{"location":"version0.35/#new-xx-shownativestacksymbols-option-added","title":"New <code>-XX:[+|-]ShowNativeStackSymbols</code> option added","text":"<p>This option controls whether Java dumps show the names of functions in native call stacks.</p> <p>For more information, see <code>-XX:[+|-]ShowNativeStackSymbols</code>.</p>"},{"location":"version0.35/#new-user2-event-added-for-the-xdump-option","title":"New <code>user2</code> event added for the <code>-Xdump</code> option","text":"<p>On operating systems other than Windows\u2122, you can now use the <code>user2</code> event for the <code>-Xdump</code> option. This event is triggered when the VM receives the <code>SIGUSR2</code> signal.</p> <p>There is a change in the <code>SIGUSR2</code> signal behavior as well whereby, the process does not exit in response to this signal.</p> <p>For more information, see <code>-Xdump</code> and Signal handling.</p>"},{"location":"version0.35/#new-xx-perftool-option-added","title":"New <code>-XX:[+|-]PerfTool</code> option added","text":"<p>This option enables or disables the JIT support for the <code>perf</code> tool without affecting the existing <code>Xjit</code> options.</p> <p>Since this option creates a file that is used by the Linux\u00ae system profiler, <code>perf</code>, it applies only to Linux.</p> <p>For more information, see <code>-XX:[+|-]PerfTool</code>.</p>"},{"location":"version0.35/#new-default-options-added-in-the-optionsdefault-file","title":"New default options added in the <code>options.default</code> file","text":"<p><code>-XX:+EnsureHashed:java/lang/Class,java/lang/Thread</code> is added to the list of default options in the <code>options.default</code> file to improve performance.</p> <p>For more information, see <code>XX:[+|-]EnsureHashed</code>.</p>"},{"location":"version0.35/#new-options-added-to-encrypt-the-jitserver-exported-metrics","title":"New options added to encrypt the JITServer exported metrics","text":"<p>You can use the <code>-XX:JITServerMetricsSSLKey</code> and <code>-XX:JITServerMetricsSSLCert</code> options to encrypt the custom metrics with TLS or SSL.</p>"},{"location":"version0.35/#xl-c-runtime-16107-or-later-required-on-aix","title":"XL C++ Runtime 16.1.0.7 or later required on AIX","text":"<p>AIX OpenJ9 builds now require version 16.1.0.7 or later of the IBM XL C++ Runtime.</p>"},{"location":"version0.35/#-xx-jitserverlocalsynccompiles-enabled-by-default","title":"<code>-XX:[+|-]JITServerLocalSyncCompiles</code> enabled by default","text":"<p>The <code>-XX:[+|-]JITServerLocalSyncCompiles</code> option is now enabled in most cases. For more information, see <code>-XX:[+|-]JITServerLocalSyncCompiles</code>.</p>"},{"location":"version0.35/#support-for-changes-to-the-maintenance-specifications-of-jsr-337-in-java-8","title":"Support for changes to the maintenance specifications of JSR 337 in Java 8","text":"<p>OpenJ9 now supports changes to the maintenance specifications in Java 8 as listed in the JSR 337 Maintenance Release 4 document.</p> <p>These changes include the change in the garbage collector behavior for handling the phantom references in Java 8. The garbage collector handles both the phantom as well as the weak references similarly, which is the current behavior in Java 11 and later. For more information, see Weak reference processing.</p>"},{"location":"version0.35/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.33.1 and v0.35.0 releases, see the Release notes.</p>"},{"location":"version0.36/","title":"Version 0.36.x","text":""},{"location":"version0.36/#whats-new-in-version-036x","title":"What's new in version 0.36.x","text":"<p>The following new features and notable changes since version 0.35.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>Changes to the location of the default directory for the shared cache and snapshot</li> <li>New <code>-XX:[+|-]MergeCompilerOptions</code> option added</li> <li>Default JITServer AOT cache name changed</li> <li>New <code>-XX:JITServerAOTmx</code> option added</li> <li>New <code>-XX:[+|-]JITServerAOTCachePersistence</code> option added</li> <li>New <code>-XX:JITServerAOTCacheDir</code> option added</li> </ul>"},{"location":"version0.36/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.36/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.36.0 supports OpenJDK 8 and 17.</p> <p>Release 0.36.1 supports OpenJDK 11.</p> <p>Support for running OpenJ9 with OpenJDK 8 or OpenJDK 11 on CentOS 6.10 is deprecated and might be removed in a future release. OpenJ9 will not be tested with OpenJDK 11 on CentOS 6.10 after the 0.36.1 release.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.36/#changes-to-the-location-of-the-default-directory-for-the-shared-cache-and-snapshot","title":"Changes to the location of the default directory for the shared cache and snapshot","text":"<p>On operating systems other than Windows\u2122 and z/OS\u00ae, the default shared classes cache directory in the user's home directory is changed from <code>javasharedresources</code> to <code>.cache/javasharedresources</code>. This change is to avoid cluttering of the home directory. If you specify <code>-Xshareclasses:groupAccess</code>, the default directory remains <code>/tmp/javasharedresources/</code>.</p> <p>If the <code>javasharedresources</code> directory in the user's home directory is empty, the <code>javasharedresources</code> directory can be deleted.</p> <p>You can find and remove caches or snapshots in the old default directory by using the following command-line options:</p> <p>For persistent caches:</p> <ul> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,listAllCaches</code> to find the caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,name=&lt;cacheName&gt;,destroy</code> to remove a particular cache</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,destroyAll</code> to remove all caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;/javasharedresources/,destroyAllLayers</code> to remove multi-layer caches</li> </ul> <p>For nonpersistent caches or snapshots:</p> <ul> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,listAllCaches</code> to find the cache or snapshot</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,name=&lt;cacheName&gt;,destroy</code> to remove a particular shared cache</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,destroyAll</code> to remove all caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,destroyAllLayers</code> to remove multi-layer caches</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,name=&lt;snapshotName&gt;,destroySnapshot</code> to remove a particular snapshot</li> <li><code>-Xshareclasses:cacheDir=&lt;HomeDir&gt;,destroyAllSnapshots</code> to remove all snapshots</li> </ul>"},{"location":"version0.36/#new-xx-mergecompileroptions-option-added","title":"New <code>-XX:[+|-]MergeCompilerOptions</code> option added","text":"<p>This option enables or disables the merging of multiple <code>-Xjit</code> or <code>-Xaot</code> options into a single <code>-Xjit</code> or <code>-Xaot</code> option.</p> <p>For more information, see <code>-XX:[+|-]MergeCompilerOptions</code>.</p>"},{"location":"version0.36/#default-jitserver-aot-cache-name-changed","title":"Default JITServer AOT cache name changed","text":"<p>A JITServer instance can have several AOT caches, each with its own name and containing different versions of compiled methods. Client JVMs with different profiles of execution can connect to the same JITServer instance, but access the cache with compiled methods optimized for their own profile with the <code>-XX:JITServerAOTCacheName</code> option. Earlier, if the cache name was not specified in this option, the default was to use a nameless cache. The default AOT cache name is now changed to <code>default</code>.</p> <p>This change is to allow AOT cache persistence, whereby JITServer can periodically save its AOT caches to files with names that include the name of the cache. JITServer can then load caches from such files when a client requests a particular cache.</p> <p>For more information, see <code>-XX:JITServerAOTCacheName</code> and <code>-XX:[+|-]JITServerAOTCachePersistence</code>.</p>"},{"location":"version0.36/#new-xxjitserveraotmx-option-added","title":"New <code>-XX:JITServerAOTmx</code> option added","text":"<p>This option specifies the maximum amount of memory that can be used by the JITServer AOT cache. Instead of unlimited memory consumption, the maximum amount of memory that all AOT cache instances combined can use at the server is now limited to 300 MB, by default.</p> <p>For more information, see <code>-XX:JITServerAOTmx</code>.</p>"},{"location":"version0.36/#new-xx-jitserveraotcachepersistence-option-added","title":"New <code>-XX:[+|-]JITServerAOTCachePersistence</code> option added","text":"<p>The JITServer AOT cache was a non-persistent in-memory cache. If the JITServer instance terminated, the cache content was lost. Now, with the <code>-XX:+JITServerAOTCachePersistence</code> option, the JITServer server periodically saves its AOT caches to files. Other JITServer instances can then load these caches from files the first time a client requests a particular cache.</p> <p>For more information, see <code>-XX:[+|-]JITServerAOTCachePersistence</code>.</p>"},{"location":"version0.36/#new-xxjitserveraotcachedir-option-added","title":"New <code>-XX:JITServerAOTCacheDir</code> option added","text":"<p>You can specify the directory for saving or loading the JITServer AOT cache files with the <code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code> option. If the option is not used, AOT cache files are saved to (or loaded from) the current working directory of the JITServer server.</p> <p>For more information, see <code>-XX:JITServerAOTCacheDir</code>.</p>"},{"location":"version0.36/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.35.0 and v0.36.x releases, see the Release notes.</p>"},{"location":"version0.37/","title":"Version 0.37.0","text":""},{"location":"version0.37/#whats-new-in-version-0370","title":"What's new in version 0.37.0","text":"<p>The following new features and notable changes since version 0.36.x are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>AIX is now built on AIX 7.2 TL5</li> <li> Linux\u00ae reference compiler updated to gcc 11.2</li> <li>Support added for the <code>com.sun.management.ThreadMXBean</code> interface</li> <li> Support for PKCS#11 token labels added on Linux on IBM Z\u00ae</li> <li>New message added to help find system dumps on Linux</li> <li> New JDK 19 features</li> </ul>"},{"location":"version0.37/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.37/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.37.0 works with OpenJDK 19. OpenJDK 19 is out of support at the time of the 0.37.0 release. Builds of 0.37.0 should not be used in production and might contain known security vulnerabilities as of 18 April 2023.</p> <p>RHEL 8.2 is out of support. RHEL 8.4 is the new minimum operating system level.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 19 and later are now compiled with Microsoft\u00ae Visual Studio 2022. The Visual Studio redistributable files included with the build are updated to match.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.37/#aix-is-now-built-on-aix-72-tl5","title":"AIX is now built on AIX 7.2 TL5","text":"<p>All AIX compiles are now moved from AIX 7.1 TL5 to AIX 7.2 TL5.</p> <p>For more information, see Supported environments.</p>"},{"location":"version0.37/#linux-reference-compiler-updated-to-gcc-112","title":"Linux reference compiler updated to gcc 11.2","text":"<p>Linux builds for platforms Linux x86 64-bit, Linux on POWER LE 64-bit, and Linux on IBM Z 64-bit now use gcc 11.2 instead of gcc 10.3. Linux AArch64 64-bit continues to use the gcc 10.3 compiler. See the list of build environments.</p>"},{"location":"version0.37/#support-added-for-the-comsunmanagementthreadmxbean-interface","title":"Support added for the <code>com.sun.management.ThreadMXBean</code> interface","text":"<p>The OpenJ9 <code>ThreadMXbean</code> interface (<code>com.ibm.lang.management.ThreadMXBean</code>) was extending the <code>java.lang.management.ThreadMXBean</code> interface. With this release, the OpenJ9 <code>ThreadMXBean</code> interface extends the <code>com.sun.management.ThreadMXBean</code> interface, whereby it now contains all the methods of the <code>java.lang.management.ThreadMXBean</code> interface with additional methods from the <code>com.sun.management.ThreadMXBean</code> interface.</p> <p>The OpenJ9 VM implementation does not support thread memory allocation measurement (<code>isThreadAllocatedMemorySupported</code> method returns false).</p>"},{"location":"version0.37/#support-for-pkcs11-token-labels-added-on-linux-on-ibm-z","title":"Support for PKCS#11 token labels added on Linux on IBM Z","text":"<p>On restarting an application, or creating or removing of tokens, the token might move to a different slot. An application that uses the <code>slot</code> or <code>slotListIndex</code> attributes might fail if it doesn\u2019t first check which slot the token is in.</p> <p>OpenJ9 now supports the use of an extra attribute, <code>tokenlabel</code>, in the SunPKCS11 configuration file on Linux on IBM Z, which helps to avoid this issue.</p> <p>For more information, see Support for PKCS#11 token labels.</p>"},{"location":"version0.37/#new-message-added-to-help-find-system-dumps-on-linux","title":"New message added to help find system dumps on Linux","text":"<p>A new message, <code>JVMPORT049I</code>, is added to help find the system dump files for <code>kernel.core_pattern</code> piped programs on Linux.</p> <p>For more information about system dumps and piped system dumps, see System dumps on Linux.</p>"},{"location":"version0.37/#new-jdk-19-features","title":"New JDK 19 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 424: Foreign Function &amp; Memory API (Preview)</li> <li>JEP 425: Virtual Threads (Preview)</li> <li>JEP 426: Vector API (Fourth Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 19 with OpenJ9:</p> <ul> <li>JEP 405: Record Patterns (Preview)</li> <li>JEP 427: Pattern Matching for switch (Third Preview)</li> </ul> <p>You can find the full list of features for JDK 19 at the OpenJDK project. Any remaining features that are listed are not implemented and hence not applicable to OpenJ9 in this release.</p>"},{"location":"version0.37/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.36.x and v0.37.0 releases, see the Release notes.</p>"},{"location":"version0.38/","title":"Version 0.38.0","text":""},{"location":"version0.38/#whats-new-in-version-0380","title":"What's new in version 0.38.0","text":"<p>The following new features and notable changes since version 0.37.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New <code>-XX:[+|-]HandleSIGUSR2</code> option added</li> <li>Technical preview of CRIU support</li> </ul>"},{"location":"version0.38/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.38/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.38.0 supports OpenJDK 8, 11 and 17.</p> <p>Support for running OpenJ9 with OpenJDK 8 or OpenJDK 11 on CentOS 6.10 is deprecated and might be removed in a future release. Since release 0.37, OpenJ9 is no longer tested with OpenJDK 11 on CentOS 6.10. Testing of OpenJ9 with OpenJDK 8 on CentOS 6.10 is likely to end in a future release.</p> <p>OpenJ9 Windows\u00ae builds for OpenJDK 8 are now compiled with Microsoft\u00ae Visual Studio 2019. The Visual Studio redistributable files included with the build are updated to match.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.38/#new-xx-handlesigusr2-option-added","title":"New <code>-XX:[+|-]HandleSIGUSR2</code> option added","text":"<p>This option controls the handling of the <code>SIGUSR2</code> signal by the VM signal handler. The VM signal handler is installed only if this option is enabled.</p> <p>For more information, see <code>-XX:[+|-]HandleSIGUSR2</code>.</p>"},{"location":"version0.38/#technical-preview-of-criu-support","title":"Technical preview of CRIU support","text":"<p>This release supports, as a technical preview, the Checkpoint/Restore In Userspace (CRIU) tool that is included with many Linux distributions. This tool is available for OpenJDK 11 and later running on Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), and Linux on IBM Z\u00ae only.</p> <p>You can use the CRIU feature to stop the VM at a checkpoint, save its state, then run the VM from the point where it was stopped. You can restore the checkpoint image in multiple other environments with improved start-up time. This capability means that the CRIU support is particularly useful in container environments. For more information, see CRIU support.</p>"},{"location":"version0.38/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.37.0 and v0.38.0 releases, see the Release notes.</p>"},{"location":"version0.39/","title":"Version 0.39.0","text":""},{"location":"version0.39/#whats-new-in-version-0390","title":"What's new in version 0.39.0","text":"<p>The following new features and notable changes since version 0.38.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>EC key generation algorithm support for OpenSSL</li> <li>New JDK 20 features</li> </ul>"},{"location":"version0.39/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.39/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.39.0 supports OpenJDK 20.</p> <p>OpenJDK 20 with Eclipse OpenJ9 is not a long term support (LTS) release.</p> <p>RHEL 8.4 is out of support. RHEL 8.6 is the new minimum operating system level.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.39/#ec-key-generation-algorithm-support-for-openssl","title":"EC key generation algorithm support for OpenSSL","text":"<p>The EC key generation algorithm can now use the native OpenSSL library for OpenJDK 20. For more information, see <code>-Djdk.nativeECKeyGen</code>.</p>"},{"location":"version0.39/#new-jdk-20-features","title":"New JDK 20 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 434: Foreign Function &amp; Memory API (Second Preview)</li> <li>JEP 436: Virtual Threads (Second Preview)</li> <li>JEP 437: Structured Concurrency (Second Incubator)</li> <li>JEP 438: Vector API (Fifth Incubator)</li> </ul> <p>The following features are implemented in OpenJDK and available in any build of OpenJDK 20 with OpenJ9:</p> <ul> <li>JEP 432: Record Patterns (Second Preview)</li> <li>JEP 433: Pattern Matching for switch (Fourth Preview)</li> </ul> <p>You can find the full list of features for JDK 20 at the OpenJDK project. Any remaining features that are listed either do not apply to OpenJ9 or are not implemented and hence not applicable to OpenJ9 in this release.</p>"},{"location":"version0.39/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.38.0 and v0.39.0 releases, see the Release notes.</p>"},{"location":"version0.40/","title":"Version 0.40.0","text":""},{"location":"version0.40/#whats-new-in-version-0400","title":"What's new in version 0.40.0","text":"<p>The following new features and notable changes since version 0.39.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li>New <code>-XX:codecachetotalMaxRAMPercentage</code> option added</li> <li>VM starts with a warning message after the container detection fails</li> <li>Support for persistent shared classes cache added on z/OS</li> <li>EC key generation algorithm and XDH key agreement and generation algorithms support for OpenSSL</li> </ul>"},{"location":"version0.40/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.40/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.40.0 supports OpenJDK 8, 11, 17 and 20.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.40/#new-xxcodecachetotalmaxrampercentage-option-added","title":"New <code>-XX:codecachetotalMaxRAMPercentage</code> option added","text":"<p>In environments with low physical memory availability, the VM might use too much memory for JIT code caches, leaving little memory for critical operations. With the <code>-XX:codecachetotalMaxRAMPercentage</code> option, you can set an upper limit for the total code cache size, where the upper limit is specified as a percentage of the physical memory the VM process is allowed to use.</p> <p>For more information, see <code>-XX:codecachetotalMaxRAMPercentage</code>.</p>"},{"location":"version0.40/#vm-starts-with-a-warning-message-after-the-container-detection-fails","title":"VM starts with a warning message after the container detection fails","text":"<p>If you mount the <code>/proc</code> file system with the <code>hidepid=2</code> option on Linux\u00ae systems and the VM does not have root privileges, it cannot access the <code>/proc</code> file system. In previous releases, the VM exits when it encounters this scenario. From this release, the VM starts with a warning message after the container detection fails.</p> <p>For more information, see the Cloud optimizations topic.</p>"},{"location":"version0.40/#support-for-persistent-shared-classes-cache-added-on-zos","title":"Support for persistent shared classes cache added on z/OS","text":"<p>Persistent shared caches are now supported on z/OS systems. The default cache type on z/OS is still non-persistent. You can use the <code>-Xshareclasses:persistent</code> option to switch to persistent shared cache.</p>"},{"location":"version0.40/#ec-key-generation-algorithm-and-xdh-key-agreement-and-generation-algorithms-support-for-openssl","title":"EC key generation algorithm and XDH key agreement and generation algorithms support for OpenSSL","text":"<p>The EC key generation algorithm can now use the native OpenSSL library for all OpenJDK versions. The XDH key agreement and generation algorithms can also use the native OpenSSL library. For more information, see <code>-Djdk.nativeECKeyGen</code>, <code>-Djdk.nativeXDHKeyAgreement</code>, and <code>-Djdk.nativeXDHKeyGen</code>.</p>"},{"location":"version0.40/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.39.0 and v0.40.0 releases, see the Release notes.</p>"},{"location":"version0.41/","title":"Version 0.41.0","text":""},{"location":"version0.41/#whats-new-in-version-0410","title":"What's new in version 0.41.0","text":"<p>The following new features and notable changes since version 0.40.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> New <code>-XX:[+|-]ShowCarrierFrames</code> option added </li> <li> New <code>-XX:ContinuationCache</code> option added </li> <li> <code>-XX:+CompactStrings</code> option enabled by default </li> <li>Change in behavior of <code>-Xshareclasses:readonly</code></li> <li>New <code>-XX:[+|-]EnableDynamicAgentLoading</code> option added</li> <li>New <code>-XX:[+|-]UseZlibNX</code> option added</li> <li>Support for OpenSSL 3.x</li> </ul>"},{"location":"version0.41/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.41/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.41.0 supports OpenJDK 8, 11, and 17.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.41/#new-xx-showcarrierframes-option-added","title":"New <code>-XX:[+|-]ShowCarrierFrames</code> option added","text":"<p>A VM maintains multiple platform threads that are used as carrier threads to run the virtual threads. Although the virtual thread runs on a carrier thread, the stack trace of the virtual thread and its carrier thread are separate. You can use the <code>-XX:+ShowCarrierFrames</code> option to add the stack trace of the carrier thread in addition to the virtual thread stack trace to the <code>Throwable.getStackTrace()</code> method, if an exception occurs.</p> <p>For more information, see <code>-XX:[+|-]ShowCarrierFrames</code>. </p>"},{"location":"version0.41/#new-xxcontinuationcache-option-added","title":"New <code>-XX:ContinuationCache</code> option added","text":"<p>When a virtual thread is created, it is associated with a continuation, which holds the target task of the virtual thread. The VM saves the current thread state in an internal data structure that is linked with the continuation and allocates the memory for that structure. The VM stores the internal data structure in a continuation cache. New continuations can reuse the cached structure instead of allocating new memory for it.</p> <p>You can optimize the virtual thread performance by tuning the continuation tier 1 and 2 cache size with the <code>-XX:ContinuationCache</code> option. </p>"},{"location":"version0.41/#-xxcompactstrings-option-enabled-by-default","title":"<code>-XX:+CompactStrings</code> option enabled by default","text":"<p>Like HotSpot, the<code>-XX:+CompactStrings</code> option is now enabled by default on Java\u2122 11 and later. In the earlier versions, this option is disabled by default.</p> <p>For more information, see <code>-XX:[+|-]CompactStrings</code>. </p>"},{"location":"version0.41/#change-in-behavior-of-xshareclassesreadonly","title":"Change in behavior of <code>-Xshareclasses:readonly</code>","text":"<p>In the earlier releases, if the <code>-Xshareclasses:readonly</code> option and the JITServer AOT cache feature were both enabled at the same time at a JITServer client, the client could not use the JITServer AOT cache because the cache for storing data that the JITServer AOT cache needed was read-only.</p> <p>Now, with the change in behavior of the <code>-Xshareclasses:readonly</code> option, the shared classes cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p>"},{"location":"version0.41/#new-xx-enabledynamicagentloading-option-added","title":"New <code>-XX:[+|-]EnableDynamicAgentLoading</code> option added","text":"<p>This option enables or disables the dynamic loading of agents into a running VM. The <code>-XX:+EnableDynamicAgentLoading</code> option is the default setting.</p> <p> For Java 21 and later, warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the <code>-XX:+EnableDynamicAgentLoading</code> option and the same agents were not loaded before. </p> <p>For more information, see <code>-XX:[+|-]EnableDynamicAgentLoading</code>.</p>"},{"location":"version0.41/#new-xx-usezlibnx-option-added","title":"New <code>-XX:[+|-]UseZlibNX</code> option added","text":"<p>AIX\u00ae system adds the <code>zlibnx</code> library directory path in the <code>LIBPATH</code> environment variable by default, if it is available in the system. You can control the loading of the <code>zlibnx</code> library by using the <code>-XX:[+|-]UseZlibNX</code> option.</p>"},{"location":"version0.41/#support-for-openssl-3x","title":"Support for OpenSSL 3.x","text":"<p>OpenSSL 3.x is now supported on all operating systems. For more information about OpenSSL support, see <code>Cryptographic operations</code>.</p>"},{"location":"version0.41/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.40.0 and v0.41.0 releases, see the Release notes.</p>"},{"location":"version0.42/","title":"Version 0.42.0","text":""},{"location":"version0.42/#whats-new-in-version-0420","title":"What's new in version 0.42.0","text":"<p>The following new features and notable changes since version 0.41.0 are included in this release:</p> <ul> <li>New binaries and changes to supported environments</li> <li> OpenJ9 <code>jextract</code> removed </li> </ul>"},{"location":"version0.42/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.42/#binaries-and-supported-environments","title":"Binaries and supported environments","text":"<p>Eclipse OpenJ9\u2122 release 0.42.0 supports OpenJDK 21.</p> <p>OpenJDK 21 with Eclipse OpenJ9 is a long term support (LTS) release and supersedes OpenJDK 20 with Eclipse OpenJ9.</p> <p>To learn more about support for OpenJ9 releases, including OpenJDK levels and platform support, see Supported environments.</p>"},{"location":"version0.42/#openj9-jextract-removed","title":"OpenJ9 <code>jextract</code> removed","text":"<p>The dump extractor tool, OpenJ9 <code>jextract</code>, that was deprecated since the 0.26.0 release is now removed from Java 21 and later. The <code>jpackcore</code> tool replaced the OpenJ9 <code>jextract</code> tool after its deprecation. </p>"},{"location":"version0.42/#known-problems-and-full-release-information","title":"Known problems and full release information","text":"<p>To see known problems and a complete list of changes between Eclipse OpenJ9 v0.41.0 and v0.42.0 releases, see the Release notes.</p>"},{"location":"version0.8/","title":"Version 0.8.0","text":""},{"location":"version0.8/#release-notes-version-080","title":"Release notes - version 0.8.0","text":"<p>Version 0.8.0 is the first release of Eclipse OpenJ9\u2122, as defined in the release plan.</p> <p>This release supports OpenJDK Version 8 binaries at AdoptOpenJDK.net that contain the Eclipse OpenJ9 virtual machine.</p> <p>For more information about supported platforms, and any issues and limitations, read the OpenJ9 GitHub release notes.</p>"},{"location":"version0.9/","title":"Version 0.9.0","text":""},{"location":"version0.9/#whats-new-in-version-090","title":"What's new in version 0.9.0","text":"<p>The following new features and notable changes from v.0.8.0 are included in this release:</p> <ul> <li>New binaries and supported environments.</li> <li>The idle tuning feature is now supported on Linux running on Power\u00ae Systems and IBM Z\u00ae Systems.</li> <li>A new Garbage Collection (GC) policy is available that performs no housekeeping.</li> <li>A command line option is provided to automatically set a larger Java heap size for applications that run in containers.</li> <li>You can now specify the maximum Java heap size as a percentage value.</li> <li>The shared classes feature now supports nested jar files.</li> <li>System dump data can now be read to help diagnose problems on Linux and Windows platforms.</li> <li>There are notable changes to the <code>java.lang.String</code> class.</li> <li>There are notable changes to the <code>com.ibm.oti.shared.SharedClassCacheInfo</code> class.</li> <li> New JDK 9 features</li> <li> New JDK 10 features</li> </ul>"},{"location":"version0.9/#features-and-changes","title":"Features and changes","text":""},{"location":"version0.9/#binaries-and-supported-platforms","title":"Binaries and supported platforms","text":"<p>The following additional OpenJDK binaries that contain the Eclipse OpenJ9\u2122 VM are now available from the AdoptOpenJDK community:</p> <ul> <li>OpenJDK version 10</li> <li>OpenJDK version 8 for 32-bit Windows</li> <li>OpenJDK version 8 for x86 64-bit Linux (Large Heap) for Java heaps &gt;57 GB.</li> </ul> <p>Complete platform support information for OpenJ9 can be found in Supported environments</p>"},{"location":"version0.9/#idle-tuning-feature","title":"Idle tuning feature","text":"<p>The idle tuning feature in OpenJ9 keeps your memory footprint small by releasing unused memory back to the operating system. Prior to Eclipse version 0.9.0 this feature was available only on Linux x86 architectures with the <code>gencon</code> garbage collection policy. From version 0.9.0, this feature is now available on Linux for IBM POWER\u00ae and IBM Z\u00ae architectures. For more information about this feature, see the following command line options, which control this behavior:</p> <ul> <li>-XX:[+|-]IdleTuningCompactOnIdle</li> <li>-XX:[+|-]IdleTuningGcOnIdle</li> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> </ul> <p>The following blog post describes the benefits of using this feature: Are you still paying for unused memory when your Java app is idle?</p>"},{"location":"version0.9/#new-gc-policy","title":"New GC policy","text":"<p>A new GC policy is introduced for JEP 318: Epsilon: A No-Op Garbage Collector.</p> <p>When this policy is enabled, the Java object heap is expanded in the normal way until the limit is reached, but memory is not reclaimed through garbage collection. When the limit is reached the VM shuts down.</p> <p>This JEP has a number of use cases including short-lived applications and certain test scenarios.</p> <p>To enable this policy you can use one of the following options:</p> <ul> <li>-Xgcpolicy:nogc</li> <li>-XX:+UseNoGC</li> </ul>"},{"location":"version0.9/#modifying-the-default-java-heap-size-for-applications-that-run-in-containers","title":"Modifying the default Java heap size for applications that run in containers","text":"<p>When using container technology, applications are typically run on their own and do not need to compete for memory. In this release, changes are introduced to detect when OpenJ9 is running inside a container. If your application is running in a container and you want the VM to allocate a larger fraction of memory to the Java heap, set the <code>-XX:+UseContainerSupport</code> option on the command line.</p> <p>The following table shows the maximum Java heap size that gets set, depending on the memory available:</p> Physical memory <code>&lt;size&gt;</code> Maximum Java heap size Less than 1 GB 50% <code>&lt;size&gt;</code> 1 GB - 2 GB <code>&lt;size&gt;</code> - 512M Greater than 2 GB 75% <code>&lt;size&gt;</code> <p>The default heap size for containers only takes affect when running in a container environment and when <code>-XX:+UseContainerSupport</code> is specified, which is expected to be the default in a future release.</p>"},{"location":"version0.9/#specifying-the-maximum-java-heap-size-as-a-percentage-value","title":"Specifying the maximum Java heap size as a percentage value","text":"<p>OpenJ9 now supports setting the heap size as a percentage of the physical memory. The following OpenJDK options are recognized and can be set for the VM:</p> <ul> <li><code>-XX:MaxRAMPercentage</code></li> <li><code>-XX:InitialRAMPercentage</code></li> </ul> <p>To understand how to set these options, see -XX:InitialRAMPercentage / -XX:MaxRAMPercentage.</p> <p>If your application is running in a container and you have specified <code>-XX:+UseContainerSupport</code>, as described in Modifying the default Java heap size for applications that run in containers, both the default heap size for containers and the <code>-XX:MaxRAMPercentage</code> and <code>-XX:InitialRAMPercentage</code> options are based on the available container memory.</p>"},{"location":"version0.9/#shared-classes-support-for-nested-jar-files","title":"Shared classes support for nested jar files","text":"<p>Changes are made to the <code>com.ibm.oti.shared</code> API to support nested jar files.</p>"},{"location":"version0.9/#direct-dump-reader-enabled-on-linux-and-windows","title":"Direct Dump Reader enabled on Linux and Windows","text":"<p>Direct Dump Reader (DDR) support is now enabled for the OpenJ9 VM on all Linux architectures and on Windows. The DDR code enables the VM to read system dump data by using the OpenJ9 Diagnostic Tool Framework for Java (DTFJ) API or the <code>jdmpview</code> tool. If you use the Eclipse Memory Analyzer\u2122 tool (MAT), you can also analyze OpenJ9 or IBM VMs by installing the DTFJ plugin. (Install from the Eclipse Help menu; Install New Software &gt; Work with \"IBM Diagnostic Tool Framework for Java\" &gt; IBM Monitoring and  Diagnostic Tools &gt; Diagnostic Tool Framework for Java)</p> <p>You must use a 32-bit VM to look at a 32-bit core, and a 64-bit VM to look at a 64-bit core. This restriction will be fixed in a later version of OpenJ9.</p>"},{"location":"version0.9/#changes-to-the-javalangstring-class","title":"Changes to the <code>java.lang.String</code> class","text":"<p> To match the behavior of OpenJDK, <code>java.lang.String</code> no longer has a count field, which changes the way that <code>String.subString()</code> works compared to Java 8. <code>String.subString()</code> now copies the value array. Similarly, <code>StringBuffer</code> and <code>StringBuilder</code> do not share the value array with any <code>String</code> created by <code>toString()</code>.</p> <p>For performance and compatibility with the new String object layout, the OpenJ9 implementations of <code>StringBuffer</code> and <code>StringBuilder</code> have been deprecated in favor of the OpenJDK implementations. </p>"},{"location":"version0.9/#changes-to-the-sharedclasscacheinfo-class","title":"Changes to the <code>SharedClassCacheInfo</code> class","text":"<p> <code>SharedClassCacheInfo.getCacheJVMLevel()</code> used to return the JVMLEVEL constant that maps to a Java version number, for example JVMLEVEL_JAVA8. This call now returns only the Java version number, for example 10 for Java 10. </p>"},{"location":"version0.9/#new-jdk-9-features","title":"New JDK 9 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 102: Process API Updates</li> <li>JEP 110: HTTP 2 Client</li> <li>JEP 143: Improve Contended Locking</li> <li>JEP 193: Variable Handles</li> <li>JEP 199: Smart Java Compilation, Phase Two</li> <li>JEP 200: The Modular JDK</li> <li>JEP 201: Modular Source Code</li> <li>JEP 211: Elide Deprecation Warnings on Import Statements</li> <li>JEP 213: Milling Project Coin</li> <li>JEP 215: Tiered Attribution for javac</li> <li>JEP 216: Process Import Statements Correctly</li> <li>JEP 217: Annotations Pipeline 2.0</li> <li>JEP 219: Datagram Transport Layer Security (DTLS)</li> <li>JEP 220: Modular Run-Time Images</li> <li>JEP 221: Simplified Doclet API</li> <li>JEP 222: jshell: The Java Shell (Read-Eval-Print Loop)</li> <li>JEP 223: New Version-String Scheme</li> <li>JEP 224: HTML5 Javadoc</li> <li>JEP 225: Javadoc Search</li> <li>JEP 226: UTF-8 Property Files</li> <li>JEP 227: Unicode 7.0</li> <li>JEP 229: Create PKCS12 Keystores by Default</li> <li>JEP 232: Improve Secure Application Performance</li> <li>JEP 235: Test Class-File Attributes Generated by javac</li> <li>JEP 236: Parser API for Nashorn</li> <li>JEP 238: Multi-Release JAR Files</li> <li>JEP 240: Remove the JVM TI hprof Agent</li> <li>JEP 241: Remove the jhat Tool</li> <li>JEP 244: TLS Application-Layer Protocol Negotiation Extension</li> <li>JEP 247: Compile for Older Platform Versions</li> <li>JEP 249: OCSP Stapling for TLS</li> <li>JEP 251: Multi-Resolution Images</li> <li>JEP 252: Use CLDR Locale Data by Default</li> <li>JEP 253: Prepare JavaFX UI Controls and CSS APIs for Modularization</li> <li>JEP 254: Compact Strings (not enabled by default)</li> <li>JEP 255: Merge Selected Xerces 2.11.0 Updates into JAXP</li> <li>JEP 256: BeanInfo Annotations</li> <li>JEP 257: Update JavaFX/Media to Newer Version of GStreamer</li> <li>JEP 258: HarfBuzz Font-Layout Engine</li> <li>JEP 259: Stack-Walking API</li> <li>JEP 260: Encapsulate Most Internal APIs</li> <li>JEP 261: Module System</li> <li>JEP 262: TIFF Image I/O</li> <li>JEP 263: HiDPI Graphics on Windows and Linux\u00ae</li> <li>JEP 264: Platform Logging API and Service</li> <li>JEP 265: Marlin Graphics Renderer</li> <li>JEP 266: More Concurrency Updates</li> <li>JEP 267: Unicode 8.0</li> <li>JEP 268: XML Catalogs</li> <li>JEP 269: Convenience Factory Methods for Collections</li> <li>JEP 272: Platform-Specific Desktop Features</li> <li>JEP 273: DRBG-Based SecureRandom Implementations</li> <li>JEP 274: Enhanced Method Handles</li> <li>JEP 275: Modular Java Application Packaging</li> <li>JEP 276: Dynamic Linking of Language-Defined Object Models</li> <li>JEP 277: Enhanced Deprecation</li> <li>JEP 280: Indify String Concatenation</li> <li>JEP 282: jlink: The Java Linker</li> <li>JEP 283: Enable GTK 3 on Linux</li> <li>JEP 285: Spin-Wait Hints</li> <li>JEP 287: SHA-3 Hash Algorithms</li> <li>JEP 288: Disable SHA-1 Certificates</li> <li>JEP 289: Deprecate the Applet API</li> <li>JEP 290: Filter Incoming Serialization Data</li> <li>JEP 292: Implement Selected ECMAScript 6 Features in Nashorn</li> <li>JEP 298: Remove Demos and Samples</li> <li>JEP 299: Reorganize Documentation</li> </ul> <p>You can find the full list of features for JDK 9 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.9/#new-jdk-10-features","title":"New JDK 10 features","text":"<p>The following features are supported by OpenJ9:</p> <ul> <li>JEP 286: Local-Variable Type Inference</li> <li>JEP 313: Remove the Native-Header Generation Tool (javah)</li> <li>JEP 314: Additional Unicode Language-Tag Extensions</li> <li>JEP 319: Root Certificates</li> <li>JEP 322: Time-Based Release Versioning</li> </ul> <p>You can find the full list of features for JDK 10 at the OpenJDK project. Any remaining features that are listed do not apply to OpenJ9.</p>"},{"location":"version0.9/#full-release-information","title":"Full release information","text":"<p>To see a complete list of changes between Eclipse OpenJ9 version 0.8.0 and version 0.9.0 releases, see the Release notes.</p>"},{"location":"vgclog/","title":"Verbose GC logs","text":""},{"location":"vgclog/#verbose-garbage-collection-logs","title":"Verbose garbage collection logs","text":"<p>Garbage collection (GC) reclaims used memory in the Java\u2122 object heap for reuse. During cleanup of the heap, the verbose GC logs, when enabled, capture information about the different GC operations that are involved in the GC cycles. GC operations aim to reorganize or reclaim memory.</p> <p>Verbose GC logs contain information about GC operations to assist with the following actions:  </p> <ul> <li>Tuning GC and improving application performance.</li> <li>Troubleshooting GC operations and policies. For example, analyzing long pauses, or determining how free memory is divided in the Java object heap before and after a GC cycle.  </li> </ul> <p>Verbose GC logs, when enabled, begin capturing information as soon as GC is initialized.</p> <p>To help you visualize and analyze the GC, you can feed verbose GC log files into various diagnostic tools and interfaces. Examples include tools such as Garbage Collection and Memory Visualizer (GCMV) and online services such as GCEasy.  </p> <p>For examples of log output, including guidance on how to analyze the logs, see Log examples.</p> <p>A further diagnostic step is to run one or more traces on GC activity by using the <code>-Xtgc</code> option. Trace output provides more granular information to help diagnose GC problems or perform finer tuning.</p>"},{"location":"vgclog/#how-to-generate-a-verbose-gc-log","title":"How to generate a verbose GC log","text":"<p>You can enable verbose GC logs by specifying the <code>-verbose:gc</code> standard option when you start your application. For more information, see standard command-line options.</p> <p>The output of <code>-verbose:gc</code> is printed to STDERR by default. To print the log output to a file, append the <code>-Xverbosegclog</code> option. You can also use this option to print to a succession of files, where each file logs a specified number of GC cycles.</p>"},{"location":"vgclog/#verbose-gc-log-contents-and-structure","title":"Verbose GC log contents and structure","text":"<p>The verbose GC logs are printed in XML format and consist of the following sections:  </p> <ul> <li> <p>A summary of your GC configuration, which is captured in the <code>&lt;initialized&gt;</code> XML element.</p> </li> <li> <p>Information about the GC cycles that ran, including GC operations and GC increments.  </p> </li> </ul> <p>For definitions of GC cycles and operations, see Garbage collection. For definitions of GC increments, see GC increments and interleaving.</p> <p>The logs record when GC cycles and their increments start and end, and list the GC operations that run within these increments to manage or reclaim memory. You can also determine which type of event triggered the cycle or increment, and the amount of memory available to your application before and after processing.  </p>"},{"location":"vgclog/#initialization","title":"Initialization","text":"<p>The log begins by recording the configuration of the Eclipse OpenJ9\u2122 runtime virtual environment (VM) and details of the GC configuration(GC). The configuration is recorded by using child elements of the <code>&lt;initialized&gt;</code> element, for example:</p> <pre><code>\n&lt;initialized id=\"1\" timestamp=\"2020-10-18T13:27:07.691\"&gt;\n  &lt;attribute name=\"gcPolicy\" value=\"-Xgcpolicy:gencon\" /&gt;\n  &lt;attribute name=\"maxHeapSize\" value=\"0x40000000\" /&gt;\n  &lt;attribute name=\"initialHeapSize\" value=\"0x40000000\" /&gt;\n  &lt;attribute name=\"compressedRefs\" value=\"true\" /&gt;\n  &lt;attribute name=\"compressedRefsDisplacement\" value=\"0x0\" /&gt;\n  &lt;attribute name=\"compressedRefsShift\" value=\"0x0\" /&gt;\n  &lt;attribute name=\"pageSize\" value=\"0x1000\" /&gt;\n  &lt;attribute name=\"pageType\" value=\"not used\" /&gt;\n  &lt;attribute name=\"requestedPageSize\" value=\"0x1000\" /&gt;\n  &lt;attribute name=\"requestedPageType\" value=\"not used\" /&gt;\n  &lt;attribute name=\"gcthreads\" value=\"4\" /&gt;\n  &lt;attribute name=\"gcthreads Concurrent Mark\" value=\"1\" /&gt;\n  &lt;attribute name=\"packetListSplit\" value=\"1\" /&gt;\n  &lt;attribute name=\"cacheListSplit\" value=\"1\" /&gt;\n  &lt;attribute name=\"splitFreeListSplitAmount\" value=\"1\" /&gt;\n  &lt;attribute name=\"numaNodes\" value=\"0\" /&gt;\n  &lt;system&gt;\n    &lt;attribute name=\"physicalMemory\" value=\"100335456256\" /&gt;\n    &lt;attribute name=\"numCPUs\" value=\"28\" /&gt;\n    &lt;attribute name=\"architecture\" value=\"amd64\" /&gt;\n    &lt;attribute name=\"os\" value=\"Linux\" /&gt;\n    &lt;attribute name=\"osVersion\" value=\"3.10.0-1160.el7.x86_64\" /&gt;\n  &lt;/system&gt;\n  &lt;vmargs&gt;\n    &lt;vmarg name=\"-Dfile.encoding=bestfit936\" /&gt;\n    ...\n    &lt;vmarg name=\"-Xms1024m\" /&gt;\n    &lt;vmarg name=\"-Xmx1024m\" /&gt;\n    ...\n    &lt;vmarg name=\"-Xverbosegclog:verbosegc.xml\" /&gt;\n    ...\n  &lt;/vmargs&gt;\n&lt;/initialized&gt;\n</code></pre> <p>The first set of <code>&lt;attribute&gt;</code> elements records the configuration of the garbage collector, such as the GC policy type, configuration of the Java object heap, and the number of threads that are used for garbage collection. For example, the <code>GCThreads</code> attribute records that the garbage collector is configured to use four threads.</p> <p>The <code>&lt;system&gt;</code> section records information about the operating system and available hardware, such as the physical memory, number of CPUs, and operating system type and version. In the example, the VM is running on Linux\u00ae amd64 V3.10 and has access to 28 CPUs and over 100 GB.</p> <p>The <code>&lt;vmargs&gt;</code> section records any VM configuration command-line options (VM arguments) that are specified. The following types of options are recorded:</p> <ul> <li>non-standard JVM <code>-X</code> options and JVM <code>-XX</code> options. In the example output, the log records the location of the file that contains VM options and definitions as <code>java/perffarm/sdks/O11_j9_x64_linux-20201014/sdk/lib/options.default</code>. The verbose GC log option is set to <code>-Xverbosegclog:verbosegc.xml</code> to write the verbose GC log output to an XML file. The initial and maximum Java object heap sizes are both set to 1024 KB by using the <code>-Xms</code> and <code>-Xmx</code> options.</li> <li>system property options. In the example output, the system property <code>file.encoding</code> is set to <code>bestfit936</code> to force the GBK converter to follow unicode 2.0 rather than 3.0 standards.</li> </ul> <p>These command-line options can be set by using the command line, or by passing a manifest file, options file, or environment variable to the VM.</p> <p>After the configurations are recorded in the Initialization section, the verbose GC log begins recording GC activities and details.</p>"},{"location":"vgclog/#gc-cycles","title":"GC cycles","text":"<p>The start of a GC cycle is recorded by the <code>&lt;cycle-start&gt;</code> XML element. The trigger for the start of a GC cycle is captured in a preceding element to the <code>&lt;cycle-start&gt;</code> element. A GC cycle or GC increment is triggered for one of the following reasons:</p> <ul> <li>an allocation failure occurs. Allocation failures occur when a request for memory fails because the Java object heap does not have enough memory available. The element <code>&lt;af-start&gt;</code> logs an allocation failure trigger.</li> <li>a memory threshold is reached. Memory threshold values, which set the conditions for triggering certain types of GC cycles or increments, are defined by the policy type and configuration options. For more information about the particular elements or attributes that are used to record a memory threshold trigger, see specific policies and cycles in Log examples.</li> </ul> <p>The following XML structure is an example of the verbose GC logs that are generated from the Generational Concurrent GC policy (<code>-Xgcpolicy:gencon</code>). In this example, the lines are indented to help illustrate the flow and attributes and some child elements are omitted for clarity:</p> <pre><code>    &lt;exclusive-start/&gt;\n\n      &lt;af-start/&gt;\n\n        &lt;cycle-start/&gt;\n\n          &lt;gc-start&gt;\n\n            &lt;mem-info&gt;\n\n              &lt;mem/&gt;\n\n            &lt;/mem-info&gt;\n\n          &lt;/gc-start&gt;\n\n          &lt;allocation-stats/&gt;\n\n              &lt;gc-op/&gt;\n\n          &lt;gc-end&gt;\n\n            &lt;mem-info&gt;\n\n              &lt;mem/&gt;\n\n            &lt;/mem-info&gt;\n\n          &lt;/gc-end&gt;\n\n        &lt;cycle-end/&gt;\n\n        &lt;allocation-satisfied/&gt;\n\n      &lt;af-end/&gt;\n\n    &lt;exclusive-end/&gt;\n</code></pre> <p>Some elements serve as markers for starting and ending parts of the GC cycle and do not contain child elements, while other elements do contain child elements. In this example, the <code>&lt;af-start/&gt;</code>, <code>&lt;cycle-start/&gt;</code>, <code>&lt;cycle-end/&gt;</code>, <code>&lt;allocation-satisfied/&gt;</code>, and <code>&lt;af-end/&gt;</code> XML elements are empty and contain only attributes. All other XML elements contain child XML elements, which are omitted from this simplified example. For detailed examples of log output for a specific cycle, see Log examples).</p>"},{"location":"vgclog/#gc-increments-and-interleaving","title":"GC increments and interleaving","text":"<p>Some GC cycle types are run in piecemeal blocks of operations called GC increments. Using GC increments reduces pause times by enabling blocks of operations or operation steps to interleave with operations or operation steps from other types of cycle.</p> <p>For example, consider the garbage collector for the <code>gencon</code> policy, which uses partial cycles and global cycles. The partial cycle consists of just 1 GC operation, scavenge, that runs on the nursery area during a stop-the-world (STW) pause. However, the <code>gencon</code> global cycle, which runs when the tenure area is close to full, is split into three increments. The initial and final global cycle increments run during a relatively short STW pause. The intermediate global cycle increment, which consists of the majority of the GC cycle's work, runs its GC operations concurrently.</p> <p>Splitting the global cycle operations into these increments reduces pause times by running most of the GC operations concurrently with application threads. The <code>gencon</code> global cycle's concurrent increment is paused when a <code>gencon</code> partial GC cycle is triggered and resumes when the partial cycle, or multiple partial cycles, complete. In this way, a global cycle can progress while other types of cycle are run by pausing and resuming the concurrent work. In some policies, concurrent operations are split further into multiple concurrent increments for better control of progress of the concurrent operation.</p> <p>You can see this interleaving of the increments in the verbose GC log. The following table illustrates how the interleaving of the <code>gencon</code> policy's partial scavenge and global cycles appears in the logs. Line numbers of an example <code>gencon</code> policy's verbose GC log are displayed, alongside columns that show the status of each cycle that is recorded in the logs. (for clarity, not all GC activities are listed):</p> Table showing how the `gencon` policy's global and partial scavenge cycles, which interleave with each other, are recorded in an example log.  Example log line number `gencon` global GC cycle status recorded in log `gencon` partial GC cycle status recorded in log 1-87 Initialization section of the logs  87-51676  -   series of partial scavenge cycles start and finish   51677  global cycle's trigger and target logged - 51680  STW pause starts - 51683  global cycle starts - 51684  STW pause ends - 518685  blank line in logs. (Concurrent increment runs)  - 51686  (concurrent increment paused) STW pause starts 51690  (concurrent increment paused) partial scavenge cycle starts 51691  (concurrent increment paused)  partial scavenge increment runs 51730  (concurrent increment paused) partial cycle ends 51733  (concurrent increment resumes) STW pause ends 51734  blank line in logs. (Concurrent increment resumes) - 51735  STW pause starts - 51741  final global increment logged  - 51793  global cycle ends  - 51795  STW pause ends - <p> Note: Zero, one, or multiple GC cycles might run between the start and end of a <code>gencon</code> global GC cycle.</p> <p>The XML elements and attribute values that define operations and increments of a particular cycle are specific to the policy and type of cycle. To follow how the different cycle's increments interleave in a log, you can locate the elements and attributes that record the increments and operations that belong to a particular type of cycle. For example, for the <code>gencon</code> policy, you can locate the start of the intermediate, concurrent increment of the global cycle by searching for the <code>&lt;concurrent-kickoff&gt;</code> element.</p> <p>For more information about the XML elements and attribute values that are used for a particular type of cycle for a particular policy, and examples of log output, see Log examples.</p> <p>You can determine the GC increments and operations that are associated with a particular instance of a cycle by using the <code>contextid</code> and <code>id</code> attributes:</p> <ol> <li>Determine the ID of the GC cycle: find the value of the <code>id</code> attribute of the <code>&lt;cycle-start&gt;</code> element that denotes the start of the GC cycle.  Note: the <code>id</code> attribute increases incrementally with each GC event.  </li> <li>Search for the <code>contextid</code> attribute values that match the GC cycle's ID. All GC increments, operations, and concurrent events that are associated with a particular cycle have a <code>contextid</code> attribute whose value matches the GC cycle's ID.</li> </ol>"},{"location":"vgclog_examples/","title":"Log examples","text":""},{"location":"vgclog_examples/#log-examples","title":"Log examples","text":"<p>To help you understand how garbage collection (GC) processes memory for your application and how these processes are recorded, a number of annotated log examples are provided from different GC policies. Each example covers a particular type of cycle from a particular policy. By following the examples, you can learn how to interpret the XML elements in a log.</p>"},{"location":"vgclog_examples/#gencon-examples","title":"<code>gencon</code> examples","text":"<p>The <code>gencon</code> policy uses two types of cycle; a partial GC cycle and a global GC cycle. By default, the partial GC cycle runs a stop-the-world (STW) scavenge operation. On specific platforms, <code>gencon</code> can run a concurrent scavenge operation (-Xgc:concurrentScavenge) instead, if enabled at run time.</p> <p>The start of a <code>gencon</code> cycle is recorded in the log by the following elements and attributes:</p> Table showing types of <code>gencon</code> cycle along with the corresponding trigger reason and XML elements for each type.  GC cycle Value of <code>type</code> attribute of the <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code>elements Element that logs the cycle trigger Trigger reason  Global <code>global</code> <code>&lt;concurrent-kickoff&gt;</code> Low free memory tenure area threshold reached. Cycle trigger element is located before the <code>&lt;cycle-start&gt;</code> element.  Partial <code>scavenge</code> <code>&lt;af-start&gt;</code> Allocation failure. Cycle trigger element is located before the <code>&lt;cycle-start&gt;</code> element. <p>You can use the <code>type</code> attribute of the <code>&lt;gc-start&gt;</code> and <code>&lt;gc-end&gt;</code> elements to locate a particular cycle. You can also locate a particular type of cycle by searching for the element that records the cycle trigger, which is located before the <code>&lt;cycle-start&gt;</code> element.</p> <p>You can analyze the increments and operations that are associated with a particular type of cycle by locating and interpreting the elements in the following table:</p> Table showing increments and operations that are associated with the <code>gencon</code> partial scavenge and global cycles. GC process Elements that log the start and end of the event Details  GC cycle <code>&lt;cycle-start&gt;</code>, <code>&lt;cycle-end&gt;</code> The start and end of a GC cycle.  GC STW increment <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> The start and end of a GC increment that begins with a pause.  GC STW increment <code>&lt;concurrent-kickoff&gt;</code> The start of the initial GC increment of the global concurrent cycle that begins the initial mark operation.  GC STW increment <code>&lt;concurrent-global-final&gt;</code> The start of the final GC increment of the global concurrent cycle that executes the final collection.  GC operations and suboperations <code>&lt;gc-op&gt;</code> A GC operation such as mark or sweep, or a suboperation such as class unload. <p> Note: For more information about the XML structure of GC cycles, see GC cycles. For more information about GC cycle increments, see GC increments and interleaving.</p> <p>The following examples use log excerpts to show how the different types of <code>gencon</code> cycle are logged.</p>"},{"location":"vgclog_examples/#scavenge-partial-gc-cycle","title":"Scavenge partial GC cycle","text":"<p>The following example is taken from a <code>gencon</code> log. The output is broken down into sections with supporting text to explain the GC processing that is taking place.</p> <p>To search for a scavenge partial GC cycle, you can search for the <code>type</code> attribute value <code>scavenge</code> in <code>cycle-start</code> and <code>cycle-end</code> elements, or search for the <code>&lt;af&gt;</code> element that logs the allocation failure trigger.</p> <p>By default, the <code>gencon</code> partial GC cycle runs by using a single STW pause. The cycle performs only one operation, a scavenge operation, which runs only on the nursery area. The cycle consists of a single GC increment, which is labeled by using the elements that are shown in the following table:</p> Table showing the <code>gencon</code> default partial scavenge cycle's GC increment and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment Details  scavenge single  STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> Contains detailed information about copied objects and the weak roots processing operation <p>The scavenge partial GC cycle follows a general structure in the verbose GC log as shown. Some elements are omitted for clarity:</p> <pre><code>\n&lt;exclusive-start/&gt;          (STW Pause starts)\n\n&lt;af-start/&gt;                 (allocation failure trigger recorded)\n\n&lt;cycle-start/&gt;              (scavenge cycle starts)\n\n&lt;gc-start&gt;                  (scavenge cycle increment starts)\n\n&lt;mem-info&gt;                  (memory status before operation)\n\n&lt;mem&gt;&lt;/mem&gt;                 (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-start&gt;\n\n&lt;allocation-stats/&gt;         (Snapshot of how memory was divided up between\n                            ... application threads before current cycle started)\n\n&lt;gc-op&gt; \u201cscavenge\"&lt;/gc-op&gt;  (scavenge operation completed)\n\n&lt;gc-end&gt;                    (scavenge cycle increment ends)\n\n&lt;mem-info&gt;                  (memory status after operation)\n\n&lt;mem&gt;&lt;/mem&gt;                 (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-end&gt;\n\n&lt;/cycle-end&gt;                (scavenge cycle ends)\n\n&lt;allocation-satisfied/&gt;     (required allocation has been achieved)\n\n&lt;af-end/&gt;\n\n&lt;exclusive-end&gt;             (STW for scavenge cycle ends)\n...\n\n</code></pre> <p>The first activity in the cycle is recorded by an <code>&lt;exclusive-start&gt;</code> element, which indicates the start of the STW pause. Application (or mutator) threads are halted to give the garbage collector exclusive access to the Java\u2122 object heap:</p> <pre><code>&lt;!-- Start of gencon scavenge partial GC cycle example --&gt;\n\n&lt;exclusive-start id=\"12392\" timestamp=\"2020-10-18T13:35:45.000\" intervalms=\"406.180\"&gt;\n  &lt;response-info timems=\"0.070\" idlems=\"0.070\" threads=\"0\" lastid=\"00000000013D6900\" lastname=\"LargeThreadPool-thread-68\" /&gt;\n&lt;/exclusive-start&gt;\n</code></pre> <p>The <code>&lt;af-start&gt;</code> element indicates that the cycle was triggered by an allocation failure in the nursery (<code>type=\"nursery\"</code>) area of the heap:</p> <pre><code>&lt;af-start id=\"12393\" threadId=\"00000000013D7280\" totalBytesRequested=\"8200\" timestamp=\"2020-10-18T13:35:45.000\" intervalms=\"418.233\" type=\"nursery\" /&gt;\n</code></pre> <p>The <code>&lt;cycle-start&gt;</code> element marks the start of the cycle. The attribute <code>type=\"scavenge\"</code> confirms that this activity is a scavenge partial GC cycle:</p> <pre><code>&lt;cycle-start id=\"12394\" type=\"scavenge\" contextid=\"0\" timestamp=\"2020-10-18T13:35:45.000\" intervalms=\"418.231\" /&gt;\n</code></pre> <p>Most elements are labeled with an <code>id</code> attribute that increases in value incrementally, a<code>timestamp</code> attribute, and a <code>contextid</code> attribute. All elements that record GC increments and operations that are associated with a particular cycle have a <code>contextid</code> value that matches the <code>id</code> value of the cycle. The <code>&lt;cycle-start&gt;</code> element of this example cycle has an <code>id=\"12394\"</code>, so all subsequent elements that have a <code>contextid=\"4\"</code>, such as the <code>&lt;gc-start&gt;</code> increment element and the <code>&lt;gc-op&gt;</code> operation element, are associated with this particular example cycle.  </p> <p>The <code>&lt;gc-start&gt;</code> element records the first GC increment. In this <code>&lt;gc-start&gt;</code> section, you can find information about the amount of memory available (<code>&lt;mem-info&gt;</code>) and where it is located in the Java object heap.</p> <p>The memory snapshot within the <code>&lt;gc-start&gt;</code> element is taken before the scavenge operation and can be compared with a similar snapshot that is taken afterward to understand the effect on the heap.</p> <pre><code>&lt;gc-start id=\"12395\" type=\"scavenge\" contextid=\"12394\" timestamp=\"2020-10-18T13:35:45.000\"&gt;\n  &lt;mem-info id=\"12396\" free=\"414960320\" total=\"1073741824\" percent=\"38\"&gt;\n    &lt;mem type=\"nursery\" free=\"0\" total=\"268435456\" percent=\"0\"&gt;\n      &lt;mem type=\"allocate\" free=\"0\" total=\"241565696\" percent=\"0\" /&gt;\n      &lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n    &lt;/mem&gt;\n    &lt;mem type=\"tenure\" free=\"414960320\" total=\"805306368\" percent=\"51\"&gt;\n      &lt;mem type=\"soa\" free=\"374694592\" total=\"765040640\" percent=\"48\" /&gt;\n      &lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n    &lt;/mem&gt;\n    &lt;remembered-set count=\"21474\" /&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The following statements describe the object heap memory allocation at the start of the increment:</p> <ul> <li>The allocate space of the nursery area is full, or close to full. The allocation failure was triggered by the lack of available memory in this space.</li> <li>The survivor space of the nursery area is reported as 'full' to reflect that no available memory is available to allocate to the mutator threads. The entire survivor space is reserved for GC operations during the GC increment.</li> <li>The tenure area has 395.7 MB (414,960,320B) of free memory available.</li> </ul> <p>The next element <code>&lt;allocation-stats&gt;</code> shows a snapshot, which was taken before the cycle started, of how memory was divided up between application threads. In this example, the thread that used the most memory was <code>LargeThreadPool-thread-79</code>.</p> <pre><code>&lt;allocation-stats totalBytes=\"235362176\" &gt;\n  &lt;allocated-bytes non-tlh=\"32880\" tlh=\"235329296\" /&gt;\n  &lt;largest-consumer threadName=\"LargeThreadPool-thread-79\" threadId=\"00000000013F0C00\" bytes=\"6288544\" /&gt;\n&lt;/allocation-stats&gt;\n</code></pre> <p>The scavenge GC operation is recorded by the <code>&lt;gc-op&gt;</code> element; child elements record details about the operation. For example,</p> <pre><code>&lt;gc-op id=\"12397\" type=\"scavenge\" timems=\"11.649\" contextid=\"12394\" timestamp=\"2020-10-18T13:35:45.012\"&gt;\n  &lt;scavenger-info tenureage=\"7\" tenuremask=\"4080\" tiltratio=\"89\" /&gt;\n  &lt;memory-copied type=\"nursery\" objects=\"154910\" bytes=\"6027440\" bytesdiscarded=\"394832\" /&gt;\n  &lt;memory-copied type=\"tenure\" objects=\"16171\" bytes=\"562848\" bytesdiscarded=\"3064\" /&gt;\n  &lt;ownableSynchronizers candidates=\"10838\" cleared=\"10824\" /&gt;\n  &lt;references type=\"soft\" candidates=\"24\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"16\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"390\" cleared=\"269\" enqueued=\"269\" /&gt;\n  &lt;references type=\"phantom\" candidates=\"1\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;object-monitors candidates=\"132\" cleared=\"0\"  /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The <code>&lt;memory-copied&gt;</code> element indicates that 5.75 MB (6,027,440B) of reachable objects were moved by the scavenge operation from the allocate space to the survivor space in the nursery area, and 0.54 MB(562,848 B) were moved to the tenure area.</p> <p>The <code>&lt;scavenger-info&gt;</code> element shows that the tenure age is set to <code>7</code>. Any object in the allocate space with an age less than or equal to <code>7</code> is copied to the survivor space during this <code>scavenge</code>operation. Any object that is copied between the allocate and survivor areas more than <code>7</code> times is moved to the tenure area.</p> <p>For more information about how the scavenge operation acts on the Java object heap, see GC processing.</p> <p>The end of the increment is recorded with <code>&lt;gc-end&gt;</code> and provides another snapshot of memory allocation on the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"12398\" type=\"scavenge\" contextid=\"12394\" durationms=\"11.785\" usertimems=\"46.278\" systemtimems=\"0.036\" stalltimems=\"0.145\" timestamp=\"2020-10-18T13:35:45.012\" activeThreads=\"4\"&gt;\n  &lt;mem-info id=\"12399\" free=\"649473560\" total=\"1073741824\" percent=\"60\"&gt;\n    &lt;mem type=\"nursery\" free=\"235142120\" total=\"268435456\" percent=\"87\"&gt;\n      &lt;mem type=\"allocate\" free=\"235142120\" total=\"241565696\" percent=\"97\" /&gt;\n      &lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n    &lt;/mem&gt;\n    &lt;mem type=\"tenure\" free=\"414331440\" total=\"805306368\" percent=\"51\" macro-fragmented=\"0\"&gt;\n      &lt;mem type=\"soa\" free=\"374065712\" total=\"765040640\" percent=\"48\" /&gt;\n      &lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n    &lt;/mem&gt;\n    &lt;pending-finalizers system=\"0\" default=\"0\" reference=\"269\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"13792\" /&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The Java object heap memory allocation at the end of the increment is as follows:</p> <ul> <li>97% of the allocate space of the nursery area is now available as free memory.</li> <li>The survivor space of the nursery area is still reported as 'full' to reflect that the entire survivor space is reserved for GC operations during the next GC increment.</li> <li>The tenure area has 395 MB (414,331,440B) of free memory available. The scavenge operation copied 562 KB from the nursery area to the tenure area so less memory is now available in the tenure area.</li> </ul> <p>The scavenge operation successfully reclaimed memory in the allocate space of the nursery area by copying objects from the allocate space into the survivor space of the nursery area, and copying objects from the survivor space into the tenure area.</p> <p>The cycle ends (<code>&lt;cycle-end&gt;</code>). The following <code>&lt;allocation-satisfied&gt;</code> element indicates that the allocation request that caused the allocation failure can now complete successfully. The STW pause ends with the <code>&lt;exclusive-end&gt;</code> element:</p> <pre><code>&lt;cycle-end id=\"12400\" type=\"scavenge\" contextid=\"12394\" timestamp=\"2020-10-18T13:35:45.012\" /&gt;\n&lt;allocation-satisfied id=\"12401\" threadId=\"00000000013D6900\" bytesRequested=\"8200\" /&gt;\n&lt;af-end id=\"12402\" timestamp=\"2020-10-18T13:35:45.012\" threadId=\"00000000013D7280\" success=\"true\" from=\"nursery\"/&gt;\n&lt;exclusive-end id=\"12403\" timestamp=\"2020-10-18T13:35:45.012\" durationms=\"12.319\" /&gt;\n\n&lt;!-- End of gencon partial GC cycle example --&gt;\n</code></pre>"},{"location":"vgclog_examples/#summary","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example global cycle has the following characteristics:</p> <ul> <li> <p>The GC cycle begins with an STW pause due to an allocation failure.</p> </li> <li> <p>All GC operations and suboperations that are associated with this cycle occur during the STW pause</p> </li> <li> <p>The cycle consists of only 1 GC increment, which runs a single scavenge operation.</p> </li> <li> <p>The GC cycle reclaims memory in the allocate area of the nursery area by coping objects from the allocate area to the survivor area and also to the tenure area.</p> </li> </ul>"},{"location":"vgclog_examples/#concurrent-scavenge-partial-gc-cycle-non-default","title":"Concurrent scavenge partial GC cycle (non-default)","text":"<p>When concurrent scavenge mode is enabled, the partial GC cycle is run as a Concurrent Scavenge cycle. This partial GC cycle is divided into increments to enable the majority of the scavenge operation to run concurrently with running application (or mutator) threads. The concurrent increment can run while application threads run, and also while the intermediate concurrent increment of the global GC cycle runs. The interleaving of the concurrent scavenge partial GC cycle with the global cycle can be seen in the logs.</p> <p>The following elements log the GC increments and operations of the concurrent scavenge partial GC cycle:</p> Table showing the <code>gencon</code> concurrent (non-default) partial scavenge cycle's GC increment and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment Details  scavenge initial  STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> Root scanning, reported as a single scavenge operation.  scavenge intermediate  concurrent <code>&lt;concurrent-start&gt;</code>, <code>&lt;concurrent-end&gt;</code> Live objects are traversed and evacuated (*copy forward*). Operation is reported as a <code>scavenge</code> operation.  scavenge final STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> weak roots scanning, reported as a complex scavenge operation. <code>&lt;gc-op&gt;</code> contains specific details for each of the weak root groups. <p>To search for a concurrent scavenge partial GC cycle, you can search for the <code>type</code> attribute value <code>scavenge</code> in <code>cycle-start</code> and <code>cycle-end</code> elements, or search for the <code>&lt;af&gt;</code> element that logs the allocation failure trigger.</p> <p>You can locate the concurrent scavenge partial cycle's concurrent increment by searching for <code>&lt;concurrent-start&gt;</code> and <code>&lt;concurrent-end&gt;</code>. The global cycle's intermediate concurrent increment, which can run at the same time, is not logged by an element, but begins immediately after application threads are restarted following the <code>&lt;cycle-start type=\"global\"/&gt;</code> element. For more information about the global cycle's intermediate concurrent increment, see <code>gencon</code> global GC cycle. For more information about GC increments, see GC increments and interleaving.</p>"},{"location":"vgclog_examples/#gencon-global-gc-cycle","title":"<code>gencon</code> global GC cycle","text":"<p>The following example shows how a global GC cycle is recorded in a <code>gencon</code> policy verbose GC log. The output is broken down into sections with supporting text to explain the GC processing that is taking place.</p> <p>The global GC cycle runs when the tenure area is close to full, which typically occurs after many partial cycles. As such, the output can be found part way down a full log. For more information about the GC initialization section, see Initialization . For an example log output for a <code>gencon</code> partial cycle, see Scavenge partial GC cycle.</p> <p>The global GC cycle is split into three increments, as shown in GC increments and interleaving. Splitting the cycle operations into the following increments reduces pause times by running the majority of the GC work concurrently. The concurrent increment pauses when a partial GC cycle is triggered and resumes after the partial cycle, or multiple cycles, finish. The interleaving of partial GC cycles with the global cycle's intermediate concurrent increment can be seen in the following <code>gencon</code> global GC cycle log output. A single partial GC cycle is logged between the initial and final increments of the global cycle.</p> <p>To search for a global cycle, you can search for the <code>type</code> attribute value <code>global</code> in <code>cycle-start</code> and <code>cycle-end</code> elements, or search for the element that logs the initial concurrent increment, <code>&lt;concurrent-kickoff&gt;</code>.</p> <p>The following elements log the GC increments and operations of the global GC cycle:</p> Table showing the <code>gencon</code> global cycle's GC increment and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment Details  n/a - initiates cycle initial STW <code>&lt;concurrent-kickoff&gt;</code> No <code>&lt;gc-op&gt;</code> is logged. This increment just initiates the concurrent mark increment.  concurrent mark intermediate  concurrent none <code>&lt;concurrent-trace-info&gt;</code> records the progress of the concurrent mark increment.  final collection final STW  <code>&lt;concurrent-global-final&gt;</code> The increment is typically triggered when a card cleaning threshold is reached. The completion of a tracing phase can also trigger the increment. Operations include a final concurrent mark, a sweep, and an optional class unload and compact. <p>The global GC cycle follows a general structure in the verbose GC log. Some child elements are omitted for clarity. Multiple partial GC cycles can start and finish between the start and end of a global GC cycle. In the following example, the structure includes a single partial GC cycle within the global cycle:</p> <pre><code>\n&lt;concurrent-kickoff/&gt;       (global cycle 1st increment recorded)\n\n&lt;exclusive-start/&gt;          (STW pause starts)\n\n&lt;cycle-start/&gt;              (global cycle starts)\n\n&lt;exclusive-end/&gt;            (STW pause ends)\n\n(mutator threads running, global cycle concurrent increment running concurrently)\n\n\n&lt;exclusive-start/&gt;          (STW for partial GC cycle starts)\n\n\n...                         (partial GC cycle starts and completes)\n\n\n&lt;exclusive-end/&gt;            (STW for partial GC cycle ends)\n\n(mutator threads running, global cycle concurrent increment running concurrently)\n\n&lt;exclusive-start/&gt;          (STW pause starts)\n\n&lt;concurrent-global-final/&gt;  (global cycle final increment recorded)\n\n&lt;gc-start/&gt;                 (global cycle final increment starts)\n\n&lt;allocation-stats/&gt;         (Snapshot of how memory was divided up between\n                            ... application threads before current cycle started)\n\n&lt;mem-info&gt;                  (memory status before operations)\n\n&lt;mem&gt;&lt;/mem&gt;                 (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-start&gt;\n\n&lt;gc-op&gt; \u201ctype=rs-scan\"&lt;/gc-op&gt;        (remembered set scan completed)\n\n&lt;gc-op&gt;\u201dtype=card-cleaning\" &lt;/gc-op&gt;  (card cleaning completed)\n\n&lt;gc-op&gt; \u201ctype=mark\u201d&lt;/gc-op&gt;           (final mark operation and weak roots processing completed)\n\n&lt;gc-op&gt; \u201ctype=classunload\u201d&lt;/gc-op&gt;    (class unload operation completed)\n\n&lt;gc-op \u201dtype=sweep\u201d /&gt;                (sweep operation completed)\n\n&lt;gc-end&gt;                     (global cycle final increment ends)\n\n&lt;mem-info&gt;                   (memory status after operations)\n\n&lt;mem&gt;&lt;/mem&gt;                  (status of different areas of heap)\n\n&lt;/mem-info&gt;\n\n&lt;/gc-end&gt;\n\n&lt;/cycle-end&gt;                 (global cycle ends)\n\n&lt;exclusive-end&gt;              (STW pause ends)\n\n&lt;exclusive-start&gt;            (STW pause starts)\n...\n\n</code></pre> <p>The first activity in the cycle is recorded by a <code>&lt;concurrent-kickoff&gt;</code> element, which records the start of the first of three increments that make up a <code>gencon</code> global GC cycle. The <code>&lt;concurrent-kickoff&gt;</code> element records the following information:</p> <ul> <li>The reason why the GC cycle was triggered. For a <code>gencon</code> global cycle, the cycle is triggered when the amount of free memory decreases to a threshold value, the <code>thresholdFreeBytes</code> value.</li> <li>The target number of bytes, <code>targetBytes</code>, that the cycle aims to mark concurrently.</li> <li>The current available memory in the different parts of the heap.</li> </ul> <pre><code>&lt;concurrent-kickoff id=\"12362\" timestamp=\"2020-10-18T13:35:44.341\"&gt;\n\n&lt;kickoff reason=\"threshold reached\" targetBytes=\"239014924\" thresholdFreeBytes=\"33024922\" remainingFree=\"32933776\" tenureFreeBytes=\"42439200\" nurseryFreeBytes=\"32933776\" /&gt;\n\n&lt;/concurrent-kickoff&gt;\n</code></pre> <p>For this example, the <code>remainingFree</code> bytes value of 31.4 MB (32,933,776B) is approaching the <code>thresholdFreeBytes</code> value of 31.5 MB (33,024,922B) so a global cycle is triggered.  </p> <p>This cycle aims to trace 228 MB (239,014,924B) during the concurrent increment. If the concurrent increment is interrupted by a card cleaning threshold value before it traces all 228 MB, the final STW increment completes the tracing during the STW pause.</p> <p> Note: To analyze specific parts of a cycle, you can search for the elements that mark a specific increment of the cycle. For example, you can search for the  element to locate the final increment of the <code>gencon</code> global cycle. See the details of a particular cycle, such as the <code>gencon</code> global GC cycle, to determine the element names for particular STW or concurrent GC increments or operations. <p>The next element recorded in the log, the <code>&lt;exclusive-start&gt;</code>element, records the start of an STW pause:</p> <pre><code>&lt;exclusive-start id=\"12363\" timestamp=\"2020-10-18T13:35:44.344\" intervalms=\"342.152\"&gt;\n\n&lt;response-info timems=\"0.135\" idlems=\"0.068\" threads=\"3\" lastid=\"00000000015DE600\" lastname=\"LargeThreadPool-thread-24\" /&gt;\n\n&lt;/exclusive-start&gt;\n</code></pre> <p>The following <code>&lt;gc-start&gt;</code> element records details of the start of a new cycle.</p> <pre><code>&lt;cycle-start id=\"12364\" type=\"global\" contextid=\"0\" timestamp=\"2020-10-18T13:35:44.344\" intervalms=\"516655.052\" /&gt;\n</code></pre> <p>The <code>type</code> attribute records the cycle as a global cycle. The <code>contextid</code> of the cycle is, which indicates that all GC events that are associated with this cycle are tagged in relation to the <code>id</code> of this cycle. In particular, all subsequent elements that are associated with this particular example cycle have a <code>contextid</code> value equal to the <code>&lt;cycle-start&gt;</code> <code>id</code> attribute value of <code>\u201c12634\u201d</code>.</p> <p>The next element in the log is <code>&lt;exclusive-end&gt;</code>, which records the end of the STW pause:</p> <pre><code>&lt;exclusive-end id=\"12365\" timestamp=\"2020-10-18T13:35:44.344\" durationms=\"0.048\" /&gt;\n</code></pre> <p>The operations and suboperations of the second increment of the <code>gencon</code> global cycle are now running concurrently.</p> <p>The next section of the logs records an STW pause that is associated with an allocation failure. The <code>&lt;cycle-start&gt;</code> element that follows this STW pause indicates that the cycle is a <code>scavenge</code> cycle, which is the partial GC cycle that is used by the <code>gencon</code> GC:</p> <pre><code>...\n&lt;cycle-start id=\"12368\" type=\"scavenge\" contextid=\"0\" timestamp=\"2020-10-18T13:35:44.582\" intervalms=\"580.047\" /&gt;\n...\n</code></pre> <p>Subsequent elements have a <code>contextid=\u201c12368\u201d</code>, which matches the <code>id</code> of this new <code>scavenge</code>cycle. For more information about how this cycle is recorded in the logs, see Scavenge partial GC cycle.</p> <p>The operations and suboperations of the second, concurrent increment of the <code>gencon</code> global cycle are paused while the STW <code>scavenge</code> operation is running, and resume when the STW pause finishes.</p> <p>After the partial GC cycle completes and the STW pause finishes, the log records a new STW pause, which is triggered to enable the final <code>gencon</code> global GC increment to run. This final increment finishes marking the nursery area and completes the global cycle. The <code>&lt;exclusive-start&gt;</code> element is followed by a <code>&lt;concurrent-global-final&gt;</code> element, which logs the beginning of this final increment (and by implication, the end of the second increment).</p> <pre><code>&lt;exclusive-start id=\"12378\" timestamp=\"2020-10-18T13:35:44.594\" intervalms=\"12.075\"&gt;\n\n&lt;response-info timems=\"0.108\" idlems=\"0.040\" threads=\"3\" lastid=\"00000000018D3800\" lastname=\"LargeThreadPool-thread-33\" /&gt;\n\n&lt;/exclusive-start&gt;\n\n&lt;concurrent-global-final id=\"12379\" timestamp=\"2020-10-18T13:35:44.594\" intervalms=\"516905.029\" &gt;\n\n&lt;concurrent-trace-info reason=\"card cleaning threshold reached\" tracedByMutators=\"200087048\" tracedByHelpers=\"12164180\" cardsCleaned=\"4966\" workStackOverflowCount=\"0\" /&gt;\n\n&lt;/concurrent-global-final&gt;\n</code></pre> <p>The <code>reason</code> attribute of the <code>&lt;concurrent-trace-info&gt;</code> child element indicates that this final STW increment of the global cycle was triggered because a card-cleaning threshold was reached. The concurrent tracing was stopped prematurely and the <code>targetBytes</code> concurrent tracing target, recorded at the cycle start by <code>&lt;concurrent-kickoff&gt;</code>, was not achieved concurrently. If the concurrent tracing completes without interruption, the <code>&lt;concurrent-trace-info</code> element logs <code>reason=tracing completed</code>.  </p> <p>In the next section that begins with the <code>gc-start</code> element, you can find information about the amount of memory available (<code>&lt;mem-info&gt;</code>) and where it is located in the java object heap. This snapshot is taken before the final increment's operations and suboperations are run and can be compared with a similar snapshot that is taken afterward to understand the effect on the heap. The child element attribute values of the<code>&lt;mem&gt;</code> and <code>&lt;mem-info&gt;</code> elements indicate the status of the memory.</p> <p> Note: You can double check that the increment is associated with the GC global cycle in the example by checking the <code>contextid</code> attribute value matches the <code>id=12364</code> attribute value of the cycle's  element. <pre><code>&lt;gc-start id=\"12380\" type=\"global\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.594\"&gt;\n\n&lt;mem-info id=\"12381\" free=\"277048640\" total=\"1073741824\" percent=\"25\"&gt;\n\n&lt;mem type=\"nursery\" free=\"234609440\" total=\"268435456\" percent=\"87\"&gt;\n\n&lt;mem type=\"allocate\" free=\"234609440\" total=\"241565696\" percent=\"97\" /&gt;\n\n&lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;mem type=\"tenure\" free=\"42439200\" total=\"805306368\" percent=\"5\"&gt;\n\n&lt;mem type=\"soa\" free=\"2173472\" total=\"765040640\" percent=\"0\" /&gt;\n\n&lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;pending-finalizers system=\"0\" default=\"0\" reference=\"405\" classloader=\"0\" /&gt;\n\n&lt;remembered-set count=\"17388\" /&gt;\n\n&lt;/mem-info&gt;\n\n&lt;/gc-start&gt;\n\n&lt;allocation-stats totalBytes=\"827488\" &gt;\n\n&lt;allocated-bytes non-tlh=\"96\" tlh=\"827392\" /&gt;\n\n&lt;largest-consumer threadName=\"LargeThreadPool-thread-68\" threadId=\"00000000013D6900\" bytes=\"65632\" /&gt;\n\n&lt;/allocation-stats&gt;\n</code></pre> <p>The next element <code>&lt;allocation-stats&gt;</code> shows a snapshot of how memory was divided up between application threads before the current cycle started. In this example, the thread that used the most memory was <code>LargeThreadPool-thread-68</code>.</p> <p>For this example, at the start of this GC increment, the tenure area is low on free memory, as expected. 25% of the total heap is available as free memory, which is split between the following areas of the heap:</p> <ul> <li>The nursery area, which has 223.7 MB (234,609,440B) of free memory available. The free memory is only available in the allocate space of the nursery area. The survivor space of the nursery area is reported as 'full' to reflect that no available memory is available to allocate to the mutator threads. The entire survivor space is reserved for GC operations during the GC increment.</li> <li>The tenure area, which has 40.5 MB (42,439,200B) available as free memory, which is only 5% of its total memory. Most of this free memory is in the large object area (LOA). Almost no free memory is available in the small object area (SOA).</li> </ul> <p>The <code>&lt;gc-op&gt;</code> elements and their child elements contain information about the operations and suboperations in the increment. The final increment of the <code>gencon</code> global cycle consists of multiple operations, each logged with a <code>&lt;gc-op&gt;</code> element. The type of operation is shown by the <code>&lt;gc-op&gt;</code> <code>type</code> attribute. The final increment of the example log runs five types of operation:</p> <ol> <li><code>rs-scan</code></li> <li><code>card-cleaning</code></li> <li><code>mark</code></li> <li><code>classunload</code></li> <li><code>sweep</code></li> </ol> <p> Note: The final increment of a <code>gencon</code> global cycle can include an optional <code>compact</code> suboperation.</p> <p>For more information about the different types of GC operation, see GC operations.</p> <pre><code>&lt;gc-op id=\"12382\" type=\"rs-scan\" timems=\"3.525\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.598\"&gt;\n\n&lt;scan objectsFound=\"11895\" bytesTraced=\"5537600\" workStackOverflowCount=\"0\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12383\" type=\"card-cleaning\" timems=\"2.910\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.601\"&gt;\n\n&lt;card-cleaning cardsCleaned=\"3603\" bytesTraced=\"5808348\" workStackOverflowCount=\"0\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12384\" type=\"mark\" timems=\"6.495\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.607\"&gt;\n\n&lt;trace-info objectcount=\"1936\" scancount=\"1698\" scanbytes=\"61200\" /&gt;\n\n&lt;finalization candidates=\"389\" enqueued=\"1\" /&gt;\n\n&lt;ownableSynchronizers candidates=\"5076\" cleared=\"523\" /&gt;\n\n&lt;references type=\"soft\" candidates=\"18420\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"32\" maxThreshold=\"32\" /&gt;\n\n&lt;references type=\"weak\" candidates=\"19920\" cleared=\"114\" enqueued=\"60\" /&gt;\n\n&lt;references type=\"phantom\" candidates=\"671\" cleared=\"50\" enqueued=\"50\" /&gt;\n\n&lt;stringconstants candidates=\"40956\" cleared=\"109\" /&gt;\n\n&lt;object-monitors candidates=\"182\" cleared=\"51\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12385\" type=\"classunload\" timems=\"1.607\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.609\"&gt;\n\n&lt;classunload-info classloadercandidates=\"425\" classloadersunloaded=\"6\" classesunloaded=\"2\" anonymousclassesunloaded=\"1\" quiescems=\"0.000\" setupms=\"1.581\" scanms=\"0.019\" postms=\"0.007\" /&gt;\n\n&lt;/gc-op&gt;\n\n&lt;gc-op id=\"12386\" type=\"sweep\" timems=\"9.464\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.618\" /&gt;\n</code></pre> <p>The end of the increment is recorded with <code>&lt;gc-end&gt;</code> and provides another snapshot of memory in the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"12387\" type=\"global\" contextid=\"12364\" durationms=\"24.220\" usertimems=\"86.465\" systemtimems=\"0.000\" stalltimems=\"2.846\" timestamp=\"2020-10-18T13:35:44.618\" activeThreads=\"4\"&gt;\n\n&lt;mem-info id=\"12388\" free=\"650476504\" total=\"1073741824\" percent=\"60\"&gt;\n\n&lt;mem type=\"nursery\" free=\"235516088\" total=\"268435456\" percent=\"87\"&gt;\n\n&lt;mem type=\"allocate\" free=\"235516088\" total=\"241565696\" percent=\"97\" /&gt;\n\n&lt;mem type=\"survivor\" free=\"0\" total=\"26869760\" percent=\"0\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;mem type=\"tenure\" free=\"414960416\" total=\"805306368\" percent=\"51\" micro-fragmented=\"98245682\" macro-fragmented=\"0\"&gt;\n\n&lt;mem type=\"soa\" free=\"374694688\" total=\"765040640\" percent=\"48\" /&gt;\n\n&lt;mem type=\"loa\" free=\"40265728\" total=\"40265728\" percent=\"100\" /&gt;\n\n&lt;/mem&gt;\n\n&lt;pending-finalizers system=\"1\" default=\"0\" reference=\"515\" classloader=\"0\" /&gt;\n\n&lt;remembered-set count=\"13554\" /&gt;\n\n&lt;/mem-info&gt;\n\n&lt;/gc-end&gt;\n</code></pre> <p>60% of the heap now contains free memory as a result of the final global cycle increment, which is split between the following areas of the heap:</p> <ul> <li>The nursery area, which gained 0.9 MB of free memory. The nursery area now has 224.6 MB (235,516,088B) available as free memory. At the start of the final increment, the nursery area had 223.7 MB (234,609,440B) of free memory available.</li> <li>The tenure area, which gained 355.2 MB (372,521,216B) of free memory. (the tenure area now has 395.7 MB (414,960,416B) available as free memory. At the start of the final increment, the tenure area had 40.5 MB (42,439,200B) of free memory available).</li> </ul> <p> Note: The global GC cycle runs to reclaim memory in the tenure area. The freeing up of memory in the nursery area is achieved by using the partial GC cycle. For more information, see <code>gencon</code> policy (default).</p> <p>After the final increment of the global cycle completes, the global cycle ends and the STW pause ends, as shown in the following output:</p> <pre><code>&lt;cycle-end id=\"12389\" type=\"global\" contextid=\"12364\" timestamp=\"2020-10-18T13:35:44.619\" /&gt;\n\n&lt;exclusive-end id=\"12391\" timestamp=\"2020-10-18T13:35:44.619\" durationms=\"24.679\" /&gt;\n</code></pre>"},{"location":"vgclog_examples/#summary_1","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example global cycle has the following characteristics:</p> <ul> <li> <p>The GC global cycle is triggered when a memory threshold is reached and begins with an STW pause.</p> </li> <li> <p>After the first increment of the GC global cycle completes, the STW pause ends and the second increment runs concurrently.</p> </li> <li> <p>A single partial GC cycle starts and finishes between the start and end of the concurrent increment.</p> </li> <li> <p>An STW pause begins after the concurrent increments completes, during which the third and final increment of the global cycle, which consists of five operations, runs.</p> </li> <li> <p>The global GC cycle reclaims memory in the tenure area and a small amount of memory in the nursery area.</p> </li> </ul>"},{"location":"vgclog_examples/#balanced-examples","title":"<code>balanced</code> examples","text":"<p>The <code>balanced</code> policy (<code>-Xgcpolicy:balanced</code>) uses two types of cycle to perform GC; a partial GC cycle and a global GC mark cycle. The policy might also run a third type of cycle, which is a global cycle, to reclaim memory after an allocation failure that results from tight memory conditions.</p> <p>For more information about the cycles used in a particular policy, see GC policies.</p> <p>The start of a <code>balanced</code> cycle is recorded in the log by the following elements and attributes:</p> Table showing types of <code>balanced</code> cycle, the corresponding trigger, and XML elements for each `type`.  GC cycle or increment Value of <code>type</code> attribute of the cycle or increment elements Element that logs the cycle trigger Trigger reason  partial cycle <code>partial gc</code> <code>&lt;allocation-taxation&gt;</code> Allocation taxation threshold reached. global mark cycle <code>global mark phase</code> <code>&lt;allocation-taxation&gt;</code> Allocation taxation threshold reached. global mark STW subincrement of global mark cycle <code>mark increment</code> n/a Allocation taxation threshold reached global mark concurrent subincrement of global mark cycle <code>GMP work packet processing</code> n/a Allocation taxation threshold reached global cycle <code>global garbage collect</code> <code>&lt;af-start&gt;</code> (or <code>&lt;sys-start reason=\"explicit\"&gt;</code> if triggered explicitly) Allocation failure. Occurs under tight memory conditions. Cycle runs rarely. <p>To locate a particular type of cycle, you can search for the <code>type</code> attribute of the <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code> elements.</p> <p>When memory in the Java object heap reaches a memory threshold, called an allocation taxation threshold, a <code>balanced</code> partial GC cycle, <code>balanced</code> global mark cycle, or <code>balanced</code> global mark cycle increment, is triggered. If the available memory in the heap is low, the GC triggers a <code>balanced</code> global mark cycle, or a global mark cycle increment if the global mark cycle is in progress. Otherwise, the GC triggers a partial cycle.</p> <p>Partial GC cycles, global mark cycles, and global GC cycles set the allocation taxation threshold at the end of their cycle or increment to schedule the next cycle or increment. For <code>balanced</code> cycles, the taxation on the mutator threads refers to pausing the mutator threads while GC work is run.</p> <p>When a partial cycle ends, if the cycle is not run between global mark phase increments of a global mark cycle, and a global mark cycle is not scheduled as the next cycle, the allocation taxation threshold is set to trigger the next partial cycle when the eden space is full. Specifically, the allocation threshold is set to be equal to the size of the eden space.</p> <p>If a partial cycle runs within a global mark cycle, or if a global mark cycle is scheduled as the next cycle, the allocation taxation threshold, set at the end of the partial cycle, is set to be smaller than the size of the eden space.  Specifically, the allocation taxation threshold is set to be half the size of the eden space so that the next global mark cycle or global mark cycle increment has enough memory available in the eden space to run.</p> <p>For more information about GC increments, see GC increments and interleaving.</p> <p>You can analyze the increments and operations that are associated with a particular type of cycle by locating and interpreting the elements in the following table:</p> Table showing increments and operations that are associated with the <code>balanced</code> partial and global mark cycles GC process Elements that log the start and end of the event&gt; Details  GC cycle <code>&lt;cycle-start&gt;</code>,<code>&lt;cycle-end&gt;</code> The start and end of a GC cycle  GC STW increment <code>&lt;gc-start&gt;</code><code>&lt;gc-end&gt;</code> The start and end of a GC increment or subincrement that begins with a STW pause. For example, a <code>global mark phase</code> global mark GC cycle increment or a partial GC cycle increment  GC concurrent increment <code>&lt;concurrent-start&gt;</code>, <code>&lt;concurrent-end&gt;</code> The start of the concurrent global mark phase work packet processing subincrements of the global mark cycle  GC operations and phases <code>&lt;gc-op&gt;</code> A GC operation such as mark or sweep, or a suboperation such as class unload. <p>For more information about the XML structure of GC cycles, see GC cycles.</p> <p>The following sections use log excerpts to show how the different GC processes are logged.</p>"},{"location":"vgclog_examples/#balanced-partial-gc-cycle","title":"<code>balanced</code> partial GC cycle","text":"<p>The following example is taken from a <code>balanced</code> policy verbose GC log. The output is broken down into sections to explain the GC processing that is taking place.</p> <p>To search for a <code>balanced</code> partial GC cycle, you can search for the <code>type</code> attribute value <code>partial gc</code> in <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code> elements.</p> <p>The partial GC cycle reclaims memory in the heap for the allocation of new objects by reducing the number of used regions. The partial GC cycle always reduces used regions in the eden space and might also reclaim memory from older regions. Multiple partial GC cycles often run in between global mark phase increments of the <code>balanced</code> global mark GC cycle.  </p> <p>All the operations in a partial GC cycle run during a single STW pause, as shown in the following table:</p> Table showing the <code>balanced</code> partial GC cycle operation and corresponding XML elements. GC operation GC increment STW or concurrent XML element of GC increment  copy forward, and optionally class unload, sweep, and compact single  STW  <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> <p>The following general structure shows a <code>balanced</code> partial GC cycle. Some child elements are omitted for clarity:</p> <pre><code>&lt;exclusive-start/&gt;                       (STW pause starts)\n\n&lt;allocation-taxation/&gt;                   (memory threshold trigger recorded)\n\n&lt;cycle-start/&gt;                            (partial cycle starts)\n\n&lt;gc-start/&gt;                             (partial  cycle increment starts)\n\n&lt;mem-info&gt;                            (memory status before operations)\n\n  &lt;mem&gt;&lt;/mem&gt;                         (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-start&gt;\n\n&lt;allocation-stats/&gt;                  (Snapshot of how memory was divided up between\n                                     ... application threads before current cycle started)\n\n&lt;gc-op&gt; type=\"copy forward\" &lt;/gc-op&gt;    (copy forward operation completed)\n\n&lt;gc-op&gt; type=\"class unload\" &lt;/gc-op&gt;    (class unload operation completed)\n\n&lt;gc-op&gt; type=\"sweep\" &lt;/gc-op&gt;           (sweep operation completed)\n\n&lt;gc-op&gt; type=\"compact\" &lt;/gc-op&gt;         (compact operation completed)\n\n&lt;gc-end&gt;                                (partial cycle increment ends)\n\n&lt;mem-info&gt;                            (memory status after operations)\n\n  &lt;mem&gt;&lt;/mem&gt;                         (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-end&gt;\n\n&lt;cycle-end&gt;                               (partial cycle ends)\n\n&lt;exclusive-end&gt;                           (STW pause ends)\n</code></pre> <p>When the <code>balanced</code> partial GC cycle is triggered, the GC runs an STW pause. Application (or mutator) threads are halted to give the garbage collector exclusive access to the heap. The STW pause is recorded in the logs by the <code>&lt;exclusive-start&gt;</code> element.</p> <pre><code>&lt;exclusive-start id=\"184\" timestamp=\"2021-02-26T11:11:42.310\" intervalms=\"3745.790\"&gt;\n  &lt;response-info timems=\"3.138\" idlems=\"1.056\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n</code></pre> <p>An allocation taxation threshold triggers a <code>balanced</code> partial GC cycle. The logs record this trigger reason by using the<code>&lt;allocation-taxation&gt;</code> element.</p> <pre><code>&lt;allocation-taxation id=\"185\" taxation-threshold=\"2147483648\" timestamp=\"2021-02-26T11:11:42.311\" intervalms=\"3745.785\" /&gt;\n</code></pre> <p>Details about the start of the cycle are recorded by the <code>&lt;cycle-start&gt;</code> element. The cycle is recorded as a <code>partial gc</code> with an <code>id=336</code>. Any subsequent elements that are associated with this cycle have a <code>contextid=186</code> to match the cycle <code>id</code>. You can use this <code>contextid</code> value to distinguish the partial GC cycle increment and operations from interleaving increments and operations of other <code>balanced</code> cycles, such as global mark cycles.</p> <pre><code>&lt;cycle-start id=\"186\" type=\"partial gc\" contextid=\"0\" timestamp=\"2021-02-26T11:11:42.311\" intervalms=\"3745.805\" /&gt;\n\n</code></pre> <p>The partial cycle begins its only GC increment, recorded by using the <code>&lt;gc-start&gt;</code> element. You can understand the effect that the increment operations have on the heap by comparing snapshots of the memory that are taken at the start and the end of the increment.  The child elements <code>&lt;mem-info&gt;</code> and <code>&lt;mem&gt;</code> of the <code>&lt;gc-start&gt;</code> and <code>&lt;gc-end&gt;</code> elements record the amount of memory available and where it is located in the heap.</p> <pre><code>&lt;gc-start id=\"187\" type=\"partial gc\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.311\"&gt;\n  &lt;mem-info id=\"188\" free=\"897581056\" total=\"4294967296\" percent=\"20\"&gt;\n    &lt;mem type=\"eden\" free=\"0\" total=\"2147483648\" percent=\"0\" /&gt;\n    &lt;arraylet-primitive objects=\"1\" leaves=\"4\" largest=\"4\" /&gt;\n    &lt;remembered-set count=\"2749664\" freebytes=\"160705664\" totalbytes=\"171704320\" percent=\"93\" regionsoverflowed=\"1\" regionsstable=\"12\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>As expected, at the start of this increment, the eden regions are full. 856 MB (897,581,056 B) of the total 4096 MB (4294,967,296 B) heap, equivalent to 20% of the heap, is available as free memory.</p> <p>The status of the remembered set, a metastructure specific to Eclipse OpenJ9\u2122 generational garbage collectors, is reported by the <code>&lt;remembered-set&gt;</code> element. The remembered set metastructure keeps a record of any object references that cross different regions. Each region corresponds to a single remembered set.</p> <p>The partial GC cycle uses and prunes the remembered set. The <code>regionsoverflowed</code> value records the number of regions that exceeded the non-object heap memory allocation that is reserved for the remembered set. The partial GC cycle cannot reclaim memory from these overflow regions. The partial GC cycle also cannot reclaim memory from any regions whose remembered set is being rebuilt by an increment of a global mark cycle that is in progress.</p> <p>At the start of the partial GC cycle, the remembered set is using 93% of its available memory capacity, with 153.26 MB (160705664 B) available. The set consists of 2,749,664 cards and has one overflow region.</p> <p>The following element, <code>&lt;allocation-stats&gt;</code>, records information about how memory was divided between application (or mutator) threads before the start of the current cycle. For this example, the thread <code>Group1.Backend.CompositeBackend{Tier1}.7</code> was the largest consumer of memory.</p> <pre><code>&lt;allocation-stats totalBytes=\"2146431360\" &gt;\n  &lt;allocated-bytes non-tlh=\"96417448\" tlh=\"2050013912\" arrayletleaf=\"0\"/&gt;\n  &lt;largest-consumer threadName=\"Group1.Backend.CompositeBackend{Tier1}.7\" threadId=\"00000000007E9300\" bytes=\"275750048\" /&gt;\n&lt;/allocation-stats&gt;\n</code></pre> <p>The operations of the GC increment are run and details are recorded in the <code>&lt;gc-op&gt;</code> elements. The logs show that this increment begins with a copy forward operation followed by a class unload. Other <code>balanced</code> partial GC cycles can also include sweep and compact operations. For more information about the operations involved in <code>balanced</code> partial GC cycles, see GC Processing.</p> <pre><code>&lt;gc-op id=\"189\" type=\"copy forward\" timems=\"400.637\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.713\"&gt;\n  &lt;memory-copied type=\"eden\" objects=\"4434622\" bytes=\"119281928\" bytesdiscarded=\"1382272\" /&gt;\n  &lt;memory-copied type=\"other\" objects=\"8847813\" bytes=\"244414264\" bytesdiscarded=\"6243176\" /&gt;\n  &lt;memory-cardclean objects=\"1446970\" bytes=\"64143048\" /&gt;\n  &lt;regions eden=\"512\" other=\"80\" /&gt;\n  &lt;remembered-set-cleared processed=\"2435794\" cleared=\"887129\" durationms=\"8.667\" /&gt;\n  &lt;finalization candidates=\"66\" enqueued=\"56\" /&gt;\n  &lt;ownableSynchronizers candidates=\"256500\" cleared=\"78012\" /&gt;\n  &lt;references type=\"soft\" candidates=\"153648\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"22\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"1266\" cleared=\"610\" enqueued=\"430\" /&gt;\n  &lt;stringconstants candidates=\"9479\" cleared=\"0\"  /&gt;\n  &lt;object-monitors candidates=\"13576\" cleared=\"13505\"  /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"190\" type=\"classunload\" timems=\"0.010\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.713\"&gt;\n  &lt;classunload-info classloadercandidates=\"179\" classloadersunloaded=\"0\" classesunloaded=\"0\" anonymousclassesunloaded=\"0\" quiescems=\"0.000\" setupms=\"0.010\" scanms=\"0.000\" postms=\"0.000\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The logs show that the copy forward operation acts on the entire eden space (512 regions), recorded as <code>type=eden</code>, and 80 older regions, which are recorded as <code>type=other</code>. 113.76 MB (119281928 B) of memory was copied from the eden space to 1st generation regions and 233.10 MB (244414264 B) of memory in non-eden regions was copied to the next generation of regions. The copy forward operation is followed by a class unload operation.</p> <p>In some cases, a copy forward operation moves some regions by copying forward the objects in those regions, but only marks the objects in other regions. For example, the following log excerpt is taken from a different partial cycle, which corresponds to a <code>contextid</code> of <code>2049</code>. The copy forward operation in the following example involves marking some regions and copying forward other regions.</p> <pre><code>&lt;gc-op id=\"2052\" type=\"copy forward\" timems=\"649.059\" contextid=\"2049\" timestamp=\"2021-02-26T11:22:34.901\"&gt;\n  &lt;memory-copied type=\"eden\" objects=\"95989\" bytes=\"7882704\" bytesdiscarded=\"501088\" /&gt;\n  &lt;memory-copied type=\"other\" objects=\"2955854\" bytes=\"86854064\" bytesdiscarded=\"626024\" /&gt;\n  &lt;memory-cardclean objects=\"1304\" bytes=\"56840\" /&gt;\n  &lt;memory-traced type=\"eden\" objects=\"23392785\" bytes=\"553756840\" /&gt;\n  &lt;memory-traced type=\"other\" objects=\"5461302\" bytes=\"131394216\" /&gt;\n  &lt;regions eden=\"488\" other=\"138\" /&gt;\n  &lt;remembered-set-cleared processed=\"156775\" cleared=\"4897\" durationms=\"1.759\" /&gt;\n  &lt;finalization candidates=\"31\" enqueued=\"12\" /&gt;\n  &lt;ownableSynchronizers candidates=\"1992467\" cleared=\"1600904\" /&gt;\n  &lt;references type=\"soft\" candidates=\"329190\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"8\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"697\" cleared=\"105\" enqueued=\"6\" /&gt;\n  &lt;stringconstants candidates=\"9848\" cleared=\"0\"  /&gt;\n  &lt;object-monitors candidates=\"1437\" cleared=\"1353\"  /&gt;\n  &lt;heap-resize type=\"expand\" space=\"default\" amount=\"0\" count=\"1\" timems=\"0.000\" reason=\"continue current collection\" /&gt;\n  &lt;warning details=\"operation aborted due to insufficient free space\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The logs record these two concurrent parts of a copy forward operation in the <code>&lt;gc-op type=\"copy forward\"&gt;</code> section by using a <code>&lt;memory-traced&gt;</code> child element. In addition,<code>evacuated</code> and <code>marked</code> attributes for the <code>&lt;regions&gt;</code> child element are used to distinguish between the number of regions that were copied-forward (recorded as <code>evacuated</code>) and the number of regions that were only marked and not copied-forward. For example, <code>&lt;regions eden=\"256\" other=\"308\" evacuated=\"308\" marked=\"256\" /&gt;</code>.</p> <p>Returning to the <code>contextid=186</code> partial cycle example, the next element in the logs, <code>&lt;gc-end&gt;</code>, records the end of the increment and provides another snapshot of memory allocation on the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"191\" type=\"partial gc\" contextid=\"186\" durationms=\"402.645\" usertimems=\"3157.520\" systemtimems=\"4.000\" stalltimems=\"47.689\" timestamp=\"2021-02-26T11:11:42.714\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"192\" free=\"3003121664\" total=\"4294967296\" percent=\"69\"&gt;\n    &lt;mem type=\"eden\" free=\"2147483648\" total=\"2147483648\" percent=\"100\" /&gt;\n    &lt;arraylet-primitive objects=\"1\" leaves=\"4\" largest=\"4\" /&gt;\n    &lt;pending-finalizers system=\"56\" default=\"0\" reference=\"430\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"2922048\" freebytes=\"160016128\" totalbytes=\"171704320\" percent=\"93\" regionsoverflowed=\"1\" regionsstable=\"12\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The following information describes the heap memory allocation at the end of the increment:</p> <ul> <li> <p>The heap now has 2864 MB (3,003,121,664 bytes) of memory available compared to the 856 MB available at the start of the increment. The increment reclaimed 2,008 MB of memory in the heap, which is slightly less than the size of the eden space, as is typically the case.</p> </li> <li> <p>The eden space is recorded to have 100% memory available as free memory. The eden space, which consists of regions containing the youngest objects, was fully re-created by reclaiming almost all of the eden regions and assigning some other empty regions of the heap to the eden space. Note that some objects from eden regions always survive.</p> </li> <li> <p>The remembered set count increased by 172,384 cards, and the number of free bytes in the remembered set decreased by 0.66 MB (689,536 B).</p> </li> </ul> <p>The cycle completes and the GC restarts application threads.</p> <pre><code>&lt;cycle-end id=\"193\" type=\"partial gc\" contextid=\"186\" timestamp=\"2021-02-26T11:11:42.714\" /&gt;\n&lt;exclusive-end id=\"194\" timestamp=\"2021-02-26T11:11:42.714\" durationms=\"404.145\" /&gt;\n</code></pre> <p>The next cycle that is recorded in the logs is another partial GC cycle. The <code>&lt;gc-start&gt;</code>element records the following information:</p> <pre><code>&lt;gc-start id=\"198\" type=\"partial gc\" contextid=\"197\" timestamp=\"2021-02-26T11:11:46.072\"&gt;\n  &lt;mem-info id=\"199\" free=\"855638016\" total=\"4294967296\" percent=\"19\"&gt;\n    &lt;mem type=\"eden\" free=\"0\" total=\"2147483648\" percent=\"0\" /&gt;\n    &lt;arraylet-primitive objects=\"1\" leaves=\"4\" largest=\"4\" /&gt;\n    &lt;remembered-set count=\"2922048\" freebytes=\"160016128\" totalbytes=\"171704320\" percent=\"93\" regionsoverflowed=\"1\" regionsstable=\"12\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The <code>&lt;mem-info&gt;</code> element shows that the following events occurred in between the end of the last (partial) GC cycle and the start of this cycle:</p> <ul> <li>All available memory in the eden area was allocated to application threads.</li> <li>Application threads also used some memory from non-eden heap areas. The total available memory in the heap reduced from 69% to 19%.</li> <li>The remembered set status is unchanged, as shown by the <code>&lt;remembered-set&gt;</code> element. When mutator threads run, they build data about object references that cross boundaries by using a card table. However, the processing of card table data into the remembered set, and the reporting of the remembered set counts, are run during other cycle operations.</li> </ul>"},{"location":"vgclog_examples/#summary_2","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example <code>balanced</code> partial GC cycle has the following characteristics:</p> <ul> <li>The partial GC cycle is triggered when the eden space is full by an allocation taxation threshold.</li> <li>All GC operations that are associated with this cycle occur during the STW pause.</li> <li>The partial GC cycle consists of only one increment, which runs a copy forward operation on 512 eden regions and 80 other regions, followed by a class-unload operation.</li> <li>The partial GC cycle re-creates a free eden space by reclaiming all possible regions from the eden space (some objects always survive) and assigning other free regions to the eden space. The GC cycle also reclaims memory from some other regions.</li> <li>2864 MB of the total 4096 MB heap was reclaimed. 100% of the eden space is available as free memory, and some older regions were also reclaimed.</li> <li>Between the start and end of the partial GC cycle, the remembered set count increases by 172,384 cards and the number of free bytes decreases by 0.66 MB (689,536 B). After performing a copy forward operation on objects to move them to older regions, the partial GC cycle rebuilds the remembered set of any regions that received these moved objects. During a partial cycle, the remembered set is also pruned. Overall, the rebuilding and pruning can lead to either an increase or a decrease in the remembered set count and free memory available.</li> <li>The remembered set metastructure remains unchanged between GC cycles, even though the mutator threads build new data about object references when the threads run. The remembered set count is identical at the end of one partial GC cycle and the beginning of the next because the remembered set consumes this data and reports to the verbose GC logs only during a cycle's operation.</li> </ul>"},{"location":"vgclog_examples/#balanced-global-mark-gc-cycle","title":"<code>balanced</code> global mark GC cycle","text":"<p>The global mark GC cycle uses a mixture of STW and concurrent operations to build a new record of object liveness across the heap for use by the <code>balanced</code> partial GC cycle. The <code>balanced</code> GC runs a <code>balanced global mark cycle</code>, or a <code>balanced</code> global mark cycle increment if the global mark cycle is in progress, if the heap satisfies a low memory condition when the allocation taxation threshold is reached.</p> <p>The global mark cycle runs a global mark phase and also triggers an associated sweep phase within the partial GC cycle that immediately follows the end of the global mark cycle.</p> <p>To search for a <code>balanced</code> global mark cycle, you can search for the <code>type</code> attribute value <code>global mark phase</code> in <code>&lt;cycle-start&gt;</code> and <code>&lt;cycle-end&gt;</code> elements.</p> <p>The global cycle is split into multiple increments, each recorded as <code>type=\"global mark phase\"</code>. A global mark phase increment involves an STW subincrement, which runs a global mark operation during an STW pause, followed by a global mark phase (GMP) work packet subincrement. The GMP work packet subincrement involves a processing operation that runs concurrently. The GMP work packet subincrement might also use an STW pause to complete if the subincrement is interrupted by a partial or global cycle trigger.</p> <p>Splitting the global mark phase into these increments and subincrements reduces pause times by running the majority of the GC work concurrently and interleaving global mark phase increments with partial GC cycles, and, rarely a <code>balanced</code> global GC cycles.</p> <p>The following elements log the GC increments, subincrements, and operations of the global mark GC cycle:</p> Table showing the global mark cycle GC increments and corresponding XML elements GC increment GC operations&gt; STW or concurrent XML element of GC increment Details <code>global mark phase</code> subincrement mark STW <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> The global mark phase operations start at the beginning of the cycle and run through all regions until the final region <code>GMP work packet processing</code> subincrement Work packet processing (WPP) operations concurrent and sometimes final operations during an STW to complete the subincrement <code>&lt;concurrent-start&gt;</code>, <code>&lt;concurrent-end&gt;</code> The <code>GMP work packet processing subincrement</code> runs immediately after the <code>global mark phase</code>  final global mark phase increment final global mark phase operations including class unload STW <code>&lt;gc-start&gt;</code>, <code>&lt;gc-end&gt;</code> Final increment. Runs the final global mark phase operations, including weak roots processing, followed by operations to finish the cycle <p>The following structure shows a <code>balanced</code> global mark GC cycle. The lines are indented to help illustrate the flow and some child elements are omitted for clarity:</p> <pre><code>&lt;exclusive-start/&gt;                        (STW pause starts)\n\n&lt;allocation-taxation/&gt;                    (memory threshold trigger recorded)\n\n&lt;cycle-start type=\"global mark phase\"/&gt;   (global mark cycle starts)\n\n&lt;gc-start type=\"global mark phase\"/&gt;      (1st GMP STW subincrement starts)\n\n    &lt;mem-info&gt;                            (memory status before operations)\n\n    &lt;remembered-set&gt;\n\n    &lt;/mem-info&gt;         \n\n&lt;/gc-start&gt;\n\n&lt;gc-op type=\"mark increment\" /&gt;           (STW copy forward operation completed)\n\n&lt;gc-end&gt;                                  (1st GMP STW subincrement ends)\n\n    &lt;mem-info&gt;                            (memory status after operations)\n\n    &lt;remembered-set&gt;\n\n    &lt;/mem-info&gt;\n\n&lt;gc-end&gt;\n\n&lt;concurrent-start type=\"GMP work packet processing\"/&gt; (1st GMP concurrent subincrement starts)\n\n&lt;exclusive-end/&gt;                                      (STW pause ends and application threads resume)\n\n&lt;concurrent-end type=\"GMP work packet processing\"/&gt;   (1st GMP concurrent subincrement ends)\n\n&lt;gc-op type=\"mark increment\"/&gt;                        (marking operation runs concurrently)\n\n&lt;/concurrent-end type=\"GMP work packet processing\"/&gt;\n\n...                                       (application threads run. STW pauses stop    \n                                          and start application threads to run\n                                          partial GC cycles.)\n\n&lt;exclusive-start/&gt;                        (STW pause starts)\n\n&lt;gc-start type=\"global mark phase\"/&gt;      (2nd STW GMP subincrement starts)\n\n...   \n\n&lt;concurrent-start type=\"GMP work packet processing\"/&gt; (2nd concurrent GMP subincrement starts)\n\n...\n\n&lt;exclusive-end/&gt;\n\n...                                       (application threads run. Partial GC cycles may run)\n\n&lt;concurrent-end type=\"GMP work packet processing\" /&gt;  (2nd concurrent GMP subincrement ends)\n...\n\n&lt;/concurrent-end&gt;\n\n...                                       (application threads run. Partial cycles\n                                          and GMP increments interleave)\n\n&lt;exclusive-start/&gt;                        (STW pause starts)\n\n...\n\n&lt;gc-start type=\"global mark phase\"/&gt;      (final STW GMP subincrement starts.)\n\n&lt;gc-op type=\"mark increment\" /&gt;           (STW copy forward operation completed)\n\n&lt;gc-op  type=\"class unload\" /&gt;            (STW class unload operation completed)\n\n&lt;gc-end&gt;                                  (1st GMP STW subincrement ends)\n...   \n&lt;gc-end type=\"global mark phase\"/&gt;        (final STW GMP subincrement ends. No concurrent subincrement runs)\n\n&lt;cycle-end type=\"global mark phase\"/&gt;     (end of global mark cycle)\n\n&lt;exclusive-end/&gt;                          (STW pause ends)    \n\n&lt;exclusive-start/&gt;                        (STW pause starts)\n\n&lt;cycle-start type=\"partial gc\" /&gt;         (partial cycle starts)\n\n...\n\n&lt;gc-op type=\"sweep\" /&gt;                    (Sweep operation associated with global mark cycle runs)\n\n...\n\n&lt;cycle-end type=\"partial gc\"/&gt;            (partial GC cycle ends)\n\n&lt;exclusive-end/&gt;                          (STw pause ends)\n</code></pre>"},{"location":"vgclog_examples/#global-mark-phase","title":"Global mark phase","text":"<p>The first activity of the global mark cycle is an STW pause, recorded by an <code>&lt;exclusive-start&gt;</code> element that precedes the <code>&lt;cycle-start type=\"global mark phase\"/&gt;</code> element. The garbage collector pauses application threads to run the initial operations.</p> <pre><code>&lt;exclusive-start id=\"1152\" timestamp=\"2021-02-26T11:17:25.033\" intervalms=\"1931.263\"&gt;\n  &lt;response-info timems=\"3.082\" idlems=\"1.041\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n</code></pre> <p>The <code>&lt;allocation-taxation&gt;</code> element indicates that an allocation taxation threshold triggered the cycle. The  <code>taxation threshold</code> is recorded as 1024 MB (1,073,741,824), which is half the total memory of the eden space (2048 MB), as expected for threshold triggers of global mark cycles and increments. For more information about taxation thresholds for the <code>balanced</code> policy, see <code>balanced</code> examples.</p> <pre><code>&lt;allocation-taxation id=\"1153\" taxation-threshold=\"1073741824\" timestamp=\"2021-02-26T11:17:25.034\" intervalms=\"1931.251\" /&gt;\n</code></pre> <p>Details about the start of the global mark GC cycle are recorded by the <code>&lt;cycle-start&gt;</code> element. The cycle is recorded as type <code>global mark phase</code> with <code>id=1154</code>. Any subsequent elements that are associated with this cycle have a <code>contextid=1154</code> to match the global mark GC cycle <code>id</code>. You can use the <code>contextid</code> value to distinguish increments and operations of the global mark GC cycle from the partial cycles that interleave with it.</p> <pre><code>&lt;cycle-start id=\"1154\" type=\"global mark phase\" contextid=\"0\" timestamp=\"2021-02-26T11:17:25.034\" intervalms=\"374365.075\" /&gt;\n</code></pre> <p>The cycle begins with the STW subincrement of a global mark phase increment. The STW subincrement is recorded by using the <code>&lt;gc-start&gt;</code> element of type <code>global mark phase</code>.</p> <pre><code>&lt;gc-start id=\"1155\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.034\"&gt;\n  &lt;mem-info id=\"1156\" free=\"1442840576\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"2197888\" freebytes=\"162912768\" totalbytes=\"171704320\" percent=\"94\" regionsoverflowed=\"3\" regionsstable=\"130\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The <code>&lt;gc-start&gt;</code> element provides a snapshot of the free memory available in the heap and the status of the remembered set. At the start of the increment, the heap is 33% free; 1376 MB (1442840576 B) of the total 4096 MB (4294967296 B).</p> <p>The <code>&lt;remembered-set&gt;</code> element records the status of the remembered set metastructure, a structure that records object references that cross different regions. During the rebuilding of the remembered set metastructure, any regions that cannot be rebuilt into a remembered set due to a lack of memory resource in the metastructure are marked as overflow regions. Partial GC cycles cannot reclaim memory from overflow regions.</p> <p>The aim of the global mark cycle is to create a new record of object liveness by populating the remembered set. The global mark cycle also attempts to rebuild the remembered set information for the overflowed regions, which can be seen in the remembered set statistics. After the global mark cycle completes, the remembered set reflects a closer snapshot of the current liveness of the heap. This more accurate snapshot of object liveness optimizes the pruning of the set, which is run by the partial GC cycle when it consumes the object liveness snapshot.</p> <p>The logs show that at the start of this STW subincrement, the remembered set count is 2,197,888 cards, the metastructure is using 94% of its total available memory, and three overflow regions need to be rebuilt.</p> <p>The <code>&lt;gc-op&gt;</code> element records that the STW subincrement runs a mark operation. This operation begins the process of building a record of object liveness across the heap.</p> <pre><code>&lt;gc-op id=\"1157\" type=\"mark increment\" timems=\"122.825\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.157\"&gt;\n  &lt;trace-info objectcount=\"7726701\" scancount=\"7584109\" scanbytes=\"213445656\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The <code>&lt;trace-info&gt;</code> element records information about the marking and scanning stages of the mark increment operation. <code>objectcount</code> records the number of objects that were marked, ready for tracing. After marking live objects, a scan is run to trace objects and references. The following values are recorded:</p> <ul> <li><code>scancount</code> records the number of marked objects that were scanned.</li> <li><code>scanbytes</code> records the total memory of all marked objects that were scanned.</li> </ul> <p>In the example, the mark increment operation marked 7,726,701 objects and scanned 7,584,109 of these marked objects. The 7,584,109 of scanned objects take up 203.5 MB (213445656 B) of memory. The number of scanned objects is less than the number of marked objects because only objects that have children require scanning. Also, the scanning part of the marking operation might be interrupted by the garbage collector if a trigger threshold for a partial cycle or global cycle is reached during the marking operation.</p> <p>The STW <code>global mark phase</code> subincrement ends, as recorded by <code>&lt;gc-end&gt;</code>, which records a snapshot of the memory status in the heap in a similar way to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"1158\" type=\"global mark phase\" contextid=\"1154\" durationms=\"123.139\" usertimems=\"977.851\" systemtimems=\"0.000\" stalltimems=\"1.453\" timestamp=\"2021-02-26T11:17:25.157\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"1159\" free=\"1442840576\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3263968\" freebytes=\"158648448\" totalbytes=\"171704320\" percent=\"92\" regionsoverflowed=\"0\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The following comparison can be made between the snapshot at the beginning and end of this STW <code>global mark phase</code> subincrement:</p> <ul> <li>The marking operation has increased the <code>count</code> value of the <code>&lt;remembered-set&gt;</code> by 1,066,080 cards (from 2,197,888 to 3,263,968). As regions are rebuilt, the new cards record the new remembered set data that is associated with these regions.</li> <li>The number of overflow regions went from three to zero.</li> <li>As expected with a global mark cycle, there is no change in the amount of free memory available, which is 1376 MB.</li> </ul> <p>The beginning of the second part of the global mark phase increment, the GMP work packet processing subincrememt, is recorded by <code>&lt;concurrent-start&gt;</code>. The child element <code>&lt;concurrent-mark-start&gt;</code> records the scan target of this subincrement as 242.74 MB (254,532,672 B).</p> <pre><code>&lt;concurrent-start id=\"1160\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.157\"&gt;\n  &lt;concurrent-mark-start scanTarget=\"254532672\" /&gt;\n&lt;/concurrent-start&gt;\n</code></pre> <p>Now that the STW global mark phase subincrement is complete, application threads are restarted.</p> <pre><code>&lt;exclusive-end id=\"1161\" timestamp=\"2021-02-26T11:17:25.157\" durationms=\"123.936\" /&gt;\n</code></pre> <p>The <code>GMP work packet processing</code> subincrement continues to run concurrently. The end of this operation is recorded by using the <code>&lt;concurrent-end&gt;</code> element.</p> <pre><code>&lt;concurrent-end id=\"1162\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.469\" terminationReason=\"Work target met\"&gt;\n&lt;gc-op id=\"1163\" type=\"mark increment\" timems=\"311.867\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:25.469\"&gt;\n  &lt;trace-info scanbytes=\"254708852\" /&gt;\n&lt;/gc-op&gt;\n&lt;/concurrent-end&gt;\n</code></pre> <p>The child element <code>&lt;trace-info&gt;</code> shows that the processing scanned 242.91 MB (254,708,852 B), which slightly exceeds the 108.25 MB scan target.</p> <p>Application threads continue to run and allocate memory. The garbage collector stops and starts the application threads to run partial GC cycles that reclaim free space in the eden space and some older regions. To see an example of how a <code>balanced</code> partial GC cycle appears in the logs, see the <code>balanced</code> partial GC cycle.</p> <p>Following some partial GC cycles, an allocation taxation threshold is reached that triggers an STW pause followed by another global mark phase increment. The element <code>&lt;gc-start&gt;</code> in the following log excerpt has a <code>contextid=1154</code> and type <code>global mark phase</code>, which indicates that this is a global mark phase subincrement associated with the global mark cycle example.</p> <pre><code>&lt;exclusive-start id=\"1175\" timestamp=\"2021-02-26T11:17:28.993\" intervalms=\"1978.886\"&gt;\n  &lt;response-info timems=\"5.111\" idlems=\"1.714\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n&lt;allocation-taxation id=\"1176\" taxation-threshold=\"1073741824\" timestamp=\"2021-02-26T11:17:28.994\" intervalms=\"1978.879\" /&gt;\n&lt;gc-start id=\"1177\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:28.994\"&gt;\n  &lt;mem-info id=\"1178\" free=\"1451229184\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3325824\" freebytes=\"158401024\" totalbytes=\"171704320\" percent=\"92\" regionsoverflowed=\"2\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>The <code>&lt;allocation-taxation&gt;</code> element shows that the allocation taxation threshold, which triggers this global mark phase increment, is set to 1024 MB, half of the size of the eden space, as expected.</p> <p><code>&lt;gc-start&gt;</code> records that the heap has 1384 MB (1,451,229,184 B) of free memory available at the beginning of this global mark phase increment. This value compares to the 1376 MB (1,442,840,576 B) of free memory available at the end of the previous global mark phase increment. Although free memory was reclaimed by the partial GC cycles that ran between these global mark phase increments, free memory was allocated to objects when application threads ran, resulting in a net reduction of free memory available.</p> <p>The status of the heap at the beginning and end of STW subincrements are automatically recorded. For this STW subincrement, there are no <code>&lt;gc-op&gt;</code> elements recorded; <code>&lt;gc-end&gt;</code> immediately follows <code>&lt;gc-start&gt;</code> in the logs. For some STW subincrements, a mark operation is run.</p> <pre><code>&lt;gc-end id=\"1179\" type=\"global mark phase\" contextid=\"1154\" durationms=\"0.289\" usertimems=\"1.000\" systemtimems=\"0.000\" stalltimems=\"0.000\" timestamp=\"2021-02-26T11:17:28.994\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"1180\" free=\"1451229184\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3325824\" freebytes=\"158401024\" totalbytes=\"171704320\" percent=\"92\" regionsoverflowed=\"2\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>The second part of the increment, the <code>GMP work packet processing</code> subincrement, is recorded by using the <code>&lt;concurrent-start&gt;</code> and <code>&lt;concurrent-end&gt;</code> elements.</p> <pre><code>&lt;concurrent-start id=\"1181\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:28.994\"&gt;\n  &lt;concurrent-mark-start scanTarget=\"258671414\" /&gt;\n&lt;/concurrent-start&gt;\n&lt;exclusive-end id=\"1182\" timestamp=\"2021-02-26T11:17:28.994\" durationms=\"0.816\" /&gt;\n\n&lt;concurrent-end id=\"1183\" type=\"GMP work packet processing\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:29.273\" terminationReason=\"Work target met\"&gt;\n&lt;gc-op id=\"1184\" type=\"mark increment\" timems=\"279.311\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:29.274\"&gt;\n  &lt;trace-info scanbytes=\"258767612\" /&gt;\n&lt;/gc-op&gt;\n&lt;/concurrent-end&gt;\n</code></pre> <p>The log excerpt shows the concurrent <code>GMP work packet processing</code> subincrement achieved the scan target of 246.69 MB (258671414 B). 246.78 MB (258767612 B) were scanned.</p> <p>More partial cycles run. This pattern of interleaving of global mark increments with partial GC cycles repeats until a final global mark increment completes the global mark cycle. The final global mark phase increment consists of an STW <code>global mark phase</code> subincrement that includes <code>mark increment</code> and <code>class unload</code> operations.</p> <pre><code>&lt;exclusive-start id=\"1217\" timestamp=\"2021-02-26T11:17:36.864\" intervalms=\"1986.124\"&gt;\n  &lt;response-info timems=\"0.287\" idlems=\"0.104\" threads=\"2\" lastid=\"00000000006EDE00\" lastname=\"RunDataWriter.1\" /&gt;\n&lt;/exclusive-start&gt;\n&lt;allocation-taxation id=\"1218\" taxation-threshold=\"1073741824\" timestamp=\"2021-02-26T11:17:36.865\" intervalms=\"1986.101\" /&gt;\n&lt;gc-start id=\"1219\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:36.865\"&gt;\n  &lt;mem-info id=\"1220\" free=\"1438646272\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;remembered-set count=\"3514496\" freebytes=\"157646336\" totalbytes=\"171704320\" percent=\"91\" regionsoverflowed=\"3\" regionsstable=\"0\" regionsrebuilding=\"133\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n&lt;gc-op id=\"1221\" type=\"mark increment\" timems=\"164.843\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:37.030\"&gt;\n  &lt;trace-info objectcount=\"7715572\" scancount=\"7665293\" scanbytes=\"214739196\" /&gt;\n  &lt;cardclean-info objects=\"3962203\" bytes=\"117924792\" /&gt;\n  &lt;finalization candidates=\"206\" enqueued=\"30\" /&gt;\n  &lt;ownableSynchronizers candidates=\"601780\" cleared=\"16925\" /&gt;\n  &lt;references type=\"soft\" candidates=\"718240\" cleared=\"2858\" enqueued=\"2832\" dynamicThreshold=\"18\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"2321\" cleared=\"142\" enqueued=\"0\" /&gt;\n  &lt;references type=\"phantom\" candidates=\"8\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;stringconstants candidates=\"9522\" cleared=\"0\"  /&gt;\n  &lt;object-monitors candidates=\"7142\" cleared=\"7066\"  /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"1222\" type=\"classunload\" timems=\"0.704\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:37.030\"&gt;\n  &lt;classunload-info classloadercandidates=\"185\" classloadersunloaded=\"13\" classesunloaded=\"13\" anonymousclassesunloaded=\"0\" quiescems=\"0.000\" setupms=\"0.644\" scanms=\"0.043\" postms=\"0.016\" /&gt;\n&lt;/gc-op&gt;\n&lt;gc-end id=\"1223\" type=\"global mark phase\" contextid=\"1154\" durationms=\"169.521\" usertimems=\"1244.810\" systemtimems=\"3.000\" stalltimems=\"27.792\" timestamp=\"2021-02-26T11:17:37.034\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"1224\" free=\"1438646272\" total=\"4294967296\" percent=\"33\"&gt;\n    &lt;pending-finalizers system=\"30\" default=\"0\" reference=\"2832\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"2241440\" freebytes=\"162738560\" totalbytes=\"171704320\" percent=\"94\" regionsoverflowed=\"3\" regionsstable=\"127\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>Comparing the memory at the start and end of this final <code>global mark phase</code> increment shows the following status:</p> <ul> <li>As expected, the final global mark phase increment does not reclaim any free memory.</li> <li>The remembered set metastructure was marginally rebuilt. The card count has increased slightly, and the number of stable regions dropped from 130 to 127. </li> <li>The number of overflow regions remains unchanged. The final global mark phase increment did not manage to rebuild any overflow regions.</li> </ul> <p>Following the final global mark increment, the global mark cycle completes and the GC ends the STW pause.</p> <pre><code>&lt;cycle-end id=\"1225\" type=\"global mark phase\" contextid=\"1154\" timestamp=\"2021-02-26T11:17:37.034\" /&gt;\n&lt;exclusive-end id=\"1226\" timestamp=\"2021-02-26T11:17:37.034\" durationms=\"170.186\" /&gt;\n</code></pre> <p>The operations to create a record of object liveness across the heap, which began with the global mark cycle, is followed by a sweep phase. The sweep phase is triggered by the end of the global mark cycle to be included in the next partial GC cycle that runs.</p>"},{"location":"vgclog_examples/#sweep-phase","title":"Sweep phase","text":"<p>The sweep operation has the following two objectives:</p> <ul> <li>To directly reclaim some memory by creating empty regions.</li> <li>To build information about occupancy and fragmentation for regions that still contain live objects. The next partial GC cycle uses this information to defragment older regions.</li> </ul> <p>While the global sweep operation is logically associated with the global mark phase, it does not run in the same global mark cycle. Instead, the sweep operation runs in the same STW increment as the first partial GC cycle that runs after the completion of the global mark cycle. This can be seen in the following log excerpt.  After the log records the end of the global mark cycle, it records an STW pause followed by a <code>partial gc</code> cycle of <code>id=1229</code>. The global sweep operation that runs after the global mark phase is recorded in the <code>&lt;gc-op&gt;</code> element that is tagged as <code>id=1229</code>.</p> <pre><code>&lt;exclusive-start id=\"1227\" timestamp=\"2021-02-26T11:17:38.804\" intervalms=\"1940.125\"&gt;\n...\n&lt;cycle-start id=\"1229\" type=\"partial gc\" contextid=\"0\" timestamp=\"2021-02-26T11:17:38.805\" intervalms=\"3926.202\" /&gt;\n...\n&lt;/gc-start&gt;\n...\n&lt;/gc-start&gt;\n&lt;gc-op id=\"1232\" type=\"sweep\" timems=\"9.472\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:38.815\" /&gt;\n&lt;gc-op id=\"1233\" type=\"copy forward\" timems=\"308.258\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:39.124\"&gt;\n...\n&lt;gc-op id=\"1234\" type=\"classunload\" timems=\"0.012\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:39.125\"&gt;\n...\n&lt;gc-end&gt;\n...\n&lt;/gc-end&gt;\n&lt;cycle-end id=\"1237\" type=\"partial gc\" contextid=\"1229\" timestamp=\"2021-02-26T11:17:39.125\" /&gt;\n&lt;exclusive-end id=\"1238\" timestamp=\"2021-02-26T11:17:39.125\" durationms=\"320.792\" /&gt;\n</code></pre> <p>A record of object liveness is now complete.</p>"},{"location":"vgclog_examples/#summary_3","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this example <code>balanced</code> global mark GC cycle has the following characteristics:</p> <ul> <li>If the total free memory is low when the taxation allocation threshold is reached, the GC triggers a global mark cycle. The allocation taxation threshold is set by the previous cycle to trigger a new cycle when the eden space is half full. This threshold value frees up eden space to enable a global mark cycle to interleave with the GC operations of partial GC cycles.</li> <li>Each global mark phase increment is triggered by an allocation taxation threshold value that is set to half of the eden space.</li> <li>Global mark GC cycle and global mark cycle increments begin with an STW pause.</li> <li>The global mark cycle does not reclaim memory. The cycle creates an updated record of object liveness by rebuilding the mark map, and also attempts to rebuild the remembered set for overflowed and stable regions. The change in status of the remembered set metastructure can be seen in the logs by inspecting the <code>&lt;remembered-set&gt;</code> attributes.</li> <li>Partial cycles run in between global mark phase increments.</li> <li>The final global mark phase increment includes a class unload. The final increment also triggers a sweep phase to run in the next partial cycle.</li> </ul>"},{"location":"vgclog_examples/#balanced-global-gc-cycle","title":"<code>balanced</code> global GC cycle","text":"<p>The following global GC cycle example is taken from a <code>balanced</code> verbose GC log. The output is broken down into sections to explain the GC processing that is taking place.</p> <p>A <code>balanced</code> global cycle is triggered if the VM is close to throwing an out of memory exception. This situation occurs only under tight memory conditions when the garbage collector cannot reclaim enough memory by using only partial and global mark cycles.</p> <p>To search for a <code>balanced</code> global cycle or increment, you can search for the <code>type</code> attribute value <code>global garbage collect</code> of the cycle or increment element.</p> <p>If the <code>balanced</code> global cycle is triggered during a <code>balanced</code> global mark GC cycle, a new <code>global</code> cycle is not recorded. Instead, the global mark cycle's global mark phase increment switches to a global garbage collect increment that is run as an STW increment. This switch is recorded in the logs by using a <code>&lt;cycle-continue&gt;</code> element, which precedes the <code>gc-start</code> element that records the new global garbage collect increment.</p> <p>If the <code>balanced</code> global cycle is not triggered during a <code>balanced</code> global mark cycle, the global cycle is recorded as a new cycle by using the <code>&lt;cycle-start&gt;</code> element.</p> <p>The element <code>&lt;sys-start reason=\"explicit\"&gt;</code> is used in the logs to record a cycle that was triggered explicitly rather than by the garbage collector. For example, the trigger reason is recorded as <code>explicit</code> if a cycle is triggered by an application calling <code>System.gc()</code>. For more information about explicitly or implicitly triggering a GC cycle, see Garbage collection.</p> <p>The global cycle operations run as a single GC increment during an STW pause.</p> Table showing the <code>balanced</code> global cycle's GC increment and corresponding XML elements. GC increment  GC operations STW or concurrent XML element of GC increment Details single STW mark-sweep operations, optionally followed by a compact operation STW <code>&lt;cycle-start&gt;</code>, <code>&lt;gc-end&gt;</code> Contains detailed information about where free memory is located and remembered set statistics <p>If the global cycle is triggered during a global mark cycle, the global cycle follows a general structure in the verbose GC log as shown. Some child elements are omitted for clarity:</p> <pre><code>...                                        (global mark cycle increment runs)\n\n&lt;af-start/&gt;                                (allocation failure trigger recorded)\n\n&lt;concurrent-end/&gt;                          (global mark cycle concurrent subincrement finishes )\n\n&lt;allocation-taxation/&gt;                     (memory threshold trigger recorded)\n\n&lt;cycle-continue/&gt;                          (change of cycle type from global mark to global)\n\n&lt;/gc-start type=\"global garbage collect\"/&gt; (global cycle STW increment starts)\n\n&lt;mem-info&gt;                                 (memory status before operations)\n\n &lt;mem&gt;&lt;/mem&gt;                               (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-start type=\"global garbage collect\"/&gt;\n\n&lt;allocation-stats/&gt;                        (Snapshot of how memory was divided up between\n                                           ... application threads before current cycle started)\n&lt;gc-op&gt; type=\"mark\" &lt;/gc-op&gt;                (mark operation completed)\n\n&lt;gc-op&gt; type=\"class unload\" &lt;/gc-op&gt;        (class unload operation completed)\n\n&lt;gc-op&gt; type=\"sweep\" &lt;/gc-op&gt;               (sweep operation completed)\n\n&lt;gc-op&gt; type=\"compact\" &lt;/gc-op&gt;             (compact operation completed)\n\n&lt;gc-end type=\"global garbage collect\"&gt;      (global cycle STW increment ends)\n\n&lt;mem-info&gt;                                  (memory status after operations)\n\n&lt;mem&gt;&lt;/mem&gt;                                 (status of different types of memory)\n\n&lt;/mem-info&gt;         \n\n&lt;/gc-end type=\"global garbage collect\"&gt;\n\n&lt;cycle-end type = \"global garbage collect\"/&gt; (cycle ends)\n\n&lt;allocation-satisfed/&gt;                      (required allocation has been achieved)\n\n&lt;exclusive-end&gt;                             (STW pause ends)\n</code></pre> <p>The following example shows a <code>balanced</code> global cycle that is triggered during a global mark cycle.</p> <p>The start of the GMP work processing subincrement of the global mark cycle, which runs concurrently with application threads, is recorded by using the <code>&lt;concurrent-start&gt;</code> element.</p> <pre><code>&lt;concurrent-start id=\"2009\" type=\"GMP work packet processing\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.109\"&gt;\n  &lt;concurrent-mark-start scanTarget=\"18446744073709551615\" /&gt;\n&lt;/concurrent-start&gt;\n</code></pre> <p>After the start of the concurrent subincrement, the logs record an allocation failure by using <code>&lt;af-start&gt;</code>. The <code>&lt;concurrent-end&gt;</code> element attribute <code>terminationReason</code> shows that a termination of the concurrent increment was requested by the garbage collector.</p> <pre><code>&lt;af-start id=\"2010\" threadId=\"00000000008AA780\" totalBytesRequested=\"24\" timestamp=\"2021-03-05T12:16:43.109\" intervalms=\"1212.727\" /&gt;\n&lt;concurrent-end id=\"2011\" type=\"GMP work packet processing\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\" terminationReason=\"Termination requested\"&gt;\n&lt;gc-op id=\"2012\" type=\"mark increment\" timems=\"0.893\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\"&gt;\n  &lt;trace-info scanbytes=\"584612\" /&gt;\n&lt;/gc-op&gt;\n&lt;/concurrent-end&gt;\n</code></pre> <p>The next element, the <code>&lt;cycle-continue&gt;</code> element, records information about the switch of cycle type from a global mark cycle, recorded as type <code>global mark phase</code>, to a global cycle, recorded as type <code>global garbage collect</code>.</p> <pre><code>&lt;cycle-continue id=\"2013\" oldtype=\"global mark phase\" newtype=\"global garbage collect\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\" /&gt;\n</code></pre> <p>A global cycle increment is recorded by <code>&lt;gc-start&gt;</code> and has the same <code>contextid</code> as the global mark cycle's elements. The global cycle operations are run during an STW pause and as a modification to the global mark cycle rather than a new cycle. The memory snapshot within the <code>&lt;gc-start&gt;</code> element is taken before the global increment's operations run and can be compared with a similar snapshot that is taken afterward to understand the effect on the heap.</p> <pre><code>&lt;gc-start id=\"2014\" type=\"global garbage collect\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.110\"&gt;\n  &lt;mem-info id=\"2015\" free=\"0\" total=\"838860800\" percent=\"0\"&gt;\n    &lt;mem type=\"eden\" free=\"0\" total=\"524288\" percent=\"0\" /&gt;\n    &lt;remembered-set count=\"12832\" freebytes=\"33331072\" totalbytes=\"33382400\" percent=\"99\" regionsoverflowed=\"0\" regionsstable=\"0\" regionsrebuilding=\"1593\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-start&gt;\n</code></pre> <p>At the start of the global cycle's increment, the amount of memory available in the heap is zero. In some cases, the heap is close to full, and in other cases, the memory is full.</p> <p>The next element <code>&lt;allocation-stats&gt;</code> shows a snapshot of how memory was divided up between application threads before the current cycle started.</p> <pre><code>&lt;allocation-stats totalBytes=\"524200\" &gt;\n  &lt;allocated-bytes non-tlh=\"0\" tlh=\"524200\" arrayletleaf=\"0\"/&gt;\n&lt;/allocation-stats&gt;\n</code></pre> <p>The <code>&lt;allocation-stats&gt;</code> element shows that very little allocation took place. Global cycles are triggered due to an allocation failure, so the low memory allocation values are expected.</p> <p>The following operations, each recorded by a <code>&lt;gc-op&gt;</code> element, run as part of the global cycle's increment:</p> <ul> <li><code>global mark</code></li> <li><code>class unload</code></li> <li><code>sweep</code></li> <li><code>compact</code></li> </ul> <pre><code>&lt;gc-op id=\"2016\" type=\"global mark\" timems=\"357.859\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.468\"&gt;\n  &lt;trace-info objectcount=\"37461962\" scancount=\"37447916\" scanbytes=\"828311396\" /&gt;\n  &lt;cardclean-info objects=\"311\" bytes=\"22632\" /&gt;\n  &lt;finalization candidates=\"195\" enqueued=\"2\" /&gt;\n  &lt;ownableSynchronizers candidates=\"2089\" cleared=\"0\" /&gt;\n  &lt;references type=\"soft\" candidates=\"3059\" cleared=\"0\" enqueued=\"0\" dynamicThreshold=\"0\" maxThreshold=\"32\" /&gt;\n  &lt;references type=\"weak\" candidates=\"10797\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;references type=\"phantom\" candidates=\"6\" cleared=\"0\" enqueued=\"0\" /&gt;\n  &lt;stringconstants candidates=\"10031\" cleared=\"0\"  /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"2017\" type=\"classunload\" timems=\"0.123\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.468\"&gt;\n  &lt;classunload-info classloadercandidates=\"25\" classloadersunloaded=\"0\" classesunloaded=\"0\" anonymousclassesunloaded=\"0\" quiescems=\"0.000\" setupms=\"0.123\" scanms=\"0.000\" postms=\"0.000\" /&gt;\n&lt;/gc-op&gt;\n&lt;gc-op id=\"2018\" type=\"sweep\" timems=\"5.120\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:43.474\" /&gt;\n&lt;gc-op id=\"2019\" type=\"compact\" timems=\"762.323\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:44.236\"&gt;\n  &lt;compact-info movecount=\"8024461\" movebytes=\"163375400\" /&gt;\n  &lt;remembered-set-cleared processed=\"777104\" cleared=\"777104\" durationms=\"2.188\" /&gt;\n&lt;/gc-op&gt;\n</code></pre> <p>The global cycle's increment ends. The end of the increment is recorded with <code>&lt;gc-end&gt;</code> and provides another snapshot of memory allocation on the heap, similar to <code>&lt;gc-start&gt;</code>.</p> <pre><code>&lt;gc-end id=\"2020\" type=\"global garbage collect\" contextid=\"2003\" durationms=\"1126.788\" usertimems=\"7971.788\" systemtimems=\"1.000\" stalltimems=\"1016.256\" timestamp=\"2021-03-05T12:16:44.237\" activeThreads=\"8\"&gt;\n  &lt;mem-info id=\"2021\" free=\"1572864\" total=\"838860800\" percent=\"0\"&gt;\n    &lt;mem type=\"eden\" free=\"1572864\" total=\"1572864\" percent=\"100\" /&gt;\n    &lt;pending-finalizers system=\"2\" default=\"0\" reference=\"0\" classloader=\"0\" /&gt;\n    &lt;remembered-set count=\"874496\" freebytes=\"29884416\" totalbytes=\"33382400\" percent=\"89\" regionsoverflowed=\"0\" regionsstable=\"0\" regionsrebuilding=\"0\"/&gt;\n  &lt;/mem-info&gt;\n&lt;/gc-end&gt;\n</code></pre> <p>Comparing the snapshot at the beginning and end of this STW <code>global mark phase</code> subincrement shows that memory was reclaimed and regions reassigned to create an empty eden space, equal to 1.5 MB (1,572,864 B). Because global cycles are triggered when memory conditions are tight, the global cycle is able to reclaim only a small amount of memory.</p> <p>The cycle ends (<code>&lt;cycle-end&gt;</code>). The following <code>&lt;allocation-satisfied&gt;</code> element indicates that the allocation request that caused the allocation failure can now complete successfully.</p> <pre><code>&lt;cycle-end id=\"2022\" type=\"global garbage collect\" contextid=\"2003\" timestamp=\"2021-03-05T12:16:44.237\" /&gt;\n&lt;allocation-satisfied id=\"2023\" threadId=\"00000000008A9E00\" bytesRequested=\"24\" /&gt;\n&lt;af-end id=\"2024\" timestamp=\"2021-03-05T12:16:44.237\" threadId=\"00000000008AA780\" success=\"true\" /&gt;\n</code></pre> <p>The STW pause ends with the <code>&lt;exclusive-end&gt;</code> element.</p> <pre><code>&lt;exclusive-end id=\"2025\" timestamp=\"2021-03-05T12:16:44.237\" durationms=\"1130.358\" /&gt;\n</code></pre>"},{"location":"vgclog_examples/#summary_4","title":"Summary","text":"<p>Analyzing the structure and elements of this example log output shows that this global cycle has the following characteristics:</p> <ul> <li> <p>The global GC cycle was triggered during a global mark GC cycle when the heap was very low in memory. The memory could not be reclaimed by just using partial GC cycles and global mark cycles.</p> </li> <li> <p>The concurrent subincrement of the global mark GC cycle was interrupted by an allocation failure that triggered the concurrent subincrement to end and the <code>global mark</code> cycle type to change to a <code>global</code> type.</p> </li> <li> <p>The global GC cycle consists of only 1 GC increment, which runs mark, sweep, and compact operations during an STW pause.</p> </li> <li> <p>The global GC cycle reclaimed the eden space (1.5 MB of memory). When global GC cycle's are triggered, which occurs when memory conditions are tight, the amount of memory that the global GC cycle reclaims is often small.</p> </li> </ul>"},{"location":"x/","title":"-X","text":""},{"location":"x/#-x","title":"-X","text":"<p>Displays help on nonstandard options.</p>"},{"location":"x/#syntax","title":"Syntax","text":"<pre><code>    -X\n</code></pre>"},{"location":"x_jvm_commands/","title":"Using -X options","text":""},{"location":"x_jvm_commands/#using-x-command-line-options","title":"Using -X command-line options","text":"<p>Use these options to configure the Eclipse OpenJ9\u2122 virtual machine (VM). Unlike standard options, options prefixed with <code>-X</code> are nonstandard and are typically unique to a Java\u2122 virtual machine implementation. However, in some cases, <code>-X</code> option names are common to different VM implementations and might have the same function.</p> <p>For options that take a <code>&lt;size&gt;</code> parameter, add a suffix to the size value: \"k\" or \"K\" to indicate kilobytes, \"m\" or \"M\" to indicate megabytes, \"g\" or \"G\" to indicate gigabytes, or \"t\" or \"T\" to indicate terabytes.</p> <p>For example, to set the <code>-Xmx</code> value to 16 MB, you can specify <code>-Xmx16M</code>, <code>-Xmx16m</code>, <code>-Xmx16384K</code>, <code>-Xmx16384k</code>, or <code>-Xmx16777216</code> on the command line.</p>"},{"location":"xaggressive/","title":"-Xaggressive","text":""},{"location":"xaggressive/#-xaggressive","title":"-Xaggressive","text":"<p>Enables performance optimizations and new platform exploitation that are expected to be the default in future releases.</p>"},{"location":"xaggressive/#syntax","title":"Syntax","text":"<pre><code>    -Xaggressive\n</code></pre>"},{"location":"xalwaysclassgc/","title":"-Xalwaysclassgc","text":""},{"location":"xalwaysclassgc/#-xalwaysclassgc","title":"-Xalwaysclassgc","text":"<p>Always perform dynamic class unloading during global garbage collection.</p>"},{"location":"xalwaysclassgc/#syntax","title":"Syntax","text":"<pre><code>    -Xalwaysclassgc\n</code></pre>"},{"location":"xalwaysclassgc/#default-behavior","title":"Default behavior","text":"<p>If you don't set this option, the default behavior is defined by <code>-Xclassgc</code>.</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xalwaysclassgc/#see-also","title":"See also","text":"<ul> <li><code>-Xclassgc</code>/<code>-Xnoclassgc</code></li> </ul>"},{"location":"xaot/","title":"-Xnoaot","text":""},{"location":"xaot/#-xaot-xnoaot","title":"-Xaot / -Xnoaot","text":"<p>Use this option to control the behavior of the ahead-of-time (AOT) compiler. When the AOT compiler is active, the compiler selects the methods to be AOT compiled with the primary goal of improving startup time.</p> <p>AOT compilation allows the compilation of Java\u2122 classes into native code for subsequent executions of the same program. The AOT compiler works with the class data sharing framework.</p> <p>The AOT compiler generates native code dynamically while an application runs and caches any generated AOT code in the shared data cache. Subsequent VMs that execute the method can load and use the AOT code from the shared data cache without incurring the performance decrease experienced with JIT-compiled native code.</p>"},{"location":"xaot/#performance","title":"Performance","text":"<p>Because AOT code must persist over different program executions, AOT-generated code does not perform as well as JIT-generated code. AOT code usually performs better than interpreted code.</p> <p>In a VM without an AOT compiler or with the AOT compiler disabled, the JIT compiler selectively compiles frequently used methods into optimized native code. There is a time cost associated with compiling methods because the JIT compiler operates while the application is running. Because methods begin by being interpreted and most JIT compilations occur during startup, startup times can be increased.</p> <p>Startup performance can be improved by using the shared AOT code to provide native code without compiling. There is a small time cost to load the AOT code for a method from the shared data cache and bind it into a running program. The time cost is low compared to the time it takes the JIT compiler to compile that method.</p>"},{"location":"xaot/#default-behavior","title":"Default behavior","text":"<p>The AOT compiler is enabled by default, but is only active for classes that are found in the shared classes cache. See Introduction to class data sharing for information about the shared classes cache, how class sharing is enabled, and what options are available to modify class sharing behavior.</p>"},{"location":"xaot/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xaot</code> Enable AOT yes <code>-Xaot:&lt;parameter&gt;[=&lt;value&gt;]</code> (See Note) Enable AOT with modifications <code>-Xnoaot</code> Disable AOT <p> Note: You can concatenate several parameters in a comma-separated list, for example: <code>-Xaot:&lt;parameter1&gt;[=&lt;value1&gt;], &lt;parameter2&gt;[=&lt;value2&gt;]</code>.</p> <p>Specify the <code>-Xaot</code> option only once. By default, if you specify this option multiple times, only the last option takes effect. You can use the <code>-XX:+MergeCompilerOptions</code> option to merge all the existing instances of the <code>-Xaot</code> options logically.</p>"},{"location":"xaot/#parameters-for-xaot","title":"Parameters for <code>-Xaot</code>","text":"Parameter Effect <code>verbose</code> Reports information about the AOT and JIT compiler configuration and method compilation. <code>count</code> Specifies the number of times a method is called before it is compiled. <code>exclude</code> Excludes specified methods when AOT code is compiled. <code>limit</code> Includes specified methods when AOT code is compiled. <code>limitFile</code> Compiles only the methods listed in the specified limit file. <code>loadExclude</code> Excludes specified methods when AOT code is loaded. <code>loadLimit</code> Includes specified methods when AOT code is loaded. <code>loadLimitFile</code> Loads only the methods listed in the specified limit file."},{"location":"xaot/#verbose","title":"<code>verbose</code>","text":"<pre><code>    -Xaot:verbose\n</code></pre> Reports information about the AOT and JIT compiler configuration and method compilation."},{"location":"xaot/#count","title":"<code>count</code>","text":"<pre><code>    -Xaot:count=&lt;n&gt;\n</code></pre> Specifies the number of times, <code>&lt;n&gt;</code>, a method is called before it is compiled or loaded from an existing shared classes cache. Setting <code>-Xaot:count=0</code> forces the AOT compiler to compile everything on first execution, which is useful for problem determination."},{"location":"xaot/#exclude","title":"<code>exclude</code>","text":"<pre><code>    -Xaot:exclude={&lt;method_name&gt;}\n</code></pre> <p>Excludes a Java method when AOT code is compiled from the shared classes cache. Use this option if the method causes the program to fail.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be excluded; the wildcard <code>*</code> may be used. Specify as much of the full package, class and method as necessary.</p> <p>For example, <code>-Xaot:exclude={test/sample/MyClass.testMethod()V}</code> excludes the single method specified. However, <code>-Xaot:exclude={test/sample/MyClass.testMethod()*}</code> excludes the method regardless of return type. Similarly, <code>-Xaot:exclude={*}</code> excludes all methods.</p> <p> Note: <code>exclude</code> has the same effect regardless of whether it's specified on <code>-Xjit</code> or <code>-Xaot</code>. In consequence, if you specify <code>-Xaot:exclude</code>, JIT compilation is also prevented and the methods specified are always interpreted.</p>"},{"location":"xaot/#limit","title":"<code>limit</code>","text":"<pre><code>    -Xaot:limit={&lt;method_name&gt;}\n</code></pre> <p>Only the Java methods specified are included when AOT code is compiled from the shared classes cache. <code>&lt;method_name&gt;</code> is the method or methods that are to be included (the wildcard <code>*</code> may be used, see <code>-Xaot:exclude</code> for details).</p> <p> Note: <code>limit</code> has the same effect regardless of whether it's specified on <code>-Xjit</code> or <code>-Xaot</code>. In consequence, if you specify <code>-Xaot:limit</code>, JIT compilation is also restricted to those methods specified; other methods are always interpreted.</p>"},{"location":"xaot/#limitfile","title":"<code>limitFile</code>","text":"<pre><code>    -Xaot:limitFile=(&lt;filename&gt;,&lt;m&gt;,&lt;n&gt;)\n</code></pre> <p>Compiles or loads only the methods listed on lines <code>&lt;m&gt;</code> to, and including, <code>&lt;n&gt;</code> in the specified limit file, <code>&lt;filename&gt;</code>. Methods not listed in the limit file and methods listed on lines outside the range are not compiled or loaded.</p> <p> Note: <code>limitFile</code> has the same effect regardless of whether it's specified on <code>-Xjit</code> or <code>-Xaot</code>. In consequence, if you specify <code>-Xaot:limitFile</code>, JIT compilation is also restricted to those methods specified; other methods are always interpreted.</p>"},{"location":"xaot/#loadexclude","title":"<code>loadExclude</code>","text":"<pre><code>    -Xaot:loadExclude={&lt;method_name&gt;}\n</code></pre> <p>Excludes the specified Java methods when AOT code is loaded from the shared classes cache. In consequence, the compiler does a JIT compilation on those methods instead.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be excluded (the wildcard <code>*</code> may be used, see <code>-Xaot:exclude</code> for details). This option does not prevent the method from being compiled.</p> <p> Note: <code>loadExclude</code> can only be specified on <code>-Xaot</code>; it does not have an equivalent on <code>-Xjit</code>.</p>"},{"location":"xaot/#loadlimit","title":"<code>loadLimit</code>","text":"<pre><code>    -Xaot:loadLimit={&lt;method_name&gt;}\n</code></pre> <p>Only the Java methods specified are included when AOT code is loaded from the shared classes cache. In consequence, the compiler does a JIT compilation on other methods instead.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be included (the wildcard <code>*</code> may be used; see <code>-Xaot:exclude</code> for details).</p> <p> Note: <code>loadLimit</code> can only be specified on <code>-Xaot</code>; it does not have an equivalent on <code>-Xjit</code>. This option filters what AOT code the compiler is allowed to load from the shared classes cache.</p>"},{"location":"xaot/#loadlimitfile","title":"<code>loadLimitFile</code>","text":"<pre><code>    -Xaot:loadLimitFile=(&lt;filename&gt;,&lt;m&gt;,&lt;n&gt;)\n</code></pre> <p>Loads only the methods listed on lines <code>&lt;m&gt;</code> to, and including, <code>&lt;n&gt;</code> in the specified limit file. In consequence, the compiler does a JIT compilation on other methods instead.</p> <p><code>&lt;filename&gt;</code>. Methods not listed in the limit file and methods listed on lines outside the range are not loaded.</p> <p> Note: <code>loadLimitFile</code> can only be specified on <code>-Xaot</code>; it does not have an equivalent on <code>-Xjit</code>.</p>"},{"location":"xaot/#see-also","title":"See also","text":"<ul> <li>Introduction to class data sharing</li> <li><code>-Xquickstart</code></li> <li><code>-Xshareclasses</code></li> <li><code>-Xjit</code></li> </ul>"},{"location":"xargencoding/","title":"-Xargencoding","text":""},{"location":"xargencoding/#-xargencoding","title":"-Xargencoding","text":"<p>The <code>java</code> and <code>javaw</code> launchers accept arguments and class names containing any character that is in the character set of the current locale. You can also specify any Unicode character in the class name and arguments by using Java\u2122 escape sequences.</p> <p>To do this, use the <code>-Xargencoding</code> command-line option.</p>"},{"location":"xargencoding/#syntax","title":"Syntax","text":"<pre><code>    -Xargencoding:&lt;parameter&gt;\n</code></pre>"},{"location":"xargencoding/#parameters","title":"Parameters","text":""},{"location":"xargencoding/#no-parameter","title":"No parameter","text":"<pre><code>    -Xargencoding\n</code></pre> You can use Unicode escape sequences in the argument list that you pass to this option. To specify a Unicode character, use escape sequences in the form <code>\\u####</code>, where <code>#</code> is a hexadecimal digit (0-9, A-F). For example, to specify a class that is called <code>HelloWorld</code> and use Unicode encoding for both capital letters, use this command:<pre><code>java -Xargencoding \\u0048ello\\u0057orld\n</code></pre>"},{"location":"xargencoding/#utf8","title":"<code>utf8</code>","text":"<pre><code>    -Xargencoding:utf8\n</code></pre> Use utf8 encoding."},{"location":"xargencoding/#latin","title":"<code>latin</code>","text":"<pre><code>    -Xargencoding:latin\n</code></pre> Use ISO8859_1 encoding."},{"location":"xbootclasspath/","title":"-Xbootclasspath","text":""},{"location":"xbootclasspath/#-xbootclasspath","title":"-Xbootclasspath","text":"<p>This Oracle\u00ae HotSpot\u2122 option specifies the search path for bootstrap classes and resources. The default is to search for bootstrap classes and resources in the internal VM directories and <code>.jar</code> files. The option is recognized by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xbootclasspath/#syntax","title":"Syntax","text":"Limited to... Setting Effect <code>-Xbootclasspath:&lt;path&gt;</code> Sets the search path for bootstrap classes and resources. <code>-Xbootclasspath/p:&lt;path&gt;</code> Prepends the specified resources to the front of the bootstrap class path. <code>-Xbootclasspath/a:&lt;path&gt;</code> Appends the specified resources to the end of the bootstrap class path. where <code>&lt;path&gt;</code> represents directories and compressed or Java\u2122 archive files separated with colons (:). On Windows\u2122 systems, use a semicolon (;) as a separator. <p> Oracle advise that you should \"not deploy applications that use this option to override a class in <code>rt.jar</code>, because this violates the JRE binary code license.\"</p>"},{"location":"xceehdlr/","title":"-XCEEHDLR","text":""},{"location":"xceehdlr/#-xceehdlr","title":"-XCEEHDLR","text":"<p>(31-bit z/OS\u00ae only)</p> <p>Controls Eclipse OpenJ9\u2122 VM Language Environment\u00ae condition handling.</p>"},{"location":"xceehdlr/#syntax","title":"Syntax","text":"<pre><code>    -XCEEHDLR\n</code></pre>"},{"location":"xceehdlr/#explanation","title":"Explanation","text":"<p>Use the <code>-XCEEHDLR</code> option if you want the new behavior for the Java\u2122 and COBOL interoperability batch mode environment, because this option makes signal and condition handling behavior more predictable in a mixed Java and COBOL environment.</p> <p>When the <code>-XCEEHDLR</code> option is enabled, a condition triggered by an arithmetic operation while executing a Java Native Interface (JNI) component causes the VM to convert the Language Environment condition into a Java <code>ConditionException</code>.</p> <p>When the <code>-XCEEHDLR</code> option is used the VM does not install POSIX signal handlers for the following signals:</p> <ul> <li><code>SIGBUS</code></li> <li><code>SIGFPE</code></li> <li><code>SIGILL</code></li> <li><code>SIGSEGV</code></li> <li><code>SIGTRAP</code></li> </ul> <p>Instead, user condition handlers are registered by the VM, using the <code>CEEHDLR()</code> method. These condition handlers are registered every time a thread calls into the VM. Threads call into the VM using the Java Native Interface and including the invocation interfaces, for example <code>JNI\\_CreateJavaVM</code>.</p> <p>The Java runtime continues to register POSIX signal handlers for the following signals:</p> <ul> <li><code>SIGABRT</code></li> <li><code>SIGINT</code></li> <li><code>SIGQUIT</code></li> <li><code>SIGTERM</code></li> </ul> <p>Signal chaining using the <code>libjsig.so</code> library is not supported.</p> <p>When the <code>-XCEEHDLR</code> option is used, condition handler actions take place in the following sequence:</p> <ol> <li>All severity 0 and severity 1 conditions are percolated.</li> <li>If a Language Environment condition is triggered in JNI code as a result of an arithmetic operation, the VM condition handler resumes executing Java code as if the JNI native code had thrown a <code>com.ibm.le.conditionhandling.ConditionException</code> exception. This exception class is a subclass of <code>java.lang.RuntimeException</code>. Note: The Language Environment conditions that correspond to arithmetic operations are <code>CEE3208S</code> through <code>CEE3234S</code>. However, the Language Environment does not deliver conditions <code>CEE3208S</code>, <code>CEE3213S</code>, or <code>CEE3234S</code> to C applications, so the VM condition handler will not receive them.</li> <li>If the condition handling reaches this step, the condition is considered to be unrecoverable. RAS diagnostic information is generated, and the VM ends by calling the <code>CEE3AB2()</code> service with abend code 3565, reason code 0, and cleanup code 0.</li> </ol> <p> Restriction: You cannot use <code>-Xsignal:userConditionHandler=percolate</code> and <code>-XCEEHDLR</code> together.</p>"},{"location":"xceehdlr/#see-also","title":"See also","text":"<ul> <li> <p>-Xsignal:userConditionHandler=percolate</p> </li> <li> <p>Signal handling</p> </li> </ul>"},{"location":"xcheck/","title":"-Xcheck","text":""},{"location":"xcheck/#-xcheck","title":"-Xcheck","text":"<p>You can use the <code>-Xcheck</code> option to run checks during Eclipse OpenJ9\u2122 virtual machine (VM) startup, such as memory checks or checks on JNI functions.</p>"},{"location":"xcheck/#syntax","title":"Syntax","text":"<pre><code>    -Xcheck:&lt;parameter&gt;\n</code></pre>"},{"location":"xcheck/#parameters","title":"Parameters","text":"Parameter Effect <code>classpath</code> Checks the classpath and reports errors such as a missing directory or JAR file. <code>dump</code> Checks the operating system for settings that might truncate system dumps. (AIX\u00ae and Linux\u00ae only) <code>gc</code> Runs additional checks on garbage collection. <code>jni</code> Runs additional checks for JNI functions. <code>memory</code> Identifies memory leaks inside the VM using strict checks that cause the VM to exit on failure. <code>vm</code> Performs additional checks on the VM."},{"location":"xcheck/#classpath","title":"<code>classpath</code>","text":"<pre><code>    -Xcheck:classpath\n</code></pre> Checks the classpath and reports errors such as a missing directory or JAR file."},{"location":"xcheck/#dump","title":"<code>dump</code>","text":"<p>AIX and Linux only</p> <pre><code>    -Xcheck:dump\n</code></pre> <p>Checks operating system settings during VM startup. Messages are issued if the operating system has settings that might truncate system dumps.</p> <p>On AIX systems, the following messages are possible:</p> <ul> <li><code>JVMJ9VM133W The system core size hard ulimit is set to &lt;value&gt;, system dumps may be truncated</code></li> </ul> This message indicates that the AIX operating system user limit is set to restrict the size of system dumps to the value indicated. If a system dump is produced by the VM it might be truncated, and therefore of greatly reduced value in investigating the cause of crashes and other issues. For more information about how to set user limits on AIX, see Setting system resource limits on AIX and Linux systems. <ul> <li><code>JVMJ9VM134W The system fullcore option is set to FALSE, system dumps may be truncated</code></li> </ul> This message indicates that the AIX operating system <code>Enable full CORE dump</code>option is set to FALSE. This setting might result in truncated system dumps. For more information about how to set this option correctly on AIX, see Setting system resource limits on AIX and Linux systems. <p>On Linux systems, the following messages are possible:</p> <ul> <li><code>JVMJ9VM133W The system core size hard ulimit is set to &lt;value&gt;, system dumps may be truncated.</code></li> </ul> This message indicates that the Linux operating system user limit is set to restrict the size of system dumps to the value indicated. If a system dump is produced by the VM, it might be truncated and therefore of greatly reduced value in investigating the cause of crashes and other issues. Review the documentation that is provided for your operating system to correctly configure the value for <code>ulimits</code>. For further information, see Setting system resource limits on AIX and Linux systems. <ul> <li><code>JVMJ9VM135W /proc/sys/kernel/core_pattern setting \"|/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t e\" specifies that core dumps are to be piped to an external program. The JVM may be unable to locate core dumps and rename them.</code></li> </ul> This message means that an external program, abrt-hook-ccpp, is configured in the operating system to intercept any system dump files that are generated. This program is part of the Automatic Bug Reporting Tool (ABRT). For more information, see Automatic Bug Reporting Tool. This tool might interfere with the VM's system dump file processing by renaming or truncating system dumps. Review the configuration of the ABRT tool and messages that are written by the tool in<code>/var/log/messages</code>. If problems occur when generating system dumps from the VM, consider disabling ABRT. <ul> <li><code>JVMJ9VM135W /proc/sys/kernel/core_pattern setting \"|/usr/share/apport/apport %p %s %c\" specifies that core dumps are to be piped to an external program. The JVM may be unable to locate core dumps and rename them.</code></li> </ul> This message means that an external program, apport, is configured in the operating system to intercept any system dump files that are generated. For more information about this tool, see: Apport The tool might interfere with the VM's system dump file processing by renaming or truncating system dumps. Review the configuration of the Apport tool and messages that are written by the tool in <code>/var/log/apport.log</code>. If problems occur when generating system dumps from the VM, consider disabling the Apport tool. <ul> <li><code>JVMJ9VM136W \"/proc/sys/kernel/core_pattern setting \"/tmp/cores/core.%e.%p.%h.%t \" specifies a format string for renaming core dumps. The JVM may be unable to locate core dumps and rename them.</code></li> </ul> This message indicates that the Linux <code>/proc/sys/kernel/core_pattern</code> option is set to rename system dumps. The tokens that are used in the operating system dump name might interfere with the VM's system dump file processing, in particular with file names specified in the VM <code>-Xdump</code> options. If problems occur when generating system dumps from the VM, consider changing the <code>/proc/sys/kernel/core_pattern</code> setting to the default value of <code>core</code>."},{"location":"xcheck/#gc","title":"<code>gc</code>","text":"<pre><code>    -Xcheck:gc[:help][:&lt;scan options&gt;][:&lt;verify options&gt;][:&lt;misc options&gt;]\n</code></pre> Runs additional checks on garbage collection. By default, no checks are made. There are many scan, verify, and miscellaneous suboptions available. If you do not specify any, all possible scan and verify suboptions are run, plus the miscellaneous verbose and check suboptions. For more information, see the output of <code>-Xcheck:gc:help</code>."},{"location":"xcheck/#jni","title":"<code>jni</code>","text":"<pre><code>    -Xcheck:jni[:help][:&lt;option&gt;]\n</code></pre> Runs additional checks for JNI functions. By default, no checks are made. For more information, see the output of <code>-Xcheck:jni:help</code>."},{"location":"xcheck/#memory","title":"<code>memory</code>","text":"<pre><code>    -Xcheck:memory[:&lt;option&gt;]\n</code></pre> Identifies memory leaks inside the VM by using strict checks that cause the VM to exit on failure. Restriction: You cannot include <code>-Xcheck:memory</code> in the options file (see <code>-Xoptionsfile</code>). <p>The available parameters are as follows:</p> <code>:all</code> (Default if no options specified) Enables checking of all allocated and freed blocks on every free and allocate call. This check of the heap is the most thorough. It typically causes the VM to exit on nearly all memory-related problems soon after they are caused. This option has the greatest affect on performance. <code>:callsite=&lt;number_of_allocations&gt;</code> <p>Displays callsite information every <code>&lt;number_of_allocations&gt;</code>. De-allocations are not counted. Callsite information is presented in a table with separate information for each callsite. Statistics include:</p> <ul> <li>The number and size of allocation and free requests since the last report.</li> <li>The number of the allocation request responsible for the largest allocation from each site.</li> </ul> <p>Callsites are presented as <code>sourcefile:linenumber</code> for C code and assembly function name for assembler code.</p> <p>Callsites that do not provide callsite information are accumulated into an \"unknown\" entry.</p> <code>:failat=&lt;number_of_allocations&gt;</code> <p>Causes memory allocation to fail (return NULL) after <code>&lt;number_of_allocations&gt;</code>. For example, setting <code>&lt;number_of_allocations&gt;</code> to 13 causes the 14th allocation to return NULL. De-allocations are not counted. Use this option to ensure that VM code reliably handles allocation failures. This option is useful for checking allocation site behavior rather than setting a specific allocation limit.</p> <code>:ignoreUnknownBlocks</code> Ignores attempts to free memory that was not allocated using the <code>-Xcheck:memory</code> tool. Instead, the -Xcheck:memory statistics that are printed out at the end of a run indicates the number of \"unknown\" blocks that were freed. <code>:mprotect=[top|bottom]</code> Locks pages of memory on supported platforms, causing the program to stop if padding before or after the allocated block is accessed for reads or writes. An extra page is locked on each side of the block returned to the user. If you do not request an exact multiple of one page of memory, a region on one side of your memory is not locked. The <code>top</code> and <code>bottom</code> options control which side of the memory area is locked. <code>top</code> aligns your memory blocks to the top of the page (lower address), so buffer underruns result in an application failure. <code>bottom</code> aligns your memory blocks to the bottom of the page (higher address) so buffer overruns result in an application failure. Standard padding scans detect buffer underruns when using <code>top</code> and buffer overruns when using <code>bottom</code>. <code>:nofree</code> Keeps a list of blocks that are already used instead of freeing memory. This list, and the list of currently allocated blocks, is checked for memory corruption on every allocation and deallocation. Use this option to detect a dangling pointer (a pointer that is \"dereferenced\" after its target memory is freed). This option cannot be reliably used with long-running applications (such as WebSphere\u00ae Application Server), because \"freed\" memory is never reused or released by the VM. <code>:noscan</code> Checks for blocks that are not freed. This option has little effect on performance, but memory corruption is not detected. This option is compatible only with <code>subAllocator</code>, <code>callsite</code>, and <code>callsitesmall</code>. <code>:quick</code> Enables block padding only and is used to detect basic heap corruption. Every allocated block is padded with sentinel bytes, which are verified on every allocate and free. Block padding is faster than the default of checking every block, but is not as effective. <code>:skipto=&lt;number_of_allocations&gt;</code> Causes the program to check only on allocations that occur after <code>&lt;number_of_allocations&gt;</code>. De-allocations are not counted. Use this option to speed up VM startup when early allocations are not causing the memory problem. The VM performs approximately 250+ allocations during startup. <code>:subAllocator[=&lt;size_in_MB&gt;]</code> Allocates a dedicated and contiguous region of memory for all VM allocations. This option helps to determine if user JNI code or the VM is responsible for memory corruption. Corruption in the VM <code>subAllocator</code> heap suggests that the VM is causing the problem; corruption in the user-allocated memory suggests that user code is corrupting memory. Typically, user and VM allocated memory are interleaved. <code>:zero</code> Newly allocated blocks are set to 0 instead of being filled with the <code>0xE7E7xxxxxxxxE7E7</code> pattern. Setting these blocks to 0 helps you to determine whether a callsite is expecting zeroed memory, in which case the allocation request is followed by <code>memset(pointer, 0, size)</code>."},{"location":"xcheck/#vm","title":"<code>vm</code>","text":"<pre><code>    -Xcheck:vm[:&lt;option&gt;]\n</code></pre> Performs additional checks on the VM. By default, no checking is performed. For more information, run <code>-Xcheck:vm:help</code>."},{"location":"xclassgc/","title":"-Xnoclassgc","text":""},{"location":"xclassgc/#-xclassgc-xnoclassgc","title":"-Xclassgc / -Xnoclassgc","text":"<p>Enables and disables the garbage collection (GC) of storage that is associated with Java classes that are no longer being used by the Eclipse OpenJ9\u2122 VM.</p> <p>When enabled, GC occurs only on class loader changes. To always enable dynamic class unloading regardless of class loader changes, set <code>-Xalwaysclassgc</code>.</p> <p> Note: Disabling class GC is not recommended because unlimited native memory growth can occur, which can lead to out-of-memory errors.</p>"},{"location":"xclassgc/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xclassgc</code> Enables dynamic class unloading on demand yes <code>-Xnoclassgc</code> Disables dynamic class unloading <p>These options can be used with all OpenJ9 GC policies.</p>"},{"location":"xclassgc/#see-also","title":"See also","text":"<ul> <li><code>-Xalwaysclassgc</code></li> </ul>"},{"location":"xcodecache/","title":"-Xcodecache","text":""},{"location":"xcodecache/#-xcodecache","title":"-Xcodecache","text":"<p>Use this option to tune performance.</p> <p>This option sets the size of each block of memory that is allocated to store the native code of compiled Java\u2122 methods. By default, this size is selected internally according to the processor architecture and the capability of your system. The maximum value you can specify is 32 MB. If you set a value larger than 32 MB, the JIT ignores the input and sets the value to 32 MB.</p> <p> Note: The JIT compiler might allocate more than one code cache for an application. Use the <code>-Xcodecachetotal</code> option to set the maximum amount of memory that is used by all code caches.</p>"},{"location":"xcodecache/#syntax","title":"Syntax","text":"<pre><code>    -Xcodecache&lt;size&gt;\n</code></pre> See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter."},{"location":"xcodecachetotal/","title":"-Xcodecachetotal","text":""},{"location":"xcodecachetotal/#-xcodecachetotal","title":"-Xcodecachetotal","text":"<p>Use this option to set the maximum size limit for the JIT code cache. This option also affects the size of the JIT data cache.</p>"},{"location":"xcodecachetotal/#syntax","title":"Syntax","text":"<pre><code>    -Xcodecachetotal&lt;size&gt;\n</code></pre> <p>The default size is 256 MB for a 64-bit VM and 64 MB for a 31/32-bit VM.</p> <p>See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xcodecachetotal/#explanation","title":"Explanation","text":"<p>By default, the total JIT code cache size is 256 MB for a 64-bit VM and 64 MB for a 31/32-bit VM or 25% of the physical memory available to the VM process, whichever is lesser. Long-running, complex, server-type applications can fill the JIT code cache, which can cause performance problems because not all of the important methods can be JIT-compiled. Use the <code>-Xcodecachetotal</code> option to increase or decrease the maximum code cache size to a setting that suits your application. The minimum size of the code cache is restricted to 2 MB.</p> <p>The value that you specify is rounded up to a multiple of the code cache block size, as specified by the -Xcodecache option. If you specify a value for the <code>-Xcodecachetotal</code> option that is smaller than the default setting, that value is ignored.</p> <p>When you use this option, the maximum size limit for the JIT data cache, which holds metadata about compiled methods, is increased or decreased proportionally to support the JIT compilations.</p> <p>The maximum size limits, for both the JIT code and data caches, that are in use by the VM are shown in Javadump output. Look for lines that begin with <code>1STSEGLIMIT</code>. Use this information together with verbose JIT tracing to determine suitable values for this option on your system. For example Javadump output, see Java dump: Storage Management (MEMINFO).</p>"},{"location":"xcodecachetotal/#see-also","title":"See also","text":"<ul> <li><code>-XX:codecachetotalMaxRAMPercentage</code></li> <li>-Xjit</li> </ul>"},{"location":"xcomp/","title":"-Xcomp","text":""},{"location":"xcomp/#-xcomp","title":"-Xcomp","text":"<p>The use of this option is deprecated; use <code>-Xjit:count=0</code> instead.</p>"},{"location":"xcomp/#syntax","title":"Syntax","text":"<pre><code>    -Xcomp\n</code></pre>"},{"location":"xcompactexplicitgc/","title":"-Xnocompactexplicitgc","text":""},{"location":"xcompactexplicitgc/#xcompactexplicitgc-xnocompactexplicitgc","title":"\u2011Xcompactexplicitgc / \u2011Xnocompactexplicitgc","text":"<p>Enables or disables full compaction each time <code>System.gc()</code> is called. </p> <p>Compaction takes place on global garbage collections if you specify <code>-Xcompactgc</code> or if compaction triggers are met. </p>"},{"location":"xcompactexplicitgc/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xcompactexplicitgc</code> Enable compaction yes <code>-Xnocompactexplicitgc</code> Disable compaction"},{"location":"xcompactexplicitgc/#see-also","title":"See also","text":"<ul> <li>Global garbage collection: Compaction phase</li> </ul>"},{"location":"xcompactgc/","title":"-Xnocompactgc","text":""},{"location":"xcompactgc/#-xcompactgc-xnocompactgc","title":"-Xcompactgc / -Xnocompactgc","text":"<p>Enables or disables full compaction on system and global garbage collection (GC) activities.</p>"},{"location":"xcompactgc/#syntax","title":"Syntax","text":"Setting Action <code>-Xcompactgc</code> Enable full compaction <code>-Xnocompactgc</code> Disable full compaction"},{"location":"xcompactgc/#default-behavior","title":"Default behavior","text":"<p>If a compaction option is not specified, the garbage collector compacts based on a series of triggers. These triggers attempt to compact only when it is beneficial to the future performance of the VM.</p> <p>These options are not applicable to the following GC policies:</p> <ul> <li>balanced GC policy (<code>-Xgcpolicy:balanced</code>): compaction is always enabled.</li> <li>metronome GC policy (<code>-Xgcpolicy:metronome</code>): compaction is not supported.</li> </ul>"},{"location":"xcompactgc/#see-also","title":"See also","text":"<ul> <li>GC compact operation</li> </ul>"},{"location":"xcompilationthreads/","title":"-XcompilationThreads","text":""},{"location":"xcompilationthreads/#-xcompilationthreads","title":"-XcompilationThreads","text":"<p>Use this option to specify the number of compilation threads that are used by the JIT compiler.</p>"},{"location":"xcompilationthreads/#syntax","title":"Syntax","text":"<pre><code>    -XcompilationThreads&lt;n&gt;\n</code></pre> Where &lt;n&gt; is the number of threads. The minimum value is 1. The default and maximum values depend on whether the VM is running with the JITServer feature enabled and if so, whether the VM is running as a JITServer server, as shown in the following table: JIT compiler scenario Default value Maximum value JIT and JITServer client Determined by internal JIT heuristics that consider the number of CPUs that the VM is allowed to use 15 JITServer server 63 999 Any number outside this range is ignored. Setting the compilation threads to zero does not disable the JIT compiler. If you want to disable the JIT, use the <code>-Xint</code> option."},{"location":"xcompilationthreads/#explanation","title":"Explanation","text":"<p>When multiple compilation threads are used, the JIT might generate several diagnostic log files. A log file is generated for each compilation thread. The naming convention for the log file generated by the first compilation thread uses the following pattern:</p> <pre><code>&lt;specified_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;pid&gt;\n</code></pre> <p>The first compilation thread has ID 0. Log files generated by the second and subsequent compilation threads append the ID of the corresponding compilation thread as a suffix to the log file name. The pattern for these log file names is as follows:</p> <pre><code>&lt;specified_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;pid&gt;.&lt;compilation_thread_ID&gt;\n</code></pre> <p>For example, the second compilation thread has ID 1. The result is that the corresponding log file name has the form:</p> <pre><code>&lt;specified_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;pid&gt;.1\n</code></pre>"},{"location":"xcompilationthreads/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xcompressedrefs/","title":"-Xnocompressedrefs","text":""},{"location":"xcompressedrefs/#-xcompressedrefs-xnocompressedrefs","title":"-Xcompressedrefs / -Xnocompressedrefs","text":"<p>(64-bit only)</p> <p>Enables or disables the use of compressed references.</p> <p> Restriction: You cannot include <code>-Xcompressedrefs</code> in the options file (see <code>-Xoptionsfile</code>).</p>"},{"location":"xcompressedrefs/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xcompressedrefs</code> Enable compression yes (see Default behavior) <code>-Xnocompressedrefs</code> Disable compression"},{"location":"xcompressedrefs/#default-behavior","title":"Default behavior","text":"<p>Compressed references are enabled by default when <code>-Xmx</code> \u2264 57 GB.</p> <p>z/OS\u00ae: This threshold value assumes that you have APAR OA49416 installed. If you do not have the APAR installed, the threshold value is 25 GB.</p> <p>AIX\u00ae and Linux\u00ae: For the metronome garbage collection policy, the threshold is 25 GB.</p>"},{"location":"xcompressedrefs/#see-also","title":"See also","text":"<ul> <li>Compressed references</li> </ul>"},{"location":"xconcurrentbackground/","title":"-Xconcurrentbackground","text":""},{"location":"xconcurrentbackground/#-xconcurrentbackground","title":"-Xconcurrentbackground","text":"<p>Specifies the number of low-priority background threads that are attached to assist the mutator threads in concurrent mark operations. This option maps directly to the HotSpot <code>-XX:ParallelCMSThreads=N</code> and <code>-XX:ConcGCThreads=N</code> options.</p>"},{"location":"xconcurrentbackground/#syntax","title":"Syntax","text":"<pre><code>    -Xconcurrentbackground&lt;n&gt;\n</code></pre>"},{"location":"xconcurrentbackground/#default-behavior","title":"Default behavior","text":"<p>The default value is <code>1</code>.</p> <p> Note: This value is reported in the header section of a verbose GC log with the entry <code>&lt;attribute name=\"gcthreads Concurrent Mark\" value=\"1\" /&gt;</code>.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xconcurrentbackground/#see-also","title":"See also","text":"<ul> <li><code>-XX:ParallelCMSThreads</code></li> <li><code>-XX:ConcGCThreads</code></li> </ul>"},{"location":"xconcurrentlevel/","title":"-Xconcurrentlevel","text":""},{"location":"xconcurrentlevel/#-xconcurrentlevel","title":"-Xconcurrentlevel","text":"<p>This option indicates the ratio between the amount of heap allocated and the amount of heap marked, which is known as the allocation tax rate.</p>"},{"location":"xconcurrentlevel/#syntax","title":"Syntax","text":"<pre><code>    -Xconcurrentlevel&lt;number&gt;\n</code></pre>"},{"location":"xconcurrentlevel/#default-behavior","title":"Default behavior","text":"<p>The default is 8.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xconcurrentslack/","title":"-Xconcurrentslack","text":""},{"location":"xconcurrentslack/#-xconcurrentslack","title":"-Xconcurrentslack","text":"<p>Attempts to keep the specified amount of the heap space free in concurrent collectors by starting the concurrent operations earlier.</p> <p>Using this option can sometimes alleviate pause time problems in concurrent collectors at the cost of longer concurrent cycles, affecting total throughput.</p>"},{"location":"xconcurrentslack/#syntax","title":"Syntax","text":"<pre><code>    -Xconcurrentslack&lt;size&gt;\n</code></pre> See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter."},{"location":"xconcurrentslack/#default-behavior","title":"Default behavior","text":"<p>The default value is 0, which is optimal for most applications.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>), the optimize for throughput policy (<code>-Xgcpolicy:optthruput</code>), or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xconmeter/","title":"-Xconmeter","text":""},{"location":"xconmeter/#-xconmeter","title":"-Xconmeter","text":"<p>This option determines the usage of which area, LOA (large object area) or SOA (small object area), is metered and therefore which allocations are taxed during concurrent mark operations.</p>"},{"location":"xconmeter/#syntax","title":"Syntax","text":"<pre><code>    -Xconmeter:&lt;parameter&gt;\n</code></pre>"},{"location":"xconmeter/#parameters","title":"Parameters","text":""},{"location":"xconmeter/#soa","title":"<code>soa</code>","text":"<pre><code>    -Xconmeter:soa\n</code></pre> (Default) Applies the allocation tax to allocations from the small object area (SOA)."},{"location":"xconmeter/#loa","title":"<code>loa</code>","text":"<pre><code>    -Xconmeter:loa\n</code></pre> Applies the allocation tax to allocations from the large object area (LOA)."},{"location":"xconmeter/#dynamic","title":"<code>dynamic</code>","text":"<pre><code>    -Xconmeter:dynamic\n</code></pre> The collector dynamically determines which area to meter based on which area is exhausted first, whether it is the SOA or the LOA."},{"location":"xconmeter/#default-behavior","title":"Default behavior","text":"<p>By default, allocation tax is applied to the SOA.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>).</p>"},{"location":"xdisablejavadump/","title":"-Xdisablejavadump","text":""},{"location":"xdisablejavadump/#-xdisablejavadump","title":"-Xdisablejavadump","text":"<p>Turns off Java dump generation on errors and signals.</p>"},{"location":"xdisablejavadump/#syntax","title":"Syntax","text":"<pre><code>    -Xdisablejavadump\n</code></pre>"},{"location":"xdisablejavadump/#default-behavior","title":"Default behavior","text":"<p>By default, Javadump generation is enabled.</p>"},{"location":"xdisablejavadump/#see-also","title":"See also","text":"<ul> <li><code>-Xdump</code></li> </ul>"},{"location":"xdump/","title":"-Xdump","text":""},{"location":"xdump/#-xdump","title":"-Xdump","text":"<p>OpenJ9 produces various types of diagnostic information for analysis when different events occur, such as a general protection fault. The dumps produced are controlled by dump agents, which are initialized when the OpenJ9 virtual machine (VM) starts. The default settings for the dump agents are sufficient for most cases. However, you can use the <code>-Xdump</code> option on the command line to fine tune the dump agent settings. For example, you can use the <code>-Xdump</code> option to add and remove dump agents for various VM events, update default dump settings, and limit the number of dumps that are produced.</p> <p>A large set of options and suboptions are available for controlling dumps, which provides a lot of flexibility.</p>"},{"location":"xdump/#xdump-option-builder","title":"Xdump Option Builder","text":"<p>Use the Xdump Option Builder tool to help you specify the correct options and avoid incompatibilities.</p>"},{"location":"xdump/#syntax","title":"Syntax","text":"<pre><code>    -Xdump:&lt;parameter&gt;\n</code></pre> <p>The following table lists the help options for <code>-Xdump</code>, which provide usage and configuration information:</p> Command Result <code>-Xdump:help</code> Displays general dump help. <code>-Xdump:events</code> Lists available trigger events. <code>-Xdump:request</code> Lists additional VM requests. <code>-Xdump:tokens</code> Lists recognized label tokens. <code>-Xdump:what</code> Shows registered agents on startup. <code>-Xdump:&lt;agent&gt;:help</code> Displays dump agent usage information. <p>The following options can be used to control the production of diagnostic data:  </p> Parameter Result <code>-Xdump:none</code> Removes all default dump agents and any preceding dump options. <code>-Xdump:dynamic</code> Enable support for pluggable agents <code>-Xdump:nofailover</code> Discards dumps when the default or specified dump location is full. <code>-Xdump:directory=&lt;path&gt;</code> Specifies a directory for all dump types to be written to. This directory path is prefixed to the path of all non-absolute dump file names, including the file names for the default dump agents. <code>-Xdump:suspendwith=&lt;offset&gt;</code> Modifies the signal that is used to suspend VM threads while a dump file is being written. Use <code>&lt;offset&gt;</code> to change the default signal number. (Linux\u00ae only) <code>-Xdump:&lt;agent&gt;:&lt;suboptions&gt;</code> Provides detailed suboptions per dump agent that provide more granular control. <p>Dump agents can be configured at a very granular level by specifying suboptions. The <code>&lt;events&gt;</code> suboption is the prime trigger mechanism. If no events are specified explicitly, then the default settings for the corresponding agent are added. For more information, see Default dump agents. You can update the default dump settings by using the <code>defaults</code> suboption. The full set of suboptions are listed in the following table:</p> Dump agent suboptions Result <code>-Xdump:&lt;agent&gt;:none</code> Removes the dump agent. <code>-Xdump:&lt;agent&gt;:defaults</code> Prints the default options for the dump agent. <code>-Xdump:&lt;agent&gt;:events=&lt;events&gt;</code> Triggers a dump agent when a specific event occurs. <code>-Xdump:&lt;agent&gt;:exec=&lt;command&gt;</code> Starts an external application for the dump agent. <code>-Xdump:&lt;agent&gt;:file=&lt;filename&gt;</code> Specifies where to write the dump for the dump agent. <code>-Xdump:&lt;agent&gt;:filter=&lt;filter&gt;</code> Filters dumps by wildcards or events. <code>-Xdump:&lt;agent&gt;:msg_filter=&lt;filter&gt;</code> Filters on text strings within an exception message. <code>-Xdump:&lt;agent&gt;:opts=&lt;options&gt;</code> Used by specific dump agents to select the type of dump file to produce. <code>-Xdump:&lt;agent&gt;:priority=&lt;0-999&gt;</code> Specifies the priority that the dump agents run in. <code>-Xdump:&lt;agent&gt;:range=&lt;ranges&gt;</code> Starts and stops a dump agent on a particular occurrence of a VM. <code>-Xdump:&lt;agent&gt;:request=&lt;requests&gt;</code> Asks the VM to prepare the state before starting the dump agent. <p>You can have multiple <code>-Xdump</code> options on the command line. You can also have multiple dump types triggered by multiple events. For example, the following command turns off the creation of heap dump files, and creates a dump agent that produces a heap dump file and a Java\u2122 dump file when either a vmstart or vmstop event occurs:</p> <pre><code>java -Xdump:heap:none -Xdump:heap+java:events=vmstart+vmstop -mp . -m &lt;class&gt; [args...]\n</code></pre> <p> Note: Multiple suboptions that follow an <code>Xdump</code> suboption must be split with a comma (,), for example:</p> <pre><code>java -Xdump:java:events=vmstart,file=/STDERR/ -version\n</code></pre> <p>For more detailed information on these parameters and suboptions, including examples, see Parameters.</p>"},{"location":"xdump/#dump-agents","title":"Dump agents","text":"<p>A dump agent performs diagnostic tasks when triggered. Most dump agents save information on the state of the VM in some form of dump or trace file for later analysis. An exception is the \"tool\" agent, which can be used to trigger external processes when specific events occur.</p> Dump agent Description stack Stack dumps are very basic dumps in which the status and Java stack of the thread is written to stderr. console Console dumps are very basic dumps, in which the status of every Java thread is written to stderr. system System dumps capture the raw process image or address space of an application. tool The tool option allows external processes to be started when an event occurs. java Java dumps are an internally generated and formatted analysis of the VM, giving information that includes the Java threads present, the classes loaded, and heap statistics. heap Heap dumps capture all object instances in the heap, including each object address, type or class name, size, and references to other objects. snap Take a snap of the trace buffers, which contain tracepoint data. ceedump LE CEEDUMP dumps are z/OS\u00ae formatted summary system dumps that show stack traces for each thread that is in the VM process, together with register information and a short dump of storage for each register. jit JIT compiler dumps contain diagnostic data in a binary format. exit Shut down the VM."},{"location":"xdump/#default-dump-agents","title":"Default dump agents","text":"<p>During VM initialization a set of dump agents are added by default. You can override this set of dump agents using <code>-Xdump</code> on the command line. To show the registered dump agents, user the <code>Xdump:what</code> option on the command line. The following sample output shows the default dump agents that are in place on a Linux system:</p> <pre><code>java -Xdump:what\n\nRegistered dump agents\n----------------------\n-Xdump:system:\n    events=gpf+abort+traceassert+corruptcache,\n    file=/home/user/core.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..0,\n    priority=999,\n    request=serial\n----------------------\n-Xdump:system:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/core.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..1,\n    priority=999,\n    request=exclusive+compact+prepwalk\n----------------------\n-Xdump:heap:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/heapdump.%Y%m%d.%H%M%S.%pid.%seq.phd,\n    range=1..4,\n    priority=500,\n    request=exclusive+compact+prepwalk,\n    opts=PHD\n----------------------\n-Xdump:java:\n    events=gpf+user+abort+traceassert+corruptcache,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n-Xdump:java:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..4,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n-Xdump:snap:\n    events=gpf+abort+traceassert+corruptcache,\n    file=/home/user/Snap.%Y%m%d.%H%M%S.%pid.%seq.trc,\n    range=1..0,\n    priority=300,\n    request=serial\n----------------------\n-Xdump:snap:\n    events=systhrow,\n    filter=java/lang/OutOfMemoryError,\n    file=/home/user/Snap.%Y%m%d.%H%M%S.%pid.%seq.trc,\n    range=1..4,\n    priority=300,\n    request=serial\n----------------------\n-Xdump:jit:\n    events=gpf+abort,\n    file=/home/user/jitdump.%Y%m%d.%H%M%S.%pid.%seq.dmp,\n    range=1..0,\n    priority=200,\n    request=serial\n----------------------\n</code></pre>"},{"location":"xdump/#dump-agent-tokens","title":"Dump agent tokens","text":"<p>You can use tokens to add context to dump file names and directories, and to pass command-line arguments to the tool agent. The tokens available are listed in the following tables:</p> Token Description %Y Year (4 digits) %y Year (2 digits) %m Month (2 digits) %d Day of the month (2 digits) %H Hour (2 digits) %M Minute (2 digits) %S Second (2 digits) %home Java home directory %last Last dump %pid Process ID %seq Dump counter %tick msec counter %uid User name <p>The following tokens are applicable only to z/OS:</p> Token Description %asid Address space ID %job Job name %jobid Job ID %sysname SYSNAME sysparm &amp;DS Dump Section. An incrementing sequence number used for splitting TDUMP files to be less than 2 GB in size. (64-bit only)"},{"location":"xdump/#merging-dump-agents","title":"Merging dump agents","text":"<p>If you configure more than one dump agent, each responds to events according to its configuration. However, the internal structures representing the dump agent configuration might not match the command line because dump agents are merged for efficiency. Two sets of options can be merged as long as none of the agent settings conflict. This means that the list of installed dump agents and their parameters produced by <code>-Xdump:what</code> might not be grouped in the same way as the original <code>-Xdump</code> options that configured them.</p> <p>For example, you can use the following command to specify that a dump agent creates a Java dump file on class unload:</p> <pre><code>java -Xdump:java:events=unload -Xdump:what\n</code></pre> <p>This command does not create a new agent, as can be seen in the results from the <code>-Xdump:what</code> option.</p> <pre><code>...\n----------------------\n-Xdump:java:\n    events=gpf+user+abort+unload+traceassert+corruptcache,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n</code></pre> <p>The configuration is merged with the existing Java dump agent for events gpf, user, abort, traceassert, and corruptcache, because none of the specified options for the new unload agent conflict with those for the existing agent.</p> <p>In the previous example, if one of the parameters for the unload agent is changed so that it conflicts with the existing agent, then it cannot be merged. For example, the following command specifies a different priority, forcing a separate agent to be created:</p> <pre><code>java -Xdump:java:events=unload,priority=100 -Xdump:what\n</code></pre> <p>The results of the <code>-Xdump:what</code> option in the command are as follows.</p> <pre><code>...\n----------------------\n-Xdump:java:\n    events=unload,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=100,\n    request=exclusive+preempt\n----------------------\n-Xdump:java:\n    events=gpf+user+abort+traceassert+corruptcache,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n</code></pre> <p>To merge dump agents, the request, filter, opts, file, and range parameters must match exactly. If you specify multiple agents that filter on the same string, but keep all other parameters the same, the agents are merged. For example:</p> <pre><code>java -Xdump:none -Xdump:java:events=uncaught,filter=java/lang/NullPointerException -Xdump:java:events=unload,filter=java/lang/NullPointerException -Xdump:what\n</code></pre> <p>The results of this command are as follows:</p> <pre><code>Registered dump agents\n----------------------\n-Xdump:java:\n    events=unload+uncaught,\n    filter=java/lang/NullPointerException,\n    file=/home/user/javacore.%Y%m%d.%H%M%S.%pid.%seq.txt,\n    range=1..0,\n    priority=400,\n    request=exclusive+preempt\n----------------------\n</code></pre>"},{"location":"xdump/#dump-events","title":"Dump events","text":"<p>Dump agents are triggered by events occurring during operation of the OpenJ9 VM. Some events can be filtered to improve the relevance of the output.</p> <p>The following table shows the events that are available as dump agent triggers:</p> Event Triggered when.... Filters on.... gpf A General Protection Fault (GPF) occurs. Not applicable user The VM receives the SIGQUIT (Linux, macOS\u00ae, AIX\u00ae, z/OS) or SIGBREAK (Windows\u2122) signal from the operating system. Not applicable user2 The VM receives the SIGUSR2 (Linux, AIX, z/OS, and macOS) signal from the operating system. Not applicable abort The VM receives the SIGABRT signal from the operating system. Not applicable vmstart The virtual machine is started. Not applicable vmstop The virtual machine stops. Exit code; for example, <code>filter=#129..#192#-42#255</code> load A class is loaded. Class name; for example, <code>filter=java/lang/String</code> unload A class is unloaded. Not applicable throw An exception is thrown explicitly in Java code. Use 'systhrow' for unexpected VM exceptions. Exception class name; for example, <code>filter=java/lang/OutOfMem*</code> catch An exception is caught. Exception class name; for example, <code>filter=*Memory*</code> uncaught A Java exception is not caught by the application. Exception class name; for example, <code>filter=*MemoryError</code> systhrow A Java exception is about to be thrown by the VM. This is different from the 'throw' event because it is only triggered for error conditions detected internally in the VM. Exception class name; for example, <code>filter=java/lang/OutOfMem*</code>. thrstart A new thread is started. Not applicable blocked A thread becomes blocked. Not applicable thrstop A thread stops. Not applicable fullgc A garbage collection cycle is started. Not applicable slow A thread takes longer than 50 ms to respond to an internal VM request. Time taken; for example, filter=#300ms will trigger when a thread takes longer than 300 ms to respond to an internal VM request. allocation A Java object is allocated with a size matching the given filter specification. Object size; a filter must be supplied. For example, filter=#5m will trigger on objects larger than 5 Mb. Ranges are also supported; for example, filter=#256k..512k will trigger on objects 256 - 512 Kb in size. traceassert An internal error occurs in the VM. Not applicable corruptcache The VM finds that the shared classes cache is corrupt. Not applicable excessivegc An excessive amount of time is being spent in the garbage collector. Not applicable <p> Notes:</p> <ul> <li>The gpf, traceassert, and abort events cannot trigger a heap dump, prepare the heap (request=prepwalk), or compact the heap (request=compact).</li> <li>The Java dump agent behaves differently when triggered by the <code>user</code> and <code>user2</code> events. For more information, see <code>request=&lt;requests&gt;</code>.</li> <li>The <code>user2</code> event is commonly used for taking system dump files with exclusive access without overriding the <code>user</code> event, which is generally left for taking Java dump files for performance investigations. For example:</li> </ul> <pre><code>-Xdump:system:events=user2,request=exclusive+prepwalk\n</code></pre>"},{"location":"xdump/#parameters","title":"Parameters","text":"<p><code>-Xdump:&lt;agent&gt;:&lt;suboptions&gt;</code> descriptions and examples.</p>"},{"location":"xdump/#help","title":"<code>help</code>","text":"<p>To print usage information for a specific dump agent, use <code>-Xdump:&lt;agent&gt;:help</code></p>"},{"location":"xdump/#noneoptions","title":"<code>none:&lt;options&gt;</code>","text":"<p>Use the <code>-Xdump:none</code> option to add and remove dump agents for various VM events, update default dump settings (such as the dump name), and limit the number of dumps that are produced.</p> <p>The option can be used to affect all agents by specifying <code>-Xdump:none:&lt;options&gt;</code> or specific agents by specifying <code>-Xdump:&lt;agent&gt;:none:&lt;suboptions&gt;</code></p> <p>where <code>&lt;suboptions&gt;</code> is one of the following control types:</p> <ul> <li><code>events=&lt;event&gt;</code></li> <li><code>exec=&lt;command&gt;</code></li> <li><code>file=&lt;filename&gt;</code></li> <li><code>filter=&lt;filter&gt;</code></li> <li><code>opts=&lt;options&gt;</code></li> <li><code>priority=&lt;0-999&gt;</code></li> <li><code>range=&lt;ranges&gt;</code></li> <li><code>request=&lt;requests&gt;</code></li> </ul> <p>Explanations for these suboptions are provided elsewhere in this topic.</p> <p>To remove all default dump agents and any preceding dump options, use <code>-Xdump:none</code>. Use this option so that you can subsequently specify a completely new dump configuration.</p> <p>You can also remove dump agents of a particular type. Here are some examples:</p> <p>To turn off all heap dumps (including default agents) but leave Java dumps enabled, use the following option:</p> <pre><code>-Xdump:java+heap:events=vmstop -Xdump:heap:none\n</code></pre> <p>To turn off all dump agents for corruptcache events:</p> <pre><code>-Xdump:none:events=corruptcache\n</code></pre> <p>To turn off just system dumps for corruptcache events:</p> <pre><code>-Xdump:system:none:events=corruptcache\n</code></pre> <p>To turn off all dumps when a <code>java/lang/OutOfMemory</code> error is thrown:</p> <pre><code>-Xdump:none:events=systhrow,filter=java/lang/OutOfMemoryError\n</code></pre> <p>To turn off just system dumps when a <code>java/lang/OutOfMemory</code> error is thrown:</p> <pre><code>-Xdump:system:none:events=systhrow,filter=java/lang/OutOfMemoryError\n</code></pre> <p>If you remove all dump agents by using <code>-Xdump:none</code> with no further <code>-Xdump</code> options, the VM still provides these basic diagnostic outputs:</p> <ul> <li>If a user signal (kill -QUIT) is sent to the VM, a brief listing of the Java threads including their stacks, status, and monitor information is written to stderr.</li> <li>If a crash occurs, information about the location of the crash, VM options, and native and Java stack traces are written to stderr. A system dump file is also written to the user's home directory.</li> </ul> <p> Note: Removing dump agents and specifying a new dump configuration can require a long set of command-line options. To reuse command-line options, save the new dump configuration in a file and use the <code>-Xoptionsfile</code> option. For more information, see -Xoptionsfile.</p>"},{"location":"xdump/#defaults","title":"<code>defaults</code>","text":"<p>Each dump type has default options. To view the default options for a particular dump type, use <code>-Xdump:&lt;agent&gt;:defaults</code>.</p> <p>You can change the default options at run time. For example, you can direct Java dump files into a separate directory for each process, and guarantee unique files by adding a sequence number to the file name using:</p> <pre><code>-Xdump:java:defaults:file=dumps/%pid/javacore-%seq.txt\n</code></pre> <p>Or, for example, on z/OS, you can add the jobname to the Java dump file name using:</p> <pre><code>-Xdump:java:defaults:file=javacore.%job.%H%M%S.txt\n</code></pre> <p>This option does not add a Java dump agent; it updates the default settings for Java dump agents. Further Java dump agents will then create dump files using this specification for filenames, unless overridden.</p> <p> Note: Changing the defaults for a dump type will also affect the default agents for that dump type added by the VM during initialization. For example, if you change the default file name for Java dump files, that will change the file name used by the default Java dump agents. However, changing the default range option will not change the range used by the default Java dump agents, because those agents override the range option with specific values.</p>"},{"location":"xdump/#eventsevent","title":"<code>events=&lt;event&gt;</code>","text":"<p>To trigger a dump as a result of an event, use the <code>-Xdump:&lt;agent&gt;:events=&lt;event&gt;</code> suboption. For a list of possible events, see Dump events.</p> <p>For example, the following command instructs the VM to create a dump agent at startup that produces a Heap dump whenever the vmstop event happens:</p> <pre><code>-Xdump:heap:events=vmstop\n</code></pre>"},{"location":"xdump/#execcommand","title":"<code>exec=&lt;command&gt;</code>","text":"<p>The exec suboption is used by the tool dump agent to specify an external application to start. You can set a specific command to run for a particular dump agent with the following command:</p> <pre><code>-Xdump:&lt;agent&gt;:exec=&lt;command&gt;\n</code></pre>"},{"location":"xdump/#filefilename","title":"<code>file=&lt;filename&gt;</code>","text":"<p>The file suboption specifies where the diagnostics information is written for the specified dump type. The syntax is <code>-Xdump:&lt;agent&gt;:file=&lt;filename&gt;</code>.</p> <p>For example, to create a Heap dump called <code>my.dmp</code> when a vmstop event is received, use:</p> <pre><code>java -Xdump:heap:events=vmstop,file=my.dmp\n</code></pre> <p>When producing system dump files on z/OS platforms, use the <code>dsn</code> option instead of the <code>file</code> option. For example:</p> <pre><code>java -Xdump:system:events=vmstop,dsn=%uid.MYDUMP\n</code></pre>"},{"location":"xdump/#writing-to-stdoutstderr","title":"Writing to <code>STDOUT</code>/<code>STDERR</code>","text":"<p>Add one of the following options to write a Java dump file to STDOUT or STDERR respectively:</p> <pre><code>-Xdump:java:file=/STDOUT/\n-Xdump:java:file=/STDERR/\n</code></pre> <ul> <li>The keywords <code>/STDOUT/</code> and <code>/STDERR/</code> are not case sensitive; <code>/stdout/</code> and <code>/stderr/</code> are equivalent.</li> <li>By common convention, you can use a dash (<code>-</code>) to refer to STDOUT:<pre><code>-Xdump:java:file=-\n</code></pre> </li> </ul>"},{"location":"xdump/#tokens","title":"Tokens","text":"<p>You can use tokens to add context to dump file names. For a list of tokens, see Dump agent tokens.</p>"},{"location":"xdump/#file-location","title":"File location","text":"<p>The location for the dump file is selected from the following options, in this order:</p> <ol> <li>The location specified by the <code>-Xdump:&lt;agent&gt;:file</code> suboption on the command line (if that location includes a path). This location applies to the specified dump agent type only.</li> <li>The location specified by the <code>-Xdump:directory</code> option on the command line. This location applies to all dump agent types.</li> <li> <p>The location specified by the relevant environment variable:</p> Dump agent type z/OS operating systems Other operating systems Java dumps <code>_CEE_DMPTARG</code> <code>IBM_JAVACOREDIR</code> Heap dumps <code>_CEE_DMPTARG</code> <code>IBM_HEAPDUMPDIR</code> System dumps <code>JAVA_DUMP_TDUMP_PATTERN</code> <code>IBM_COREDIR</code> JIT dumps <code>_CEE_DMPTARG</code> <code>IBM_COREDIR</code> Snap traces <code>_CEE_DMPTARG</code> <code>IBM_COREDIR</code> </li> <li> <p>The current working directory of the OpenJ9 VM process.</p> </li> </ol> <p>If the directory does not exist, it is created.</p> <p>If the dump file cannot be written to the selected location, the VM reverts to using the following locations, in this order:</p> <ol> <li>On Windows platforms only, the system default location is <code>C:\\WINDOWS</code>.</li> <li>The location specified by the <code>TMPDIR</code> environment variable.</li> <li>The <code>C:\\Temp</code> on Windows operating systems, or the <code>/tmp</code> directory on other operating systems.</li> </ol> <p>This VM action does not apply to system dumps on z/OS operating systems that use the <code>dsn</code> option. You can prevent the VM reverting to different dump locations by using the <code>-Xdump:nofailover</code> option.</p>"},{"location":"xdump/#filterfilter","title":"<code>filter=&lt;filter&gt;</code>","text":"<p>Some VM events occur thousands of times during the lifetime of an application. Dump agents can use filters and ranges to avoid producing an excessive number of dump files. The following syntax must be used:</p> <pre><code>-Xdump:&lt;agent&gt;:filter=&lt;filter&gt;\n</code></pre>"},{"location":"xdump/#wildcards","title":"Wildcards","text":"<p>You can use a wildcard in your exception event filter by placing an asterisk only at the beginning or end of the filter. The following command does not work because the second asterisk is not at the end:</p> <pre><code>-Xdump:java:events=throw,filter=*InvalidArgumentException#*.myVirtualMethod\n</code></pre> <p>To fix the problem, change this filter to the following string:</p> <pre><code>-Xdump:java:events=throw,filter=*InvalidArgumentException#MyApplication.*\n</code></pre>"},{"location":"xdump/#class-loading-and-exception-events","title":"Class loading and exception events","text":"<p>You can filter class loading (load) and exception (throw, catch, uncaught, systhrow) events by the name of the class that is being loaded, thrown or caught. For example:</p> <pre><code>-Xdump:java:events=load,filter=java/lang/String\n-Xdump:java:events=throw,filter=java/lang/ArrayStoreException\n-Xdump:java:events=catch,filter=java/lang/NullPointerException\n</code></pre> <p>In addition, you can filter throw, uncaught, and systhrow exception events by the name of the method that throws the exception. The name of the parent class must include the full package name, using the forward slash (/) as a separator. Use a dot (.) to separate the method name from the class name. You can use an asterisk (*) as a wildcard character, to include all methods (optional portions are shown in brackets). For example:</p> <pre><code>-Xdump:java:events=throw,filter=ExceptionClassName[#com/ibm/ThrowingClassName.throwingMethodName[#stackFrameOffset]]\n</code></pre> <p>For example, to trigger a Java dump when method <code>MyApplication.myMethod()</code> throws a <code>NullPointerException</code> exception, use the following syntax:</p> <pre><code>-Xdump:java:events=throw,filter=java/lang/NullPointerException#com/ibm/MyApplication.myMethod\n</code></pre> <p>The stack frame offset allows you to filter on the name of a method that calls the throwing method. This option is useful if the exception is being thrown from a general purpose or utility class. For example, to trigger a Java dump when a method called by <code>MyApplication.main()</code> throws a <code>NullPointerException</code>, use the following syntax:</p> <pre><code>-Xdump:java:events=throw,filter=java/lang/NullPointerException#com/ibm/MyApplication.main#1\n</code></pre> <p>The default value of the stack frame offset is zero.</p> <p>You can filter the catch exception events by Java method name (optional portions are shown in brackets). For example:</p> <pre><code>-Xdump:java:events=catch,filter=ExceptionClassName[#com/ibm/CatchingClassName.catchingMethodName]\n</code></pre> <p>You can filter throw, uncaught, and systhrowexception events by Java method name (optional portions are shown in brackets):</p> <pre><code>-Xdump:java:events=throw,filter=ExceptionClassName[#com/ibm/ThrowingClassName.throwingMethodName[#stackFrameOffset]]\n</code></pre> <p>You can filter the catch exception events by Java method name (optional portions are shown in brackets):</p> <pre><code>-Xdump:java:events=catch,filter=ExceptionClassName[#com/ibm/CatchingClassName.catchingMethodName]\n</code></pre> <p> Note: The filters apply to the stacktrace and fire every time the same exception is rethrown, which might result in multiple Java core files.</p>"},{"location":"xdump/#vmstop-event","title":"vmstop event","text":"<p>You can filter the VM shut down event (vmstop) by using one or more exit codes:</p> <pre><code>-Xdump:java:events=vmstop,filter=#129..192#-42#255\n</code></pre>"},{"location":"xdump/#slow-event","title":"slow event","text":"<p>You can filter the slow event to change the time threshold from the default of 50 ms:</p> <pre><code>-Xdump:java:events=slow,filter=#300ms\n</code></pre>"},{"location":"xdump/#allocation-event","title":"allocation event","text":"<p>You must filter the allocation event to specify the size of objects that cause a trigger. You can set the filter size from zero up to the maximum value of a 32-bit pointer on 32-bit platforms, or the maximum value of a 64-bit pointer on 64-bit platforms. Setting the lower filter value to zero triggers a dump on all allocations.</p> <p>For example, to trigger dumps on allocations greater than 5 Mb in size, use:</p> <pre><code>-Xdump:stack:events=allocation,filter=#5m\n</code></pre> <p>To trigger dumps on allocations between 256 Kb and 512 Kb in size, use:</p> <pre><code>-Xdump:stack:events=allocation,filter=#256k..512k\n</code></pre>"},{"location":"xdump/#other-events","title":"Other events","text":"<p>If you apply a filter to an event that does not support filtering, the filter is ignored.</p>"},{"location":"xdump/#msg_filterfilter","title":"<code>msg_filter=&lt;filter&gt;</code>","text":"<p>You can use the msg_filter suboption to filter on text strings within an exception message, allowing you to reduce the number of dump files produced. This option is supported only for the following events: throw, catch, systhrow, and uncaught.</p> <p>Use the following syntax to include message filtering in your dump output:</p> <pre><code>-Xdump:&lt;agent&gt;:events=&lt;event&gt;,msg_filter=&lt;filter&gt;`\n</code></pre> <p>where <code>&lt;filter&gt;</code> is a text string from the exceptions that you want to include in the dump file. This suboption supports asterisks as wild cards.</p> <p>The following example filters <code>java/lang/VerifyError</code> exceptions that contain the text string class format:</p> <pre><code>-Xdump:java:events=throw,filter=java/lang/VerifyError,msg_filter=*class format*\n</code></pre>"},{"location":"xdump/#optsoptions","title":"<code>opts=&lt;options&gt;</code>","text":"<p>The full syntax is <code>-Xdump:&lt;agent&gt;:opts=&lt;options&gt;</code>.</p> <p>The heap dump agent uses this suboption to specify the type of file to produce. On z/OS, the system dump agent uses this suboption to specify the type of dump to produce.</p>"},{"location":"xdump/#heap-dumps","title":"Heap dumps","text":"<p>You can specify a PHD heap dump file (PHD), a classic text heap dump file (CLASSIC), or both. The default is a PHD file. For example:</p> <pre><code>-Xdump:heap:opts=PHD  \n-Xdump:heap:opts=CLASSIC\n-Xdump:heap:opts=PHD+CLASSIC\n</code></pre>"},{"location":"xdump/#zos-system-dumps","title":"z/OS system dumps","text":"<p>You can specify a system transaction dump (IEATDUMP), an LE dump (CEEDUMP), or both. The default is an IEADUMP file. For example:</p> <pre><code>-Xdump:system:opts=IEATDUMP\n-Xdump:system:opts=CEEDUMP\n-Xdump:system:opts=IEATDUMP+CEEDUMP\n</code></pre> <p>The ceedump agent is the preferred way to specify LE dumps, for example:</p> <pre><code>-Xdump:ceedump:events=gpf\n</code></pre>"},{"location":"xdump/#tool-dumps","title":"Tool dumps","text":"<p>The tool dump agent supports two suboptions that can be specified using the <code>opts</code> subption. You can run the external process asynchronously with opts=ASYNC. You can also specify a delay in milliseconds that produces a pause after starting the command. These two options can be used independently or together. The following examples show different options for starting a new process that runs <code>myProgram</code>:</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram\n</code></pre> <p>Without the <code>opts</code> suboption, the tool dump agent starts the process, and waits for the process to end before continuing.</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram,opts=ASYNC\n</code></pre> <p>When <code>opts=ASYNC</code> is specified, the tool dump agent starts the process, and continues without waiting for the new process to end.</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram,opts=WAIT1000\n</code></pre> <p>This option starts the process, waits for the process to end, and then waits a further 1 second (1000 milliseconds) before continuing.</p> <pre><code>-Xdump:tool:events=vmstop,exec=myProgram,opts=ASYNC+WAIT10000\n</code></pre> <p>Finally, the last example starts the process and waits for 10 seconds before continuing, whether the process is still running or not. This last form is useful if you are starting a process that does not end, but requires time to initialize properly.</p>"},{"location":"xdump/#priority0-999","title":"<code>priority=&lt;0-999&gt;</code>","text":"<p>One event can generate multiple dump files. The agents that produce each dump file run sequentially and their order is determined by the priority keyword set for each agent. The full syntax for this command is <code>-Xdump:&lt;agent&gt;:priority=&lt;0-999&gt;</code>.</p> <p>Examination of the output from <code>-Xdump:what</code> shows that a gpf event produces a snap trace, a Java dump file, and a system dump file. In this example, the system dump runs first, with priority 999. The snap dump runs second, with priority 500. The Java dump runs last, with priority 10:</p> <pre><code>-Xdump:heap:events=vmstop,priority=123\n</code></pre> <p>The maximum value allowed for priority is 999. Higher priority dump agents are started first.</p> <p>If you do not specifically set a priority, default values are taken based on the dump type. The default priority and the other default values for a particular type of dump, can be displayed by using <code>-Xdump:&lt;type&gt;:defaults</code>. For example:</p> <pre><code>java -Xdump:heap:defaults -version\n</code></pre> <p>Default <code>-Xdump:heap</code> settings:</p> <pre><code>  events=gpf+user\n  filter=\n  file=/home/user/heapdump.%Y%m%d.%H%M%S.%pid.phd\n  range=1..0\n  priority=500\n  request=exclusive+compact+prepwalk\n  opts=PHD\n</code></pre>"},{"location":"xdump/#rangeranges","title":"<code>range=&lt;ranges&gt;</code>","text":"<p>You can start and stop dump agents on a particular occurrence of a VM event by using the <code>range</code> suboption: <code>-Xdump:&lt;agent&gt;:range=&lt;ranges&gt;</code></p> <p>For example:</p> <pre><code>-Xdump:java:events=fullgc,range=100..200\n</code></pre> <p> Note: range=1..0 against an event means \"on every occurrence\".</p> <p>The VM default dump agents have the range suboption set to 1..0 for all events except systhrow. Most systhrow events with <code>filter=java/lang/OutOfMemoryError</code> have the range suboption set to 1..4, which limits the number of dump files produced on <code>OutOfMemory</code> conditions to a maximum of 4. For more information, see Default dump agents.</p> <p>If you add a new dump agent and do not specify the range, a default of 1..0 is used.</p>"},{"location":"xdump/#requestrequests","title":"<code>request=&lt;requests&gt;</code>","text":"<p>Use the request suboption to ask the VM to prepare the state before starting the dump agent: <code>-Xdump:&lt;agent&gt;:request=&lt;requests&gt;</code></p> <p>The available suboptions are listed in the following table:</p> suboption value Description exclusive Request exclusive access to the VM. compact Run garbage collection. This option removes all unreachable objects from the heap before the dump file is generated. prepwalk Prepare the heap for walking. You must also specify exclusive when you use this option. serial Suspend other dumps until this dump is finished. preempt Applies to the Java dump agent and controls whether native threads in the process are forcibly pre-empted in order to collect stack traces. If this option is not specified, only Java stack traces are collected in the Java dump. <p>You can specify more than one request option by using +. For example:</p> <pre><code>-Xdump:heap:request=exclusive+compact+prepwalk\n</code></pre> <p>The VM exclusive access mechanism allows a VM thread to halt the activity of other VM threads in a controlled way by using internal VM locks. When the <code>request=exclusive</code> option is specified for a dump agent, the VM thread that is producing the dump waits for threads that are running Java code to halt, and for garbage collection operations to complete, before the dump file is written. This process helps ensure that the dump has consistent data. When the dump is complete, the mechanism allows the other threads to resume.</p> <p>By default, only system dumps for <code>OutOfMemoryError</code> exceptions request exclusive access. Other system dump events typically result from a crash. In these cases, exclusive access is not requested because acquiring locks during a crash can be problematic.</p> <p>If system dumps are requested by using the <code>com.ibm.jvm.Dump.SystemDump()</code> API, the default system dump agent settings are used, and exclusive access is not requested. However, if you intend to use the system dump file for Java heap memory analysis, use the following option to request exclusive access when the dump is taken:</p> <pre><code>-Xdump:system:defaults:request=exclusive+compact+prepwalk\n</code></pre> <p>These settings avoid capturing a dump file with in-flight data during garbage collection. As an alternative, you can use the <code>com.ibm.jvm.Dump.triggerDump()</code> API and specify <code>request=exclusive+compact+prepwalk</code> on the API call.</p> <p>For more information about the <code>com.ibm.jvm.Dump API</code>, see the API reference information.</p> <p>The default setting of the <code>request</code> suboption for Java dump files is <code>request=exclusive+preempt</code>. To change the settings so that Java dump files are produced without pre-empting threads to collect native stack traces, use the following option:</p> <pre><code>-Xdump:java:request=exclusive\n</code></pre> <p>The Java dump agent ignores the <code>request=exclusive</code> setting if a <code>user</code> event occurs and another event already has exclusive access. In this scenario, the Java dump agent shares the access instead. This behavior is useful because it allows you to obtain a Java dump file during a deadlock situation, when exclusive access is not released. However, the resulting Java dump file, even in other situations, might omit thread stacks and contain inconsistent thread information, as indicated by the following line in the file:</p> <pre><code>1TIPREPINFO    Exclusive VM access not taken: data may not be consistent across javacore sections\n</code></pre> <p>On operating systems other than Windows, you can enforce exclusive access and obtain a complete dump file by specifying that the <code>user2</code> event triggers the Java dump agent instead of the <code>user</code> event. For example:</p> <pre><code>-Xdump:java:events=user2,request=exclusive+preempt\n</code></pre> <p>When a <code>user2</code> event occurs, for example, when you enter <code>kill -USR2 &lt;pid&gt;</code> on the command line, the Java dump agent accepts the <code>request=exclusive</code> setting and waits for exclusive access before creating the Java dump file.</p> <p>For more information about events, see Dump events.</p> <p>In general, the default request options are sufficient.</p>"},{"location":"xdump/#dump-output","title":"Dump output","text":"<p>Dump output is written to different files, depending on the type of dump and the platform. File names include a time stamp.</p> Dump type File name  (AIX, Linux, macOS, Windows) File name (z/OS) System dump core.%Y%m%d.%H%M%S.%pid.dmp %uid.JVM.TDUMP.%job.D%Y%m%d.T%H%M%S (31-bit),  %uid.JVM.%job.D%y%m%d.T%H%M%S.X&amp;DS (64-bit) See Note Java dump javacore.%Y%m%d.%H%M%S.%pid.%seq.txt javacore.%Y%m%d.%H%M%S.%pid.%seq.txt Heap dump heapdump.%Y%m%d.%H%M%S.%pid.phd heapdump.%Y%m%d.T%H%M%S.phd JIT dump jitdump%Y%m%d.%H%M%S.%pid.%seq.dmp jitdump%Y%m%d.%H%M%S.%pid.%seq.dmp LE CEEDUMP - CEEDUMP.%Y%m%d.%H%M%S.%pid See Note <p>The tokens used in this table, for example <code>%Y</code>, are described in Dump agent tokens.</p> <p> Note: On z/OS, the system dump file name can be set with the <code>JAVA_DUMP_TDUMP_PATTERN</code> environment variable. The CEEDUMP, which is not produced by default, is stored in the directory specified by <code>_CEE_DMPTARG</code> or the current directory if <code>_CEE_DMPTARG</code> is not specified.</p>"},{"location":"xdump/#system-dumps-on-linux","title":"System dumps on Linux","text":"<p>Linux does not provide an operating system API for generating a system dump from a running process. The VM produces system dumps on Linux by using the fork() API to start an identical process to the parent VM process. The VM then generates a SIGSEGV signal in the child process. The SIGSEGV signal causes Linux to create a system dump for the child process. The parent VM processes and renames the system dump, as required, by the <code>-Xdump</code> options, and might add additional data into the dump file.</p> <p>The system dump file for the child process contains an exact copy of the memory areas used in the parent. The dump viewer can obtain information about the Java threads, classes, and heap from the system dump. However, the dump viewer, and other system dump debuggers show only the single native thread that was running in the child process.</p> <p>You can use the Linux <code>kernel.core_pattern</code> setting to specify the name and path for system dumps. The VM dump agents override the Linux system dump name and path by renaming the dump as specified in the <code>-Xdump</code> options. If the <code>kernel.core_pattern</code> setting specifies a different file system to the <code>-Xdump</code> options, the VM dump agents might be unable to change the file path. In this case the VM renames the dump file, but leaves the file path unchanged. You can find the dump file name and location in the <code>JVMDUMP010I</code> message.</p> <p> Note: If you use the <code>%t</code> specifier in the <code>kernel.core_pattern</code> setting, the VM does not rename the dump. The VM cannot determine the exact time that Linux generated the core file, and therefore cannot be certain which Linux dump file is the correct one to rename.</p>"},{"location":"xdump/#piped-system-dumps","title":"Piped system dumps","text":"<p>The Linux option, <code>kernel.core_pattern=|&lt;program&gt;</code>, might be set to pipe system dumps to a system dump processing program (specified by <code>&lt;program&gt;</code>). If such a program is specified and the VM cannot find the system dump, you will see the following messages:</p> <ul> <li><code>JVMPORT030W</code></li> <li><code>JVMDUMP012E</code></li> <li><code>JVMPORT049I</code></li> </ul> <p>These messages do not necessarily indicate a problem with the system dump. Review the documentation for the program listed in the <code>kernel.core_pattern</code> property to find the location of the system dump and how to configure the program to ensure that the dump file is not truncated.</p> <p>You can find the current setting of <code>kernel.core_pattern</code> by running one of the following commands. For example,</p> <pre><code>$ cat /proc/sys/kernel/core_pattern\n|/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %h\n</code></pre> <pre><code>$ sysctl kernel.core_pattern\nkernel.core_pattern = |/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %h\n</code></pre> <p>The <code>kernel.core_pattern</code> setting is also available in a Java dump. For example:</p> <pre><code>2CISYSINFO     /proc/sys/kernel/core_pattern = |/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %h\n</code></pre> <p>Here are some of the most common system dump processing programs and their default system dump locations:</p> <ul> <li> <p>systemd-coredump:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/usr/lib/systemd/systemd-coredump</code></li> <li>By default, dump files go to <code>/var/lib/systemd/coredump/</code>.</li> <li>Versions before v251 truncate 64-bit Java dumps at 2 GB. To avoid this, consider updating the configuration file, <code>/etc/systemd/coredump.conf</code> to increase the values of the <code>ProcessSizeMax</code> and <code>ExternalSizeMax</code> properties and load the updated configuration by running the <code>systemctl daemon-reload</code> command. For v251 and later versions, similar changes are needed if the dump files are greater than 32 GB.</li> </ul> </li> <li> <p>apport:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/usr/share/apport/apport</code></li> <li>By default, dump files go to <code>/var/crash/</code> or <code>/var/lib/apport/coredump/</code>.</li> <li>Default settings do not truncate the dump files.</li> </ul> </li> <li> <p>abrt-hook-ccpp:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/usr/libexec/abrt-hook-ccpp</code></li> <li>By default, dump files go to <code>/var/spool/abrt</code>.</li> <li>Default settings might truncate the dump files. Consider updating <code>/etc/abrt/abrt.conf</code> to set <code>MaxCrashReportsSize=0</code> and restart <code>abrtd</code>.</li> </ul> </li> <li> <p>Dynatrace rdp:</p> <ul> <li>Sample setting - <code>kernel.core_pattern=|/opt/dynatrace/oneagent/agent/rdp</code></li> <li>The program passes the dump files to the underlying system dump processing program specified in <code>/opt/dynatrace/oneagent/agent/conf/original_core_pattern</code>.</li> </ul> </li> </ul> <p>In container environments, such as OpenShift, piped system dump files are stored in the worker node rather than in the container. Here is one example method for retrieving a dump file that was piped to the <code>systemd-coredump</code> program:</p> <ol> <li>To access the system dump files, you must have access to the cluster as a user that has the <code>cluster-admin</code> role.</li> <li> <p>Find the worker node of the pod. For example:</p> <p><code>oc get pod --namespace MyNamespace --output \"jsonpath={.spec.nodeName}{'\\n'}\" MyPodname</code></p> <p>Where, MyNamespace and MyPodname are names of your namespace and pod.</p> </li> <li> <p>Start a debug pod on the worker node. For example:</p> <p><code>oc debug node/MyNode -t</code></p> <p>Where, MyNode is the worker node retrieved in step 2.</p> </li> <li> <p>List the available system dump files. For example:</p> </li> </ol> <pre><code>#chroot /host coredumpctl\n\nTIME                             PID        UID   GID SIG COREFILE  EXE\n\nWed 2022-08-03 18:52:29 UTC  2923161 1000650000     0  11 present   /opt/java/semeru/jre/bin/java\n</code></pre> <ol> <li>Find the line for the system dump that you want to download, copy the PID number from that row, and then pass it to the <code>info</code> sub-command to search for the dump location. For example:</li> </ol> <pre><code># chroot /host coredumpctl info 2923161 | grep Storage:\nStorage: /var/lib/systemd/coredump/core.kernel-command-.1000650000.08b9e28f46b348f3aabdffc6896838e0.2923161.1659552745000000.lz4\n</code></pre> <ol> <li> <p>Run a command to print output on a loop so that the debug pod doesn't timeout:</p> <p><code>while true; do echo 'Sleeping'; sleep 8; done</code></p> </li> <li> <p>Open a new terminal and then find the debug pod and namespace. For example:</p> </li> </ol> <pre><code>$ oc get pods --field-selector=status.phase==Running --all-namespaces | grep debug\nopenshift-debug-node-pwcn42r47f       worker3-debug       1/1     Running            0                  3m38s\n</code></pre> <ol> <li>Use the namespace (first column) and pod name (second column) that you retrieved in step 7 to download the system dump file from the <code>Storage</code> location that was listed in the output of step 5 on the worker node. Ensure that you prefix the <code>Storage</code> location with <code>/host/</code>. For example:</li> </ol> <pre><code>oc cp --namespace openshift-debug-node-pwcn42r47f worker3-debug:/host/var/lib/systemd/coredump/core.kernel-command-.1000650000.08b9e28f46b348f3aabdffc6896838e0.2923161.1659552745000000.lz4 core.dmp.lz4\n</code></pre> <p>This example stores the system dump locally in a compressed file, <code>core.dmp.lz4</code>.</p> <ol> <li>After the download completes, in the first terminal window, exit the loop by pressing <code>Ctrl+C</code> and end the debug pod by typing <code>exit</code>.</li> </ol>"},{"location":"xdump/#see-also","title":"See also","text":"<ul> <li><code>-Xtrace</code></li> <li><code>-Xdisablejavadump</code></li> <li><code>-XX[+|-]HandleSIGUSR2</code></li> </ul>"},{"location":"xenableexcessivegc/","title":"-Xenableexcessivegc","text":""},{"location":"xenableexcessivegc/#xenableexcessivegc-xdisableexcessivegc","title":"\u2011Xenableexcessivegc / \u2011Xdisableexcessivegc","text":"<p>Enables or disables the throwing of an <code>OutOfMemory</code> exception if excessive time is spent in the GC.</p> <p>If excessive time is spent in the GC, the option returns <code>null</code> for an allocate request and thus causes an <code>OutOfMemory</code> exception to be thrown.</p> <p> Note: The <code>OutOfMemory</code> exception is thrown only when the heap has been fully expanded and the percentage of application run time that is spent in garbage collection is at least 95%. This percentage is the default value that triggers an excessive GC event. You can control this value with the <code>-Xgc:excessiveGCratio</code> option.</p>"},{"location":"xenableexcessivegc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xenableexcessivegc</code> Enable exception yes <code>-Xdisableexcessivegc</code> Disable exception <p>These options can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xenableexplicitgc/","title":"-Xenableexplicitgc","text":""},{"location":"xenableexplicitgc/#xenableexplicitgc-xdisableexplicitgc","title":"\u2011Xenableexplicitgc / \u2011Xdisableexplicitgc","text":"<p>Enables and disables garbage collection (GC) when calls are made to <code>System.gc()</code>.</p>"},{"location":"xenableexplicitgc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xenableexplicitgc</code> Enable explicit GC calls yes <code>-Xdisableexplicitgc</code> Disable explicit GC calls"},{"location":"xenableexplicitgc/#explanation","title":"Explanation","text":"<p>Although it is possible to programmatically trigger a global GC by calling <code>System.gc()</code>, performance can be adversely affected by halting the application before it is really necessary. Use this option to prevent the VM responding to application requests for a GC cycle.</p> <p>The default for all Eclipse OpenJ9\u2122 GC policies is <code>-Xenableexplicitgc</code> except for <code>-Xgcpolicy:nogc</code>, where the default is <code>-Xdisableexplicitgc</code>.</p> <p>These options can be used with all OpenJ9 GC policies.</p>"},{"location":"xenablestringconstantgc/","title":"-Xenablestringconstantgc","text":""},{"location":"xenablestringconstantgc/#xenablestringconstantgc-xdisablestringconstantgc","title":"\u2011Xenablestringconstantgc / \u2011Xdisablestringconstantgc","text":"<p>Enables or disables the collection of strings from the string intern table.</p>"},{"location":"xenablestringconstantgc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xenablestringconstantgc</code> Enable collection yes <code>-Xdisablestringconstantgc</code> Disable collection <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>).</p>"},{"location":"xfastresolve/","title":"-Xfastresolve","text":""},{"location":"xfastresolve/#-xfastresolve","title":"-Xfastresolve","text":"<p>Tune performance by improving the resolution time for classes when the field count exceeds the specified threshold.</p> <p>If profiling tools show significant costs in field resolution, change the threshold until the costs are reduced. If you enable this option, additional memory is used when the threshold is exceeded.</p> <p> Note: The use of this option is deprecated.</p>"},{"location":"xfastresolve/#syntax","title":"Syntax","text":"<pre><code>    -Xfastresolve&lt;n&gt;\n</code></pre> where <code>&lt;n&gt;</code> is the required threshold."},{"location":"xfuture/","title":"-Xfuture","text":""},{"location":"xfuture/#-xfuture","title":"-Xfuture","text":"<p>As described in the Oracle \"Non-Standard Options\" documentation, this HotSpot option turns on strict class-file format checks. For compatibility, this option is also supported by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xfuture/#syntax","title":"Syntax","text":"<pre><code>    -Xfuture\n</code></pre>"},{"location":"xfuture/#explanation","title":"Explanation","text":"<p>Oracle recommend that you use this flag when you are developing new code because stricter checks will become the default in future releases.</p> <p> Note: You cannot use this setting in conjunction with -XX:+ClassRelationshipVerifier.</p>"},{"location":"xfuture/#default-behavior","title":"Default behavior","text":"<p>By default, strict format checks are disabled.</p>"},{"location":"xgc/","title":"-Xgc","text":""},{"location":"xgc/#-xgc","title":"-Xgc","text":"<p>Options that change the behavior of the garbage collector.</p>"},{"location":"xgc/#syntax","title":"Syntax","text":"<pre><code>    -Xgc:&lt;parameter&gt;\n</code></pre>"},{"location":"xgc/#parameters","title":"Parameters","text":"Parameter Effect <code>breadthFirstScanOrdering</code> Sets the scan mode to breadth first. <code>classUnloadingKickoffThreshold</code> Sets a threshold to start an early concurrent global garbage collection (GC) cycle due to recent, heavy class loading activity <code>classUnloadingThreshold</code> Sets a threshold to trigger a class unloading operation in a global GC cycle <code>concurrentScavenge</code> Enables a GC mode with less pause times. <code>dnssExpectedTimeRatioMaximum</code> Sets the maximum percentage of time to spend on local GC pauses <code>dnssExpectedTimeRatioMinimum</code> Sets the minimum percentage of time to spend on local GC pauses <code>dynamicBreadthFirstScanOrdering</code> Sets scan mode to dynamic breadth first. <code>excessiveGCratio</code> Sets a boundary value beyond which GC is deemed to be excessive. <code>hierarchicalScanOrdering</code> Sets scan mode to hierarchical. <code>minContractPercent</code> Sets the minimum percentage of the heap that can be contracted at any given time. <code>maxContractPercent</code> Sets the maximum percentage of the heap that can be contracted at any given time. <code>noConcurrentScavenge</code> Disables concurrent scavenge. <code>noSynchronousGCOnOOM</code> Prevents an application stopping to allow GC activity. <code>overrideHiresTimerCheck</code> Overrides GC operating system checks for timer resolution. <code>preferredHeapBase</code> Sets a memory range for the Java\u2122 heap. (AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122 only) <code>scvNoAdaptiveTenure</code> Turns off the adaptive tenure age in the generational concurrent GC policy. <code>scvTenureAge</code> Sets the initial scavenger tenure age in the generational concurrent GC policy. <code>stdGlobalCompactToSatisfyAllocate</code> Prevents the GC from performing a compaction unless absolutely required. <code>synchronousGCOnOOM</code> Stops an application to allow GC activity. <code>targetPausetime</code> Sets the target GC pause time for the <code>metronome</code> and <code>balanced</code> GC policies. <code>targetUtilization</code> Sets application utilization for the <code>metronome</code> GC policy. <code>tlhIncrementSize</code> Sets the size of the thread local heap (TLH) increment. <code>tlhInitialSize</code> Sets the initial size of the thread local heap. <code>tlhMaximumSize</code> Sets the maximum size of the thread local heap. <code>verboseFormat</code> Sets the verbose GC format. <code>verbosegcCycleTime</code> Sets the criteria for verbose GC logging."},{"location":"xgc/#breadthfirstscanordering","title":"<code>breadthFirstScanOrdering</code>","text":"<pre><code>     -Xgc:breadthFirstScanOrdering\n</code></pre> This option sets the scan mode for GC operations that evacuate objects in the heap (scavenge operations (<code>gencon</code>) and copy forward operations (<code>balanced</code>)) to breadth first mode. The scan mode reflects the method for traversing the object graph and is also known as Cheney's algorithm."},{"location":"xgc/#classunloadingkickoffthreshold","title":"<code>classUnloadingKickoffThreshold</code>","text":"<pre><code>     -Xgc:classUnloadingKickoffThreshold=&lt;value&gt;\n</code></pre> Where <code>&lt;value&gt;</code> is equal to the number of class loaders plus the number of anonymous classes that are loaded since the previous class unloading operation. This option sets a threshold that is used to start an early concurrent global GC cycle due to recent class loading activity. The default value is 80000. This option is applicable to the following GC policies: <code>gencon</code> and <code>optavgpause</code>."},{"location":"xgc/#classunloadingthreshold","title":"<code>classUnloadingThreshold</code>","text":"<pre><code>     -Xgc:classUnloadingThreshold=&lt;value&gt;\n</code></pre> Where <code>&lt;value&gt;</code> is equal to the number of class loaders plus the number of anonymous classes that are loaded since the previous class unloading operation. This option sets a threshold that is used to trigger an optional GC class unloading operation in a global GC cycle, irrespective of how the global GC cycle is triggered. The default value is 6. This option is applicable to the following GC policies: <code>gencon</code>, <code>optavgpause</code>, and <code>optthruput</code>."},{"location":"xgc/#concurrentscavenge","title":"<code>concurrentScavenge</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xgc:concurrentScavenge\n</code></pre> <p>This option supports pause-less garbage collection mode when you use the Generational Concurrent (<code>gencon</code>) garbage collection policy (the default policy). This option cannot be used with any other GC policies.</p> <p>If you set this option, the VM attempts to reduce GC pause times for response-time sensitive, large-heap applications. This mode can be enabled with hardware-based support (Linux on IBM Z\u00ae and z/OS\u00ae) and software-based support (64-bit: Linux on (x86-64, POWER\u00ae, IBM Z\u00ae) AIX\u00ae, macOS\u00ae, and z/OS).</p> <p> Note: Linux on IBM Z and z/OS</p> <p>This option is supported by all generations of IBM Z hardware to enable pause-less GC with two modes of operation: hardware-based and software-based operations. IBM z13\u2122 and earlier hardware operates in software-based pause-less GC mode; IBM z14\u2122 and later hardware (with supported software) operates in hardware-based mode.</p> <p>Hardware-based pause-less GC is supported on IBM z14 and later hardware running the following software:</p> <p>Operating systems:</p> <ul> <li>z/OS V2R3</li> <li>z/OS V2R2 and APAR OA51643.</li> <li>RHEL 7.5 (minimum kernel level 4.14)</li> <li>Ubuntu 18.04 (minimum kernel level 4.15)</li> </ul> <p>Hypervisors:</p> <ul> <li>IBM z/VM 6.4 with APAR VM65987</li> <li>IBM z/VM 7.1</li> <li>KVM solutions with QEMU 2.10 or later and minimum host kernel level 4.12 (for example, RHEL 7.5 with kernel level 4.14)</li> </ul> <p>If these requirements are not met, the option is ignored.</p> <p> Note: On z/OS, the virtual storage used might exceed the Java maximum heap size. Set the z/OS memory limit, specified by <code>ulimit -M</code>, to a larger value than the maximum heap size.</p>"},{"location":"xgc/#dnssexpectedtimeratiomaximum","title":"<code>dnssExpectedTimeRatioMaximum</code>","text":"<pre><code>    -Xgc:dnssExpectedTimeRatioMaximum=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [percentage] 5 for gencon, 5 for balanced <p>The maximum percentage of time spent in local garbage collection pauses. For the <code>gencon</code> policy, this refers to the amount of time spent on the nursery area of the heap (scavenge operation). For the <code>balanced</code> policy, this refers to the amount of time spent on the eden regions of the heap (PGC operation).</p> <p>This option applies only to the <code>gencon</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgc/#dnssexpectedtimeratiominimum","title":"<code>dnssExpectedTimeRatioMinimum</code>","text":"<pre><code>    -Xgc:dnssExpectedTimeRatioMinimum=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [percentage] 1 for gencon, 2 for balanced <p>The minimum percentage of time spent in local garbage collection pauses. For the <code>gencon</code> policy, this refers to the amount of time spent in Scavenge operation (on the nursery area of the heap). For the <code>balanced</code> policy, this refers to the amount of time spent in PGC operations (mostly on the eden and young regions, but also some other regions for de-fragmentation purposes). </p> <p>This option applies only to the <code>gencon</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgc/#dynamicbreadthfirstscanordering","title":"<code>dynamicBreadthFirstScanOrdering</code>","text":"<pre><code>     -Xgc:dynamicBreadthFirstScanOrdering\n</code></pre> This option sets the scan mode for GC operations that evacuate objects in the heap (scavenge operations (<code>gencon</code>) and copy forward operations (<code>balanced</code>)) to dynamic breadth first mode. This scan mode reflects the method for traversing the object graph and is a variant that adds partial depth first traversal on top of the breadth first scan mode. The aim of dynamic breadth first mode is driven by object field hotness. This mode is the default for the <code>balanced</code> GC policy."},{"location":"xgc/#excessivegcratio","title":"<code>excessiveGCratio</code>","text":"<pre><code>    -Xgc:excessiveGCratio=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [percentage] 95 <p>where <code>&lt;value&gt;</code> is a percentage of total application run time that is spent in GC.</p> <p>The default value is 95, which means that anything over 95% of total application run time spent on GC is deemed excessive. This option can be used only when <code>-Xenableexcessivegc</code> is set (enabled by default).</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xgc/#hierarchicalscanordering","title":"<code>hierarchicalScanOrdering</code>","text":"<pre><code>    -Xgc:hierarchicalScanOrdering\n</code></pre> This option sets the scan mode for the scavenge operation (<code>gencon</code> GC policy) to hierarchical mode. This mode reflects the method for traversing the object graph and adds partial depth first traversal on top of breadth first scan mode. The aim of hierarchical mode is to minimize object distances. This option is the default for the <code>gencon</code> GC policy."},{"location":"xgc/#mincontractpercent","title":"<code>minContractPercent</code>","text":"<pre><code>    -Xgc:minContractPercent=&lt;n&gt;\n</code></pre> Setting Value Default <code>&lt;n&gt;</code> [percentage] - <p>The minimum percentage of the heap that can be contracted at any given time.</p> <p>This option can be used with all OpenJ9 GC policies.</p>"},{"location":"xgc/#maxcontractpercent","title":"<code>maxContractPercent</code>","text":"<pre><code>    -Xgc:maxContractPercent=&lt;n&gt;\n</code></pre> Setting Value Default <code>&lt;n&gt;</code> [percentage] - <p>The maximum percentage of the heap that can be contracted at any given time. For example, <code>-Xgc:maxContractPercent=20</code> causes the heap to contract by as much as 20%.</p> <p>This option can be used with all OpenJ9 GC policies.</p>"},{"location":"xgc/#noconcurrentscavenge","title":"<code>noConcurrentScavenge</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xgc:noConcurrentScavenge\n</code></pre> <p>This option disables pause-less garbage collection that you might have enabled with the <code>-Xgc:concurrentScavenge</code> option when using the default <code>gencon</code> GC policy. This option applies only to the <code>gencon</code> GC policy.</p> <p> Note: No concurrent scavenge is the default state, but the <code>noConcurrentScavenge</code> option is useful as it will disable concurrent scavenge even if it has been enabled by a previous option; the right-most option always takes precedence.</p>"},{"location":"xgc/#nosynchronousgconoom","title":"<code>nosynchronousGCOnOOM</code>","text":"<pre><code>    -Xgc:nosynchronousGCOnOOM\n</code></pre> Setting <code>-Xgc:nosynchronousGCOnOOM</code> implies that when heap memory is full your application stops and issues an out-of-memory message. The default is <code>-Xgc:synchronousGCOnOOM</code>. This option applies only to the <code>metronome</code> GC policy."},{"location":"xgc/#overridehirestimercheck","title":"<code>overrideHiresTimerCheck</code>","text":"<pre><code>    -Xgc:overrideHiresTimerCheck\n</code></pre> <p>When the VM starts, the GC checks that the operating system can meet the timer resolution requirements for the requested target pause time. Typically, this check correctly identifies operating systems that can deliver adequate time resolution. However, in some cases the operating system provides a more conservative answer than strictly necessary for GC pause time management, which prevents startup. Specifying this parameter causes the GC to ignore the answer returned by the operating system. The VM starts, but GC pause time management remains subject to operating system performance, which might not provide adequate timer resolution.</p> <p> Note: Use this option with caution, and only when you are unable to use a supported operating system.</p> <p>This option applies only to the <code>metronome</code> GC policy.</p>"},{"location":"xgc/#preferredheapbase","title":"<code>preferredHeapBase</code>","text":"<p>(AIX, Linux, macOS, and Windows only)</p> <pre><code>    -Xgc:preferredHeapBase=&lt;address&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> [hexadecimal] - <p>where, <code>&lt;address&gt;</code> is the base memory address for the heap. Use this option with the <code>-Xcompressedrefs</code> option to allocate the heap you specify with the <code>-Xmx</code> option, in a memory range of your choice. If <code>-Xcompressedrefs</code> is not specified, this option has no effect. In the following example, the heap is located at the 4 GB mark, leaving the lowest 4 GB of address space for use by other processes.</p> <pre><code>-Xgc:preferredHeapBase=0x100000000\n</code></pre> <p>If the heap cannot be allocated in a contiguous block at the <code>preferredHeapBase</code> address you specified, an error occurs detailing a Garbage Collection (GC) allocation failure startup. When the <code>preferredHeapBase</code> option is used with the <code>-Xlp</code> option, the <code>preferredHeapBase</code> address must be a multiple of the large page size. If you specify an inaccurate heap base address, the heap is allocated with the default page size.</p> <p>This option can be used with all OpenJ9 GC policies.</p>"},{"location":"xgc/#scvnoadaptivetenure","title":"<code>scvNoAdaptiveTenure</code>","text":"<pre><code>    -Xgc:scvNoAdaptiveTenure\n</code></pre> Turns off the adaptive tenure age in the <code>gencon</code> GC policy. The initial age that is set is maintained throughout the run time of the VM. See <code>scvTenureAge</code>. This option applies only to the <code>gencon</code> GC policy."},{"location":"xgc/#scvtenureage","title":"<code>scvTenureAge</code>","text":"<pre><code>    -Xgc:scvTenureAge=&lt;n&gt;\n</code></pre> Setting Value Default <code>&lt;n&gt;</code> [1 - 14] 10 <p>Sets the initial scavenger tenure age in the <code>gencon</code> GC policy. For more information, see <code>gencon</code> policy (default).</p> <p>This option applies only to the <code>gencon</code> GC policy.</p>"},{"location":"xgc/#stdglobalcompacttosatisfyallocate","title":"<code>stdGlobalCompactToSatisfyAllocate</code>","text":"<pre><code>    -Xgc:stdGlobalCompactToSatisfyAllocate\n</code></pre> Prevents the GC from performing a compaction unless absolutely required to satisfy the current allocation failure by removing the dynamic compaction triggers that look at heap occupancy. This option works only with the following GC policies: <ul> <li><code>gencon</code></li> <li><code>optthruput</code></li> <li><code>optavgpause</code></li> </ul> This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>)."},{"location":"xgc/#synchronousgconoom","title":"<code>synchronousGCOnOOM</code>","text":"<pre><code>    -Xgc:synchronousGCOnOOM\n</code></pre> GC cycles can occur when the Java heap runs out of memory. If there is no more free space in the heap, using <code>-Xgc:synchronousGCOnOOM</code> stops your application while GC operations remove unused objects. If free space runs out again, consider decreasing the target utilization to allow GC operations more time to complete. Setting <code>-Xgc:nosynchronousGCOnOOM</code> implies that when heap memory is full your application stops and issues an out-of-memory message. The default is <code>-Xgc:synchronousGCOnOOM</code>. This option applies only to the <code>metronome</code> GC policy."},{"location":"xgc/#targetpausetime","title":"<code>targetPausetime</code>","text":"<pre><code>    -Xgc:targetPausetime=N\n</code></pre> Sets the target GC pause time, where <code>N</code> is the time in milliseconds. When this option is specified with the <code>metronome</code> policy, the garbage collector operates with pauses that do not exceed the value specified. If this option is not specified when using the <code>metronome</code> policy, the default pause time target is set to 3 milliseconds. For example, running with <code>-Xgc:targetPausetime=20</code> causes the garbage collector to pause for no longer than 20 milliseconds during GC operations. <p>When this option is specified with the <code>balanced</code> policy, the GC will use the specified pause time as a soft pause time target. If this option is not specified when using the <code>balanced</code> policy, the default pause time target is set to 200 milliseconds. If the GC pauses are longer than the specified target, then the GC may shrink the amount of eden regions in order to satisfy the target pause time. If the percentage of time spent in PGC pauses is higher than <code>dnssExpectedTimeRatioMaximum</code> and the GC pauses are longer than the specified pause time target, then the target pause time may not be satisfied, in order to balance reaching the target pause time goal and percentage of time in GC pause goal.</p> <p> Note: Specifying an ultra low <code>targetPausetime</code> with the Balanced GC policy may cause the percentage of time spent in GC pauses to noticeably increase.</p> <p>This option applies only to the <code>metronome</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgc/#targetutilization","title":"<code>targetUtilization</code>","text":"<pre><code>    -Xgc:targetUtilization=N\n</code></pre> <p>Sets the application utilization to <code>N%</code>; the garbage collector attempts to use at most (100-N)% of each time interval. Reasonable values are in the range of 50-80%. Applications with low allocation rates might be able to run at 90%. The default is 70%.</p> <p>In the following example, the maximum size of the heap is set to 30 MB. The garbage collector attempts to use 25% of each time interval because the target utilization for the application is set to 75%.</p> <pre><code>java -Xgcpolicy:metronome -Xmx30m -Xgc:targetUtilization=75 Test\n</code></pre> <p>This option applies only to the <code>metronome</code> GC policy.</p>"},{"location":"xgc/#tlhincrementsize","title":"<code>tlhIncrementSize</code>","text":"<pre><code>    -Xgc:tlhIncrementSize=&lt;bytes&gt;\n</code></pre> Sets the increment size of the thread local heap (TLH), which plays a key role in cache allocation. Threads start creating TLHs with a predefined initial size (default 2 KB). On every TLH refresh, the requested size for that thread is increased by an increment (default 4 KB). Use this option to control the increment size. This option can be used with all OpenJ9 GC policies."},{"location":"xgc/#tlhinitialsize","title":"<code>tlhInitialSize</code>","text":"<pre><code>    -Xgc:tlhInitialSize=&lt;bytes&gt;\n</code></pre> Sets the initial size of the TLH. The default size is 2 KB. This option can be used with all OpenJ9 GC policies."},{"location":"xgc/#tlhmaximumsize","title":"<code>tlhMaximumSize</code>","text":"<pre><code>    -Xgc:tlhMaximumSize=&lt;bytes&gt;\n</code></pre> Sets the maximum size of the TLH. The size of the TLH varies from 512 bytes (768 on 64-bit JVMs) to 128 KB, depending on the allocation rate of the thread. Larger TLHs can help reduce heap lock contention, but might also reduce heap utilisation and increase heap fragmentation. Typically, when the maximum TLH size is increased, you should also increase the increment size (<code>-XtlhIncrementSize</code>) proportionally, so that active threads can reach the maximum requested TLH size more quickly. This option can be used with all OpenJ9 GC policies."},{"location":"xgc/#verboseformat","title":"<code>verboseFormat</code>","text":"<pre><code>    -Xgc:verboseFormat=&lt;format&gt;\n</code></pre> Setting Value Default <code>&lt;format&gt;</code> <code>default</code> yes <code>deprecated</code> <ul> <li><code>default</code>: The default verbose garbage collection format for OpenJ9. For more information, see Verbose garbage collection logs.</li> <li><code>deprecated</code>: The verbose garbage collection format available in the IBM J9 VM V2.4 and earlier.</li> </ul> <p>This option does not apply to the <code>metronome</code> GC policy. The verbose log format for the <code>metronome</code> GC policy is equivalent to <code>-Xgc:verboseFormat=deprecated</code>.</p>"},{"location":"xgc/#verbosegccycletime","title":"<code>verbosegcCycleTime</code>","text":"<pre><code>    -Xgc:verbosegcCycleTime=N\n</code></pre> <p><code>N</code> is the time in milliseconds that the summary information should be logged.</p> <p> Note: The cycle time does not mean that the summary information is logged precisely at that time, but when the last GC event that meets this time criterion passes.</p> <p>This option applies only to the <code>metronome</code> GC policy.</p>"},{"location":"xgcmaxthreads/","title":"-Xgcmaxthreads","text":""},{"location":"xgcmaxthreads/#-xgcmaxthreads","title":"-Xgcmaxthreads","text":"<p>Specifies the maximum number of threads that the garbage collector can use for parallel operations. This option behaves in the same way as <code>-Xgcthreads</code> but does not enforce a fixed thread count, which allows the garbage collector to adjust the thread count when used with the <code>-XX:+AdaptiveGCThreading</code> option.</p>"},{"location":"xgcmaxthreads/#syntax","title":"Syntax","text":"<pre><code>    -Xgcmaxthreads&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the maximum number of threads that can be used for parallel operations.</p>"},{"location":"xgcpolicy/","title":"-Xgcpolicy","text":""},{"location":"xgcpolicy/#-xgcpolicy","title":"-Xgcpolicy","text":"<p>Controls which garbage collection (GC) policy is used for your Java\u2122 application.</p>"},{"location":"xgcpolicy/#syntax","title":"Syntax","text":"<pre><code>    -Xgcpolicy:&lt;parameter&gt;\n</code></pre>"},{"location":"xgcpolicy/#parameters","title":"Parameters","text":"Parameter Default <code>gencon</code> yes <code>balanced</code> (64-bit only) <code>metronome</code> (AIX\u00ae, Linux\u00ae x86 only) <code>optavgpause</code> <code>optthruput</code> <code>nogc</code> <p>For a detailed description of the policies, when to use them, and how they work, see Garbage Collection policies. The following GC policies are available:</p>"},{"location":"xgcpolicy/#gencon","title":"<code>gencon</code>","text":"<pre><code>    -Xgcpolicy:gencon\n</code></pre> The generational concurrent policy (default) requires a heap that is divided into two main areas (nursery and tenure) to manage two generation groups (new and older). The policy uses a global GC cycle of concurrent mark-sweep operations, optionally followed by compact operations. The policy also uses a partial GC cycle to run scavenge operations on the nursery area. The partial cycle helps reduce the frequency and duration of the global GC cycle. Note that scavenge is a stop-the-world operation, unless <code>-Xgcpolicy:gencon</code> is specified with the <code>-Xgc:concurrentScavenge</code> option. To learn more about this policy, when to use it, and how it works, see Garbage collection: <code>gencon</code> policy."},{"location":"xgcpolicy/#balanced-64-bit-only","title":"<code>balanced</code> (64-bit only)","text":"<pre><code>    -Xgcpolicy:balanced\n</code></pre> The Balanced policy requires a multi-region heap to manage multiple generations of objects. The policy uses a global GC cycle that involves an incremental concurrent mark operation (global mark phase), followed by stop-the-world (STW) sweep operation. The policy also uses a partial GC cycle to run copy forward or mark-compact operations. Regions are individually managed to reduce the maximum pause time on large heaps and increase the efficiency of garbage collection. The policy tries to avoid global collections by matching object allocation and survival rates. With the <code>balanced</code> policy, the global mark and partial GC cycles interleave. The global STW sweep operation runs within the same GC increment as the first partial GC cycle that follows the global mark phase. The <code>balanced</code> policy also exploits large systems that have Non-Uniform Memory Architecture (NUMA) characteristics (x86 and POWER\u2122 platforms only), which might further improve application throughput. Note: If you are using this GC policy in a Docker container that uses the default <code>seccomp</code> Docker profile, you must start the container with <code>--security-opt seccomp=unconfined</code> to exploit NUMA characteristics. These options are not required if you are running in Kubernetes because <code>unconfined</code> is set by default (see Seccomp). To learn more about this policy, how it works, and when to use it, see Garbage collection: <code>balanced</code> policy."},{"location":"xgcpolicy/#balanced-defaults-and-options","title":"<code>balanced</code> defaults and options","text":"<p>The initial heap size is Xmx/1024, rounded down to the nearest power of 2, where Xmx is the maximum heap size available. You can override this value by specifying the <code>-Xms</code> option on the command line.</p> <p>The following options can also be specified on the command line with <code>-Xgcpolicy:balanced</code>:</p> <ul> <li><code>-Xdisableexcessivegc</code></li> <li><code>-Xdisableexplicitgc</code></li> <li><code>-Xenableexcessivegc</code></li> <li><code>-Xgcthreads&lt;number&gt;</code></li> <li><code>-Xgcworkpackets&lt;number&gt;</code></li> <li><code>-Xmaxe&lt;size&gt;</code></li> <li><code>-Xmaxf&lt;percentage&gt;</code></li> <li><code>-Xmaxt&lt;percentage&gt;</code></li> <li><code>-Xmca&lt;size&gt;</code></li> <li><code>-Xmco&lt;size&gt;</code></li> <li><code>-Xmine&lt;size&gt;</code></li> <li><code>-Xminf&lt;percentage&gt;</code></li> <li><code>-Xmint&lt;percentage&gt;</code></li> <li><code>-Xmn&lt;size&gt;</code></li> <li><code>-Xmns&lt;size&gt;</code></li> <li><code>-Xmnx&lt;size&gt;</code></li> <li><code>-Xms&lt;size&gt;</code></li> <li><code>-Xmx&lt;size&gt;</code></li> <li><code>-Xnuma:none</code></li> <li><code>-Xsoftmx&lt;size&gt;</code></li> <li><code>-Xsoftrefthreshold&lt;number&gt;</code></li> <li><code>-Xverbosegclog[:&lt;file&gt; [, &lt;X&gt;,&lt;Y&gt;]]</code></li> </ul> <p>The behavior of the following options is different when specified with <code>-Xgcpolicy:balanced</code>:</p> <code>-Xcompactgc</code> (default) Forces compaction in each Global GC cycle. <code>-Xnocompactgc</code> Disables internal compaction heuristics in Global GC cycles. <code>-Xcompactexplicitgc</code> (default) Forces compaction in explicit Global GC cycles, such as those invoked by <code>System.gc()</code>. Compaction in implicit Global GC remains optional, triggered by internal heuristics. <code>-Xnocompactexplicitgc</code> Disables compaction in explicit Global GC cycles. Compaction in implicit Global GC remains optional, triggered by internal heuristics. <code>-Xgc:targetPausetime</code> Uses the specified GC pause time as a soft GC pause time target. <p>The following options are ignored when specified with <code>-Xgcpolicy:balanced</code>:</p> <ul> <li><code>-Xconcurrentbackground&lt;number&gt;</code></li> <li><code>-Xconcurrentlevel&lt;number&gt;</code></li> <li><code>-Xconcurrentslack&lt;size&gt;</code></li> <li><code>-Xconmeter:&lt;soa | loa | dynamic&gt;</code></li> <li><code>-Xdisablestringconstantgc</code></li> <li><code>-Xenablestringconstantgc</code></li> <li><code>-Xloa</code></li> <li><code>-Xloainitial&lt;percentage&gt;</code></li> <li><code>-Xloamaximum&lt;percentage&gt;</code></li> <li><code>-Xloaminimum&lt;percentage&gt;</code></li> <li><code>-Xmo&lt;size&gt;</code></li> <li><code>-Xmoi&lt;size&gt;</code></li> <li><code>-Xmos&lt;size&gt;</code></li> <li><code>-Xmr&lt;size&gt;</code></li> <li><code>-Xmrx&lt;size&gt;</code></li> <li><code>-Xnoloa</code></li> </ul>"},{"location":"xgcpolicy/#optavgpause","title":"<code>optavgpause</code>","text":"<pre><code>    -Xgcpolicy:optavgpause\n</code></pre> <p>The optimize for pause time policy requires a flat heap and uses a global GC cycle to run concurrent mark-sweep operations, optionally followed by compact operations. Pause times are shorter than with <code>optthruput</code>, but application throughput is reduced. The impact on throughput occurs because some garbage collection work is taking place in the context of mutator (application) threads, and because GC frequency is increased.</p> <p>To learn more about this policy and when to use it, see Garbage collection: <code>optavgpause</code> policy.</p>"},{"location":"xgcpolicy/#optthruput","title":"<code>optthruput</code>","text":"<pre><code>    -Xgcpolicy:optthruput\n</code></pre> <p>The optimize for throughput policy requires a flat heap and uses a global GC cycle to run mark-sweep operations, optionally followed by compact operations. Because the application stops during a global GC cycle, long pauses can occur.</p> <p>To learn more about this policy, how it works, and when to use it, see Garbage collection: <code>optthruput</code> policy.</p>"},{"location":"xgcpolicy/#metronome-aix-linux-x86-only","title":"<code>metronome</code> (AIX, Linux x86 only)","text":"<pre><code>    -Xgcpolicy:metronome\n</code></pre> <p>The metronome policy is an incremental, deterministic garbage collector with short pause times. Applications that are dependent on precise response times can take advantage of this technology by avoiding potentially long delays from GC activity. The <code>metronome</code> policy is supported on specific hardware and operating system configurations.</p> <p>To learn more about this policy, how it works, and when to use it, see Garbage collection: <code>metronome</code> policy.</p>"},{"location":"xgcpolicy/#metronome-options","title":"<code>metronome</code> options","text":"<p>The following options are specific to the <code>metronome</code> GC policy:</p> <ul> <li><code>-Xgc:nosynchronousGCOnOOM</code></li> <li><code>-Xgc:overrideHiresTimerCheck</code></li> <li><code>-Xgc:synchronousGCOnOOM</code></li> <li><code>-Xgc:targetUtilization</code></li> <li><code>-Xgc:verbosegcCycleTime</code></li> </ul> <p><code>-Xgc:targetPausetime</code> option also applies to the <code>metronome</code> GC policy. This option applies only to the <code>metronome</code> and <code>balanced</code> GC policies.</p>"},{"location":"xgcpolicy/#nogc","title":"<code>nogc</code>","text":"<pre><code>    -Xgcpolicy:nogc\n</code></pre> <p>This policy handles only memory allocation and heap expansion, but doesn't reclaim any memory. If the available Java heap becomes exhausted, an <code>OutOfMemoryError</code> exception is triggered and the VM stops.</p> <p>You should be especially careful when using any of the following techniques with <code>nogc</code> because memory is never released under this policy: - Finalization - Direct memory access - Weak, soft, and phantom references</p> <p>To learn when to use this policy, see Garbage collection: <code>nogc</code> policy.</p> <p>This policy can also be enabled with the <code>-XX:+UseNoGC</code> option.</p> <p>Further details are available at JEP 318: Epsilon: A No-Op Garbage Collector.</p>"},{"location":"xgcsplitheap/","title":"-Xgc:splitheap","text":""},{"location":"xgcsplitheap/#-xgcsplitheap","title":"-Xgc:splitheap","text":"<p>(Windows\u2122 32-bit only)</p> <p>By default, the VM uses a contiguous Java\u2122 heap to store Java objects. However, on Windows 32-bit systems, there are restrictions in the 32-bit memory space that prevents a process accessing more than 2GB of memory, even if there is more memory available. To increase the maximum allocatable heap size, Eclipse OpenJ9\u2122 can split the heap, allowing memory use up to the 4GB limit.</p> <p> Restrictions:</p> <ul> <li>A split heap forces the garbage collector to use the <code>gencon</code> policy and allocates the new and old areas of the generational Java heap in separate areas of memory. Resizing of the new and old memory areas is disabled.</li> <li> This option can be used only with Java SE version 8 runtime environments.  This option is deprecated in Version 8 and will be removed from future versions.</li> </ul>"},{"location":"xgcsplitheap/#syntax","title":"Syntax","text":"<pre><code>    -Xgc:splitheap\n</code></pre>"},{"location":"xgcsplitheap/#explanation","title":"Explanation","text":"<p>Use <code>-Xgc:splitheap</code> for applications that must run on the 32-bit VM because of 32-bit JNI libraries, a 32-bit operating system, or 32-bit hardware, but need large Java heaps. By using a larger heap, you can allocate more objects before incurring a garbage collection (GC) and you can increase the number of live objects that you can use before an <code>OutOfMemoryError</code> exception occurs.</p> <p>With a split heap, the old area is committed to its maximum size (set with <code>-Xmox</code>) in a lower region of memory and the new area is committed to its maximum size (set with <code>-Xmnx</code>) in a higher region of memory.</p> <p>This option is not recommended if your application works in the any of the following ways:</p> <ul> <li>Performs poorly under the <code>gencon</code> GC policy.</li> <li>Loads a very large number of classes.</li> <li>Uses large amounts of native system memory in JNI libraries; the increased size Java heap might reserve too much of the application's address space.</li> </ul>"},{"location":"xgcthreads/","title":"-Xgcthreads","text":""},{"location":"xgcthreads/#-xgcthreads","title":"-Xgcthreads","text":"<p>Sets the number of threads that the garbage collector uses for parallel operations.</p> <p> Notes:</p> <p>This option enforces a fixed thread count and cannot be used with the <code>-XX:+AdaptiveGCThreading</code> option, which enables the garbage collector to adjust the number of parallel threads based on heuristics. If you want to use <code>-XX:+AdaptiveGCThreading</code>, use <code>-Xgcmaxthreads</code> instead of <code>-Xgcthreads</code>.</p>"},{"location":"xgcthreads/#syntax","title":"Syntax","text":"<pre><code>    -Xgcthreads&lt;number&gt;\n</code></pre>"},{"location":"xgcthreads/#explanation","title":"Explanation","text":"<p>The total number of GC threads is composed of one application thread with the remainder being dedicated GC threads. By default, the number is set to <code>n-1</code>, where <code>n</code> is the number of reported CPUs, up to a maximum of 64. Where SMT or hyperthreading is in place, the number of reported CPUs is larger than the number of physical CPUs. Likewise, where virtualization is in place, the number of reported CPUs is the number of virtual CPUs assigned to the operating system. To set it to a different number, for example 4, use <code>-Xgcthreads4</code>. The minimum valid value is 1, which disables parallel operations, at the cost of performance. No advantage is gained if you increase the number of threads to more than the default setting.</p> <p>On systems running multiple VMs or in LPAR environments where multiple VMs can share the same physical CPUs, you might want to restrict the number of GC threads used by each VM. The restriction helps prevent the total number of parallel operation GC threads for all VMs exceeding the number of physical CPUs present, when multiple VMs perform garbage collection at the same time.</p> <p>This option is directly mapped to the HotSpot option <code>-XX:ParallelGCThreads</code> and can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xgcworkpackets/","title":"-Xgcworkpackets","text":""},{"location":"xgcworkpackets/#-xgcworkpackets","title":"-Xgcworkpackets","text":"<p>Specifies the total number of work packets available in the global collector.</p>"},{"location":"xgcworkpackets/#syntax","title":"Syntax","text":"<pre><code>    -Xgcworkpackets&lt;number&gt;\n</code></pre>"},{"location":"xgcworkpackets/#explanation","title":"Explanation","text":"<p>If you do not specify a value, the collector allocates a number of packets based on the maximum heap size.</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xint/","title":"-Xint","text":""},{"location":"xint/#-xint","title":"-Xint","text":"<p>As described in the Oracle \"Non-Standard Options\" documentation, this VM option runs an application in interpreted-only mode. For compatibility, this option is also supported by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xint/#syntax","title":"Syntax","text":"<pre><code>    -Xint\n</code></pre>"},{"location":"xint/#explanation","title":"Explanation","text":"<p>If you use this option, the OpenJ9 VM uses only the interpreter, disabling the OpenJ9 just-in-time (JIT) and ahead-of-time (AOT) compilers. By default, both these compilers are enabled, although the AOT compiler is not used by the VM unless shared classes are also enabled.</p>"},{"location":"xjit/","title":"-Xnojit","text":""},{"location":"xjit/#-xjit-xnojit","title":"-Xjit / -Xnojit","text":"<p>Use this option to control the behavior of the JIT compiler.</p> <p>Specifying <code>-Xjit</code> with no parameters has no effect because the JIT compiler is enabled by default.</p> <p>Specifying <code>-Xnojit</code> turns off the JIT compiler but does not affect the AOT compiler.</p> <p>Specify the <code>-Xjit</code> option only once. By default, if you specify this option multiple times, only the last option takes effect. You can use the <code>-XX:+MergeCompilerOptions</code> option to merge all the existing instances of the <code>-Xjit</code> options logically.</p> <p>You can specify multiple parameters for the <code>-Xjit</code> option by using commas to separate the parameters. For example: </p> <p><code>-Xjit:enableGPU,exclude={ilog/rules/engine/sequential/generated/*}</code> </p> <p>Parameters such as <code>exclude</code> are additive so you can specify them multiple times within the same <code>-Xjit</code> option.</p>"},{"location":"xjit/#syntax","title":"Syntax","text":"Setting Action Default <code>-Xjit</code> Enable JIT yes <code>-Xjit[:&lt;parameter&gt;=&lt;value&gt;{,&lt;parameter&gt;=&lt;value&gt;}]</code> Enable JIT with options <code>-Xnojit</code> Disable JIT"},{"location":"xjit/#parameters","title":"Parameters","text":"<p>These parameters can be used to modify the behavior of <code>-Xjit</code>:</p> Parameter Effect <code>count</code> Specifies the number of times a method is called before it is compiled. <code>disableRMODE64</code> Allows the JIT to allocate executable code caches above the 2 GB memory bar. <code>enableGPU</code> Allows the JIT to offload certain processing tasks to a graphics processing unit (GPU) <code>exclude</code> Excludes the specified method from compilation. <code>limit</code> Includes the specified method in compilation. <code>limitFile</code> Compile methods that are listed in the limit file. <code>optlevel</code> Forces the JIT compiler to compile all methods at a specific optimization level. <code>verbose</code> Reports information about the JIT and AOT compiler configuration and method compilation. <code>vlog</code> Sends verbose output to a file. <code>perfTool</code> Facilitates JIT-compiled code symbol resolution when profiling the VM on Linux."},{"location":"xjit/#count","title":"<code>count</code>","text":"<pre><code>    -Xjit:count=&lt;n&gt;\n</code></pre> Specifies the number of times, <code>&lt;n&gt;</code>, a method is called before it is compiled. For example, setting <code>count=0</code> forces the JIT compiler to compile everything on first execution, which is useful for problem determination."},{"location":"xjit/#disablermode64","title":"<code>disableRMODE64</code>","text":"<p>(z/OS\u00ae only)</p> <pre><code>    -Xjit:disableRMODE64\n</code></pre> From z/OS V2R3, residency mode for 64-bit applications (RMODE64) is enabled by default. This feature allows the JIT to allocate executable code caches above the 2 GB memory bar, which is the default behavior. Use this option to turn off this JIT behavior."},{"location":"xjit/#enablegpu","title":"<code>enableGPU</code>","text":"<p>(Windows (x86-64) or Linux (x86-64 and IBM POWER LE))</p> <pre><code>    -Xjit:enableGPU\n</code></pre> Enables the JIT compiler to offload certain processing tasks to a graphics processing unit (GPU). The JIT determines which functions to offload based on performance heuristics. Systems must support NVIDIA Compute Unified Device Architecture (CUDA). The JIT requires the CUDA Toolkit 7.5 and your GPU device must have a minimum compute capability of 3.0. To troubleshoot operations between the JIT compiler and the GPU, use <code>-Xjit:enableGPU={verbose}</code>, which provides output showing the processing tasks that are offloaded and their status. To send this output to a file (<code>output.txt</code>), run <code>-Xjit:enableGPU={verbose},vlog=output.txt</code> when you start your application."},{"location":"xjit/#exclude","title":"<code>exclude</code>","text":"<pre><code>    -Xjit:exclude={&lt;method&gt;}\n</code></pre> <p>Excludes the specified method from compilation.</p> <p><code>&lt;method_name&gt;</code> is the method or methods that are to be excluded; the wildcard <code>*</code> may be used. Specify as much of the full package, class and method as necessary. </p> <p>For example, <code>-Xjit:exclude={test/sample/MyClass.testMethod()V}</code> excludes the single method specified. However, <code>-Xjit:exclude={test/sample/MyClass.testMethod()*}</code> excludes the method regardless of return type. Similarly, <code>-Xjit:exclude={*}</code> excludes all methods.</p> <p> Note: <code>exclude</code> has the same effect regardless of whether it is specified on <code>-Xaot</code> or <code>-Xjit</code>. In consequence, if you specify <code>-Xjit:exclude</code>, AOT compilation is also prevented and the methods specified are always interpreted.</p>"},{"location":"xjit/#limit","title":"<code>limit</code>","text":"<pre><code>    -Xjit:limit={&lt;method_name&gt;}\n</code></pre> Only the Java\u2122 methods specified are included when code is compiled or loaded from the shared classes cache. <code>&lt;method_name&gt;</code> is the method or methods that are to be included (the wildcard <code>*</code> can be used, see <code>-Xjit:exclude</code> for details). Note: <code>limit</code> has the same effect regardless of whether it is specified on <code>-Xaot</code> or <code>-Xjit</code>. In consequence, if you specify <code>-Xjit:limit</code>, AOT compilation is also restricted to those methods specified; other methods are always interpreted."},{"location":"xjit/#limitfile","title":"<code>limitFile</code>","text":"<pre><code>    -Xjit:limitFile=(&lt;vlog_filename&gt;, &lt;m&gt;, &lt;n&gt;)\n</code></pre> Compile only the methods that are listed on lines <code>&lt;m&gt;</code> to <code>&lt;n&gt;</code> in the specified limit file, where the limit file is a verbose log that you generated with the <code>-Xjit:verbose,vlog=&lt;vlog_filename&gt;</code> option. Methods that are not listed in the limit file and methods that are listed on lines outside the range are not compiled. Note: <code>limitFile</code> has the same effect regardless of whether it is specified on <code>-Xaot</code> or <code>-Xjit</code>. In consequence, if you specify <code>-Xjit:limitFile</code>, AOT compilation is also restricted to those methods specified; other methods are always interpreted."},{"location":"xjit/#optlevel","title":"<code>optlevel</code>","text":"<pre><code>    -Xjit:optlevel=[noOpt|cold|warm|hot|veryHot|scorching]\n</code></pre> Forces the JIT compiler to compile all methods at a specific optimization level. Specifying <code>optlevel</code> might have an unexpected effect on performance, including reduced overall performance."},{"location":"xjit/#verbose","title":"<code>verbose</code>","text":"<pre><code>    -Xjit:verbose\n</code></pre> Generates a JIT verbose log. The log provides a summary of which methods were compiled by the JIT and some of the compilation heuristic decisions that were taken while the JIT operates inside the Eclipse OpenJ9\u2122 VM.<pre><code>-Xjit:verbose={compileStart}\n</code></pre> <p>Prints a line when the JIT is about to start compiling a method.</p> <pre><code>-Xjit:verbose={compileEnd}\n</code></pre> <p>Prints a line when the JIT stops compiling a method.</p> <pre><code>-Xjit:verbose={compilePerformance}\n</code></pre> <p>Adds the values <code>time</code> (time taken to do the compilation) and <code>mem</code> (the amount of memory that was allocated during the compilation) into each line. This option includes the <code>compileStart</code> and <code>compileEnd</code> suboptions by default.</p> <pre><code>-Xjit:verbose={disableInlining}\n</code></pre> <p>Turns off inlining operations.</p> <pre><code>-Xjit:verbose={inlining}\n</code></pre> <p>Shows the methods that are inlined.</p> <p> Note: Suboptions can be chained together by using a pipe (<code>|</code>) symbol. When used, you must enclose the full option name in single quotation marks (<code>'</code>) to avoid the shell misinterpreting these characters as pipe commands. For example:</p> <pre><code>java '-Xjit:verbose={compileStart|compileEnd|inlining}' -version\n</code></pre>"},{"location":"xjit/#vlog","title":"<code>vlog</code>","text":"<pre><code>    -Xjit:vlog=&lt;vlog_filename&gt;\n</code></pre> Sends verbose output to a file, of the format <code>&lt;vlog_filename&gt;.&lt;date&gt;.&lt;time&gt;.&lt;JVM_process_ID&gt;</code>, which is created in your current directory. Running the command multiple times produces multiple distinct versions of this file. If you do not specify this parameter, the output is sent to the standard error output stream (STDERR). This type of log file can be used with the <code>limitFile</code> suboption to target the compilation of specific methods."},{"location":"xjit/#perftool","title":"<code>perfTool</code>","text":"<pre><code>    -Xjit:perfTool\n</code></pre> generates a <code>/tmp/perf-&lt;pid&gt;.map</code> file for the JIT-compiled code. This file is used by the Linux\u00ae system profiler, <code>perf</code>, to map the samples in the JIT-compiled code to the corresponding Java method names for profiling the VM. <p>For more information, see <code>-XX:[+|-]PerfTool</code>.</p>"},{"location":"xjit/#examples","title":"Examples","text":""},{"location":"xjit/#generating-a-jit-verbose-log","title":"Generating a JIT verbose log","text":"<p>The following example requests a JIT verbose log of the <code>java -version</code> command:</p> <pre><code>java -Xjit:verbose,vlog=vlogfile -version\n</code></pre>"},{"location":"xjit/#analyzing-jit-performance","title":"Analyzing JIT performance","text":"<p>The following example requests information about the performance of JIT compiler threads, with output written to <code>vlogfile</code>.</p> <pre><code>java -Xjit:verbose={compilePerformance},vlog=vlogfile -version\n</code></pre> <p>The output generated by using this command adds the following information to compilation entry:</p> <ul> <li>the amount of time taken to do the compilation.</li> <li>the amount of memory that was allocated during the compilation.</li> </ul>"},{"location":"xjit/#analyzing-inlining-operations","title":"Analyzing inlining operations","text":"<p>The following example generates output that contains performance data and inlining operations. The suboptions <code>count</code> and <code>-XcompilationThreads1</code> are used only to simplify the output. These options are not recommended for production because performance will be affected.</p> <pre><code>java '-Xjit:verbose={compileStart|compileEnd|inlining},count=5,vlog=vlogfile' -XcompilationThreads1 -version\n</code></pre>"},{"location":"xjit/#see-also","title":"See also","text":"<ul> <li>Diagnosing a JIT or AOT problem</li> <li>-Xaot</li> </ul>"},{"location":"xjni/","title":"-Xjni","text":""},{"location":"xjni/#-xjni","title":"-Xjni","text":"<p>Sets JNI options.</p>"},{"location":"xjni/#syntax","title":"Syntax","text":"<pre><code>    -Xjni:&lt;parameter&gt;\n</code></pre>"},{"location":"xjni/#parameters","title":"Parameters","text":""},{"location":"xjni/#arraycachemax","title":"<code>arrayCacheMax</code>","text":"<pre><code>    -Xjni:arrayCacheMax=&lt;size in bytes&gt;\n    -Xjni:arrayCacheMax=unlimited\n</code></pre> Sets the maximum size of the array cache. The default size is 128 KB (<code>-Xjni:arrayCacheMax=131072</code>)."},{"location":"xlinenumbers/","title":"-Xnolinenumbers","text":""},{"location":"xlinenumbers/#-xlinenumbers-xnolinenumbers","title":"-Xlinenumbers / -Xnolinenumbers","text":"<p>Enables or disables line numbers in stack traces for debugging.</p>"},{"location":"xlinenumbers/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xlinenumbers</code> Enable yes <code>-Xnolinenumbers</code> Disable"},{"location":"xlinenumbers/#explanation","title":"Explanation","text":"<p>If you start the Eclipse OpenJ9\u2122 VM with <code>-Xnolinenumbers</code> when creating a new shared classes cache, the Class Debug Area is not created. The option <code>-Xnolinenumbers</code> advises the VM not to load any class debug information, so there is no need for this region. If <code>-Xscdmx</code> is also used on the command line to specify a non zero debug area size, then a debug area is created despite the use of <code>-Xnolinenumbers</code>.</p>"},{"location":"xloa/","title":"-Xnoloa","text":""},{"location":"xloa/#-xloa-xnoloa","title":"-Xloa / -Xnoloa","text":"<p>This option enables or prevents the allocation of a large object area (LOA) during garbage collection (GC).</p>"},{"location":"xloa/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xloa</code> Enable LOA yes (see Default behavior) <code>-Xnoloa</code> Disable LOA"},{"location":"xloa/#default-behavior","title":"Default behavior","text":"<p>By default, allocations are made in the small object area (SOA). If there is no room in the SOA, and an object is larger than 64KB, the object is allocated in the LOA.</p> <p>If the LOA is not used, it is shrunk to zero after a few collections. You can disable it explicitly by specifying the <code>-Xnoloa</code> option.</p>"},{"location":"xloa/#explanation","title":"Explanation","text":"<p>The LOA is an area of the tenure area of the heap set used solely to satisfy allocations for large objects. The LOA is used when the allocation request cannot be satisfied in the main area (the SOA of the tenure heap.</p> <p>As objects are allocated and freed, the heap can become fragmented in such a way that allocation can be met only by time-consuming compactions. This problem is more pronounced if an application allocates large objects. In an attempt to alleviate this problem, the LOA is allocated. A large object in this context is considered to be any object 64 KB or greater in size. Allocations for new TLH objects are not considered to be large objects.</p> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>), which do not use an LOA. Any LOA options passed on the command line are ignored. These policies address the issues that are solved by an LOA by reorganizing object layout with the VM to reduce heap fragmentation and compaction requirements.</p>"},{"location":"xloa/#see-also","title":"See also","text":"<ul> <li>-Xloainitial / -Xloaminimum / -Xloamaximum</li> </ul>"},{"location":"xloaminimum/","title":"-Xloaminimum","text":""},{"location":"xloaminimum/#-xloainitial-xloaminimum-xloamaximum","title":"-Xloainitial / -Xloaminimum / -Xloamaximum","text":"<p>Specifies the initial, minimum, and maximum proportion of the current tenure space allocated to the large object area (LOA).</p> <p>The LOA does not shrink to less than the minimum value.</p>"},{"location":"xloaminimum/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xloainitial&lt;value&gt;</code> Set initial space <code>0.05</code> <code>-Xloaminimum&lt;value&gt;</code> Set minimum space <code>0.01</code> <code>-Xloamaximum&lt;value&gt;</code> Set minimum space <code>0.5</code>"},{"location":"xloaminimum/#see-also","title":"See also","text":"<ul> <li>-Xloa / Xnoloa</li> </ul> <p>This option is not supported with the balanced GC policy (<code>-Xgcpolicy:balanced</code>) or metronome GC policy (<code>-Xgcpolicy:metronome</code>), which do not use an LOA.</p>"},{"location":"xlockreservation/","title":"-XlockReservation","text":""},{"location":"xlockreservation/#-xlockreservation","title":"-XlockReservation","text":"<p>Enables an optimization that presumes a monitor is owned by the thread that last acquired it.</p> <p>This optimization minimizes the runtime cost of acquiring and releasing a monitor for a single thread if the monitor is rarely acquired by multiple threads.</p>"},{"location":"xlockreservation/#syntax","title":"Syntax","text":"<pre><code>    -XlockReservation\n</code></pre>"},{"location":"xlockword/","title":"-Xlockword","text":""},{"location":"xlockword/#-xlockword","title":"-Xlockword","text":"<p>Test whether performance optimizations are negatively impacting an application.</p>"},{"location":"xlockword/#syntax","title":"Syntax","text":"<pre><code>    -Xlockword:&lt;parameters&gt;\n</code></pre>"},{"location":"xlockword/#parameters","title":"Parameters","text":""},{"location":"xlockword/#mode","title":"<code>mode</code>","text":"<pre><code>    -Xlockword:mode=all\n    -Xlockword:mode=default\n</code></pre> <p>Locking optimizations typically reduce memory usage and improve performance. However, there might be some situations where a smaller heap size is achieved for an application, but overall application performance decreases.</p> <p>For example, if your application synchronizes on objects that are not typically synchronized on, such as <code>Java.lang.String</code>, run the following test: Use the following command-line option to revert to behavior that is closer to earlier versions and monitor application performance:</p> <pre><code>-Xlockword:mode=all\n</code></pre> <p>If performance does not improve, remove the previous command-line options or use the following command-line option to reestablish the new behavior:</p> <pre><code>-Xlockword:mode=default\n</code></pre>"},{"location":"xlockword/#nolockword","title":"<code>nolockword</code>","text":"<pre><code>    -Xlockword:nolockword=&lt;class_name&gt;\n</code></pre> <p>Removes the lockword from object instances of the class <code>&lt;class_name&gt;</code>, reducing the space required for these objects. However, this action might have an adverse effect on synchronization for those objects.</p> <p>You should only use this option for troubleshooting.</p>"},{"location":"xlockword/#what","title":"<code>what</code>","text":"<pre><code>    -Xlockword:what\n</code></pre> Shows the current lockword configuration."},{"location":"xlog/","title":"-Xlog","text":""},{"location":"xlog/#-xlog","title":"-Xlog","text":"<p>This option is supported for better compatibility with the reference implementation. However, only forms of <code>-Xlog</code> that enable garbage collection (GC) logging are recognized. Note that the behavior of this option changed in Eclipse OpenJ9\u2122 0.24.0.</p>"},{"location":"xlog/#syntax","title":"Syntax","text":"<pre><code>    -Xlog[:&lt;parameters&gt;]\n</code></pre> <p>Note: In Eclipse OpenJ9 version 0.24.0, the <code>-Xsyslog</code> option replaced the existing OpenJ9 <code>-Xlog</code> option for message logging to avoid conflicts with the reference implementation. For backward compatibility, you can control the behavior of the <code>-Xlog</code> option with the <code>-XX:[+|-]LegacyXlogOption</code> option.</p>"},{"location":"xlog/#explanation","title":"Explanation","text":"<p>Use of the <code>-Xlog</code> option is supported for GC logging only. The following table describes the behavior of the option depending on what you specify on the command line.</p> <code>-Xlog</code> option type Behavior An option that returns GC data. For example <code>-Xlog:gc</code> An equivalent OpenJ9 GC logging option is enabled. See the next table for more details. An option that, in the reference implementation, returns GC data and also other data. For example: <code>-Xlog</code>, <code>-Xlog:all</code>, <code>-Xlog:gc+&lt;other_tag&gt;</code>, or  <code>-Xlog:gc:stdout</code> An equivalent OpenJ9 GC logging option is enabled as before but because non-GC data is not supported, the following error message is also produced:  <code>JVMJ9VM007W Command-line option unrecognised: &lt;option&gt;</code> An option that, in the reference implementation, returns only non-GC data Non-GC data is not supported, so the following error message is produced:  <code>JVMJ9VM007W Command-line option unrecognised: &lt;option&gt;</code> <p>The following table shows some examples of the mapping between <code>-Xlog</code> parameters and the equivalent OpenJ9 GC parameters:</p> <code>-Xlog</code> parameter OpenJ9 GC equivalent <code>-Xlog:gc</code> <code>-Xlog:gc:stderr</code> <code>-verbose:gc</code> <code>-Xlog:gc:&lt;filename&gt;</code> <code>-Xlog:gc:file=&lt;filename&gt;</code> <code>-Xverbosegclog:&lt;updated_filename&gt;</code> <p>In the table, the value of <code>&lt;filename&gt;</code> can contain the following tokens, which are processed and passed to the <code>-Xverbosegclog</code> option as <code>&lt;updated_filename&gt;</code>:</p> <ul> <li><code>%p</code> is replaced with the process ID (equivalent to dump agent token <code>%pid</code>)</li> <li><code>%t</code> is replaced with the dump agent tokens <code>%Y-%m-%d_%H-%M-%S</code>.</li> </ul>"},{"location":"xlog/#see-also","title":"See also","text":"<ul> <li><code>-Xsyslog</code></li> <li><code>-Xverbosegclog</code></li> <li><code>-XX:[+|-]LegacyXlogOption</code></li> </ul>"},{"location":"xlp/","title":"-Xlp","text":""},{"location":"xlp/#-xlp","title":"-Xlp","text":"<p>Requests the Eclipse OpenJ9\u2122 VM to allocate the Java\u2122 object heap and JIT code cache memory with large pages.</p> <p> Note: This option is deprecated in all versions later than Java 8. Use the <code>-Xlp:codecache</code> and <code>-Xlp:objectheap</code> options instead.</p> <p> Restriction: This option does not work on macOS\u00ae.</p> <p>If you use the <code>-Xgc:preferredHeapBase</code> option with <code>-Xlp</code>, the preferredHeapBase address must be a multiple of the large page size. If you specify an inaccurate heap base address, the heap is allocated with the default page size.</p> <p>To find out the large page sizes available and the current setting, use the <code>-verbose:sizes</code> option. Note that the current settings are the requested sizes and not the sizes obtained. For object heap size information, check the <code>-verbose:gc</code> output.</p>"},{"location":"xlp/#syntax","title":"Syntax","text":"<pre><code>    -Xlp[&lt;size&gt;]\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xlp/#explanation","title":"Explanation","text":""},{"location":"xlp/#aix","title":"AIX\u00ae","text":"<p>If <code>&lt;size&gt;</code> is specified, the VM attempts to allocate the JIT code cache memory by using pages of that size. Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 32-bit VM.</p> <p>If a size is not specified, this option requests the VM to allocate the Java object heap (the heap from which Java objects are allocated) with large (16 MB) pages.</p> <p>If large pages are not available, the Java object heap is allocated with the next smaller page size that is supported by the system. AIX requires special configuration to enable large pages.</p> <p>The VM supports the use of large pages only to back the Java object heap shared memory segments. The VM uses <code>shmget()</code> with the SHM_LGPG and SHM_PIN flags to allocate large pages. The <code>-Xlp</code> option replaces the environment variable <code>IBM_JAVA_LARGE_PAGE_SIZE</code>, which is now ignored if set.</p> <p>For more information about configuring AIX support for large pages, see Large pages in the AIX product documentation.</p>"},{"location":"xlp/#linux","title":"Linux\u00ae","text":"<p>If <code>&lt;size&gt;</code> is specified, the VM attempts to allocate the JIT code cache memory by using pages of that size. Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 32-bit VM.</p> <p>If large pages are not available, the VM does not start and produces an error message. The VM uses <code>shmget()</code> to allocate large pages for the heap. Large pages are supported by systems that have Linux kernels v2.6 or higher.</p> <p> Note: Linux for IBM Z\u00ae supports only a large page size of 1 M.</p> <p>Depending on the architecture, 1 MB or 2 MB large pages, when available, are the default size for the object heap and the code cache. The options that control these sizes are <code>Xlp:codecache</code> and <code>-Xlp:objectheap</code>.</p>"},{"location":"xlp/#windows","title":"Windows\u2122","text":"<p>If <code>&lt;size&gt;</code> is specified, the VM attempts to allocate the JIT code cache memory by using pages of that size.</p> <p>Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 32-bit VM.</p>"},{"location":"xlp/#zos","title":"z/OS\u00ae","text":"<p>If <code>&lt;size&gt;</code> is specified but unsuccessful, or if executable pages of that size are not supported, 1 M pageable is attempted. If 1 M pageable is not available, the JIT code cache memory is allocated by using the default or smallest available executable page size.</p> <p>If <code>&lt;size&gt;</code> is not specified, the 1 M nonpageable size is used. If large pages are not supported by the hardware, or enabled in RACF\u00ae, the VM does not start and produces an error message.</p> <p>Allocating large pages by using <code>-Xlp</code> is supported only on the 64-bit VM, not the 31-bit VM. The <code>-Xlp[&lt;size&gt;]</code> option supports only a large page size of 2 G and 1 M (nonpageable).</p> <p>1 M pageable pages, when available, are the default size for the object heap and the code cache. The options that control these sizes are <code>Xlp:codecache</code> and <code>-Xlp:objectheap</code>.</p> <p>Specifying <code>-Xlp1M</code> uses a 1 M pageable size for the code cache, when available. Specifying <code>-Xlp2G</code> sets the object heap size, but generates a warning that 2 G nonpageable pages cannot be used for the code cache. Use the <code>-Xlp:objectheap:pagesize=2G,nonpageable</code> option to avoid the warning.</p>"},{"location":"xlp/#limitation-and-workaround","title":"Limitation and workaround","text":"<p>The VM ends if insufficient operating system resources are available to satisfy the request. However, an error message is not issued. There are a number of reasons why the VM cannot honor a large page request. For example, there might be insufficient large pages available on the system at the time of the request. To check whether the <code>-Xlp</code> request was honored, you can review the output from <code>-verbose:gc</code>. Look for the attributes <code>requestedPageSize</code> and <code>pageSize</code> in the <code>-verbose:gc</code> log file. The attribute <code>requestedPageSize</code> contains the value specified by <code>-Xlp</code>. The attribute <code>pageSize</code> is the actual page size used by the VM.</p>"},{"location":"xlp/#see-also","title":"See also","text":"<ul> <li>Configuring large page memory allocation.</li> </ul>"},{"location":"xlpcodecache/","title":"-Xlp:codecache","text":""},{"location":"xlpcodecache/#-xlpcodecache","title":"-Xlp:codecache","text":"<p>Requests the Eclipse OpenJ9\u2122 VM to allocate the JIT code cache by using large page sizes.</p> <p>If the requested large page size is not available, the VM starts, but the JIT code cache is allocated by using a platform-defined size. A warning is displayed when the requested page size is not available.</p> <p>To find out the large page sizes available and the current setting, use the <code>-verbose:sizes</code> option. Note that the current settings are the requested sizes and not the sizes obtained. For object heap size information, check the <code>-verbose:gc</code> output.</p>"},{"location":"xlpcodecache/#syntax","title":"Syntax","text":"<p>AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122:</p> <pre><code>    -Xlp:codecache:pagesize=&lt;size&gt;\n</code></pre> <p>z/OS\u00ae:</p> <pre><code>    -Xlp:codecache:pagesize=&lt;size&gt;,pageable\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xlpcodecache/#default-values","title":"Default values","text":""},{"location":"xlpcodecache/#aix","title":"AIX","text":"<p>The code cache page size is controlled by the <code>DATAPSIZE</code> setting of the <code>LDR_CNTRL</code> environment variable. The page size cannot be controlled by the <code>-Xlp:codecache:pagesize=&lt;size&gt;</code> option. Specifying any other page size results in a warning that the page size is not available. The <code>-verbose:sizes</code> output reflects the current operating system setting.</p> <p>For more information about the <code>LDR_CNTRL</code> environment variable, see Configuring large page memory allocation: AIX systems.</p>"},{"location":"xlpcodecache/#linux","title":"Linux","text":"<p>The default size for the code cache depends on the architecture:</p> <ul> <li>Linux on x86 and AMD64/EM64T systems: 2 MB large pages</li> <li>Linux on IBM Z\u00ae: 1 MB large pages</li> <li>Linux on Power Systems\u2122: The code cache page size cannot be controlled by the <code>-Xlp:codecache:pagesize=&lt;size&gt;</code> option. Specifying any other page size results in a warning that the page size is not available. The <code>-verbose:sizes</code> output reflects the current operating system setting.</li> <li>On other architectures, the VM uses the default operating system page size.</li> </ul>"},{"location":"xlpcodecache/#macos","title":"macOS","text":"The default size for the code cache is 4 KB large pages."},{"location":"xlpcodecache/#zos","title":"z/OS","text":"<p>1 MB pageable pages, when available, are the default size for the code cache.</p> <p>The <code>-Xlp:codecache:pagesize=&lt;size&gt;,pageable</code> option supports only a large page size of 1 MB pageable large pages. The use of 1 MB pageable large pages for the JIT code cache can improve the runtime performance of some Java\u2122 applications. A page size of 4 KB can also be used.</p>"},{"location":"xlpcodecache/#see-also","title":"See also","text":"<ul> <li>Configuring large page memory allocation.</li> </ul>"},{"location":"xlpobjectheap/","title":"-Xlp:objectheap","text":""},{"location":"xlpobjectheap/#-xlpobjectheap","title":"-Xlp:objectheap","text":"<p>Requests the Eclipse OpenJ9\u2122 VM to allocate the Java\u2122 object heap by using large page sizes.</p> <p>To find out the large page sizes available and the current setting, use the <code>-verbose:sizes</code> option. Note that the current settings are the requested sizes and not the sizes obtained. For object heap size information, check the <code>-verbose:gc</code> output.</p>"},{"location":"xlpobjectheap/#syntax","title":"Syntax","text":"<p>AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122:</p> <pre><code>    -Xlp:objectheap:pagesize=&lt;size&gt;[,strict|warn]\n</code></pre> <p>z/OS\u00ae:</p> <pre><code>    -Xlp:objectheap:pagesize=&lt;size&gt;[,strict|warn][,pageable|nonpageable]\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xlpobjectheap/#parameters","title":"Parameters","text":""},{"location":"xlpobjectheap/#pagesize","title":"<code>pagesize</code>","text":"<pre><code>    -Xlp:objectheap:pagesize=&lt;size&gt;\n</code></pre> <p>The large page size that you require.</p> <p>If the operating system does not have sufficient resources to satisfy the request, the page size you requested might not be available when the VM starts up. By default, the VM starts and the Java object heap is allocated by using a different platform-defined page size. Alternatively, you can use the <code>strict</code> or <code>warn</code> suboptions to customize behavior.</p>"},{"location":"xlpobjectheap/#default-page-sizes","title":"Default page sizes","text":"<p>On Linux systems, the default size for the object heap depends on the architecture:</p> <ul> <li>Linux on x86 and AMD64/EM64T systems: 2 MB large pages</li> <li>Linux on IBM Z\u00ae: 1 MB large pages</li> <li>On other architectures, the VM uses the default operating system page size.</li> </ul> <p>On macOS, the default page size is 4 KB.</p> <p>On z/OS systems, the default page size is 1 MB pageable large pages. For more information, see <code>pageable</code>|<code>nonpageable</code>.</p>"},{"location":"xlpobjectheap/#strict-warn","title":"<code>strict</code> | <code>warn</code>","text":"<pre><code>    -Xlp:objectheap:strict\n    -Xlp:objectheap:warn\n</code></pre> <ul> <li><code>strict</code> causes an error message to be generated if large pages are requested but cannot be obtained. This option causes the VM to end.</li> <li><code>warn</code> causes a warning message to be generated if large pages are requested but cannot be obtained. This option allows the VM to continue.</li> </ul> <p> Note: If both <code>strict</code> and <code>warn</code> are specified, <code>strict</code> takes precedence.</p>"},{"location":"xlpobjectheap/#pageablenonpageable","title":"<code>pageable</code>|<code>nonpageable</code>","text":"<pre><code>    -Xlp:objectheap:pageable\n    -Xlp:objectheap:nonpageable\n</code></pre> <p>On z/OS systems, defines the type of memory to allocate for the Java object heap.</p> <p>1 MB pageable large pages, when available, are the default size for the object heap.  </p> <p>64-bit VMs support large page sizes of 1 MB nonpageable and 2 GB nonpageable with the following requirements:</p> <ul> <li>2 GB nonpageable sizes are supported only on IBM zEnterprise EC12 processors or later.</li> <li>A system programmer must configure z/OS for nonpageable large pages.</li> <li>Users who require large pages must be authorized to the IARRSM.LRGPAGES resource in the RACF FACILITY class with read authority.</li> </ul> <p>31-bit VMs support a large page size of only 1 MB pageable.</p> <p>A page size of 4 KB can also be used.</p>"},{"location":"xlpobjectheap/#examples","title":"Examples","text":"<ol> <li>z/OS: To allocate 1 GB of real memory by using 1 MB nonpageable pages when the VM starts, set the following options:</li> </ol> <pre><code>-Xmx1023m -Xms512m -Xlp:objectheap:pagesize=1M,nonpageable\n</code></pre> <ol> <li>z/OS: To allocate 1 GB of real memory by using 2 GB nonpageable pages, set the following options:</li> </ol> <pre><code>-Xmx1023m -Xms512m -Xlp:objectheap:pagesize=2G,nonpageable\n</code></pre> <p>In this example the heap is allocated on a 2 GB large page. Even though the object heap is only 1 GB, 2 GB of memory are consumed and the large page is never paged out while the VM is running.</p>"},{"location":"xlpobjectheap/#see-also","title":"See also","text":"<ul> <li>Configuring large page memory allocation.</li> </ul>"},{"location":"xmca/","title":"-Xmco","text":""},{"location":"xmca/#-xmca-xmco","title":"-Xmca / -Xmco","text":"<p>Sets the expansion step for the memory allocated to store the RAM (<code>-Xmca</code>) and ROM (<code>-Xmco</code>) portions of loaded classes.</p> <p>Each time more memory is required to store classes in RAM or ROM, the allocated memory is increased by the amount set.</p> <p>If the expansion step size you choose is too large, <code>OutOfMemoryError</code> is reported. The exact value of a \"too large\" expansion step size varies according to the platform and the specific machine configuration.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the value that is being used by the VM.</p>"},{"location":"xmca/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmca&lt;size&gt;</code> Set expansion step for RAM 32 KB <code>-Xmco&lt;size&gt;</code> Set expansion step for ROM 128 KB <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>This option cannot be used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</p>"},{"location":"xmca/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> </ul>"},{"location":"xmcrs/","title":"-Xmcrs","text":""},{"location":"xmcrs/#-xmcrs","title":"-Xmcrs","text":"<p>Sets an initial size for an area in memory that is reserved for any native classes, monitors, and threads that are used by compressed references within the lowest 4 GB memory area.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the value that is being used by the VM.</p> <p> Notes:</p> <ul> <li>Native memory <code>OutOfMemoryError</code> exceptions might occur when using compressed references if the lowest 4 GB of address space becomes full, particularly when loading classes, starting threads, or using monitors. </li> <li>If you are not using compressed references and this option is set, the option is ignored and the output of <code>-verbose:sizes</code> shows <code>-Xmcrs0</code>.</li> </ul>"},{"location":"xmcrs/#syntax","title":"Syntax","text":"<pre><code>    -Xmcrs&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xmine/","title":"-Xmine","text":""},{"location":"xmine/#-xmine-xmaxe","title":"-Xmine / -Xmaxe","text":"<p>Set the minimum and maximum amounts by which the garbage collector expands the heap.</p>"},{"location":"xmine/#syntax","title":"Syntax","text":"Setting Default <code>-Xmine&lt;size&gt;</code> 1 MB <code>-Xmaxe&lt;size&gt;</code> 0 (unlimited expansion) <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xmine/#explanation","title":"Explanation","text":"<p>Typically, the garbage collector expands the heap by the amount required to restore the free space to 30% (or the amount specified by <code>-Xminf</code>).</p> <p>If heap expansion is required:</p> <ul> <li><code>-Xmine</code> forces the expansion to be at least the specified value. For example, <code>-Xmine10M</code> sets the expansion size to a minimum of 10 MB.  </li> <li><code>-Xmaxe</code> limits the expansion to the specified value. For example <code>-Xmaxe50M</code> prevents expansion by more than 50 MB. (<code>-Xmaxe0</code> allows unlimited expansion.)</li> </ul> <p>For the <code>gencon</code> GC policy, the values apply only to the tenure part of the heap. For the <code>balanced</code>, <code>optthruput</code>, and <code>optavgpause</code> GC policies, these values apply to the whole heap. This option cannot be used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</p>"},{"location":"xmine/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> </ul>"},{"location":"xminf/","title":"-Xminf","text":""},{"location":"xminf/#-xminf-xmaxf","title":"<code>-Xminf</code> / <code>-Xmaxf</code>","text":"<p>Specifies the minimum and maximum proportion of the heap that must remain free after a global garbage collection (GC) cycle.</p> <p>If the free space is above or below these limits, the Eclipse OpenJ9\u2122 VM attempts to adjust the heap size so that: <code>-Xminf</code> \u2264 free space \u2264 <code>-Xmaxf</code>.</p>"},{"location":"xminf/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xminf&lt;value&gt;</code> Set minimum free space 0.3 <code>-Xmaxf&lt;value&gt;</code> Set maximum free space 0.6 <p>The value range is 0.0 - 1.0.</p> <ul> <li>For the <code>balanced</code> GC policy, these values apply only to the non-eden space part of the heap. The non-eden heap resizing decision is made by observing both <code>-Xmint</code>/<code>-Xmaxt</code> and <code>-Xminf</code>/<code>-Xmaxf</code>. Free memory in eden space is not considered for <code>-Xminf</code>/<code>-Xmaxf</code> purposes.</li> <li>For the <code>gencon</code> GC policy, the values apply only to the tenure part of the heap and only at global GC points.</li> <li>For the <code>optthruput</code> and <code>optavgpause</code> GC policies, these values apply to the whole heap at every GC point.</li> <li>This option cannot be used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</li> </ul>"},{"location":"xminf/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> <li>Garbage collection policies</li> </ul>"},{"location":"xmint/","title":"-Xmint","text":""},{"location":"xmint/#-xmint-xmaxt","title":"-Xmint / -Xmaxt","text":"<p>Sets the minimum and maximum proportion of time to spend in the garbage collection (GC) process as a percentage of the overall running time that included the last three GC runs. Therefore, the time spent in the GC process includes time spent in global mark phase and global GC operations but excludes partial garbage collection pauses because the latter apply only to the eden space.</p> <ul> <li>If the percentage of time drops to less than the minimum, the Eclipse OpenJ9\u2122 VM tries to shrink the heap.</li> <li>If the percentage of time exceeds the maximum, the VM tries to expand the heap.</li> </ul> <p> Restrictions:</p> <ul> <li>This option applies only to GC policies that include stop-the-world (STW) operations, such as <code>-Xgcpolicy:optthruput</code>.  </li> </ul>"},{"location":"xmint/#syntax","title":"Syntax","text":"Setting Effect Default for balanced policy Default for other policies <code>-Xmint&lt;value&gt;</code> Set minimum time in GC 0.02 0.05 <code>-Xmaxt&lt;value&gt;</code> Set maximum time in GC 0.05 0.13 <ul> <li>For the <code>balanced</code> GC policy, the values apply only to the non-eden space part of the heap. The non-eden heap resizing decision is made by observing both <code>-Xmint</code>/<code>-Xmaxt</code> and <code>-Xminf</code>/<code>-Xmaxf</code>.</li> <li>For the <code>gencon</code> GC policy, the values apply only to the tenure part of the heap.</li> <li>For the <code>optthruput</code>, and <code>optavgpause</code> GC policies, these values apply to the whole heap.</li> <li>This option cannot be used with the <code>metronome</code> GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</li> </ul>"},{"location":"xmint/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> <li>Garbage collection policies</li> </ul>"},{"location":"xmn/","title":"-Xmnx","text":""},{"location":"xmn/#-xmn-xmns-xmnx","title":"-Xmn / -Xmns / -Xmnx","text":"<p>Sets the initial and maximum size of the nursery area when using the <code>gencon</code> garbage collection (GC) policy (<code>-Xgcpolicy:gencon</code>), and sets the size of eden when using the <code>balanced</code> garbage collection (GC) policy (<code>-Xgcpolicy:balanced</code>). These options are ignored if they are used with any other GC policy.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the value that is being used by the VM.</p>"},{"location":"xmn/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmn&lt;size&gt;</code> Equivalent to setting both <code>-Xmns</code> and <code>-Xmnx</code> Not set <code>-Xmns&lt;size&gt;</code> Set initial size 25% of <code>-Xms</code> when using <code>gencon</code> and <code>balanced</code> policies <code>-Xmnx&lt;size&gt;</code> Set maximum size 25% of <code>-Xmx</code> when using <code>gencon</code>, and 75% of <code>-Xmx</code> when using <code>balanced</code> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p> Restriction: If you try to set <code>-Xmn</code> with either <code>-Xmns</code> or <code>-Xmnx</code>, the VM does not start, returning an error.</p> <p> Notes:</p> <ul> <li>When using the <code>balanced</code> GC policy without specifying <code>-Xmn</code> or <code>-Xmns</code>, the GC may decide to shrink eden size below its initial size (25% of <code>-Xms</code>) if it determines that doing so will improve GC performance.</li> <li>When using the <code>balanced</code> GC policy, specifying <code>-Xmn</code>/<code>-Xmns</code>/<code>-Xmnx</code> may affect <code>balanced</code> GC's ability to satisfy <code>-Xgc:targetPausetime</code></li> <li>Specifying <code>-Xmn</code>/<code>-Xmns</code>/<code>-Xmnx</code> may affect both <code>gencon</code> and <code>balanced</code> GC's ability to satisfy <code>-Xgc:dnssexpectedtimeratiomaximum</code> and <code>-Xgc:dnssexpectedtimeratiominimum</code></li> </ul> <p>To set the size of the tenure area of the heap when using <code>gencon</code> GC policy, see <code>-Xmo/-Xmos/-Xmox</code>.</p>"},{"location":"xmn/#see-also","title":"See also","text":"<ul> <li><code>gencon</code> GC policy (default)</li> <li><code>balanced</code> GC policy</li> <li><code>-Xmo/-Xmos/-Xmox</code></li> <li><code>-Xms</code>/<code>-Xmx</code></li> </ul>"},{"location":"xmo/","title":"-Xmox","text":""},{"location":"xmo/#-xmo-xmos-xmox","title":"-Xmo / -Xmos / -Xmox","text":"<p>Sets the size of the tenure area of the heap for the <code>gencon</code> garbage collection (GC) policy.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p>"},{"location":"xmo/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmo&lt;size&gt;</code> Equivalent to setting both <code>-Xmos</code> and <code>-Xmox</code> not set <code>-Xmos&lt;size&gt;</code> Set initial size of the tenure area of the heap 75% of <code>-Xms</code> <code>-Xmox&lt;size&gt;</code> Set maximum size of the tenure area of the heap Same as <code>-Xmx</code> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p> Restriction: If you try to set <code>-Xmo</code> with either <code>-Xmos</code> or <code>-Xmox</code>, the VM does not start, returning an error.</p> <p>To set the size of the nursery area of the heap, see <code>-Xmn/-Xmns/-Xmnx</code>.</p>"},{"location":"xmo/#see-also","title":"See also","text":"<ul> <li><code>gencon</code> policy (default)</li> <li><code>-Xmn/-Xmns/-Xmnx</code></li> <li><code>-Xms</code>/<code>-Xmx</code></li> </ul>"},{"location":"xmoi/","title":"-Xmoi","text":""},{"location":"xmoi/#-xmoi","title":"-Xmoi","text":"<p>Sets the heap expansion allocation increment.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p>"},{"location":"xmoi/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmoi&lt;size&gt;</code> Sets the heap expansion allocation increment See Notes <p> Notes:</p> <ul> <li>By default, the increment size (<code>-Xmoi</code>) is calculated on the expansion size, set by <code>-Xmine</code> and <code>-Xminf</code>.  If you set <code>-Xmoi</code> to zero, no expansion is allowed.</li> <li>For the <code>gencon</code> GC policy, the expansion increment applies to the tenure area of the heap.  </li> </ul> <p>This option is not supported for the <code>metronome</code> GC policy, because the heap is always fully expanded.</p> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xmoi/#see-also","title":"See also","text":"<ul> <li>Heap expansion and contraction</li> </ul>"},{"location":"xmr/","title":"-Xmrx","text":""},{"location":"xmr/#-xmr-xmrx","title":"-Xmr / \u00a0 -Xmrx","text":"<p>Sets the initial and maximum size of the the garbage collection (GC) remembered set in the <code>gencon</code> GC policy. The remembered set is a list of objects in the tenure area of the heap that have references to objects in the new area.</p>"},{"location":"xmr/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xmr&lt;size&gt;</code> Set initial size 16 K <code>-Xmrx&lt;size&gt;</code> Set maximium size <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>This option applies only to the <code>gencon</code> GC policy.</p>"},{"location":"xms/","title":"-Xmx","text":""},{"location":"xms/#-xms-xmx","title":"-Xms / -Xmx","text":"<p>These Oracle\u00ae HotSpot\u2122 options set the initial/minimum Java\u2122 heap size, and the maximum heap size respectively. These options are recognized by the Eclipse OpenJ9\u2122 VM.</p> <p> Notes:</p> <ul> <li>If you set <code>-Xms</code> &gt; <code>-Xmx</code>, the VM fails with the message <code>-Xms too large for -Xmx</code>.</li> <li>If you exceed the limit set by the <code>-Xmx</code> option, the VM generates an <code>OutofMemoryError</code>.</li> <li>If you set a value for <code>-Xms</code>, the <code>-XX:InitialRAMPercentage</code> option is ignored.</li> <li>If you set a value for <code>-Xmx</code>, the <code>-XX:MaxRAMPercentage</code> option is ignored.</li> </ul> <p>For the <code>gencon</code> GC policy, you can also use the <code>-Xmo</code> option:</p> <ul> <li>If the scavenger is enabled, <code>-Xms</code> \u2265 <code>-Xmn</code> + <code>-Xmo</code> </li> <li>If the scavenger is disabled, <code>-Xms</code> \u2265 <code>-Xmo</code> </li> </ul>"},{"location":"xms/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xms&lt;size&gt;</code> Set initial heap size 8 MB <code>-Xmx&lt;size&gt;</code> Set maximum heap size 25% of available memory (25 GB maximum) <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter. See Default settings for the OpenJ9 VM for more about default values.</p> <p>The <code>-Xmx</code> option can be used with all OpenJ9 GC policies. However, the <code>-Xms</code> option can be used with all GC policies except for the <code>metronome</code> GC policy because the heap is always fully expanded.</p>"},{"location":"xms/#examples","title":"Examples","text":"<code>-Xms2m -Xmx64m</code> Heap starts at 2 MB and grows to a maximum of 64 MB. <code>-Xms100m -Xmx100m</code> Heap starts at 100 MB and never grows. <code>-Xms50m</code> Heap starts at 50 MB and grows to the default maximum. <code>-Xmx256m</code> Heap starts at default initial value and grows to a maximum of 256 MB."},{"location":"xms/#see-also","title":"See also","text":"<ul> <li>-Xsoftmx (Set \"soft\" maximum Java heap size)</li> </ul>"},{"location":"xmso/","title":"-Xmso","text":""},{"location":"xmso/#-xmso","title":"-Xmso","text":"<p>Sets the native stack size for operating system threads.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p> <p>When a native method makes a call into the VM, the VM calculates whether the memory required for the call will exceed the <code>-Xmso</code> value. If so, a <code>java/lang/StackOverflowError</code> error is thrown.</p> <p> Note: Java methods and native methods run on two different stacks and the VM handles switching between them for JNI calls. Each stack is sized using separate options; this option applies to the native stack only. For the Java stack option, see the link in the See also section.</p>"},{"location":"xmso/#syntax","title":"Syntax","text":"<pre><code>    -Xmso&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.  </p>"},{"location":"xmso/#default-setting","title":"Default setting","text":"<p>Default values vary by platform. See Default settings for the Eclipse OpenJ9\u2122 VM.</p> <p> Note: On 64-bit z/OS, the default size is the minimum that can be allocated by the operating system. So if you set a value that is smaller, that value is ignored by the VM.</p>"},{"location":"xmso/#see-also","title":"See also","text":"<ul> <li><code>-Xiss/-Xss/-Xssi</code> (stack size and increment for Java\u2122 threads)</li> </ul>"},{"location":"xnumanone/","title":"-Xnuma:none","text":""},{"location":"xnumanone/#-xnumanone","title":"-Xnuma:none","text":"<p>(AIX\u00ae, Linux\u00ae, and Windows\u2122 only)</p> <p>Use this option to turn off non-uniform memory architecture (NUMA) awareness when using the balanced garbage collection policy.</p> <p>For workloads that do most of their work in one thread, or workloads that maintain a full heap, turning off NUMA awareness can improve performance.</p>"},{"location":"xnumanone/#syntax","title":"Syntax","text":"<pre><code>    -Xnuma:none\n</code></pre>"},{"location":"xnumanone/#default-behavior","title":"Default behavior","text":"<p>NUMA awareness is enabled by default.</p>"},{"location":"xoptionsfile/","title":"-Xoptionsfile","text":""},{"location":"xoptionsfile/#-xoptionsfile","title":"-Xoptionsfile","text":"<p>Specifies a file that contains VM options and definitions.</p> <p>The contents of the options file are recorded in the <code>ENVINFO</code> section of a Java\u2122 dump.</p>"},{"location":"xoptionsfile/#syntax","title":"Syntax","text":"<pre><code>    -Xoptionsfile=&lt;file_name&gt;\n</code></pre> where <code>&lt;file_name&gt;</code> specifies a file that contains options that are processed as if they had been entered directly as command-line options."},{"location":"xoptionsfile/#explanation","title":"Explanation","text":"<p>At startup, the VM automatically adds <code>-Xoptionsfile=&lt;path&gt;/options.default</code> at the beginning of the command line, where <code>&lt;path&gt;</code> is the path to the VM directory.</p> <p> <code>&lt;path&gt;</code> is the VM directory, as shown in Directory conventions.  <code>&lt;path&gt;</code> is the <code>&lt;java_home&gt;/lib</code> directory, where <code>&lt;java_home&gt;</code> is the directory for your runtime environment. </p> <p>The file <code>options.default</code> can be updated with any options that you want to specify at run time.</p> <p>The options file does not support these options:</p> <ul> <li><code>-assert</code></li> <li><code>-fullversion</code></li> <li><code>-help</code></li> <li><code>-showversion</code></li> <li><code>-version</code></li> <li><code>-Xcompressedrefs</code></li> <li><code>-Xcheck:memory</code></li> <li><code>-Xoptionsfile</code></li> <li><code>-XshowSettings</code></li> </ul> <p>Although you cannot use <code>-Xoptionsfile</code> recursively within an options file, you can use <code>-Xoptionsfile</code> multiple times on the same command line to load more than one options files.</p> <p>Some options use quoted strings as parameters. Do not split quoted strings over multiple lines using the forward slash line continuation character (\\). The Yen symbol (\u00a5) is not supported as a line continuation character. For example, the following example is not valid in an options file:</p> <pre><code>-Xevents=vmstop,exec=\"cmd /c \\\necho %pid has finished.\"\n</code></pre> <p>The following example is valid in an options file:</p> <pre><code>-Xevents=vmstop, \\\nexec=\"cmd /c echo %pid has finished.\"\n</code></pre>"},{"location":"xoptionsfile/#example","title":"Example","text":"<p>Here is an example of an options file:</p> <pre><code>#My options file\n-X&lt;option1&gt;\n-X&lt;option2&gt;=\\\n&lt;value1&gt;,\\\n&lt;value2&gt;\n-D&lt;sysprop1&gt;=&lt;value1&gt;\n</code></pre>"},{"location":"xoptionsfile/#see-also","title":"See also","text":"<ul> <li>Specifying command-line options</li> <li>Javadump: TITLE, GPINFO, and ENVINFO sections</li> </ul>"},{"location":"xquickstart/","title":"-Xquickstart","text":""},{"location":"xquickstart/#-xquickstart","title":"-Xquickstart","text":"<p>This option causes the JIT compiler to run with a subset of optimizations, which can improve the performance of short-running applications.</p> <p> Note: For compatibility with other Java\u2122 virtual machines, you can also specify the <code>-client</code> option, which results in identical behavior to <code>-Xquickstart</code>.</p>"},{"location":"xquickstart/#syntax","title":"Syntax","text":"<pre><code>    -Xquickstart\n</code></pre>"},{"location":"xquickstart/#default-behavior","title":"Default behavior","text":"<p>By default, <code>-Xquickstart</code> is disabled.</p>"},{"location":"xquickstart/#explanation","title":"Explanation","text":"<p>The JIT compiler is tuned for long-running applications typically used on a server. When you specify this option, the compiler uses a subset of optimizations, which results in faster compilation times that improve startup time. However, longer running applications might run more slowly, especially applications that contain hot methods and other methods using a large amount of processing resource.</p> <p>When the AOT compiler is active (both shared classes and AOT compilation enabled), <code>-Xquickstart</code> causes all methods to be AOT compiled. The AOT compilation improves the startup time of subsequent runs, but might reduce performance for longer running applications, especially those that contain hot methods.</p> <p> Note: The implementation of <code>-Xquickstart</code> is subject to change in future releases.</p>"},{"location":"xrs/","title":"-Xrs","text":""},{"location":"xrs/#-xrs","title":"-Xrs","text":"<p>Prevents the Eclipse OpenJ9\u2122 runtime environment from handling any internally or externally generated signals such as <code>SIGSEGV</code> and <code>SIGABRT</code>. Any signals that are raised are handled by the default operating system handlers, which you might want if you are using a debugger such as GDB or WinDbg to diagnose problems in JNI code.</p> <p>Disabling signal handling in the OpenJ9 VM reduces performance by approximately 2-4%, depending on the application.</p> <p> Note: Setting this option prevents dumps being generated by the OpenJ9 VM for signals such as <code>SIGSEGV</code> and <code>SIGABRT</code>, because the VM is no longer intercepting these signals. Do not use the <code>-Xrs</code> option with the following options:</p> <ul> <li><code>-XX:+HandleSIGABRT</code></li> <li><code>-XX:+HandleSIGUSR2</code></li> </ul> <p>An error is thrown if either of the options is enabled together with the <code>-Xrs</code> option. To resolve this error, one of the options should be disabled.</p>"},{"location":"xrs/#syntax","title":"Syntax","text":"<pre><code>    -Xrs\n    -Xrs:sync\n</code></pre>"},{"location":"xrs/#parameters","title":"Parameters","text":"<p>If you specify the <code>sync</code> parameter:</p> <ul> <li>On AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae systems: Disables signal handling in the VM for <code>SIGSEGV</code>, <code>SIGFPE</code>, <code>SIGBUS</code>, <code>SIGILL</code>, <code>SIGTRAP</code>, and <code>SIGABRT</code> signals. However, the VM still handles the <code>SIGQUIT</code> and <code>SIGTERM</code> signals, among others.</li> <li>On Windows\u2122 systems: Hardware exceptions are not handled by the OpenJ9 VM when this option is specified. However, the Windows CTRL_BREAK_EVENT signal, triggered by the Ctrl-Break key combination, is still handled by the VM.</li> </ul> <p>Linux and macOS systems always use the <code>SIGUSR1</code> signal.</p>"},{"location":"xrs/#see-also","title":"See also","text":"<ul> <li>Signal handling</li> </ul>"},{"location":"xrsonrestoresynconrestore/","title":"-Xrs:onRestore / -Xrs:syncOnRestore","text":""},{"location":"xrsonrestoresynconrestore/#-xrsonrestore-xrssynconrestore","title":"-Xrs:onRestore / -Xrs:syncOnRestore","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>The <code>-Xrs</code> option is an existing option for disabling signal handling in the VM. CRIU support adds new suboptions <code>onRestore</code> and <code>syncOnRestore</code> for disabling signal handling when you restore a VM.</p> <p>If the VM was started with signal handling enabled, then when you restore the VM, the signal handling is enabled by default. It is possible that there are frames with attached signal handlers already on the stack. These frames remain unchanged and their signal handlers remain active. Likewise, some global handlers might not be removed as well. The new options prevent the addition of new signal handlers and force recompilation of Java\u2122 methods that make use of the existing signal handlers.</p> <p> Restrictions: This option takes effect only when the <code>-XX:+EnableCRIUSupport</code> option is enabled. This option can be used only on restore.</p>"},{"location":"xrsonrestoresynconrestore/#parameters","title":"Parameters","text":""},{"location":"xrsonrestoresynconrestore/#onrestore","title":"<code>onRestore</code>","text":"<pre><code>    -Xrs:onRestore\n</code></pre> <p>The <code>-Xrs:onRestore</code> option is similar to the <code>-Xrs</code> option.</p>"},{"location":"xrsonrestoresynconrestore/#synconrestore","title":"<code>syncOnRestore</code>","text":"<pre><code>    -Xrs:syncOnRestore\n</code></pre> <p>The <code>-Xrs:syncOnRestore</code> option is similar to the <code>-Xrs:sync</code> option.</p> <p>Although there are similarities between the existing options and the new CRIU related options, there are behavioural differences that limits what can be disabled with the existing options at the restore time.</p>"},{"location":"xrsonrestoresynconrestore/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xsamplingexpirationtime/","title":"-XsamplingExpirationTime","text":""},{"location":"xsamplingexpirationtime/#-xsamplingexpirationtime","title":"-XsamplingExpirationTime","text":"<p>Disables JIT sampling after a specified amount of time. </p> <p>When the JIT sampling thread is disabled, no processor cycles are used by an idle Eclipse OpenJ9\u2122 VM.</p> <p>Use this option with care; after the sampling thread is disabled, you cannot reactivate it. However, because the profiling frequency is automatically reduced, you should not have to use this option. </p> <p>Allow the sampling thread to run for long enough to identify important optimizations.</p>"},{"location":"xsamplingexpirationtime/#syntax","title":"Syntax","text":"<pre><code>    -XsamplingExpirationTime&lt;time&gt;\n</code></pre> where <code>&lt;time&gt;</code> is specified in seconds."},{"location":"xsamplingexpirationtime/#explanation","title":"Explanation","text":"<p>The JIT sampling thread profiles the running Java\u2122 application to discover commonly used methods. The memory and processor usage of the sampling thread is negligible, and the frequency of profiling is automatically reduced when the OpenJ9 VM is idle, to once per second instead of once every 10ms, or once every 100 seconds if the idle state lasts more than 50 seconds.</p>"},{"location":"xscdmx/","title":"-Xscdmx","text":""},{"location":"xscdmx/#-xscdmx","title":"-Xscdmx","text":"<p>Use the <code>-Xscdmx</code> option to control the size of the class debug area when you create a shared classes cache.</p>"},{"location":"xscdmx/#syntax","title":"Syntax","text":"<pre><code>    -Xscdmx&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscdmx/#explanation","title":"Explanation","text":"<p>The <code>-Xscdmx</code> option works in a similar way to the <code>-Xscmx</code> option, which is used to control the overall size of the shared classes cache. The size of <code>-Xscdmx</code> must be smaller than the size of <code>-Xscmx</code>. By default, the size of the class debug area is a percentage of the free class data bytes in a newly created or empty cache.</p> <p>A class debug area is still created if you use the <code>-Xnolinenumbers</code> option with the <code>-Xscdmx</code> option on the command line.</p>"},{"location":"xscminaot/","title":"-Xscminaot","text":""},{"location":"xscminaot/#-xscminaot-xscmaxaot","title":"-Xscminaot / -Xscmaxaot","text":"<p>When you create a shared classes cache, you can use these options to set the minimum and maximum number of bytes in the class cache to reserve for AOT data.</p> <p>Setting <code>-Xscmaxaot</code> is useful if you want a certain amount of cache space guaranteed for non-AOT data.</p>"},{"location":"xscminaot/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xscminaot&lt;size&gt;</code> Set minimum size for AOT class cache 0 <code>-Xscmaxaot&lt;size&gt;</code> Set maximum size for AOT class cache The amount of free space in the cache <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscminaot/#-xscminaot","title":"<code>-Xscminaot</code>","text":"<p>If <code>-Xscminaot</code> is not specified, no space is reserved for AOT data. However, AOT data is still written to the cache until the cache is full or the <code>-Xscmaxaot</code> limit is reached. </p> <p>The value of <code>-Xscminaot</code> must not exceed the value of <code>-Xscmx</code> or <code>-Xscmaxaot</code> and should be considerably less than the total cache size, because AOT data can be created only for cached classes. If the value of <code>-Xscminaot</code> equals the value of <code>-Xscmx</code>, no class data or AOT data can be stored.</p> <ul> <li>You can also adjust the <code>-Xscminaot</code> value by using:<ul> <li><code>-Xshareclasses:adjustminaot=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMinAotBytes()</code> method in the <code>com.ibm.lang.management</code> API</li> </ul> </li> <li>You can also adjust the <code>-Xscmaxaot</code> value by using:<ul> <li><code>-Xshareclasses:adjustmaxaot=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMaxAotBytes()</code> method in the <code>com.ibm.lang.management</code> API.</li> </ul> </li> </ul>"},{"location":"xscminaot/#-xscmaxaot","title":"<code>-Xscmaxaot</code>","text":"<p>The value of this option must not be smaller than the value of <code>-Xscminaot</code> and must not be larger than the value of <code>-Xscmx</code>.</p> <p>When you run an application with the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the amount of AOT data that is not stored due to the current setting of the maximum AOT data space. You can also get this information by using the <code>MemoryMXBean.getSharedClassCacheMaxAotUnstoredBytes()</code> method in the <code>com.ibm.lang.management</code> API. You can increase the maximum AOT data space size accordingly if you want to add the unstored AOT data to the shared cache.</p>"},{"location":"xscminaot/#see-also","title":"See also","text":"<ul> <li>-Xshareclasses</li> </ul>"},{"location":"xscminjitdata/","title":"-Xscminjitdata","text":""},{"location":"xscminjitdata/#-xscminjitdata-xscmaxjitdata","title":"-Xscminjitdata / -Xscmaxjitdata","text":"<p>When you create a shared classes cache, you can use these options to set a minimum and maximum number of bytes in the class cache that can be used for JIT data.</p> <p>When you run an application with the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the amount of JIT data that is not stored due to the current setting of the the maximum JIT data space. You can also get this information by using the <code>MemoryMXBean.getSharedClassCacheMaxJitDataUnstoredBytes()</code> method in the <code>com.ibm.lang.management</code> API. </p> <p>You can increase the maximum JIT data space size accordingly if you want to add the unstored data to the shared cache. However, the VM that provided the information no longer has the opportunity to store the JIT data. Subsequent VMs can store JIT data in the shared cache.</p>"},{"location":"xscminjitdata/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xscminjitdata&lt;size&gt;</code> Set minimum size for JIT data 0 (See Default behavior) <code>-Xscmaxjitdata&lt;size&gt;</code> Set maximum size for JIT data The amount of free space in the cache <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscminjitdata/#default-behavior","title":"Default behavior","text":"<p>If <code>-Xscminjitdata</code> is not specified, no space is reserved for JIT data, although JIT data is still written to the cache until the cache is full or the <code>-Xscmaxjitdata</code> limit is reached. </p>"},{"location":"xscminjitdata/#explanation","title":"Explanation","text":""},{"location":"xscminjitdata/#-xscminjitdata","title":"<code>-Xscminjitdata</code>","text":"<p>The value of <code>-Xscminjitdata</code> must not exceed the value of <code>-Xscmx</code> or <code>-Xscmaxjitdata</code>. The value of <code>-Xscminjitdata</code> must always be considerably less than the total cache size, because JIT data can be created only for cached classes. If the value of <code>-Xscminjitdata</code> equals the value of <code>-Xscmx</code>, no class data or JIT data can be stored.</p> <ul> <li>You can also adjust the <code>-Xscminjitdata</code> value by using:<ul> <li><code>-Xshareclasses:adjustminjitdata=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMinJitDataBytes()</code> method in the <code>com.ibm.lang.management</code> API.</li> </ul> </li> </ul>"},{"location":"xscminjitdata/#-xscmaxjitdata","title":"<code>-Xscmaxjitdata</code>","text":"<p>Setting <code>-Xscmaxjitdata</code> is useful if you want a certain amount of cache space guaranteed for non-JIT data. If this option is not specified, the maximum limit for JIT data is the amount of free space in the cache. The value of this option must not be smaller than the value of <code>-Xscminjitdata</code>, and must not be larger than the value of <code>-Xscmx</code>.</p> <ul> <li>You can also adjust the <code>-Xscmaxjitdata</code> value by using:<ul> <li><code>-Xshareclasses:adjustmaxjitdata=&lt;size&gt;</code> option</li> <li><code>MemoryMXBean.setSharedClassCacheMinJitDataBytes()</code> method in the <code>com.ibm.lang.management</code> API.</li> </ul> </li> </ul>"},{"location":"xscminjitdata/#see-also","title":"See also","text":"<ul> <li><code>-Xscmx</code></li> </ul>"},{"location":"xscmx/","title":"-Xscmx","text":""},{"location":"xscmx/#-xscmx","title":"-Xscmx","text":"<p>For a new shared classes cache, specifies either:</p> <ul> <li>the actual size of the cache, if the <code>-XX:SharedCacheHardLimit</code> option is not present</li> <li>the soft maximum size of the cache, if used with the <code>-XX:SharedCacheHardLimit</code> option (See <code>-XX:SharedCacheHardLimit</code>)</li> </ul> <p>This option applies only if a cache is being created and no cache of the same name exists.</p> <p>When you run an application with the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the soft maximum size. You can also get this information by using the <code>MemoryMXBean.getSharedClassCacheSoftmxUnstoredBytes()</code> method in the <code>com.ibm.lang.management</code> API.</p> <p>You can increase the soft maximum size accordingly if you want to add the unstored data to the shared cache. However, the VM that provided the information no longer has the opportunity to store that data. Therefore, increasing the soft maximum size does not necessarily cause any more data to be stored in the shared cache by the current VM, but subsequent VMs can add data to the shared cache.</p>"},{"location":"xscmx/#syntax","title":"Syntax","text":"<pre><code>    -Xscmx&lt;size&gt;\n</code></pre> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p>"},{"location":"xscmx/#explanation","title":"Explanation","text":""},{"location":"xscmx/#setting-a-soft-maximum-size","title":"Setting a soft maximum size","text":"<p>If you specify the <code>-Xscmx</code> option with the -XX:SharedCacheHardLimit option, the <code>-Xscmx</code> option sets the soft maximum size of a new shared classes cache, and the <code>-XX:SharedCacheHardLimit</code> option sets the actual maximum size. The value of the <code>-Xscmx</code> option must therefore not exceed the value of <code>-XX:SharedCacheHardLimit</code>.</p> <p>When the soft maximum limit is reached, no more data can be added into the shared cache, unless there is reserved AOT or JIT data space. If such reserved space exists, AOT or JIT data can still be added into the reserved space. The reserved AOT and JIT data spaces are counted as used space within the soft maximum size, so the soft maximum size should not be less than the minimum reserved space for AOT and JIT data if you specify the -Xscminaot or -Xscminjitdata options.</p> <p>You can change the soft maximum size by using the <code>-Xshareclasses:adjustsoftmx=&lt;size&gt;</code> option or the <code>MemoryMXBean.setSharedClassCacheSoftmxBytes()</code> method in the <code>com.ibm.lang.management</code> API. By using this API, Java\u2122 applications can dynamically monitor and adjust the cache soft maximum size as required. This function can be useful in virtualized or cloud environments, for example, where the shared cache size might change dynamically to meet business needs.</p> <p>For example, you might create a 64 MB shared cache and set a smaller value, such as 16 MB, for the <code>-Xscmx</code> option, to limit the data stored in the cache:</p> <pre><code>-XX:SharedCacheHardLimit=64m -Xscmx16m\n</code></pre> <p>You can then use the <code>com.ibm.lang.management</code> API from within a Java application to increase the soft maximum value during run time, as load increases. This change allows the application to use more shared cache space than you specified initially.</p> <p>You can increase the soft maximum size if it is currently less than the actual cache size. If you attempt to reduce the soft maximum size to a value that is less than the number of bytes already used in the cache, the number of used bytes is set as the new soft maximum size.</p>"},{"location":"xscmx/#cache-size-limits","title":"Cache size limits","text":"<p>The theoretical cache size limit is 2 GB. The size of the cache that you can specify is limited by the following factors:</p> <ul> <li>AIX\u00ae, Linux\u00ae, and macOS\u00ae: The amount of physical memory and paging space available to the system.</li> <li>Windows\u00ae: The amount of available disk space and available virtual address space.</li> <li>z/OS\u00ae: The amount of swap space available to the system.</li> </ul> <p>Non-persistent caches are stored in shared memory and are removed when a system is rebooted. On systems other than Windows, non-persistent caches are allocated by using the System V IPC shared memory mechanism. To ensure that sufficient shared memory is available for class data sharing, see Setting shared memory values.</p> <p> Note: By default, a cache is persistent on all platforms, except z/OS.</p>"},{"location":"xscmx/#see-also","title":"See also","text":"<ul> <li><code>-Xscdmx</code> (control the size of the class debug area)</li> </ul>"},{"location":"xshareclasses/","title":"-Xshareclasses","text":""},{"location":"xshareclasses/#-xshareclasses","title":"-Xshareclasses","text":"<p>Use the <code>-Xshareclasses</code> option to enable, disable, or modify class sharing behavior. Class data sharing is enabled by default for bootstrap classes only (the equivalent of specifying <code>-Xshareclasses:bootClassesOnly,nonFatal,silent</code>), unless your application is running in a container.</p> <p>This option can take a number of parameters, some of which are cache utilities. Cache utilities carry out specific operations on a specified cache without starting the Java virtual machine (VM). Although you can combine multiple suboptions, which are separated by commas, the cache utilities are mutually exclusive.</p> <p>Some cache utilities can work with caches from previous Java\u2122 versions or caches that are created by VMs with different bit-widths. These caches are referred to as \"incompatible\" caches.</p> <p>See also the Class data sharing topic, which includes some best practices for using <code>-Xshareclasses</code>.</p>"},{"location":"xshareclasses/#syntax","title":"Syntax","text":"<pre><code>    -Xshareclasses:&lt;parameter&gt;\n</code></pre> <p>When you specify <code>-Xshareclasses</code> without any parameters and without specifying either the <code>-Xscmx</code> or <code>-XX:SharedCacheHardLimit</code> options, a shared classes cache is created with a default size, as follows:</p> <ul> <li>For 64-bit platforms, the default size is 300 MB, with a \"soft\" maximum limit for the initial size of the cache (<code>-Xscmx</code>) of 64 MB, with the following exceptions:<ul> <li>For a persistent cache, if the free disk space is less than 6 GB, the default size is set to 64 MB and an <code>-Xscmx</code> size is not set.</li> <li>For a non-persistent cache on Linux\u00ae or macOS\u00ae systems, the cache size is limited by the maximum amount of memory that can be reserved by a process (<code>SHMMAX</code>). If <code>SHMMAX</code> is less than 300 MB, the default shared cache size is set to equal <code>SHMMAX</code>. If <code>SHMMAX</code> is greater than 80 MB, <code>-Xscmx</code> is set to 64 MB. If <code>SHMMAX</code> is less than 80 MB an <code>-Xscmx</code> size is not set.</li> </ul> </li> <li>For other platforms, the default size is 16 MB.</li> </ul>"},{"location":"xshareclasses/#parameters","title":"Parameters","text":""},{"location":"xshareclasses/#adjustmaxaot-cache-utility","title":"<code>adjustmaxaot</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustmaxaot=&lt;size&gt;\n</code></pre> Adjusts the maximum shared classes cache space that is allowed for AOT data. When you use the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the <code>-Xscmaxaot</code> option."},{"location":"xshareclasses/#adjustminaot-cache-utility","title":"<code>adjustminaot</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustminaot=&lt;size&gt;\n</code></pre> Adjusts the minimum shared classes cache space that is reserved for AOT data. Use the <code>-Xscminaot</code> option to set the initial minimum size."},{"location":"xshareclasses/#adjustmaxjitdata-cache-utility","title":"<code>adjustmaxjitdata</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustmaxjitdata=&lt;size&gt;\n</code></pre> Adjusts the maximum shared classes cache space that is allowed for JIT data. When you use the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the <code>-Xscmaxjitdata</code> option."},{"location":"xshareclasses/#adjustminjitdata-cache-utility","title":"<code>adjustminjitdata</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustminjitdata=&lt;size&gt;\n</code></pre> Adjusts the minimum shared classes cache space that is reserved for JIT data. Use the <code>-Xscminjitdata</code> option to set the initial minimum size."},{"location":"xshareclasses/#adjustsoftmx-cache-utility","title":"<code>adjustsoftmx</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:adjustsoftmx=&lt;size&gt;\n</code></pre> Adjusts the soft maximum size of the cache. When you use the <code>-Xshareclasses:verbose</code> option, the VM writes to the console the number of bytes that are not stored due to the current setting of the soft maximum size. For more information about the soft maximum size, see -Xscmx."},{"location":"xshareclasses/#allowclasspaths","title":"<code>allowClasspaths</code>","text":"<pre><code>    -Xshareclasses:allowClasspaths\n</code></pre> Allows a VM to store classpaths into an existing shared cache that was created by using the <code>restrictClasspaths</code> option."},{"location":"xshareclasses/#bootclassesonly","title":"<code>bootClassesOnly</code>","text":"<pre><code>    -Xshareclasses:bootClassesOnly\n</code></pre> Disables caching of classes that are loaded by class loaders other than the bootstrap class loader. If you use this suboption, the <code>nonfatal</code> suboption is also set, so this suboption is the equivalent of specifying <code>-Xshareclasses:bootClassesOnly,nonfatal</code>."},{"location":"xshareclasses/#cachedir","title":"<code>cacheDir</code>","text":"<pre><code>    -Xshareclasses:cacheDir=&lt;directory&gt;\n</code></pre> <p>Sets the directory in which cache data is read and written. Do not set the cache directory on an NFS mount or a shared mount across systems or LPARs. The following defaults apply:</p> <ul> <li>On Windows\u2122 systems, <code>&lt;directory&gt;</code> is the user's <code>C:\\Users\\&lt;username&gt;\\AppData\\Local\\javasharedresources</code> directory.</li> <li>On z/OS\u00ae systems, <code>&lt;directory&gt;</code> is the <code>/tmp/javasharedresources</code> directory.</li> <li>On other operating systems, <code>&lt;directory&gt;</code> is <code>.cache/javasharedresources</code> in the user's home directory, unless the <code>groupAccess</code> parameter is specified, in which case it is <code>/tmp/javasharedresources</code>, because some members of the group might not have access to the user's home directory. You must have sufficient permissions in <code>&lt;directory&gt;</code>. Do not set user's home directory on a NFS or shared mount.</li> </ul> <p>On AIX\u00ae, Linux, macOS, and Windows systems, the VM writes persistent cache files directly into the directory specified. Persistent cache files can be safely moved and deleted from the file system.</p> <p>Non-persistent caches are stored in shared memory and have control files that describe the location of the memory. Control files are stored in a <code>javasharedresources</code> subdirectory of the <code>cacheDir</code> specified. Do not move or delete control files in this directory. The <code>listAllCaches</code> utility, the <code>destroyAll</code> utility, and the <code>expire</code> suboption work only in the scope of a given <code>cacheDir</code>.</p> <p>On AIX, Linux, and macOS systems, if you specify the <code>cacheDir=&lt;directory&gt;</code> option, persistent caches are created with the following permissions (<code>-rw-r--r--</code>):</p> <ul> <li>User: read/write</li> <li>Group: read (read/write if you also specify <code>-Xshareclasses:groupAccess</code>)</li> <li>Other: read only</li> </ul> <p>Otherwise, persistent caches are created with the same permissions as non-persistent caches. The permissions for non-persistent caches are <code>-rw-r-----</code>, or <code>-rw-rw----</code> if you also specify <code>-Xshareclasses:groupAccess</code>.</p> <p> Note: It is good practice to set an application-specific cache directory to avoid sharing the default cache directory with the default cache, or other application caches that don't set a cache directory, and means that your application is therefore unaffected by a user running <code>java -Xshareclasses:destroyAll</code>. See Class data sharing: Best practices for using <code>-Xshareclasses</code>.</p>"},{"location":"xshareclasses/#cachedirperm","title":"<code>cacheDirPerm</code>","text":"(Not Windows)<pre><code>-Xshareclasses:cacheDirPerm=&lt;permission&gt;\n</code></pre> <p>Sets Unix-style permissions when you are creating a cache directory. <code>&lt;permission&gt;</code> must be an octal number in the ranges 0700 - 0777 or 1700 - 1777. If <code>&lt;permission&gt;</code> is not valid, the VM ends with an appropriate error message.</p> <p>The permissions that are specified by this suboption are used only when you are creating a new cache directory. If the cache directory already exists, this suboption is ignored and the cache directory permissions are not changed.</p> <p>If you set this suboption to 0000, the default directory permissions are used. If you set this suboption to 1000, the machine default directory permissions are used, but the sticky bit is enabled.</p> <p>If the cache directory is the platform default directory, <code>&lt;HomeDir&gt;/.cache/javasharedresources</code>,  being the user's home directory, this suboption is ignored and the cache directory permissions are set to 0777. <p>If you do not set this suboption, the default permissions are used according to the following conditions:</p> Condition Permissions The cache directory is <code>&lt;HomeDir&gt;/.cache/javasharedresources</code>. If this directory already exists with different permissions, the permissions are changed when the cache is opened.\u2020 0777 The cache directory is a new directory and you also specify the <code>groupAcess</code> suboption 0770 The cache directory is a new directory and you do not specify the <code>groupAccess</code> suboption 0700 The cache directory already exists and is not <code>&lt;HomeDir&gt;/.cache/javasharedresources</code> Unchanged \u2020On z/OS\u00ae systems, permissions for existing cache directories are unchanged, to avoid generating RACF\u00ae errors, which generate log messages. Note: It is good practice to explicitly set permissions for the cache directory when the defaults are not appropriate. See Class data sharing: Best practices for using <code>-Xshareclasses</code>."},{"location":"xshareclasses/#cacheretransformed","title":"<code>cacheRetransformed</code>","text":"<pre><code>    -Xshareclasses:cacheRetransformed\n</code></pre> Enables caching of classes that are transformed by using the JVMTI <code>RetransformClasses</code> function. For more information, see Redefined and retransformed classes. <p>The option <code>enableBCI</code> is enabled by default. However, if you use the <code>cacheRetransformed</code> option, this option forces cache creation into <code>-Xshareclasses:disableBCI</code> mode.</p>"},{"location":"xshareclasses/#checkurltimestamps","title":"<code>checkURLTimestamps</code>","text":"<pre><code>    -Xshareclasses:checkURLTimestamps\n</code></pre> Causes timestamps of <code>jar</code> or <code>zip</code> files to be checked every time a class is loaded. If a timestamp has changed, the class is loaded from the <code>jar</code> or <code>zip</code> file and not from the shared cache. This suboption is not enabled by default and reflects the legacy behavior of the shared classes cache. Note: The timestamp of a bootstrap <code>jar</code> or <code>zip</code> file is checked once when it is used for the first time to load a class."},{"location":"xshareclasses/#createlayer","title":"<code>createLayer</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xshareclasses:createLayer\n</code></pre> Creates layered caches. If there are multiple VMs in a race condition while creating a layered cache, more than one new layered cache can be created. To avoid this situation, use the <code>-Xshareclasses:layer=&lt;number&gt;</code> suboption to create a new layered cache with a specific layer number. See <code>layer</code> for more information about layered caches."},{"location":"xshareclasses/#destroy-cache-utility","title":"<code>destroy</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:destroy\n</code></pre> Destroys a cache that is specified by the <code>name</code>, <code>cacheDir</code>, and <code>nonpersistent</code> suboptions. A cache can be destroyed only if all VMs that are using it have ended and the user has sufficient permissions."},{"location":"xshareclasses/#destroyall-cache-utility","title":"<code>destroyAll</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:destroyAll\n</code></pre> Tries to destroy all the caches that are specified by the <code>cacheDir</code> and <code>nonpersistent</code> suboptions. On Windows and z/OS systems, a cache can be destroyed only if all VMs that are using it have shut down and the user has sufficient permissions. Note: On z/OS, when the <code>destroyAll</code> option is invoked from a 31-bit VM, 64-bit caches are not destroyed. Similarly, when the <code>destroyAll</code> option is invoked from a 64-bit VM, 31-bit caches are not destroyed. The following message is displayed:<pre><code>JVMSHRC735I: Use a nn-bit VM to perform the requested operation on the\nnn-bit shared cache \"cachename\" as the nn-bit VM\ncannot verify that the shared memory was created by the VM.\n</code></pre> <p>On AIX, Linux, and macOS systems:</p> <ul> <li> <p>Non-persistent caches can be destroyed only if all VMs that are using it have shut down and the user has sufficient permissions.</p> </li> <li> <p>Persistent caches that are still in use continue to exist even when you use this option, but they are unlinked from the file system so they are not visible to new VM invocations. If you update the VM then restart an application for which a persistent shared cache already exists, the VM unlinks the existing cache and creates a new cache. Because the unlinked caches are not visible to new VMs, you cannot find them by using the <code>-Xshareclasses:listAllCaches</code> option, and you cannot use the <code>-Xshareclasses:printStats</code> option on them. You can therefore have multiple unlinked caches that consume file system space until they are no longer in use.</p> </li> </ul>"},{"location":"xshareclasses/#destroyalllayers-cache-utility","title":"<code>destroyAllLayers</code> (Cache utility)","text":"<p>(64-bit only)</p> <pre><code>    -Xshareclasses:destroyAllLayers\n</code></pre> Destroys all shared cache layers that are specified by the <code>name</code> suboption. For example, <code>-Xshareclasses:name=Cache1,destroyAllLayers</code> destroys all layers of the cache called <code>Cache1</code>. If you use the <code>destroy</code> suboption on a layered cache, for example <code>-Xshareclasses:name=Cache1,destroy</code>, only the top layer of the cache is destroyed. For more information about layered caches, see Creating layer caches."},{"location":"xshareclasses/#destroyallsnapshots-cache-utility","title":"<code>destroyAllSnapshots</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:destroyAllSnapshots\n</code></pre> <p>Destroys all shared cache snapshots that are available as a result of the specified <code>cacheDir</code> suboption.</p>"},{"location":"xshareclasses/#destroysnapshot-cache-utility","title":"<code>destroySnapshot</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:destroySnapshot\n</code></pre> <p>Destroys a snapshot that is specified by the <code>name</code> and <code>cacheDir</code> suboptions.</p>"},{"location":"xshareclasses/#disablebci","title":"<code>disableBCI</code>","text":"<pre><code>    -Xshareclasses:disableBCI\n</code></pre> Turns off BCI support. This option can be used to override <code>-XXShareClassesEnableBCI</code>."},{"location":"xshareclasses/#enablebci","title":"<code>enableBCI</code>","text":"<pre><code>    -Xshareclasses:enableBCI\n</code></pre> This option is enabled by default. Allows a JVMTI <code>ClassFileLoadHook</code> event to be triggered every time, for classes that are loaded from the cache. This mode also prevents caching of classes that are modified by JVMTI agents. For more information about bytecode modification, see Support for bytecode instrumentation. This option is incompatible with the <code>cacheRetransformed</code> option. Using the two options together causes the VM to end with an error message, unless <code>-Xshareclasses:nonfatal</code> is specified. In this case, the VM continues without using shared classes. A cache that is created without the <code>enableBCI</code> suboption cannot be reused with the <code>enableBCI</code> suboption. Attempting to do so causes the VM to end with an error message, unless <code>-Xshareclasses:nonfatal</code> is specified. In this case, the VM continues without using shared classes. A cache that is created with the <code>enableBCI</code> suboption can be reused without specifying this suboption. In this case, the VM detects that the cache was created with the <code>enableBCI</code> suboption and uses the cache in this mode."},{"location":"xshareclasses/#expire-cache-utility","title":"<code>expire</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:expire=&lt;time_in_minutes&gt;\n</code></pre> Destroys all caches that are unused for the time that is specified before loading shared classes. This option is not a utility option because it does not cause the VM to exit. On Windows systems, which have NTFS file systems, the <code>expire</code> option is accurate to the nearest hour."},{"location":"xshareclasses/#fatal","title":"<code>fatal</code>","text":"<pre><code>    -Xshareclasses:fatal\n</code></pre> The VM does not start if class data sharing fails, for example because there was an error when accessing the cache directory. An error message is generated. This suboption is specified by default unless you use the <code>bootClassesOnly</code> suboption, which is equivalent to <code>-Xshareclasses:bootClassesOnly,nonfatal</code>. You can override this behavior by specifying <code>-Xshareclasses:bootClassesOnly,fatal</code>. See also <code>nonfatal</code>."},{"location":"xshareclasses/#findaotmethods-cache-utility","title":"<code>findAotMethods</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:findAotMethods=&lt;method_specification&gt;\n    -Xshareclasses:findAotMethods=help\n</code></pre> Print the AOT methods in the shared classes cache that match the method specifications. Methods that are already invalidated are indicated in the output. Use this suboption to check which AOT methods in the shared classes cache would be invalidated by using the same method specifications with the <code>invalidateAotMethods</code> suboption. To learn more about the syntax to use for <code>&lt;method_specification&gt;</code>, including how to specify more than one method, see Method specification syntax."},{"location":"xshareclasses/#groupaccess","title":"<code>groupAccess</code>","text":"(Not Windows)<pre><code>-Xshareclasses:groupAccess\n</code></pre> <p>Sets operating system permissions on a new cache to allow group access to the cache. Group access can be set only when permitted by the operating system <code>umask</code> setting. The default is user access only.</p> <p>On AIX, Linux, and macOS systems, if a user creates a cache by specifying the <code>groupAccess</code> suboption, other users in the same group must also specify this suboption to be granted access to the same cache.</p> <p>When <code>groupAccess</code> is specified, the default directory for a cache is <code>/tmp/javasharedresources</code>. Some systems might clear the content of the <code>/tmp</code> directory on a reboot, removing the shared cache. To avoid that problem, you are therefore recommended to use <code>cacheDir</code> to set a different location for the cache. If necessary, use <code>cacheDirPerm</code> to ensure that the cache directory permissions are set appropriately.</p> <p>In certain situations, warning messages might be generated when the <code>groupAccess</code> suboption is used.</p> <p>This message can occur when persistent caches are used:</p> <pre><code>JVMSHRC756W Failed to set group access permission on the shared cache\nfile as requested by the 'groupAccess' sub-option\n</code></pre> <p>These messages can occur when non-persistent caches are used:</p> <pre><code>JVMSHRC759W Failed to set group access permission as requested by the\n'groupAccess' sub-option on the semaphore control file associated\nwith shared classes cache.\n\nJVMSHRC760W Failed to set group access permission as requested by the\n'groupAccess' sub-option on the shared memory control file associated\nwith shared classes cache.\n</code></pre> <p>This message can occur in combination with the <code>snapshotCache</code> suboption:</p> <pre><code>JVMSHRC761W Failed to set group access permission as requested by the\n'groupAccess' sub-option on the shared cache snapshot file.\n</code></pre> <p>All of these warning messages mean that the user's umask setting does not allow either, or both, of the group <code>read</code> and <code>write</code> permission to be set on the file. The typical umask setting restricts only the <code>write</code> permission. To resolve the warning, either change the umask setting or remove the <code>groupAccess</code> suboption.</p>"},{"location":"xshareclasses/#help","title":"<code>help</code>","text":"<pre><code>    -Xshareclasses:help\n</code></pre> Lists all the command-line options."},{"location":"xshareclasses/#invalidateaotmethods-cache-utility","title":"<code>invalidateAotMethods</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:invalidateAotMethods=&lt;method_specification&gt;\n    -Xshareclasses:invalidateAotMethods=help\n</code></pre> Modify the existing shared cache to invalidate the AOT methods that match the method specifications. Use this suboption to invalidate AOT methods that cause a failure in the application, without having to destroy the shared cache. Invalidated AOT methods remain in the shared cache, but are then excluded from being loaded. VMs that have not processed the methods, or new VMs that use the cache are not affected by the invalidated methods. The AOT methods are invalidated for the lifetime of the cache, but do not prevent the AOT methods from being compiled again if a new shared cache is created. To prevent AOT method compilation into a new shared cache, use the <code>-Xaot:exclude</code> option. For more information, see -Xaot. To identify AOT problems, see Diagnosing a JIT or AOT problem. To revalidate an AOT method, see the <code>revalidateAotMethods</code> suboption. Use the <code>findAotMethod</code> suboption to determine which AOT methods match the method specifications. To learn more about the syntax to use for <code>&lt;method_specification&gt;</code>, including how to specify more than one method, see Method specification syntax."},{"location":"xshareclasses/#layer","title":"<code>layer</code>","text":"<p>(64-bit only)</p> <pre><code>    -Xshareclasses:layer=&lt;number&gt;\n</code></pre> Creates layered caches. This suboption has the same effect as the <code>createLayer</code> suboption, but with the added ability to specify the layer number. For more information about creating a shared classes cache with layers, see Creating layer caches."},{"location":"xshareclasses/#listallcaches-cache-utility","title":"<code>listAllCaches</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:listAllCaches\n</code></pre> Lists all the compatible and incompatible caches, and snapshots that exist in the specified cache directory. If you do not specify <code>cacheDir</code>, the default directory is used. Summary information, such as Java version and current usage, is displayed for each cache. Output includes <code>cache-type</code> (persistent or non-persistent) and <code>feature</code> (compressed references (<code>cr</code>) or non-compressed references (<code>non-cr</code>))."},{"location":"xshareclasses/#mprotect","title":"<code>mprotect</code>","text":"AIX, z/OS 31-bit:<pre><code>-Xshareclasses:mprotect=[default|all|none]\n</code></pre> <p>Linux, Windows, macOS:</p> <pre><code>-Xshareclasses:mprotect=[default|all|partialpagesonstartup|onfind|nopartialpages|none]\n</code></pre> <p>where:</p> <ul> <li><code>default</code>: By default, the memory pages that contain the cache are always protected, unless a specific page is being updated. This protection helps prevent accidental or deliberate corruption to the cache. The cache header is not protected by default because this protection has a performance cost. On Linux, macOS, and Windows systems, after the startup phase, the Java virtual machine (VM) protects partially filled pages whenever new data is added to the shared classes cache in the following sequence:<ul> <li>The VM changes the memory protection of any partially filled pages to read/write.</li> <li>The VM adds the data to the cache.</li> <li>The VM changes the memory protection of any partially filled pages to read only.</li> </ul> </li> <li><code>all</code>: This value ensures that all the cache pages are protected, including the header. See Note.</li> <li><code>partialpagesonstartup</code>: This value causes the VM to protect partially filled pages during startup as well as after the startup phase. This value is available only on Linux, macOS, and Windows systems.</li> <li><code>onfind</code>: When this option is specified, the VM protects partially filled pages when it reads new data in the cache that is added by another VM. This option is available only on Linux, macOS, and Windows systems.</li> <li><code>nopartialpages</code>: Use this value to turn off the protection of partially filled pages. This value is available only on Linux, macOS, and Windows systems.</li> <li><code>none</code>: Specifying this value disables the page protection.</li> </ul> <p> Note: Specifying <code>all</code> has a negative impact on performance. You should specify <code>all</code> only for problem diagnosis and not for production. Specifying values <code>partialpagesonstartup</code> or <code>onfind</code> can also have a negative impact on performance when the cache is being populated. There is no further impact when the cache is full or no longer being modified.</p>"},{"location":"xshareclasses/#modified","title":"<code>modified</code>","text":"<pre><code>    -Xshareclasses:modified=&lt;modified_context&gt;\n</code></pre> Used when a JVMTI agent is installed that might modify bytecode at run time. If you do not specify this suboption and a bytecode modification agent is installed, classes are safely shared with an extra performance cost. The <code>&lt;modified context&gt;</code> is a descriptor that is chosen by the user; for example, myModification1. This option partitions the cache so that only VMs that are using context myModification1 can share the same classes. So if, for example, you run an application with a modification context and then run it again with a different modification context, all classes are stored twice in the cache. For more information, see Sharing modified bytecode. If you are migrating from IBM\u00ae SDK, Java Technology Edition, Version 7, or earlier releases, you must set <code>-Xshareclasses:disableBCI</code> when you use this option to retain the same behavior."},{"location":"xshareclasses/#name","title":"<code>name</code>","text":"<pre><code>    -Xshareclasses:name=&lt;name&gt;\n</code></pre> Connects to a cache of a given name, creating the cache if it does not exist. This option is also used to indicate the cache that is to be modified by cache utilities; for example, <code>destroy</code>. Use the <code>listAllCaches</code> utility to show which named caches are currently available. If you do not specify a name, the default name \"sharedcc_%u\" is used. \"%u\" in the cache name inserts the current user name. On operating systems other than Windows, you can specify \"%g\" in the cache name to insert the current group name. Note: It is good practice to explicitly specify a cache for your application. This avoids the application sharing a cache that is enabled by default or with another application that doesn't set a name, and ensures that the size of your application cache can be set appropriately and that cache space is used exclusively for your application. Note that you cannot change the size of a default cache that already exists by using the <code>-Xscmx</code> option, as that option has no effect on a pre-existing cache. See Class data sharing: Best practices for using <code>-Xshareclasses</code>."},{"location":"xshareclasses/#noaot","title":"<code>noaot</code>","text":"<pre><code>    -Xshareclasses:noaot\n</code></pre> Disables caching and loading of AOT code. AOT code already in the shared data cache can be loaded."},{"location":"xshareclasses/#nobootclasspath","title":"<code>noBootclasspath</code>","text":"<pre><code>    -Xshareclasses:noBootclasspath\n</code></pre> Disables the storage of classes that are loaded by the bootstrap class loader in the shared classes cache. Often used with the <code>SharedClassURLFilter</code> API to control exactly which classes are cached. For more information about shared class filtering, see The Java shared classes Helper API."},{"location":"xshareclasses/#notimestampchecks","title":"<code>noTimestampChecks</code>","text":"<pre><code>    -Xshareclasses:noTimestampChecks\n</code></pre> Turns off timestamp checking when finding classes in the shared cache. Use this option only when you know there are no updates to the classes from the class paths or module paths in your application. Otherwise, obsolete classes might be loaded from the shared cache. If this happens, remove the <code>noTimestampChecks</code> option."},{"location":"xshareclasses/#nocheckurltimestamps","title":"<code>nocheckURLTimestamps</code>","text":"<pre><code>    -Xshareclasses:nocheckURLTimestamps\n</code></pre> Timestamps of <code>jar</code> or <code>zip</code> files are checked only when they are added to a class loader and used for the first time to look up a class. This is the default behavior, which can improve the performance of class loading from the shared classes cache, especially on Windows systems. To revert to the behavior of the shared classes cache in earlier releases, use the <code>CheckURLTimeStamps</code> suboption. Restriction: When the <code>nocheckURLTimestamps</code> suboption is used (default), if <code>jar</code> or <code>zip</code> files are updated after a class loader starts loading classes from them, an older version of the class might be loaded from the shared classes cache. If this scenario occurs, use the <code>checkURLTimestamps</code> option."},{"location":"xshareclasses/#nojitdata","title":"<code>nojitdata</code>","text":"<pre><code>    -Xshareclasses:nojitdata\n</code></pre> Disables caching of JIT data. JIT data already in the shared data cache can be loaded."},{"location":"xshareclasses/#none","title":"<code>none</code>","text":"<pre><code>    -Xshareclasses:none\n</code></pre> Added to the end of a command line, disables class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption disables the shared class utility APIs. To disable class data sharing without disabling the utility APIs, use the <code>utilities</code> suboption. For more information about the shared class utility APIs, see The Java shared classes utility API."},{"location":"xshareclasses/#nonfatal","title":"<code>nonfatal</code>","text":"<pre><code>    -Xshareclasses:nonfatal\n</code></pre> Allows the VM to start, in most cases, even if class data sharing fails. Normal behavior for the VM is to refuse to start if class data sharing fails. If you select <code>nonfatal</code> and the shared classes cache fails to initialize, the VM attempts to connect to the cache in read-only mode. If this attempt fails, the VM starts without class data sharing. See also <code>fatal</code>. Note: Unless it is important that your application runs with class data sharing, it is good practice to set this parameter. See Creating a shared classes cache. However, cache corruption as a result of a bug in the operating system, VM, or user code might not be detected when opening the cache. In this situation, the cache is used and the application might crash."},{"location":"xshareclasses/#nonpersistent","title":"<code>nonpersistent</code>","text":"<pre><code>    -Xshareclasses:nonpersistent\n</code></pre> Uses a non-persistent cache. The cache is lost when the operating system shuts down. Non-persistent and persistent caches can have the same name. On Linux, macOS, and Windows systems, you must always use the <code>nonpersistent</code> suboption when you run utilities such as <code>destroy</code> on a non-persistent cache. Note: On macOS systems, you must set <code>kern.sysv.shmmax</code> and <code>kern.sysv.shmall</code> when using a non-persistent cache."},{"location":"xshareclasses/#nopersistentdiskspacecheck","title":"<code>noPersistentDiskSpaceCheck</code>","text":"<pre><code>    -Xshareclasses:noPersistentDiskSpaceCheck\n</code></pre> Instructs the VM not to check for available storage on the file system before creating a persistent shared classes cache. This option prevents an error on file systems that do not support the checking of free space, where a value of 0 is returned and a shared cache cannot be created. Regardless of whether you choose to set this option, if there isn't enough disk space available when the VM writes to the shared cache memory, a SIGBUS or SIGSEGV signal occurs and the VM ends. If you are using the <code>readonly</code> suboption, the VM does not check the available disk space, so you do not need to set the <code>noPersistentDiskSpaceCheck</code> suboption."},{"location":"xshareclasses/#persistent","title":"<code>persistent</code>","text":"<pre><code>    -Xshareclasses:persistent\n</code></pre> Uses a persistent cache. The cache is created on disk, which persists beyond operating system restarts. Non-persistent and persistent caches can have the same name. On AIX, you must always use the <code>persistent</code> suboption when you run utilities such as <code>destroy</code> on a persistent cache. Notes: <ul> <li>With the 31-bit VM on all versions of z/OS, the shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit <code>MAXMMAPAREA</code>. For more information about the suggested value for the <code>MAXMMAPAREA</code> limit, see Setting resource limits (z/OS).</li> <li> <p>With the 64-bit VM, the shared cache is mapped as follows:</p> <ul> <li>On z/OS version 2.3 and earlier, the persistent shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit <code>MAXMMAPAREA</code>.</li> <li> <p>On z/OS version 2.4 and later, the persistent shared cache is mapped above the 2 GB address range. The maximum size of persistent shared classes cache is limited by the <code>MAXSHARE</code> value within the <code>SMFLIMxx</code> member of <code>SYS1.PARMLIB</code>. You can use the following machine configuration to create up to 1 GB shared classes cache mapped above the 2 GB address range:</p> <ol> <li>Add the following line in the SMFLIMxx member of SYS1.PARMLIB.</li> </ol> <p><code>REGION JOBNAME(*) MAXSHARE(262144)</code></p> <ol> <li>Load the change with the following command in the SDSF panel.</li> </ol> <p><code>/SET SMFLIM=xx</code></p> </li> </ul> <p>For more information about the SMFLIMxx member of SYS1.PARMLIB, see Statements and parameters for SMFLIMxx.</p> <p>On z/OS version 2.4, fixes for APARs OA60306 and PH32235 must be installed for the support of this memory mapping. On z/OS version 2.5 and later, the fixes for APARs OA60306 and PH32235 are included by default.</p> </li> </ul>"},{"location":"xshareclasses/#printallstats-cache-utility","title":"<code>printAllStats</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:printAllStats\n</code></pre> Displays detailed information about the contents of the cache that is specified in the <code>name</code> suboption. If the name is not specified, statistics are displayed about the default cache. For layered caches, information is shown for all layers (to see information for the top layer cache only, use <code>printTopLayerStats=all</code>). Every class is listed in chronological order with a reference to the location from which it was loaded. For more information, see Shared classes cache diagnostic utilities."},{"location":"xshareclasses/#printstats-cache-utility","title":"<code>printStats</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:printStats=&lt;data_type&gt;[+&lt;data_type&gt;]\n</code></pre> Displays summary information for the cache that is specified by the <code>name</code>, <code>cacheDir</code>, and <code>nonpersistent</code> suboptions. For layered caches, information is shown for all layers (to see information for the top layer cache only, use <code>printTopLayerStats</code>). The most useful information that is displayed is how full the cache is and how many classes it contains. Stale classes are classes that are updated on the file system and which the cache has therefore marked as \"stale\". Stale classes are not purged from the cache and can be reused. Use the <code>printStats=stale</code> option to list all the stale entries and stale bytes. Specify one or more data types, which are separated by a plus symbol (+), to see more detailed information about the cache content. Data types include AOT data, class paths, and ROMMethods. For more information and for a full list of data types, see Shared classes cache diagnostic utilities."},{"location":"xshareclasses/#printtoplayerstats-cache-utility","title":"<code>printTopLayerStats</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:printTopLayerStats=&lt;data_type&gt;[+&lt;data_type&gt;]\n</code></pre> Equivalent to <code>printStats</code> but for the top layer cache only. For more information about layered caches, see Creating a layer cache."},{"location":"xshareclasses/#readonly","title":"<code>readonly</code>","text":"<pre><code>    -Xshareclasses:readonly\n</code></pre> By default, a shared classes cache is created with read/write access. Use the <code>readonly</code> suboption to open an existing cache with read-only permissions. Opening a cache read-only prevents the VM from making any updates to the cache. If you specify this suboption, the VM can connect to caches that were created by other users or groups without requiring write access. On AIX, Linux, and macOS systems, this access is permitted only if the cache was created by using the <code>-Xshareclasses:cacheDir</code> option to specify a directory with appropriate permissions. If you do not use the <code>-Xshareclasses:cacheDir</code> option, the cache is created with default permissions, which do not permit access by other users or groups. By default, this suboption is not specified. The <code>-Xshareclasses:readonly</code> option is ignored under the following conditions: <ul> <li>The JITServer AOT cache feature is enabled (<code>-XX:+JITServerUseAOTCache</code>), and the VM is a client.</li> <li>The VM is running in a container.</li> <li>AOT compilation is enabled. For more information about AOT compilation, see the Ahead-Of-Time (AOT) compiler topic.</li> <li>The shared classes cache is persistent. (<code>-Xshareclasses:persistent</code>)</li> </ul> <p>If a persistent shared classes cache is started under the mentioned conditions, the cache startup creates a temporary new (writable) top layer. The JITServer AOT cache uses the new top layer to store a small amount of metadata that the cache needs to function. With this top layer, the JITServer AOT cache can be used without modifying the existing layers.</p>"},{"location":"xshareclasses/#reset","title":"<code>reset</code>","text":"<pre><code>    -Xshareclasses:reset\n</code></pre> Causes a cache to be destroyed and then re-created when the VM starts up. This option can be added to the end of a command line as <code>-Xshareclasses:reset</code>."},{"location":"xshareclasses/#restorefromsnapshot-cache-utility","title":"<code>restoreFromSnapshot</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:restoreFromSnapshot\n</code></pre> <p>Restores a new non-persistent shared cache from a snapshot file. The snapshot and shared cache have the same name and location, as specified by the <code>name</code> and <code>cacheDir</code> suboptions. The non-persistent cache cannot already exist when the snapshot is restored. Restoring a snapshot does not remove the snapshot file; it can be restored multiple times. On platforms that support persistent caches, the <code>nonpersistent</code> suboption must be specified in order to restore a snapshot.</p>"},{"location":"xshareclasses/#restrictclasspaths","title":"<code>restrictClasspaths</code>","text":"<pre><code>    -Xshareclasses:restrictClasspaths\n</code></pre> Allows only the first VM that is initializing a shared cache to store classpaths in the cache. Subsequent VMs are not allowed to store classpaths in the cache unless the <code>allowClasspaths</code> option is specified. Use the <code>restrictClasspaths</code> option only if the application is designed to create class loaders of type <code>java.net.URLClassloader</code> or its subclass, such that their classpaths are unique to the instance of the application, but the classes that are loaded from these classpaths are the same. In such cases application classpaths that are stored by one VM cannot be used by another VM. <p>For example, consider two VMs, VM1 and VM2, that are using class paths CP1 and CP2 respectively, where:</p> <ul> <li>CP1: <code>url1;url2;url3;tempurl1;url4;url5</code></li> <li>CP2: <code>url1;url2;url3;tempurl2;url4;url5</code></li> </ul> <p>These class paths differ only by one entry, which is the <code>tempurl</code>. The <code>url1</code>, <code>url2</code>, <code>url3</code>, <code>url4</code>, and <code>url5</code> entries never change from run to run, whereas the <code>tempurl</code> entry is always different. This difference means that a class that is loaded from <code>url4</code> or <code>url5</code>, and stored into the shared cache by VM1, cannot be located by VM2. Therefore, an attempt by VM2 to load a class from <code>url4</code> or <code>url5</code> would cause it to store its own classpath <code>CP2</code> into the shared cache, and also add new metadata for classes that are loaded from <code>url4</code> or <code>url5</code>. Addition of such unique class paths into the shared cache is not useful. Moreover, the additional metadata might adversely affect the performance of other VMs that connect to the shared cache. Because classes loaded from <code>url4</code> or <code>url5</code> are not loaded from the shared cache when the <code>tempurl</code> differs from the original, it is good practice to put the <code>tempurl</code> as the last entry in the class path.</p> <p>In situations such as that described in the example, the <code>restrictClasspaths</code> option can be used to restrict the addition of classpaths by ensuring that the first VM initializes the shared cache, and then prevents the addition of unique classpaths by subsequent VMs that attach to the shared cache. Note that use of the <code>restrictClasspaths</code> option in any other scenario is likely to negatively impact a VM's performance when it is using an existing cache.</p>"},{"location":"xshareclasses/#revalidateaotmethods-cache-utility","title":"<code>revalidateAotMethods</code> (Cache utility)","text":"<pre><code>    -Xshareclasses:revalidateAotMethods=&lt;method_specification&gt;\n    -Xshareclasses:revalidateAotMethods=help\n</code></pre> Modify the shared cache to revalidate the AOT methods that match the method specifications. Use this suboption to revalidate AOT methods that were invalidated by using the <code>invalidateAotMethods</code> suboption. Revalidated AOT methods are then eligible for loading into a VM, but do not affect VMs where the methods have already been processed. To learn more about the syntax to use for <code>&lt;method_specification&gt;</code>, including how to specify more than one method, see Method specification syntax."},{"location":"xshareclasses/#silent","title":"<code>silent</code>","text":"<pre><code>    -Xshareclasses:silent\n</code></pre> Disables all shared class messages, including error messages. Unrecoverable error messages, which prevent the VM from initializing, are displayed."},{"location":"xshareclasses/#snapshotcache-cache-utility","title":"<code>snapshotCache</code> (Cache utility)","text":"(Not Windows)<pre><code>-Xshareclasses:snapshotCache\n</code></pre> <p>Creates a snapshot file of an existing non-persistent shared cache. The snapshot has the same name and location as the shared cache, as specified by the <code>name</code> and <code>cacheDir</code> suboptions. The shared cache can be in use when the snapshot is taken, but VMs are blocked when they try to write to the shared cache, while the cache data is copied to the file.</p> <p>Typically, after a system is reinitialized, the snapshot file is used to restore the copy of the non-persistent cache into shared memory, via the <code>restoreFromSnapshot</code> suboption. Since this process removes all non-persistent caches from shared memory, restoring the cache from the snapshot file can result in better VM startup performance, because the contents of the shared cache, including classes and AOT code, do not have to be re-created.</p> <p>A snapshot can be created only if the user has sufficient permissions to create the destination snapshot file. If a snapshot of the same name exists already, it is overwritten. On platforms that support persistent caches, the <code>nonpersistent</code> suboption must be specified in order to create a snapshot. For information about removing snapshot files, see the <code>destroySnapshot</code> and <code>destroyAllSnapshots</code> suboptions.</p>"},{"location":"xshareclasses/#utilities","title":"<code>utilities</code>","text":"<pre><code>    -Xshareclasses:utilities\n</code></pre> Can be added to the end of a command line to disable class data sharing. This suboption overrides class sharing arguments found earlier on the command line. This suboption is like <code>none</code>, but does not disable the shared class utility APIs. For more information, see The Java shared classes utility API."},{"location":"xshareclasses/#verbose","title":"<code>verbose</code>","text":"<pre><code>    -Xshareclasses:verbose\n</code></pre> Gives detailed output on the cache I/O activity, listing information about classes that are stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders ask their parents for a class if they can't find it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy. The standard option <code>-verbose:class</code> also enables class sharing verbose output if class sharing is enabled."},{"location":"xshareclasses/#verboseaot","title":"<code>verboseAOT</code>","text":"<pre><code>    -Xshareclasses:verboseAOT\n</code></pre> Enables verbose output when compiled AOT code is being found or stored in the cache. AOT code is generated heuristically. You might not see any AOT code that is generated at all for a small application. You can disable AOT caching by using the <code>noaot</code> suboption. See the VM Messages Guide for a list of the messages produced."},{"location":"xshareclasses/#verbosehelper","title":"<code>verboseHelper</code>","text":"<pre><code>    -Xshareclasses:verboseHelper\n</code></pre> Enables verbose output for the Java Helper API. This output shows you how the Helper API is used by your class loader."},{"location":"xshareclasses/#verboseio","title":"<code>verboseIO</code>","text":"<pre><code>    -Xshareclasses:verboseIO\n</code></pre> Gives detailed output on the cache I/O activity, listing information about classes that are stored and found. Each class loader is given a unique ID (the bootstrap loader is always 0) and the output shows the class loader hierarchy at work, where class loaders must ask their parents for a class before they can load it themselves. It is typical to see many failed requests; this behavior is expected for the class loader hierarchy."},{"location":"xshareclasses/#method-specification-syntax","title":"Method specification syntax","text":"<p>The following examples show how to specify more than one method specification when you are using the <code>findAotMethods</code>, <code>invalidateAotMethods</code>, or <code>revalidateAotMethods</code> suboptions.</p> <p>Each method specification is defined as follows:</p> <pre><code>&lt;packagename&gt;/&lt;classname&gt;[.&lt;methodname&gt;[(&lt;parameters&gt;)]]\n</code></pre> <p>If you want to include more than one method specification in a single option, separate the specifications with a comma and enclose all the specifications in {braces}. For example:</p> <pre><code>{&lt;packagename/classname&gt;}[.{&lt;methodname&gt;}[({&lt;parameters&gt;})]]\n</code></pre> <ul> <li>You can use an asterisk (*) in most places as a wildcard.</li> <li>You can use an exclamation point (!) before the specification to mean \"everything except this\".</li> <li>Parameters are optional, but if specified, should be enclosed in parentheses and the following native signature formats must be used:<ul> <li><code>B</code> for byte</li> <li><code>C</code> for char</li> <li><code>D</code> for double</li> <li><code>F</code> for float</li> <li><code>I</code> for int</li> <li><code>J</code> for long</li> <li><code>S</code> for short</li> <li><code>Z</code> for Boolean</li> <li><code>L&lt;classname&gt;;</code> for objects</li> <li><code>[</code> before the signature means array</li> </ul> </li> </ul> <p>If you want to specify parameters to distinguish between methods, you can use <code>-Xshareclasses:findAotMethods=*</code> (with a wildcard) to list all the parameter variations. Copy the signature for the method that you want from the output. For example, the signature for the parameters</p> <pre><code>(byte[] bytes, int offset, int length, Charset charset)\n</code></pre> <p>is</p> <pre><code>([BIILjava/nio/charset/Charset;)\n</code></pre> <p>Here are some examples:</p> Method signature Matches... <code>*</code> All AOT methods. <code>java/lang/Object</code> All AOT methods in the <code>java.lang.Object</code> class <code>java/util/*</code> All AOT classes and methods in the <code>java.util</code> package <code>java/util/HashMap.putVal</code> All <code>putVal</code> methods in the <code>java.util.HashMap</code> class <code>java/util/HashMap.hash(Ljava/lang/Object;)</code> The private <code>java.util.HashMap.hash(java.lang.Object)</code> method <code>*.equals</code> All <code>equals</code> methods in all classes <code>{java/lang/Object,!java/lang/Object.clone}</code> All methods in <code>java.lang.Object</code> except <code>clone</code> <code>{java/util/*.*(),java/lang/Object.*(*)}</code> All classes or methods with no input parameter in the <code>java.util</code> package, and all methods in <code>java.lang.Object</code> <code>{java/util/*.*(),!java/util/*.*()}</code> Nothing. <ul> <li>Introduction to class data sharing</li> <li>-Xscmx</li> <li>-XX:SharedCacheHardLimit</li> </ul>"},{"location":"xshareclassesdisableonrestore/","title":"-Xshareclasses:disableOnRestore","text":""},{"location":"xshareclassesdisableonrestore/#-xshareclassesdisableonrestore","title":"-Xshareclasses:disableOnRestore","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>The <code>-Xshareclasses</code> option is an existing option and <code>disableOnRestore</code> is its new parameter that can be used if the CRIU feature is available. This option is disabled by default.</p> <p> Restrictions:</p> <ul> <li>This option takes effect only when the <code>-XX:+EnableCRIUSupport</code> option is enabled.</li> <li>This option can be used only on restore.</li> </ul>"},{"location":"xshareclassesdisableonrestore/#parameters","title":"Parameters","text":""},{"location":"xshareclassesdisableonrestore/#disableonrestore","title":"<code>disableOnRestore</code>","text":"<pre><code>    -Xshareclasses:disableOnRestore\n</code></pre> <p>The <code>-Xshareclasses:disableOnRestore</code> option disables further use of the shared classes cache (SCC) on restore. You can still use the shared classes utility APIs, for example, to obtain metrics about the shared cache.</p> <p>The <code>-Xshareclasses:disableOnRestore</code> option is similar to the existing <code>-Xshareclasses:none</code> option but with the following differences:</p> <ul> <li>The <code>-Xshareclasses:none</code> option turns off the cache on the VM startup but the <code>-Xshareclasses:disableOnRestore</code> option turns off the cache on restore. If you turn off the cache on startup, then specifying the <code>-Xshareclasses:disableOnRestore</code> option has no impact because there is no cache existing in the checkpoint image for the option to disable.</li> <li>The <code>-Xshareclasses:none</code> option disables the shared classes utility APIs but the <code>-Xshareclasses:disableOnRestore</code> option keeps the utility APIs working.</li> </ul>"},{"location":"xshareclassesdisableonrestore/#see-also","title":"See also","text":"<ul> <li>-Xshareclasses</li> <li>CRIU support</li> </ul>"},{"location":"xsigcatch/","title":"-Xsigcatch","text":""},{"location":"xsigcatch/#-xsigcatch-xnosigcatch","title":"-Xsigcatch / -Xnosigcatch","text":"<p>Enables and disables VM signal handling code.</p>"},{"location":"xsigcatch/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xsigcatch</code> Enable yes <code>-Xnosigcatch</code> Disable"},{"location":"xsigcatch/#see-also","title":"See also","text":"<ul> <li>Signal handling</li> </ul>"},{"location":"xsigchain/","title":"-Xsigchain","text":""},{"location":"xsigchain/#-xsigchain-xnosigchain","title":"-Xsigchain / -Xnosigchain","text":"<p>Enables and disables signal handler chaining.</p>"},{"location":"xsigchain/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xsigchain</code> Enable yes (except on z/OS\u00ae) <code>-Xnosigchain</code> Disable"},{"location":"xsigchain/#see-also","title":"See also","text":"<ul> <li>Signal handling</li> </ul>"},{"location":"xsignal/","title":"-Xsignal","text":""},{"location":"xsignal/#-xsignal","title":"-Xsignal","text":"<p>(z/OS\u00ae only)</p> <p>This option controls the behavior of Eclipse OpenJ9\u2122 VM signal handlers.</p>"},{"location":"xsignal/#syntax","title":"Syntax","text":"<pre><code>    -Xsignal:&lt;parameter&gt;=&lt;value&gt;\n</code></pre>"},{"location":"xsignal/#parameters","title":"Parameters","text":"<p> Restriction: You cannot use these parameters together.</p>"},{"location":"xsignal/#posixsignalhandler","title":"<code>posixSignalHandler</code>","text":"<pre><code>    -Xsignal:posixSignalHandler=cooperativeShutdown\n</code></pre> <p>When the VM signal handlers for SIGSEGV, SIGILL, SIGBUS, SIGFPE, SIGTRAP, and SIGABRT end a process, they call <code>exit()</code>, by default. In this case, the z/OS\u2122 Language Environment\u00ae is not aware that the VM ended abnormally.</p> <p>With <code>-Xsignal:posixSignalHandler=cooperativeShutdown</code>, the VM no longer uses <code>exit()</code> to end the process from the signal handlers. Instead, the VM behaves in one of the following ways:</p> <ul> <li>In response to a z/OS hardware exception, the VM uses <code>return()</code>.</li> <li>In response to signals raised or injected by software, the VM ends the enclave with <code>abend 3565</code>.</li> </ul> <p>Language Environment detects that the VM is ending abnormally and initiates Resource Recovery Services.</p>"},{"location":"xsignal/#userconditionhandler","title":"<code>userConditionHandler</code>","text":"(31-bit z/OS only)<pre><code>-Xsignal:userConditionHandler=percolate\n</code></pre> <p>This option results in similar behavior to the <code>-XCEEHDLR</code> option: the VM registers user condition handlers to handle the z/OS exceptions that would otherwise be handled by the VM POSIX signal handlers for the SIGBUS, SIGFPE, SIGILL, SIGSEGV, and SIGTRAP signals.</p> <p>As with the <code>-XCEEHDLR</code> option, the VM does not install POSIX signal handlers for these signals.</p> <p>This option differs from the <code>-XCEEHDLR</code> option in that the VM percolates all Language Environment\u00ae conditions that were not triggered and expected by the VM during normal running, including conditions that are severity 2 or greater. The VM generates its own diagnostic information before percolating severity 2 or greater conditions.</p> <p>The VM is in an undefined state after percolating a severity 2 or greater condition. Applications cannot resume running then call back into, or return to, the VM.</p>"},{"location":"xsignal/#see-also","title":"See also","text":"<ul> <li><code>-XCEEHDLR</code></li> <li>Signal handling</li> </ul>"},{"location":"xsoftmx/","title":"-Xsoftmx","text":""},{"location":"xsoftmx/#-xsoftmx","title":"-Xsoftmx","text":"<p>This option sets a \"soft\" maximum limit for the Java\u2122 heap.</p>"},{"location":"xsoftmx/#syntax","title":"Syntax","text":"<pre><code>    -Xsoftmx&lt;size&gt;\n</code></pre>"},{"location":"xsoftmx/#explanation","title":"Explanation","text":"<p>Use the <code>-Xmx</code> option to set a \"hard\" limit for the maximum size of the heap. By default, <code>-Xsoftmx</code> is set to the same value as <code>-Xmx</code>. The value of <code>-Xms</code> must be less than, or equal to, the value of <code>-Xsoftmx</code>.</p> <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>You can set this option on the command line, then modify it at run time by using the <code>MemoryMXBean.setMaxHeapSize()</code> method in the <code>com.ibm.lang.management</code> API. By using this API, Java applications can dynamically monitor and adjust the heap size as required. This function can be useful in virtualized or cloud environments, for example, where the available memory might change dynamically to meet business needs. When you use the API, you must specify the value in bytes, such as <code>2147483648</code> instead of <code>2g</code>.</p> <p>For example, you might set the initial heap size to 1 GB and the maximum heap size to 8 GB. You might set a smaller value, such as 2 GB, for <code>-Xsoftmx</code>, to limit the heap size that is used initially:</p> <pre><code>-Xms1g -Xsoftmx2g -Xmx8g\n</code></pre> <p>You can then use the <code>com.ibm.lang.management</code> API from within a Java application to increase the <code>-Xsoftmx</code> value during run time, as load increases. This change allows the application to use more memory than you specified initially.</p> <p>If you reduce the <code>-Xsoftmx</code> value, the garbage collector attempts to respect the new limit. However, the ability to shrink the heap depends on a number of factors. There is no guarantee that a decrease in the heap size will occur. If or when the heap shrinks to less than the new limit, the heap will not grow beyond that limit.</p> <p>When the heap shrinks, the garbage collector might release memory. The ability of the operating system to reclaim and use this memory varies based on the capabilities of the operating system.</p> <p> Notes:</p> <ul> <li>When using <code>-Xgcpolicy:gencon</code> with <code>-Xsoftmx</code>, the proportion of heap space used for nursery within the <code>-Xsoftmx</code> limit is proportional to the maximum amount of nursery space specified (see Xmn/Xmnx) relative to the <code>-Xmx</code> value. For example, if the following is specified on the command line <code>-Xsoftmx2g -Xmnx4g  -Xmx8g</code>, nursery space is allowed to use 50%(4G/8G) of the specified <code>-Xsoftmx</code> value, which in this example is 1G.</li> <li>When using <code>-Xgcpolicy:balanced</code> with <code>-Xsoftmx</code> and <code>-Xmn</code>/<code>-Xmnx</code>/<code>-Xmns</code> options,  the maximum and minimum size for eden are absolute (rather than the proportional nursery behaviour for gencon), and do not depend on the <code>-Xsoftmx</code> value specified. For example, if <code>-Xmnx1G</code> is specified, then eden will be able to grow up to <code>1G</code> in size, regardless of the <code>-Xsoftmx</code> value specified.</li> <li>This option is ignored if used with the metronome GC policy (<code>-Xgcpolicy:metronome</code>) because the heap is always fully expanded.</li> <li>There might be little benefit in reducing the <code>-Xsoftmx</code> value when the Java heap is using large pages. Large pages are pinned in memory and are not reclaimed by the operating system, with the exception of 1M pageable pages on z/OS\u00ae. On certain platforms and processors the VM starts with large pages enabled by default for the Java heap when the operating system is configured to provide large pages. For more information, see Configuring large page memory allocation. A future version of the Java virtual machine might provide a hint to the operating system when large pages are no longer in use.</li> </ul>"},{"location":"xsoftrefthreshold/","title":"-Xsoftrefthreshold","text":""},{"location":"xsoftrefthreshold/#-xsoftrefthreshold","title":"-Xsoftrefthreshold","text":"<p>Sets the value used by the garbage collector to determine the number of garbage collection (GC) cycles after which a soft reference is cleared if its referent has not been marked.</p>"},{"location":"xsoftrefthreshold/#syntax","title":"Syntax","text":"<pre><code>    -Xsoftrefthreshold&lt;value&gt;\n</code></pre>"},{"location":"xsoftrefthreshold/#default-behavior","title":"Default behavior","text":"<p>The default value is 32.</p> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xsoftrefthreshold/#explanation","title":"Explanation","text":"<p>A soft reference (where its referent is not marked) is cleared after a number of GC cycles, which is calculated as: <code>&lt;value&gt;</code> * (proportion of free heap space)</p> <p>For example, if <code>-Xsoftrefthreshold</code> is set to 32, and the heap is 25% free, soft references are cleared after 8 GC cycles.</p>"},{"location":"xss/","title":"-Xssi","text":""},{"location":"xss/#-xiss-xss-xssi","title":"-Xiss / -Xss / -Xssi","text":"<p>Sets the stack size and increment for Java\u2122 threads.</p> <p>If you exceed the maximum Java thread stack size, a <code>java/lang/OutOfMemoryError</code> message is reported.</p> <p>You can use the <code>-verbose:sizes</code> option to find out the values that the VM is currently using.</p> <p> Note: Java methods and native methods run on two different stacks and the VM handles switching between them for JNI calls. Each stack is sized using separate options; these options apply to the Java stack only. For the native stack option, see the link in the See also section.</p>"},{"location":"xss/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xiss&lt;size&gt;</code> Set initial Java thread stack size 2 KB <code>-Xss&lt;size&gt;</code> Set maximum Java thread stack size 320 KB (31/32-bit); 1024 KB (64-bit) <code>-Xssi&lt;size&gt;</code> Set Java thread stack size increment 16 KB <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.  </p> <p>See Default settings for the Eclipse OpenJ9\u2122 VM for more about default values.</p>"},{"location":"xss/#see-also","title":"See also","text":"<ul> <li><code>-Xmso</code> (Native stack size for operating system threads)</li> </ul>"},{"location":"xsyslog/","title":"-Xsyslog","text":""},{"location":"xsyslog/#-xsyslog","title":"-Xsyslog","text":"<p>Enables operating system message logging.</p> <p> Notes:</p> <ul> <li>Changes made to message logging by using the <code>-Xsyslog</code> option do not affect messages written to the standard error stream (<code>stderr</code>).</li> <li>This option replaces the Eclipse OpenJ9\u2122 <code>-Xlog</code> option in Eclipse OpenJ9 version 0.24.0. If the <code>-XX:+LegacyXlogOption</code> is set, <code>-Xlog</code> behaves in the same way as <code>-Xsyslog</code> and with the same parameters.</li> </ul>"},{"location":"xsyslog/#syntax","title":"Syntax","text":"<pre><code>    -Xsyslog:&lt;parameter&gt;{,&lt;parameter&gt;}\n</code></pre>"},{"location":"xsyslog/#parameters","title":"Parameters","text":"<p> Restriction: The parameters <code>all</code>, <code>none</code> and <code>help</code> must be used on their own and cannot be combined. However, the other parameters can be grouped. For example, to include error, vital and warning messages use <code>-Xsyslog:error,vital,warn</code>.</p> <p>For message details see OpenJ9 VM messages.</p>"},{"location":"xsyslog/#help","title":"<code>help</code>","text":"<pre><code>    -Xsyslog:help\n</code></pre> Gives details the available parameters. (This parameter cannot be combined with others.)"},{"location":"xsyslog/#error","title":"<code>error</code>","text":"<pre><code>    -Xsyslog:error\n</code></pre> Turns on logging for all OpenJ9 VM error messages (default)."},{"location":"xsyslog/#vital","title":"<code>vital</code>","text":"<pre><code>    -Xsyslog:vital\n</code></pre> Turns on logging for selected information messages <code>JVMDUMP006I</code>, <code>JVMDUMP032I</code>, and <code>JVMDUMP033I</code>, which provide valuable additional information about dumps produced by the OpenJ9 VM (default)."},{"location":"xsyslog/#info","title":"<code>info</code>","text":"<pre><code>    -Xsyslog:info\n</code></pre> Turns on logging for all OpenJ9 VM information messages."},{"location":"xsyslog/#warn","title":"<code>warn</code>","text":"<pre><code>    -Xsyslog:warn\n</code></pre> Turns on logging for all OpenJ9 VM warning messages."},{"location":"xsyslog/#config","title":"<code>config</code>","text":"<pre><code>    -Xsyslog:config\n</code></pre> Turns on logging for all OpenJ9 VM configuration messages."},{"location":"xsyslog/#all","title":"<code>all</code>","text":"<pre><code>    -Xsyslog:all\n</code></pre> Turns on logging for all OpenJ9 VM messages. (This parameter cannot be combined with others.)"},{"location":"xsyslog/#none","title":"<code>none</code>","text":"<pre><code>    -Xsyslog:none\n</code></pre> Turns off logging for all OpenJ9 VM messages. (This parameter cannot be combined with others.)"},{"location":"xtgc/","title":"-Xtgc","text":""},{"location":"xtgc/#-xtgc","title":"-Xtgc","text":"<p>Provides garbage collection tracing options.</p>"},{"location":"xtgc/#syntax","title":"Syntax","text":"<pre><code>    -Xtgc:&lt;parameter&gt;{,&lt;parameter&gt;}\n</code></pre>"},{"location":"xtgc/#parameters","title":"Parameters","text":"Specify one one or more of the following parameters in a comma-separated list:"},{"location":"xtgc/#backtrace","title":"<code>backtrace</code>","text":"<pre><code>    -Xtgc:backtrace\n</code></pre> Before a garbage collection, a single line is printed containing the name of the main thread for garbage collection, as well as the value of the <code>osThread</code> slot in the <code>J9VMThread</code> structure."},{"location":"xtgc/#compaction","title":"<code>compaction</code>","text":"<pre><code>    -Xtgc:compaction\n</code></pre> Prints extra information showing the relative time spent by threads in the \"move\" and \"fixup\" phases of compaction"},{"location":"xtgc/#concurrent","title":"<code>concurrent</code>","text":"<pre><code>    -Xtgc:concurrent\n</code></pre> Prints extra information showing the activity of the concurrent mark background thread"},{"location":"xtgc/#dump","title":"<code>dump</code>","text":"<pre><code>    -Xtgc:dump\n</code></pre> Prints a line of output for every free chunk of memory in the system, including \"dark matter\" (free chunks that are not on the free list for some reason, typically because they are too small). Each line contains the base address and the size in bytes of the chunk. If the chunk is followed in the heap by an object, the size and class name of the object is also printed. This argument has a similar effect to the <code>terse</code> argument."},{"location":"xtgc/#file","title":"<code>file</code>","text":"<pre><code>    -Xtgc:file=&lt;filename&gt;\n</code></pre> Directs the logs to a file. Otherwise they are directed to stderr."},{"location":"xtgc/#freelist","title":"<code>freeList</code>","text":"<pre><code>    -Xtgc:freeList\n</code></pre> Before a garbage collection, prints information about the free list and allocation statistics since the last garbage collection. Prints the number of items on the free list, including \"deferred\" entries (with the scavenger, the unused space is a deferred free list entry). For TLH and non-TLH allocations, prints the total number of allocations, the average allocation size, and the total number of bytes discarded during allocation. For non-TLH allocations, also included is the average number of entries that were searched before a sufficiently large entry was found."},{"location":"xtgc/#parallel","title":"<code>parallel</code>","text":"<pre><code>    -Xtgc:parallel\n</code></pre> Produces statistics on the activity of the parallel threads during each operation (mark, sweep, scavenge etc.) of a GC cycle."},{"location":"xtgc/#rootscantime","title":"<code>rootscantime</code>","text":"<pre><code>    -Xtgc:rootscantime\n</code></pre> Prints duration of strong and weak roots scanning of a GC cycle."},{"location":"xtgc/#scavenger","title":"<code>scavenger</code>","text":"<pre><code>    -Xtgc:scavenger\n</code></pre> Prints extra information after each scavenger collection. A histogram is produced showing the number of instances of each class, and their relative ages, present in the survivor space. The information is obtained by performing a linear walk-through of the space."},{"location":"xtgc/#terse","title":"<code>terse</code>","text":"<pre><code>    -Xtgc:terse\n</code></pre> Dumps the contents of the entire heap before and after a garbage collection. For each object or free chunk in the heap, a line of trace output is produced. Each line contains the base address, \"a\" if it is an allocated object, and \"f\" if it is a free chunk, the size of the chunk in bytes, and, if it is an object, its class name."},{"location":"xthr/","title":"-Xthr","text":""},{"location":"xthr/#-xthr","title":"-Xthr","text":""},{"location":"xthr/#syntax","title":"Syntax","text":"<pre><code>    -Xthr:&lt;parameter&gt;\n</code></pre>"},{"location":"xthr/#parameters","title":"Parameters","text":""},{"location":"xthr/#adaptspin-noadaptspin","title":"<code>AdaptSpin</code> | <code>noAdaptSpin</code>","text":"<pre><code>    -Xthr:AdaptSpin\n    -Xthr:noAdaptSpin\n</code></pre> This tuning option is available to test whether performance optimizations are negatively impacting an application."},{"location":"xthr/#fastnotify-nofastnotify","title":"<code>fastNotify</code> | <code>noFastNotify</code>","text":"<pre><code>    -Xthr:fastNotify\n    -Xthr:noFastNotify\n</code></pre> When a large number of threads try to acquire a Java\u2122 monitor, throughput of an application can be reduced. This issue is known as high contention. If high contention occurs when the Java <code>wait</code> and <code>notify</code> features are regularly used, you can use <code>-Xthr:fastNotify</code> to increase throughput. However, <code>-Xthr:noFastNotify</code> is the default setting, because it is faster in all other scenarios."},{"location":"xthr/#cfsyield-nocfsyield-linux-only","title":"<code>cfsYield</code> | <code>noCfsYield</code> (Linux\u00ae only)","text":"<pre><code>    -Xthr:cfsYield\n    -Xthr:noCfsYield\n</code></pre> The default value, <code>cfsYield</code>, enables threading optimizations for running on Linux with the Completely Fair Scheduler (CFS) in the default mode (<code>sched_compat_yield=0</code>). The <code>noCfsYield</code> value disables these threading optimizations. You might want to use the <code>noCfsYield</code> value if your application uses the <code>Thread.yield()</code> method extensively, because otherwise you might see a performance decrease in cases where yielding is not beneficial."},{"location":"xthr/#minimizeusercpu","title":"<code>minimizeUserCPU</code>","text":"<pre><code>    -Xthr:minimizeUserCPU\n</code></pre> Minimizes user-mode CPU usage in thread synchronization where possible. The reduction in CPU usage might be a trade-off in exchange for decreased performance."},{"location":"xthr/#secondaryspinforobjectmonitors-nosecondaryspinforobjectmonitors","title":"<code>secondarySpinForObjectMonitors</code> | <code>noSecondarySpinForObjectMonitors</code>","text":"<pre><code>    -Xthr:secondarySpinForObjectMonitors\n    -Xthr:noSecondarySpinForObjectMonitors\n</code></pre> This tuning option is available to test whether performance optimizations are negatively impacting an application."},{"location":"xtlhprefetch/","title":"-XtlhPrefetch","text":""},{"location":"xtlhprefetch/#-xtlhprefetch","title":"-XtlhPrefetch","text":"<p>(AIX\u00ae, Windows\u2122 only)</p> <p>Speculatively prefetches bytes in the thread local heap (TLH) ahead of the current allocation pointer during object allocation. This option helps reduce the performance cost of subsequent allocations.</p>"},{"location":"xtlhprefetch/#syntax","title":"Syntax","text":"<pre><code>    -XtlhPrefetch\n</code></pre> <p>This option can be used with all Eclipse OpenJ9\u2122 GC policies.</p>"},{"location":"xtrace/","title":"-Xtrace","text":""},{"location":"xtrace/#-xtrace","title":"-Xtrace","text":"<p>Eclipse OpenJ9\u2122 VM tracing is a powerful feature to help you diagnose problems with minimal effect on performance. Tracing is enabled by default, together with a small set of trace points going to memory buffers. You can enable tracepoints at run time by using levels, components, group names, or individual tracepoint identifiers to trace VM internal operations and instrumented Java\u2122 applications. You can also trace Java methods. See the About trace section that follows for more detail.</p> <p>Trace data can be output in human-readable or in compressed binary formats. The VM provides a tool to process and convert the compressed binary data into a readable format. See Trace formatter.</p> <p> Note: You can also control trace by using the <code>com.ibm.jvm.Trace</code> API or by using JVMTI from an external agent.</p>"},{"location":"xtrace/#xtrace-option-builder","title":"Xtrace Option Builder","text":"<p>Use the Xtrace Option Builder tool to help you specify the correct options and avoid incompatibilities.</p>"},{"location":"xtrace/#syntax","title":"Syntax","text":"<pre><code>-Xtrace:&lt;parameter&gt;\n</code></pre> <p>You can get help with <code>-Xtrace</code>by using the following options:</p> <ul> <li><code>-Xtrace:help</code> \u00a0 Displays general trace help</li> <li><code>-Xtrace:what</code> \u00a0 Shows the current trace settings</li> </ul>"},{"location":"xtrace/#configuring-trace","title":"Configuring trace","text":"<p>The following parameters can be used to configure trace. (Follow links for more information about individual options.)</p> Command Result <code>-Xtrace:properties[=&lt;filename&gt;]</code> Configures trace options based on a file <code>-Xtrace:buffers=&lt;size&gt;[dynamic\\|nodynamic]</code> Modifies the size of buffers that are used to store trace data <code>-Xtrace:exception.output=&lt;filename&gt;[,&lt;size&gt;]</code> Redirects exceptions trace data to a file. <code>-Xtrace:methods=&lt;method_specification&gt;</code> Traces methods <code>-Xtrace:output=&lt;filename&gt;[,&lt;size&gt;[,&lt;generations&gt;]]</code> Sends trace data to a file, optionally of a specific size and number of generations. <code>-Xtrace:resume</code> Resumes tracing globally. <code>-Xtrace:resumecount=&lt;count&gt;</code> Enables tracing at a thread level after a specified count. <code>-Xtrace:sleeptime=&lt;time&gt;</code> Pauses trace operations for a specified length of time. <code>-Xtrace:stackdepth=&lt;n&gt;</code> Limits the maximum number of stack frames reported by the jstacktrace trace trigger action. <code>-Xtrace:suspend</code> Suspends tracing globally. <code>-Xtrace:suspendcount=&lt;count&gt;</code> Suspends tracing at a thread level after a specified count. <code>-Xtrace:trigger=&lt;clause&gt;</code> Determines when various triggered trace actions occur, including turning trace on or off. <p> Note: If an option value contains commas, it must be enclosed in braces. For example: <code>methods={java/lang/*,com/ibm/*}</code></p>"},{"location":"xtrace/#controlling-tracepoint-activation","title":"Controlling tracepoint activation","text":"<p>The following parameters can be used to control tracepoint activation. (Follow links for more information about individual options.)</p> Command Result <code>-Xtrace:maximal=&lt;tracepoint_specification&gt;</code> Records all associated data. <code>-Xtrace:minimal=&lt;tracepoint_specification&gt;</code> Records only the time stamp and tracepoint identifier. <code>-Xtrace:count=&lt;tracepoint_specification&gt;</code> Counts the tracepoints that are used in a trace configuration. <code>-Xtrace:print=&lt;tracepoint_specification&gt;</code> Prints the specified tracepoints to stderr in real time. <code>-Xtrace:iprint=&lt;tracepoint_specification&gt;</code> Prints the specified tracepoints to stderr in real time with indentation. <code>-Xtrace:exception=&lt;tracepoint_specification&gt;</code> Enables exception tracing. <code>-Xtrace:external&lt;tracepoint_specification&gt;</code> Routes trace data to trace listeners, which are registered by using the JVMTI APIs. <code>-Xtrace:none[=&lt;tracepoint_specification&gt;]</code> Prevents the trace engine from loading if it is the only trace option specified. <p> Note: These options control which individual tracepoints are activated at run time and the implicit destination of the trace data. All these properties are independent of each other and can be mixed and matched in any way that you choose. For more information, see Tracepoint activation.</p>"},{"location":"xtrace/#about-trace","title":"About trace","text":"<p>With the OpenJ9 trace feature, you can trace VM internal operations, Java applications, and Java methods, or any combination of these.</p> VM internal operations The OpenJ9 virtual machine (VM) is extensively instrumented with tracepoints for tracing operations. Interpreting this trace data requires detailed knowledge of the VM, and is intended to diagnose VM problems. No guarantee is given that tracepoints will not vary from release to release and from platform to platform. Applications VM trace contains an application trace facility that allows tracepoints to be placed in Java code, enabling you to combine trace data with the other forms of trace. This capability is supported by the <code>com.ibm.jvm.Trace</code> API. Note that an instrumented Java application runs only on an OpenJ9 VM. For more information, see Application trace. Java methods Use method trace to debug and trace application code and the system classes provided with the VM. You can trace entry to and exit from Java methods run by the VM. You can select method trace by classname, method name, or both. You can also use wildcards to create complex method selections. For more information about command syntax, see methods. <p>Trace can produce large amounts of data in a very short time. Before running trace, think carefully about what information you need in order to solve the problem. Here are some considerations:</p> <ul> <li>If you need only the trace information that is produced shortly before the problem occurs, consider wrapping the file by using the <code>output</code> option.</li> <li>In many cases, just use internal trace with an increased buffer size and snap the trace when the problem occurs.</li> <li>If the problem results in a thread stack dump or operating system signal or exception, trace buffers are snapped automatically to a file that is in the current directory. The file is called: <code>Snapnnnn. yyyymmdd.hhmmssth.process.trc</code>.</li> </ul> <p>You must also think carefully about which components need to be traced and what level of tracing is required. For example, if you are tracing a suspected shared classes problem, it might be enough to trace all components at level 1, and j9shr at level 9, while <code>maximal</code> can be used to show parameters and other information for the failing component. Tracepoint components and trace levels are described in the following sections: Tracepoint specification and Trace levels.</p> <p>There are two types of tracepoints inside the VM:</p> <ul> <li>Regular tracepoints include method tracepoints, application tracepoints, data tracepoints inside the VM and data tracepoints inside class libraries. You can display regular tracepoint data on the screen or save the data to a file. You can also use command line options to trigger specific actions when regular tracepoints fire.</li> <li>Auxiliary tracepoints are a special type of tracepoint that can be fired only when another tracepoint is being processed. For example, the stack frame information produced by the jstacktrace <code>-Xtrace:trigger</code> command. You cannot control where auxiliary tracepoint data is sent and you cannot set triggers on auxiliary tracepoints. Auxiliary tracepoint data is sent to the same destination as the tracepoint that caused them to be generated.</li> </ul> <p>Trace data can be written to one of the following locations:</p> <ul> <li>Memory buffers that can be dumped or snapped when a problem occurs. Use the <code>-Xtrace:buffers=&lt;size&gt;</code> option to control the size of the buffer allocated to each thread. Buffers allocated to a thread are discarded when that thread terminates. To examine the trace data captured in these memory buffers, you must snap or dump the data. Use the <code>-Xdump:snap</code> option to vary the events that cause a snap trace file to be produced. When produced, format the buffers by using the trace formatter.</li> <li>One or more files that are using buffered I/O. Use the <code>-Xtrace:output</code> option.</li> <li>An external agent in real time, using the <code>-Xtrace:external</code> option.</li> <li><code>stderr</code> in real time.</li> <li>Any combination of the other items in this list.</li> </ul>"},{"location":"xtrace/#default-tracing","title":"Default tracing","text":"<p>By default, the equivalent of the following trace command line is always available in the VM:</p> <pre><code>-Xtrace:maximal=all{level1},exception=j9mm{gclogger}\n</code></pre> <p>When startup is complete, the equivalent of the following command line is added to enable level 2 trace points:</p> <pre><code>-Xtrace:maximal=all{level2}\n</code></pre> <p>Level 2 is used for default tracing that would produce too much data during the startup of the VM. If you set other trace options on the command line, or before the VM finishes startup (through use of JVMTI or the <code>com.ibm.jvm.Trace</code> API), the level 2 trace points are enabled just before your trace options are processed. This behavior ensures that the default level 2 trace points do not override any changes that you specify.</p> <p>The data generated by the tracepoints is continuously captured in wrapping memory buffers for each thread.</p> <p>You can find tracepoint information in the following diagnostics data:</p> <ul> <li>System memory dumps, extracted by using jdmpview.</li> <li>Snap traces, generated when the VM encounters a problem or an output file is specified. Using dump agents describes more ways to create a snap trace.</li> <li>For exception trace only, in Javadumps.</li> </ul>"},{"location":"xtrace/#default-memory-management-tracing","title":"Default memory management tracing","text":"<p>The default trace options are designed to ensure that Javadumps always contain a record of the most recent memory management history, regardless of how much work the VM has performed since the garbage collection cycle was last called.</p> <p>The <code>exception=j9mm{gclogger}</code> clause of the default trace set specifies that a history of garbage collection cycles that have occurred in the VM is continuously recorded. The gclogger group of tracepoints in the j9mm component constitutes a set of tracepoints that record a snapshot of each garbage collection cycle. These tracepoints are recorded in their own separate buffer, called the exception buffer. The effect is that the tracepoints are not overwritten by the higher frequency tracepoints of the VM.</p> <p>The GC History section of the Javadump is based on the information in the exception buffer. If a garbage collection cycle has occurred in a traced VM, the Java dump probably contains a GC History section.</p>"},{"location":"xtrace/#default-assertion-tracing","title":"Default assertion tracing","text":"<p>The VM includes assertions, implemented as special trace points. By default, internal assertions are detected and diagnostics logs are produced to help assess the error.</p> <p>Assertion failures often indicate a serious problem, and the VM usually stops immediately. In these circumstances, raise an issue, including the standard error output and any diagnostic files that are produced.</p> <p>When an assertion trace point is reached, a message like the following output is produced on the standard error stream:</p> <pre><code>16:43:48.671 0x10a4800    j9vm.209    *   ** ASSERTION FAILED ** at jniinv.c:251:\n((javaVM == ((void *)0)))\n</code></pre> <p>This error stream is followed with information about the diagnostic logs produced:</p> <pre><code>JVMDUMP007I JVM Requesting System Dump using 'core.20060426.124348.976.dmp'\nJVMDUMP010I System Dump written to core.20060426.124348.976.dmp\nJVMDUMP007I JVM Requesting Snap Dump using 'Snap0001.20060426.124648.976.trc'\nJVMDUMP010I Snap Dump written to Snap0001.20060426.124648.976.trc\n</code></pre> <p>Assertions are special trace points. They can be enabled or disabled by using the standard trace command-line options.</p> <p>Assertion failures might occur early during VM startup, before trace is enabled. In this case, the assert message has a different format, and is not prefixed by a timestamp or thread ID. For example:</p> <pre><code>** ASSERTION FAILED ** j9vmutil.15 at thrinfo.c:371 Assert_VMUtil_true((\n  publicFlags &amp; 0x200))\n</code></pre> <p>Assertion failures that occur early during startup cannot be disabled. These failures do not produce diagnostic dumps, and do not cause the VM to stop.</p>"},{"location":"xtrace/#tracepoint-activation","title":"Tracepoint activation","text":"<p>The options that control which individual tracepoints are activated at run time and the implicit destination of the trace data are listed under Syntax: Controlling tracepoint activation</p> <p>In some cases, you must use them with other options. For example, if you specify <code>maximal</code> or <code>minimal</code> tracepoints, the trace data is put into memory buffers. If you are going to send the data to a file, you must use an <code>output</code> option to specify the destination file name.</p> <p>With the exception of <code>none</code>, all options require at least one <code>&lt;tracepoint_specification&gt;</code>, which is described in the following section. Multiple statements of each type of trace are allowed and their effect is cumulative. If you want to use multiple trace options of the same name, use a properties file. (See <code>properties</code>.)</p>"},{"location":"xtrace/#tracepoint-specification","title":"Tracepoint specification","text":"<p>Tracepoints are enabled by specifying component and tracepoint.</p> <p>If no qualifier parameters are entered, all tracepoints are enabled, except for <code>&lt;exception.output&gt;</code> trace, where the default is all {exception}.</p> <p>The <code>&lt;tracepoint_specification&gt;</code> syntax can be further broken down as follows:</p> <pre><code>[!]&lt;component&gt;[{&lt;group&gt;}] or [!]&lt;component&gt;[{&lt;type&gt;}] or [!]&lt;tracepoint_id&gt;[,&lt;tracepoint_id&gt;]\n</code></pre> <p>Where:</p> <ul> <li>The <code>!</code> symbol is a logical not. That is, the tracepoints that are in a specification starting with ! are turned off.</li> <li><code>&lt;component&gt;</code> is a Java component.</li> <li><code>&lt;group&gt;</code> is a tracepoint group, which is a set of tracepoints that are defined within a component.</li> <li><code>&lt;type&gt;</code> is the tracepoint type: <code>entry</code>, <code>exit</code>, <code>event</code>, <code>exception</code>, and <code>mem</code>.</li> <li><code>&lt;tracepoint_id&gt;</code> is the tracepoint identifier. The tracepoint identifier constitutes the component name of the tracepoint, followed by its integer number inside that component. For example, <code>j9mm.49</code>, <code>j9shr.20-29</code>, <code>j9vm.15</code>. To understand these numbers, see Determining the tracepoint ID of a tracepoint.</li> </ul> <p>Some tracepoints can be both an <code>exit</code> and an <code>exception</code>; that is, the function ended with an error. If you specify either <code>exit</code> or <code>exception</code>, these tracepoints are included.</p> <p>Lists of Java components and tracepoint groups can be found in the tables that follow.</p> <p>The following table lists the possible Java components (<code>&lt;component&gt;</code>). To include all Java components, specify all.</p> Component name Description avl VM AVL tree support io Class library java.io native code j9bcu VM byte code utilities j9bcverify VM byte code verification j9codertvm VM byte code run time j9dmp VM dump j9jcl VM class libraries j9jit VM JIT interface j9jni VM JNI support j9jvmti VM JVMTI support j9mm VM memory management j9prt VM port library j9scar VM class library interface j9shr VM shared classes j9trc VM trace j9util VM utilities j9vm VM general j9vmutil VM utilities j9vrb VM verbose stack walker map VM mapped memory support mt Java methods (see Note) net Class library TCP/IP networking native code pool VM storage pool support rpc VM RPC support simplepool VM storage pool support sunvmi VM class library interface <p> Note: When specifying the mt component you must also specify the <code>methods</code> option.</p> <p>The following table lists all the tracepoint groups (<code>&lt;group&gt;</code>). Each group is associated with one or more Java components:</p> Component name or names Group name Description j9mm <code>gclogger</code> A set of tracepoints that record each garbage collection cycle. Equivalent to <code>-verbose:gc</code> output j9prt <code>nlsmessage</code> A set of tracepoints that record each NLS message that is issued by the VM. j9jcl, j9vm <code>verboseclass</code> A set of tracepoints that record each class as it is loaded. Equivalent to <code>-verbose:class</code> output. j9jni, j9vm <code>checkjni</code> A set of tracepoints that record JNI function checks. Equivalent to <code>-Xcheck:jni</code> output. j9vm <code>checkmemory</code> A set of tracepoints that record memory checks. Equivalent to <code>-Xcheck:memory</code> output. j9vm <code>checkvm</code> A set of tracepoints that record VM checks. Equivalent to <code>-Xcheck:vm</code> output. j9jit <code>verbose</code> A set of tracepoints that record JIT compiler configuration and method compilation. Equivalent to <code>-Xjit:verbose</code> output. mt <code>compiledMethods</code> A set of tracepoints that record compiled Java methods. mt <code>nativeMethods</code> A set of tracepoints that record Java native methods. mt <code>staticMethods</code> A set of tracepoints that record Java static methods. <p>Here are some examples:</p> <p>To trace all tracepoints, specify the following command:</p> <pre><code>-Xtrace:maximal=all\n</code></pre> <pre><code>To trace all tracepoints except **j9vrb** and **j9trc**, specify the following command:\n\n    -Xtrace:minimal={all},minimal={!j9vrb,j9trc}\n</code></pre> <p>To trace all entry and exit tracepoints in j9bcu, specify the following command:</p> <pre><code>-Xtrace:maximal={j9bcu{entry},j9bcu{exit}}\n</code></pre> <pre><code>To trace all tracepoints in **j9mm** except tracepoints 20-30, specify the following command:\n\n    -Xtrace:maximal=j9mm,maximal=!j9mm.20-30\n</code></pre> <p>To trace tracepoints <code>j9prt.5</code> through <code>j9prt.15</code>, specify the following command:</p> <pre><code>-Xtrace:print=j9prt.5-15\n</code></pre> <pre><code>To trace all **j9trc** tracepoints, specify the following command:\n\n    -Xtrace:count=j9trc\n</code></pre> <p>To trace all <code>entry</code> and <code>exit</code> tracepoints, specify the following command:</p> <pre><code>-Xtrace:external={all{entry},all{exit}}\n</code></pre>"},{"location":"xtrace/#trace-levels","title":"Trace levels","text":"<p>Tracepoints have been assigned levels 0 through 9 that are based on the importance of the tracepoint.</p> <p>A level 0 tracepoint is the most important. It is reserved for extraordinary events and errors. A level 9 tracepoint is in-depth component detail. To specify a given level of tracing, the <code>level0</code> through <code>level9</code> keywords are used. You can abbreviate these keywords to l0 through l9. For example, if <code>level5</code> is selected, all tracepoints that have levels 0 through 5 are included. Level specifications do not apply to explicit tracepoint specifications that use the TPNID keyword.</p> <p>The level is provided as a modifier to a component specification, for example:</p> <pre><code>-Xtrace:maximal={all{level5}}\n</code></pre> <p>or</p> <pre><code>-Xtrace:maximal={j9mm{L2},j9trc,j9bcu{level9},all{level1}}\n</code></pre> <p>In the first example, tracepoints that have a level of 5 or less are enabled for all components. In the second example, all level 1 tracepoints are enabled. All level 2 tracepoints in j9mm are enabled. All tracepoints up to level 9 are enabled in j9bcu.</p> <p> Note: The level applies only to the current component. If multiple trace selection components are found in a trace properties file, the level is reset to the default for each new component. Level specifications do not apply to explicit tracepoint specifications that use the TPNID keyword.</p> <p>When the not operator is specified, the level is inverted; that is, <code>!j9mm{level5}</code> disables all tracepoints of level 6 or greater for the j9mm component. The following example enables trace for all components at level 9 (the default), but disables level 6 and higher for the locking component, and level 7 and higher for the storage component:</p> <pre><code>-Xtrace:print={all},print={!j9trc{l5},j9mm{l6}}\n</code></pre> <p>Here are some examples:</p> <p>To count the level zero and level one tracepoints matched, specify the following command:</p> <pre><code>-Xtrace:count=all{L1}\n</code></pre> <p>To produce maximal trace of all components at level 5 and j9mm at level 9, specify the following command:</p> <pre><code>-Xtrace:maximal={all{level5},j9mm{L9}}\n</code></pre> <p>To trace all components at level 6, but do not trace <code>j9vrb</code> at all, and do not trace the <code>entry</code> and <code>exit</code> tracepoints in the j9trc component, specify the following command:</p> <pre><code>-Xtrace:minimal={all{l6}},minimal={!j9vrb,j9trc{entry},j9trc{exit}}\n</code></pre>"},{"location":"xtrace/#parameters","title":"Parameters","text":"<p>Parameters to use with the <code>-Xtrace</code> option:</p>"},{"location":"xtrace/#buffers","title":"<code>buffers</code>","text":"<p>You can modify the size of the buffers to change how much diagnostic output is provided in a snap dump. This buffer is allocated for each thread that makes trace entries. The following table shows how this parameter can be set:</p> Command Effect <code>-Xtrace:buffers=&lt;size&gt;</code> Creates buffers of the specified <code>&lt;size&gt;</code> in k (KB) or m (MB), allocated as needed to match the rate of trace data generation to the output media. <code>-Xtrace:buffers=&lt;size&gt;dynamic</code> Creates buffers of the specified <code>&lt;size&gt;</code>, allocated as needed to match the rate of trace data generation to the output media. <code>-Xtrace:buffers=&lt;size&gt;nodynamic</code> Creates buffers of the specified <code>&lt;size&gt;</code>, with a maximum allocation of two buffers per thread. <p>If external trace is enabled, the number of buffers is doubled; that is, each thread allocates two or more buffers. The same buffer size is used for state and exception tracing, but, in this case, buffers are allocated globally. The default is 8 KB per thread.</p> <p>The <code>dynamic</code> and <code>nodynamic</code> suboptions have meaning only when tracing to an output file.</p> <p> Note: If <code>nodynamic</code> is specified, you might lose trace data if the volume of trace data exceeds the bandwidth of the trace output file. Message UTE115 is issued when the first trace entry is lost, and message UTE018 is issued when the VM ends.</p> <p>Here are some command line examples:</p> <p>To set a buffer size of 2 MB per thread, with dynamic buffering, use:</p> <pre><code>-Xtrace:buffers=2m\n</code></pre> <p>To limit each thread to 2 trace buffers, each of 128 KB:</p> <pre><code>-Xtrace:buffers={128k,nodynamic}\n</code></pre>"},{"location":"xtrace/#count-tracepoint","title":"<code>count</code> (tracepoint)","text":"<pre><code>-Xtrace:count=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The count option requests that only a count of the selected tracepoints is kept. When the VM ends, all nonzero totals of tracepoints (sorted by tracepoint id) are written to a file, called <code>utTrcCounters</code>, in the current directory. This information is useful if you want to determine the overhead of particular tracepoints, but do not want to produce a large amount (GB) of trace data.</p> <p>For example, to count the tracepoints that are used in the default trace configuration, use the following command:</p> <pre><code>-Xtrace:count=all{level1},count=j9mm{gclogger}\n</code></pre>"},{"location":"xtrace/#exception-tracepoint","title":"<code>exception</code> (tracepoint)","text":"<pre><code>-Xtrace:exception=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>When exception trace is enabled, the trace data is collected in internal buffers that are separate from the normal buffers. These internal buffers can then be written to a snap file or written to the file that is specified in an <code>exception.output</code> option.</p> <p>The <code>exception</code> option allows low-volume tracing in buffers and files that are distinct from the higher-volume information that <code>minimal</code> and <code>maximal</code> tracing have provided. In most cases, this information is exception-type data, but you can use this option to capture any trace data that you want.</p> <p>This form of tracing is channeled through a single set of buffers, as opposed to the buffer-per-thread approach for normal trace. Buffer contention might occur if high volumes of trace data are collected. A difference exists in the <code>&lt;tracepoint_specification&gt;</code> defaults for exception tracing;  see Tracepoint specification.</p> <p> Notes:</p> <ul> <li>The exception trace buffers are intended for low-volume tracing. By default, the exception trace buffers log garbage collection (GC) event tracepoints, see Default tracing. You can send additional tracepoints to the exception buffers or turn off the GC tracepoints. Changing the exception trace buffers alters the contents of the GC History section in any Javadumps.</li> <li>When exception trace is entered for an active tracepoint, the current thread ID is checked against the previous caller's thread ID. If it is a different thread, or this is the first call to exception trace, a context tracepoint is put into the trace buffer first. This context tracepoint consists only of the current thread ID, which is necessary because of the single set of buffers for exception trace. (The formatter identifies all trace entries as coming from the Exception trace pseudo thread when it formats exception trace files.)</li> </ul>"},{"location":"xtrace/#exceptionoutput","title":"<code>exception.output</code>","text":"<p>Use exception output to redirect exceptions trace data to a file.</p> <pre><code>-Xtrace:exception.output=&lt;filename&gt;[,&lt;size&gt;]\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;filename&gt;</code> is a file name, which is created automatically if it does not exist. Otherwise, it is overwritten. To embed specific values in the file name use any of the following variables: %d (today's date in \" yyyymmdd\" format), %p (process ID number of the process generating the trace), or %t (time in 24-hour hhmmss format).</li> <li>Optionally, <code>&lt;size&gt;</code> is a value in megabytes (MB), for example, use 4m to specify 4 MB. When full, it wraps nondestructively to the beginning. If you do not limit the file, it grows indefinitely, until limited by disk space.</li> </ul> <p>Here are some examples:</p> <p>Exception trace output goes to file <code>/u/traces/exception.trc</code> with no size limit:</p> <pre><code>-Xtrace:exception.output=/u/traces/exception.trc,maximal\n</code></pre> <p>Exception trace output goes to file <code>except</code> and wraps at 2 MB:</p> <pre><code>-Xtrace:exception.output={except,2m},maximal\n</code></pre> <p>Exception trace output goes to a file whose filename contains today's date in * yyyymmdd* format (for example, <code>traceout.20181025.trc</code>):</p> <pre><code>-Xtrace:exception.output=traceout.%d.trc,maximal\n</code></pre> <p>Exception trace output goes to a file whose filename contains the number of the process (the PID number) that generated it (for example, <code>tracefrompid2112.trc</code>):</p> <pre><code>-Xtrace:exception.output=tracefrompid%p.trc,maximal\n</code></pre> <p>Exception trace output goes to a file whose filename contains the time in hhmmss format (for example, <code>traceout.080312.trc</code>):</p> <pre><code>-Xtrace:exception.output=traceout.%t.trc,maximal\n</code></pre>"},{"location":"xtrace/#external-tracepoint","title":"<code>external</code> (tracepoint)","text":"<pre><code>-Xtrace:external&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The <code>external</code> option routes trace data to trace listeners, which are registered by using the JVMTI <code>RegisterTracePointSubscriber()</code> and <code>DeregisterTracePointSubscriber()</code> APIs.</p>"},{"location":"xtrace/#help","title":"<code>help</code>","text":"<pre><code>-Xtrace:help\n</code></pre> <p>Displays general trace help</p>"},{"location":"xtrace/#iprint-tracepoint","title":"<code>iprint</code> (tracepoint)","text":"<pre><code>-Xtrace:iprint=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The <code>iprint</code> option is the same as the <code>print</code> option, but uses indenting to format the trace.</p>"},{"location":"xtrace/#maximal-tracepoint","title":"<code>maximal</code> (tracepoint)","text":"<pre><code>-Xtrace:maximal=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>When specified, trace data is placed into internal trace buffers that can then be written to a snap file or written to the files that are specified in an output trace option. All associated data is traced.</p> <p><code>minimal</code> and <code>maximal</code> traces are independent from any types that follow them. For example, if the <code>maximal</code> option is specified, it does not affect a later option such as <code>print</code>.</p>"},{"location":"xtrace/#methods","title":"<code>methods</code>","text":"<p>Using method trace provides a complete and potentially large diagnosis of code paths inside your application and the system classes. Use wild cards and filtering to control method trace so that you can focus on the sections of code that interest you. Note that method trace is powerful but it also has a cost. Application throughput is affected by method trace.</p> <p>To specify one or more method specifications, use the following syntax:</p> <pre><code>-Xtrace:methods=&lt;method_specification&gt;[,&lt;method_specification&gt;]\n</code></pre> <p>The syntax for <code>&lt;method_specification&gt;</code> can be further broken down to the following suboptions:</p> <pre><code>-Xtrace:methods={[!][*][&lt;package&gt;/]&lt;class&gt;[*],[[*]&lt;method&gt;[*]|[()]]}\n</code></pre> <p>Where:</p> <ul> <li>The delimiter between parts of the package name is a forward slash, \"/\".</li> <li>The ! in the methods parameter is a NOT operator that allows you to tell the VM not to trace the specified method or methods.</li> <li>The parentheses, (), define whether or not to include method parameters in the trace.</li> <li>If a method specification includes any commas, the whole specification must be enclosed in braces, for example: <code>-Xtrace:methods={java/lang/*,java/util/*},print=mt</code></li> <li>It might be necessary to enclose your command line in quotation marks to prevent the shell intercepting and fragmenting comma-separated command lines, for example: <code>\"-Xtrace:methods={java/lang/*,java/util/*},print=mt\"</code></li> </ul> <p>To output all method trace information to stderr, use either the <code>print</code> or <code>iprint</code> suboptions:</p> <pre><code>-Xtrace:print=mt,methods=*.*\n-Xtrace:iprint=mt,methods=*.*\n</code></pre> <p>The <code>iprint</code> suboption prints to stderr with indentation. To output method trace information in binary format, see the <code>output</code> option</p> <p>Internal Native Library (INL) native methods inside the VM cannot be traced because they are not implemented by using JNI. The list of methods that are not traceable is subject to change without notice.</p> <p>Here are some examples:</p> <p>Tracing entry and exit of all methods in a given class: To trace all method entry and exit of the <code>ReaderMain</code> class in the default package and the <code>java.lang.String</code> class, specify the following command:</p> <pre><code>-Xtrace:methods={ReaderMain.*,java/lang/String.*},print=mt\n</code></pre> <p>Tracing entry, exit and input parameters of all methods in a class: To trace all method entry, exit, and input of the <code>ReaderMain</code> class in the default package, specify the following command:</p> <pre><code>-Xtrace:methods=ReaderMain.*(),print=mt\n</code></pre> <p>Tracing all methods in a given package: To trace all method entry, exit, and input of all classes in the package <code>com.ibm.socket</code>, specify the following command:</p> <pre><code>-Xtrace:methods=com/ibm/socket/*.*(),print=mt\n</code></pre> <p>Multiple method trace: To trace all method entry, exit, and input in the <code>Widget</code> class in the default package and all method entry and exit in the <code>common</code> package, specify the following command:</p> <pre><code>-Xtrace:methods={Widget.*(),common/*},print=mt\n</code></pre> <p>Using the ! operator: To trace all methods in the <code>ArticleUI</code> class in the default package except those beginning with \"get\", specify the following command:</p> <pre><code>-Xtrace:methods={ArticleUI.*,!ArticleUI.get*},print=mt\n</code></pre> <p>Tracing a specific method in a class: This example traces entry and exit of the substring method of the <code>java.lang.String class</code>. If there is more than one method with the same name, they are all traced. You cannot filter method trace by the signature of the method.</p> <pre><code>-Xtrace:print=mt,methods={java/lang/String.substring}\n</code></pre> <p>Tracing the constructor of a class: This example traces entry and exit of the constructors of the <code>java.lang.String</code> class.</p> <pre><code>-Xtrace:print=mt,methods={java/lang/String.&lt;init&gt;}\n</code></pre> <p>Here is some example output:</p> <pre><code>java \"-Xtrace:methods={java/lang*.*},iprint=mt\" HW\n10:02:42.281*0x9e900      mt.4         &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4          &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4           &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4            &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10           &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10          &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4           &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10          &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.10         &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4          &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.281 0x9e900      mt.4           &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.10          &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.10         &lt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4          &gt; java/lang/String.&lt;clinit&gt;()V Compiled static method\n10:02:42.296 0x9e900      mt.4           &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4            &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4             &gt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.10            &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.296 0x9e900      mt.4             &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10            &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10           &lt; java/lang/J9VMInternals.verify(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.4            &gt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10           &lt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.4            &gt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10           &lt; java/lang/J9VMInternals.setInitStatus(Ljava/lang/Class;I)\n                              V Compiled static method\n10:02:42.328 0x9e900      mt.10          &lt; java/lang/J9VMInternals.initialize(Ljava/lang/Class;)\n                              V Compiled static method\n</code></pre> <p>The output lines comprise of:</p> <ul> <li><code>0x9e900</code>, the current <code>execenv</code> (execution environment). Because every VM thread has its own <code>execenv</code>, you can regard <code>execenv</code> as a <code>thread-id</code>. All trace with the same <code>execenv</code> relates to a single thread.</li> <li>The individual tracepoint ID in the mt component that collects and emits the data.</li> <li>The remaining fields show whether a method is being entered (&gt;) or exited (&lt;), followed by details of the method.</li> </ul>"},{"location":"xtrace/#minimal-tracepoint","title":"<code>minimal</code> (tracepoint)","text":"<pre><code>-Xtrace:minimal=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>When specified, trace data is placed into internal trace buffers that can then be written to a snap file or written to the files that are specified in an output trace option. Only the time stamp and tracepoint identifier are recorded. When the trace is formatted, missing trace data is replaced with the characters \"???\" in the output file.</p> <p><code>minimal</code> and <code>maximal</code> traces are independent from any types that follow them. For example, if the <code>minimal</code> option is specified, it does not affect a later option such as <code>print</code>.</p>"},{"location":"xtrace/#none-tracepoint","title":"<code>none</code> (tracepoint)","text":"<pre><code>-Xtrace:none[=&lt;tracepoint_specification&gt;]\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p><code>-Xtrace:none</code> prevents the trace engine from loading if it is the only trace option specified. However, if other <code>-Xtrace</code> options are on the command line, it is treated as the equivalent of <code>-Xtrace:none=all</code> and the trace engine still loads.</p> <p>If you specify other tracepoints without specifying <code>-Xtrace:none</code>, the tracepoints are added to the default set.</p>"},{"location":"xtrace/#output","title":"<code>output</code>","text":"<p>Sends trace data to a file, optionally of a specific size and number of generations.</p> <pre><code>-Xtrace:output=&lt;filename&gt;[,&lt;size&gt;[,&lt;generations&gt;]]`\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;filename&gt;</code> is a file name, which is created automatically if it does not exist. Otherwise, it is overwritten. To embed specific values in the file name use any of the following variables: %d% (today's date in \" yyyymmdd\" format), %p% (process ID number of the process generating the trace), or %t% (time in 24-hour hhmmss format).</li> <li>Optionally, <code>&lt;size&gt;</code> is a value in megabytes (MB), for example, use 4m to specify 4 MB. When full, it wraps to the beginning. If you do not limit the file, it grows indefinitely, until limited by disk space.</li> <li>Optionally, <code>&lt;generations&gt;</code> is a value 2 through 36. These values cause up to 36 files to be used sequentially as each file reaches its <code>&lt;size&gt;</code> threshold. When a file needs to be reused, it is overwritten. If <code>&lt;generations&gt;</code> is specified, the filename must contain a # (hash, pound symbol), which will be substituted with its generation identifier, the sequence of which is 0 through 9 followed by A through Z.</li> </ul> <p> Note: When tracing to a file, buffers for each thread are written when the buffer is full or when the VM ends. If a thread has been inactive for a period of time before the VM ends, what seems to be 'old' trace data is written to the file. When formatted, it then seems that trace data is missing from the other threads, but this is an unavoidable side-effect of the buffer-per-thread design. This effect becomes especially noticeable when you use the generation facility, and format individual earlier generations.</p> <p>Here are some examples:</p> <p>Trace output goes to file <code>/u/traces/gc.problem</code> with no size limit:</p> <pre><code>-Xtrace:output=/u/traces/gc.problem,maximal=j9gc\n</code></pre> <p>Trace output goes to file <code>trace</code>, which will wrap at 2 MB:</p> <pre><code>-Xtrace:output={trace,2m},maximal=j9gc\n</code></pre> <p>Trace output goes to files <code>gc0.trc</code>, <code>gc1.trc</code>, and <code>gc2.trc</code>, each 10 MB in size:</p> <pre><code>-Xtrace:output={gc#.trc,10m,3},maximal=j9gc\n</code></pre> <p>Trace output goes to a file, where the filename contains today's date in * yyyymmdd* format (for example, <code>traceout.20181025.trc</code>):</p> <pre><code>-Xtrace:output=traceout.%d.trc,maximal=j9gc\n</code></pre> <p>Trace output goes to a file whose name contains the number of the process (the PID number) that generated it (for example, <code>tracefrompid2112.trc</code>):</p> <pre><code>-Xtrace:output=tracefrompid%p.trc,maximal=j9gc\n</code></pre> <p>Trace output goes to a file whose name contains the time in hhmmss format (for example, <code>traceout.080312.trc</code>):</p> <pre><code>-Xtrace:output=traceout.%t.trc,maximal=j9gc\n</code></pre>"},{"location":"xtrace/#print-tracepoint","title":"<code>print</code> (tracepoint)","text":"<pre><code>-Xtrace:print=&lt;tracepoint_specification&gt;\n</code></pre> <p>For further information about <code>&lt;tracepoint_specification&gt;</code> syntax, see Tracepoint specification.</p> <p>The print option causes the specified tracepoints to be routed to stderr in real time. The VM tracepoints are formatted by using <code>J9TraceFormat.dat</code>. The class library tracepoints are formatted by <code>J9TraceFormat.dat</code> and <code>TraceFormat.dat</code>.</p>"},{"location":"xtrace/#properties","title":"<code>properties</code>","text":"<p>You can use properties files to control trace. A properties file saves typing and allows you to create a library of files that are tailored to solving problems in a particular area.</p> <pre><code>-Xtrace:properties[=&lt;filename&gt;]\n</code></pre> <p>If <code>&lt;filename&gt;</code> is not specified, the VM searches for a default name of IBMTRACE.properties in the current directory.</p> <p>All the options that are in the file are processed in the sequence in which they are stored in the file, before the next option that is obtained through the normal mechanism is processed. Therefore, a command-line property always overrides a property that is in the file.</p> <p>Here is an example of a properties file:</p> <pre><code>minimal=all\n// maximal=j9mm\nmaximal=j9shr\nbuffers=128k,nodynamic\noutput=c:\\traces\\classloader.trc\nprint=tpnid(j9vm.23-25)\n</code></pre> <p>The following restrictions apply to the file:</p> <ul> <li>The file must be a flat ASCII file.</li> <li>Nesting is not supported; that is, the file cannot contain a properties option.</li> <li>You cannot leave properties that have the form <code>&lt;name&gt;=&lt;value&gt;</code> to default if they are specified in the property file; that is, you must specify a value, for example <code>maximal=all</code>.</li> <li>Do not add white space before, after, or within the trace options.</li> </ul> <p>If any error is found when the file is accessed, VM initialization fails with an explanatory error message and return code.</p> <p>To use a file <code>trace.props</code> stored in the <code>c:\\trc\\gc</code> directory, specify the following command:</p> <pre><code>-Xtrace:properties=c:\\trc\\gc\\trace.props\n</code></pre>"},{"location":"xtrace/#resume","title":"<code>resume</code>","text":"<p>The resume option resumes tracing globally.</p> <pre><code>-Xtrace:resume\n</code></pre> <p>The <code>suspend</code> and <code>resume</code> options are not recursive. That is, two suspends that are followed by a single resume cause trace to be resumed.</p>"},{"location":"xtrace/#resumecount","title":"<code>resumecount</code>","text":"<p>This trace option determines whether tracing is enabled for each thread.</p> <pre><code>-Xtrace:resumecount=&lt;count&gt;\n</code></pre> <p>If <code>&lt;count&gt;</code> is greater than zero, each thread initially has its tracing disabled and must receive <code>&lt;count&gt;</code> <code>resumethis</code> actions before it starts tracing. This option is used with the trigger option.</p> <p> Note: You cannot use <code>resumecount</code> and <code>suspendcount</code> together because they use the same internal counter.</p> <p>The following example starts with all tracing turned off. Each thread starts tracing when it has had three <code>resumethis</code> actions performed on it:</p> <pre><code>-Xtrace:resumecount=3\n</code></pre>"},{"location":"xtrace/#sleeptime","title":"<code>sleeptime</code>","text":"<p>You can specify how long the sleep lasts when using the <code>sleep</code> trigger action.</p> <pre><code>-Xtrace:sleeptime=nnn|aaams|bbbs\n</code></pre> <p>Where:</p> <ul> <li>nnn sleeps for nnn milliseconds.</li> <li>aaams sleeps for aaa milliseconds.</li> <li>bbbs sleeps for bbb seconds.</li> </ul> <p>The default length of time is 30 seconds. If no units are specified, the default time unit is milliseconds.</p>"},{"location":"xtrace/#stackdepth","title":"<code>stackdepth</code>","text":"<p>Use this option to limit the maximum number of stack frames reported by the <code>jstacktrace</code> trace trigger action.</p> <pre><code>-Xtrace:stackdepth=&lt;n&gt;\n</code></pre> <p>Where <code>&lt;n&gt;</code> is the maximum number of stack frames reported.</p>"},{"location":"xtrace/#suspend","title":"<code>suspend</code>","text":"<pre><code>-Xtrace:suspend\n</code></pre> <p>Suspends tracing globally for all threads and all forms of tracing but leaves tracepoints activated.</p>"},{"location":"xtrace/#suspendcount","title":"<code>suspendcount</code>","text":"<p>This trace option determines whether tracing is enabled for each thread.</p> <pre><code>-Xtrace:suspendcount=&lt;count&gt;\n</code></pre> <p>If <code>&lt;count&gt;</code> is greater than zero, each thread initially has its tracing enabled and must receive <code>&lt;count&gt;</code> <code>suspendthis</code> actions before it stops tracing.</p> <p> You cannot use <code>resumecount</code> and <code>suspendcount</code> together because they both set the same internal counter.</p> <p>This trace option is for use with the trigger option.</p> <p>The following example starts with tracing turned on. Each thread stops tracing when it has had three <code>suspendthis</code> actions performed on it:</p> <pre><code>-Xtrace:suspendcount=3\n</code></pre>"},{"location":"xtrace/#trigger","title":"<code>trigger</code>","text":"<p>The <code>trigger</code> parameter determines when various triggered trace actions occur. Supported actions include turning tracing on and off for all threads, turning tracing on or off for the current thread, or producing various dumps.</p> <pre><code>-Xtrace:trigger=&lt;clause&gt;[,&lt;clause&gt;]\n</code></pre> <p>This trace option does not control what is traced. It controls only whether the information that has been selected by the other trace options is produced as normal or is blocked.</p>"},{"location":"xtrace/#types","title":"Types","text":"<p>Each clause of the <code>trigger</code> parameter can be one of the following types:</p> <ul> <li>a method (<code>-Xtrace:trigger=method{...}</code>)</li> <li>a tracepoint ID (<code>-Xtrace:trigger=tpnid{...}</code>)</li> <li>a group (<code>-Xtrace:trigger=group{...}</code>)</li> </ul> <p>You can specify multiple clauses of the same type if required, but you do not need to specify all types.</p> method <pre><code> -Xtrace:trigger=method{&lt;methodspec&gt;[,&lt;entryAction&gt;[,&lt;exitAction&gt;[,&lt;delayCount&gt;[,&lt;matchcount&gt;]]]]}\n</code></pre> <p>On entering a method that matches <code>&lt;methodspec&gt;</code>, the specified <code>&lt;entryAction&gt;</code> is run. On leaving a method that matches <code>&lt;methodspec&gt;</code>, the specified <code>&lt;exitAction&gt;</code> is run. If you specify a <code>&lt;delayCount&gt;</code>, the actions are performed only after a matching <code>&lt;methodspec&gt;</code> has been entered that many times. If you specify a <code>&lt;matchCount&gt;</code>, <code>&lt;entryAction&gt;</code> and <code>&lt;exitAction&gt;</code> are performed at most that many times.</p> <p><code>&lt;methodspec&gt;</code> is the specification of a Java method, consisting of a class and a method name separated by a dot. For example, specify <code>HelloWorld.main</code>. If the class is in a package, the package name must be included, separated by slashes. For example, specify <code>java/lang/String.getBytes</code>.</p> <p>A wildcard \"*\" can be used at the start or end of the class and method names, or both. For example, you can specify <code>*/String.get*</code>. To specify a constructor method, use <code>&lt;init&gt;</code> as the method name. Method signatures cannot be specified, so a method specification applies to all overloaded methods.</p> tracepoint ID <pre><code> -Xtrace:trigger=tpnid{&lt;tpnid&gt;|&lt;tpnidRange&gt;,&lt;action&gt;[,&lt;delayCount&gt;[,&lt;matchcount&gt;]]}\n</code></pre> <p>On finding the specified active tracepoint ID (<code>&lt;tpnid&gt;</code>) or a tracepoint ID) that falls inside the specified <code>&lt;tpnidRange&gt;</code>, the specified action is run. If you specify a <code>&lt;delayCount&gt;</code>, the action is performed only after the VM finds such an active <code>&lt;tpnid&gt;</code> that many times. If you specify a <code>&lt;matchCount&gt;</code>, <code>&lt;action&gt;</code> is performed at most that many times.</p> group <pre><code> -Xtrace:trigger=group{&lt;groupname&gt;,&lt;action&gt;[,&lt;delayCount&gt;[,&lt;matchcount&gt;]]}\n</code></pre> <p>On finding any active tracepoint that is defined as being in trace group <code>&lt;groupname&gt;</code>, for example Entry or Exit, the specified action is run. If you specify a <code>&lt;delayCount&gt;</code>, the action is performed only after that many active tracepoints from group <code>&lt;groupname&gt;</code> have been found. If you specify a <code>&lt;matchCount&gt;</code>, <code>&lt;action&gt;</code> is performed at most that many times.</p>"},{"location":"xtrace/#actions","title":"Actions","text":"<p>Wherever an action (<code>&lt;action&gt;</code>, <code>&lt;entryAction&gt;</code>, or <code>&lt;exitAction&gt;</code>) must be specified in one of the <code>trigger</code> parameter clauses, you must select from these options:</p> <code>&lt;action&gt;</code> Effect <code>abort</code> Halt the VM. <code>ceedump</code> This action is applicable to z/OS\u00ae only. For more information, see z/OS LE CEEDUMPs. <code>coredump</code> Produce a system dump. See Dump agents (<code>-Xdump:system</code>) <code>heapdump</code> Produce a heap dump. See Heap dump. <code>javadump</code> Produce a Java dump. See Java dump. <code>jstacktrace</code> Examine the Java stack of the current thread and generate auxiliary tracepoints for each stack frame. The auxiliary tracepoints are written to the same destination as the tracepoint or method trace that triggered the action. You can control the number of stack frames examined with the <code>stackdepth=n</code> option. See the stackdepth option. <code>resume</code> Resume all tracing (except for threads that are suspended by the action of the resumecount property and <code>Trace.suspendThis()</code> calls). <code>resumethis</code> Decrement the suspend count for this thread. If the suspend count is zero or less, resume tracing for this thread. <code>segv</code> Cause a segmentation violation. (Intended for use in debugging.) <code>sleep</code> Delay the current thread for a length of time controlled by the sleeptime option. The default is 30 seconds. See sleeptime option. <code>snap</code> Snap all active trace buffers to a file in the current working directory. The file name has the format: <code>Snapnnnn.yyyymmdd.hhmmssth.ppppp.trc</code>, where nnnn is the sequence number of the snap file since VM startup, yyyymmdd is the date, hhmmssth is the time, and ppppp is the process ID in decimal with leading zeros removed. <code>suspend</code> Suspend all tracing (except for special trace points). <code>suspendthis</code> Increment the suspend count for this thread. If the suspend-count is greater than zero, prevent all tracing for this thread. <code>sysdump</code> (or <code>coredump</code>) Produce a system dump. See Dump agents(<code>-Xdump:system</code>). <p>Here are some examples of using the <code>trigger</code> option:</p> <p>To produce a Java dump when a method is entered, specify the following command:</p> <pre><code>-Xtrace:trigger=method{java/lang/String.getBytes,javadump}\n</code></pre> <p>To produce a system dump when a method is entered, specify the following command:</p> <pre><code>-Xtrace:trigger=method{java/lang/String.getBytes,sysdump}\n</code></pre> <p>To produce a Java dump when a class constructor is called, specify the following command:</p> <pre><code>\"-Xtrace:trigger=method{java/lang/Thread.&lt;init&gt;,javadump}\"\n</code></pre> <p> Note: This trace option is enclosed in quotation marks to avoid unwanted shell expansion of some of the characters.</p> <p>To produce a Java dump when a class static initializer is called, specify the following command:</p> <pre><code>\"-Xtrace:trigger=method{java/lang/Thread.&lt;clinit&gt;,javadump}\"\n</code></pre> <p> Note: This trace option is enclosed in quotation marks to avoid unwanted shell expansion of some of the characters.</p> <p>To produce a Java dump when a method is entered 1000 times and 1001 times, specify the following command:</p> <pre><code>-Xtrace:trigger=method{java/lang/String.getBytes,javadump,,1000,2}\n</code></pre> <p>To start tracing this thread when it enters any method in <code>java/lang/String</code>, and to stop tracing the thread after exiting the method, specify the following command:</p> <pre><code>-Xtrace:resumecount=1\n</code></pre> <p>-Xtrace:trigger=method{java/lang/String.*,resumethis,suspendthis}</p> <p>To resume all tracing when any thread enters a method in any class that starts with error, specify the following command:</p> <pre><code>-Xtrace:trigger=method{*.error*,resume}\n</code></pre> <p>To trace (all threads) while the application is active; that is, not starting or shut down. (The application name is <code>HelloWorld</code>), specify the following command:</p> <pre><code>-Xtrace:suspend,trigger=method{HelloWorld.main,resume,suspend}\n</code></pre> <p>To print a Java stack trace to the console when the mycomponent.1 tracepoint is reached, specify the following command:</p> <pre><code>-Xtrace:print=mycomponent.1,trigger=tpnid{mycomponent.1,jstacktrace}\n</code></pre> <p>To write a Java stack trace to the trace output file when the <code>Sample.code()</code> method is called, specify the following command:</p> <pre><code>-Xtrace:maximal=mt,output=trc.out,methods={mycompany/mypackage/Sample.code},trigger=method{mycompany/mypackage/Sample.code,jstacktrace}\n</code></pre>"},{"location":"xtrace/#what","title":"<code>what</code>","text":"<pre><code>-Xtrace:what\n</code></pre> <p>Shows the current trace settings</p>"},{"location":"xtrace/#see-also","title":"See also","text":"<ul> <li>Application trace</li> <li>Heap dump</li> <li>Java dump</li> <li>Dump viewer</li> </ul>"},{"location":"xtunevirtualized/","title":"-Xtune:virtualized","text":""},{"location":"xtunevirtualized/#-xtunevirtualized","title":"-Xtune:virtualized","text":"<p>Optimizes Eclipse OpenJ9\u2122 VM function for virtualized environments, such as a cloud, by reducing OpenJ9 VM CPU consumption when idle.</p> <p> Note: Performance is optimized if there is a large shared classes cache (SCC) and AOT space in the SCC is not capped.</p>"},{"location":"xtunevirtualized/#syntax","title":"Syntax","text":"<pre><code>    -Xtune:virtualized\n</code></pre> <p>This option is recommended for CPU-constrained environments, such as those found in cloud deployments that use containers. Internally, the option makes the JIT compiler more conservative with inlining and recompilation decisions, which saves CPU resources. The Garbage Collector also reduces the rate of heap expansion, which reduces the memory footprint. These changes to reduce the amount of CPU that is consumed are at the expense of a small loss in throughput.</p> <p>When <code>-Xtune:virtualized</code> is used in conjunction with the <code>-Xshareclasses</code> option, the JIT compiler is more aggressive with its use of AOT-compiled code compared to setting only <code>-Xshareclasses</code>. This action provides additional CPU savings during application start-up and ramp-up, but comes at the expense of an additional small loss in throughput.</p>"},{"location":"xtunevirtualized/#see-also","title":"See also","text":"<ul> <li>For an example of the effect of using this option, see: Measuring the strengths of OpenJDK with Eclipse OpenJ9</li> </ul>"},{"location":"xverbosegclog/","title":"-Xverbosegclog","text":""},{"location":"xverbosegclog/#-xverbosegclog","title":"-Xverbosegclog","text":"<p>Causes garbage collection (GC) output from the <code>-verbose:gc</code> option to be written to a specified file.</p>"},{"location":"xverbosegclog/#syntax","title":"Syntax","text":"<pre><code>    -Xverbosegclog[:&lt;filename&gt;[,&lt;x&gt;,&lt;y&gt;]]\n</code></pre> <p>where <code>&lt;filename&gt;</code> is the name of the file to which output is written. Dump agent tokens can be used in the filename.</p> <p>If the file cannot be found, the file is created, and output is written to the new file.</p> <p>If the file cannot be created (for example, if an invalid filename is specified), output is redirected to <code>stderr</code>.</p> <p>If you do not specify a file name, <code>verbosegc.%Y%m%d.%H%M%S.%pid.txt</code> is used (for example, <code>verbosegc.20180124.093210.1234.txt</code>).</p> <p>If you specify <code>&lt;x&gt;</code> and <code>&lt;y&gt;</code>, output is redirected to <code>x</code> files, each containing <code>y</code> GC cycles.</p>"},{"location":"xverbosegclog/#default-behavior","title":"Default behavior","text":"<p>By default, no verbose GC logging occurs.</p>"},{"location":"xverbosegclog/#see-also","title":"See also","text":"<ul> <li>Dump agent tokens for more information.</li> <li>Verbose GC logs and Log examples for more information about verbose GC logs.</li> </ul>"},{"location":"xverify/","title":"-Xverify","text":""},{"location":"xverify/#-xverify","title":"-Xverify","text":"<p>As described in the Oracle documentation, this HotSpot option enables or disables the verifier. For compatibility, this option is also supported by the Eclipse OpenJ9\u2122 VM.</p>"},{"location":"xverify/#syntax","title":"Syntax","text":"Setting Effect Default <code>-Xverify</code> Enables verification for all non-bootstrap classes. <code>-Xfuture</code> verification is not enabled. yes <code>-Xverify:all</code> Enables verification for all classes and enables <code>-Xfuture</code> verification. \u00a0 You cannot use this setting in conjunction with -XX:+ClassRelationshipVerifier. \u00a0 Note: This setting might have an impact on performance. <code>-Xverify:remote</code> For compatibility, this parameter is accepted, but is equivalent to the default <code>-Xverify</code>. <code>-Xverify:none</code> Disables the verifier. \u00a0 Note: This is not a supported configuration and, as noted, was deprecated from Java 13. If you encounter problems with the verifier turned off, remove this option and try to reproduce the problem. <p> Note: The option <code>-Xverify:none</code> (and its equivalent <code>-noverify</code>) was deprecated in Java 13. Both options might be removed in a future release. OpenJ9 issues a warning if these options are used in Java 13 and later versions. </p>"},{"location":"xx_jvm_commands/","title":"Using -XX options","text":""},{"location":"xx_jvm_commands/#using-xx-command-line-options","title":"Using -XX command-line options","text":"<p>Java\u2122 VM command-line options that are specified with <code>-XX:</code> are not checked for validity. If the VM does not recognize the option, the option is ignored. These options can therefore be used across different VM versions without ensuring a particular level of the VM.  If you want to turn off this behavior to test whether your -XX options are valid, use the -XX:-IgnoreUnrecognizedXXColonOptions option.</p> <p>For options that take a <code>&lt;size&gt;</code> parameter, add a suffix to the size value: \"k\" or \"K\" to indicate kilobytes, \"m\" or \"M\" to indicate megabytes, \"g\" or \"G\" to indicate gigabytes, or \"t\" or \"T\" to indicate terabytes.</p> <p>For example, to set the <code>-XX:MaxDirectMemorySize</code> value to 16 MB, you can specify <code>-XX:MaxDirectMemorySize16M</code>, <code>-XX:MaxDirectMemorySize16m</code>, <code>-XX:MaxDirectMemorySize16384K</code>, or <code>XX:MaxDirectMemorySize16384k</code> on the command line.</p>"},{"location":"xxactiveprocessorcount/","title":"-XXActiveProcessorCount","text":""},{"location":"xxactiveprocessorcount/#-xxactiveprocessorcount","title":"-XX:ActiveProcessorCount","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122 for compatibility. Use this option to override the number of CPUs that the VM automatically detects and uses when creating threads for various subsystems.</p>"},{"location":"xxactiveprocessorcount/#syntax","title":"Syntax","text":"<pre><code>    -XX:ActiveProcessorCount=&lt;n&gt;\n</code></pre> <p>Where <code>&lt;n&gt;</code> is the number of CPUs.</p> Setting Value Default <code>&lt;n&gt;</code> 1 or greater There is no default value. This option is not enabled by default. If set to <code>0</code>, there is no effect. <p>When you set this option the following line in a Java dump file is updated to indicate the number of CPUs specified:</p> <pre><code>2CIACTIVECPU Active CPUs\n</code></pre> <p>If this option is not set, the value for this line is <code>0</code> Active CPUs.</p>"},{"location":"xxadaptivegcthreading/","title":"-XX:[+|-]AdaptiveGCThreading","text":""},{"location":"xxadaptivegcthreading/#-xx-adaptivegcthreading","title":"-XX:[+|-]AdaptiveGCThreading","text":"<p> Restriction: Currently, this feature is available only with the <code>gencon</code> GC policy.</p> <p>When this option is enabled, the active GC thread count is adjusted for each garbage collection (GC) cycle based on heuristics. That is, when a GC cycle successfully completes, the collector evaluates parallelism using aggregated thread statistics gathered during the completed cycle and projects a new thread count for the next cycle. For example, the thread count might be reduced if it is determined that an unnecessary overhead was incurred as a result of synchronization, lack of work sharing, or CPU availability. Similarly, the thread count may be increased if there's an opportunity to gain benefits from increased parallelism. </p> <p> Notes:</p> <ul> <li>This option is ignored when the GC thread count is enforced, for example when using the <code>-xgcthreads</code> or <code>-XX:ParallelGCThreads</code> options.</li> <li>By default, the number of GC threads is based on the number of CPUs reported by the operating system. This value is used as the maximum thread count. However, an upper bound can be specified by using <code>-xgcmaxthreads</code> or <code>XX:ParallelGCMaxThreads</code>.</li> </ul>"},{"location":"xxadaptivegcthreading/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]AdaptiveGCThreading\n</code></pre> Setting Effect Default <code>-XX:+AdaptiveGCThreading</code> Enable yes <code>-XX:-AdaptiveGCThreading</code> Disable <p>This optimization aims to automatically tune the GC thread count. Manually tuning and setting a thread count can be suboptimal because workloads typically change over the lifetime of an application.</p> <p>You can check the active thread count value that is used by the garbage collector to complete the cycle by inspecting verbose GC output. The following example shows active thread count being reduced from 8 to 3:</p> <pre><code>&lt;gc-end id=\"8\" type=\"scavenge\" contextid=\"4\" durationms=\"2.248\" usertimems=\"3.694\" systemtimems=\"1.345\" stalltimems=\"11.003\" timestamp=\"2021-03-12T01:35:10.768\" activeThreads=\"8\"&gt;\n&lt;gc-end id=\"20\" type=\"scavenge\" contextid=\"16\" durationms=\"7.045\" usertimems=\"6.360\" systemtimems=\"0.955\" stalltimems=\"31.964\" timestamp=\"2021-03-12T01:35:10.777\" activeThreads=\"6\"&gt;\n&lt;gc-end id=\"32\" type=\"scavenge\" contextid=\"28\" durationms=\"1.943\" usertimems=\"7.112\" systemtimems=\"0.454\" stalltimems=\"6.076\" timestamp=\"2021-03-12T01:35:10.781\" activeThreads=\"5\"&gt;\n&lt;gc-end id=\"44\" type=\"scavenge\" contextid=\"40\" durationms=\"1.253\" usertimems=\"2.910\" systemtimems=\"0.297\" stalltimems=\"2.416\" timestamp=\"2021-03-12T01:35:10.788\" activeThreads=\"4\"&gt;\n&lt;gc-end id=\"56\" type=\"scavenge\" contextid=\"52\" durationms=\"1.487\" usertimems=\"3.991\" systemtimems=\"0.447\" stalltimems=\"2.918\" timestamp=\"2021-03-12T01:35:10.790\" activeThreads=\"4\"&gt;\n&lt;gc-end id=\"68\" type=\"scavenge\" contextid=\"64\" durationms=\"0.400\" usertimems=\"1.002\" systemtimems=\"0.178\" stalltimems=\"0.658\" timestamp=\"2021-03-12T01:35:10.791\" activeThreads=\"4\"&gt;\n&lt;gc-end id=\"80\" type=\"scavenge\" contextid=\"76\" durationms=\"0.187\" usertimems=\"1.099\" systemtimems=\"0.127\" stalltimems=\"0.112\" timestamp=\"2021-03-12T01:35:10.792\" activeThreads=\"3\"&gt;\n&lt;gc-end id=\"92\" type=\"scavenge\" contextid=\"88\" durationms=\"0.195\" usertimems=\"0.940\" systemtimems=\"0.114\" stalltimems=\"0.067\" timestamp=\"2021-03-12T01:35:10.796\" activeThreads=\"3\"&gt;\n&lt;gc-end id=\"104\" type=\"scavenge\" contextid=\"100\" durationms=\"0.277\" usertimems=\"0.899\" systemtimems=\"0.118\" stalltimems=\"0.139\" timestamp=\"2021-03-12T01:35:10.797\" activeThreads=\"3\"&gt;\n</code></pre>"},{"location":"xxallowvmshutdown/","title":"-XXallowvmshutdown","text":""},{"location":"xxallowvmshutdown/#-xxallowvmshutdown","title":"-XXallowvmshutdown","text":"<p>This option is provided as a workaround for applications that cannot shut down cleanly, as described in APAR IZ59734.</p>"},{"location":"xxallowvmshutdown/#syntax","title":"Syntax","text":"<pre><code>    -XX:allowvmshutdown:[false|true]\n</code></pre> Setting Effect Default false Disable true Enable yes"},{"location":"xxalwayspretouch/","title":"-XX:[+|-]AlwaysPreTouch","text":""},{"location":"xxalwayspretouch/#-xx-alwayspretouch","title":"-XX:[+|-]AlwaysPreTouch","text":"<p>This Oracle HotSpot option enables or disables the committing of memory during initial heap inflation or heap expansion.</p>"},{"location":"xxalwayspretouch/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]AlwaysPreTouch\n</code></pre> Setting Effect Default <code>-XX:+AlwaysPreTouch</code> Enable <code>-XX:-AlwaysPreTouch</code> Disable yes"},{"location":"xxcheckpointgcthread/","title":"-XX:CheckpointGCThreads","text":""},{"location":"xxcheckpointgcthread/#-xxcheckpointgcthreads","title":"-XX:CheckpointGCThreads","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>At the VM startup, you can set the number of threads that the garbage collector uses for parallel operations (<code>-Xgcthreads</code>). At the time of taking the checkpoint, the <code>-XX:CheckpointGCThreads</code> option reduces the number of garbage collection (GC) threads that was set at startup.</p> <p> Restrictions: This option takes effect only when <code>-XX:+EnableCRIUSupport</code> is enabled.</p>"},{"location":"xxcheckpointgcthread/#syntax","title":"Syntax","text":"<pre><code>    -XX:CheckpointGCThreads=&lt;number&gt;\n</code></pre> Setting Value Default <code>&lt;number&gt;</code> Greater than 0 and less than or equal to the number of GC threads at the VM startup 4 <p>If the <code>&lt;number&gt;</code> is greater than the number of GC threads at startup, the VM ignores this option.</p>"},{"location":"xxcheckpointgcthread/#explanation","title":"Explanation","text":"<p>When taking a checkpoint, the VM reduces the number of GC threads that was specified at the startup and makes it equal to the thread count specified in the <code>-XX:CheckpointGCThreads</code> option. Since restoring threads adds latency to the overall VM restore time, you can minimize the restore time by reducing the GC thread count. After restoring from the checkpoint, the VM increases the GC thread count. The VM checks the following settings to determine the new GC thread count at the time of restore:</p> <ul> <li><code>-Xgcthreads</code> set at restore</li> <li>Default thread count at restore</li> <li>Checkpoint GC threads</li> </ul> <p>If you have specified the GC thread count at restore in the <code>-Xgcthreads</code> option and the count is greater than the checkpoint GC threads, the VM increases the thread count to the GC thread count set at restore.</p> <p>If you have not specified the GC thread count in the <code>-Xgcthreads</code> option or if the thread count is less than the checkpoint GC threads, then the VM determines the default thread count (as explained in the <code>-Xgcthreads</code> topic) at restore. If the default thread count is greater than the checkpoint thread count, then the VM increases the thread count to the default thread count.</p> <p>If the default thread count is lesser than the checkpoint thread count, then the thread count at restore time is same as the checkpoint thread count.</p>"},{"location":"xxcheckpointgcthread/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxclassrelationshipverifier/","title":"-XX:[+|-]ClassRelationshipVerifier","text":""},{"location":"xxclassrelationshipverifier/#-xx-classrelationshipverifier","title":"-XX:[+|-]ClassRelationshipVerifier","text":"<p>This option enables and disables the recording of class relationships in the verifier to delay validation until triggered by class loading.</p> <p> Note: You cannot use this setting in conjunction with <code>-Xfuture</code> or <code>-Xverify:all</code>, which itself enables <code>-Xfuture</code>.</p>"},{"location":"xxclassrelationshipverifier/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ClassRelationshipVerifier\n</code></pre> Setting Effect Default <code>-XX:+ClassRelationshipVerifier</code> Enable <code>-XX:-ClassRelationshipVerifier</code> Disable yes"},{"location":"xxclassrelationshipverifier/#explanation","title":"Explanation","text":"<p>When enabled, this option delays validating the relationships between classes until the classes are required to be loaded during program execution. In this way, classes that are not required, are never loaded thus reducing VM startup time. </p> <p>A verify error is thrown if validation fails.</p>"},{"location":"xxcodecachetotal/","title":"-XX:codecachetotal","text":""},{"location":"xxcodecachetotal/#-xxcodecachetotal","title":"-XX:codecachetotal","text":"<p>This option is an alias for the <code>-Xcodecachetotal</code> option.</p>"},{"location":"xxcodecachetotal/#syntax","title":"Syntax","text":"<pre><code>    -XX:codecachetotal=&lt;size&gt;\n</code></pre> See Using -X command-line options for more information about specifying the <code>&lt;size&gt;</code> parameter."},{"location":"xxcodecachetotal/#see-also","title":"See also","text":"<ul> <li><code>-XX:codecachetotalMaxRAMPercentage</code></li> </ul>"},{"location":"xxcodecachetotalmaxrampercentage/","title":"-XX:codecachetotalMaxRAMPercentage","text":""},{"location":"xxcodecachetotalmaxrampercentage/#-xxcodecachetotalmaxrampercentage","title":"-XX:codecachetotalMaxRAMPercentage","text":"<p>This option sets the maximum limit for the total JIT code cache size based on the amount of physical memory available to the VM.</p>"},{"location":"xxcodecachetotalmaxrampercentage/#syntax","title":"Syntax","text":"<pre><code>    -XX:codecachetotalMaxRAMPercentage=&lt;number&gt;\n</code></pre> Setting Value Default <code>&lt;number&gt;</code> Between 1 and 100 (fractional numbers are allowed) 25 <p>Where <code>&lt;number&gt;</code> is the maximum limit that is expressed as a percentage of the available physical memory.</p> <p>For example, if you specify <code>-XX:codecachetotalMaxRAMPercentage=30</code>, the VM is not allowed to use more than 30% of the available physical memory for the internal JIT code caches.</p>"},{"location":"xxcodecachetotalmaxrampercentage/#explanation","title":"Explanation","text":"<p>The default total size of the JIT code cache is computed as the minimum of the following two limits:</p> <ul> <li>A platform-based limit that is expressed as an absolute memory value. This limit is set at 256 MB for 64-bit systems and at 64 MB for 31/32-bit systems.</li> <li>A percentage of the amount of available physical memory the VM process is allowed to use. By default, the VM is not allowed to use more than 25% of the available physical memory for its code caches.</li> </ul> <p>In memory constrained environments, the percentage limit is relevant because the code cache size is then based on the available physical memory. The percentage limit prevents the VM from using too much memory for its code caches and thus, leaving too little memory for other VM or JIT data structures.</p> <p>For example, on a 64-bit system, the platform-specific code cache limit is 256 MB. If the VM is constrained to less than 1024 MB, say 512 MB, then the code cache limit becomes 128 MB (25% of 512 MB) because the percentage limit is less than the platform limit.</p> <p>To fine-tune the code cache size limit for your specific application as a percentage of the available physical memory, you can use the <code>-XX:codecachetotalMaxRAMPercentage</code> option.</p> <p>As an alternative, you can use the <code>-XX:codecachetotal</code> or the <code>-Xcodecachetotal</code> options to set the code cache size limit as an absolute value (platform-based limit). The absolute value that is specified with these options takes precedence over the percentage that is specified with the <code>-XX:codecachetotalMaxRAMPercentage</code> option.</p> <p> Restrictions:</p> <ul> <li>If the <code>-XX:codecachetotal</code> or <code>-Xcodecachetotal</code> option is specified, then the <code>-XX:codecachetotalMaxRAMPercentage</code> option is ignored.</li> <li>The percentage of the available physical memory that is specified in the <code>-XX:codecachetotalMaxRAMPercentage</code> option is used only if the total cache value thus calculated is less than the default total code cache value set for the platform (minimum of the two limits).</li> </ul>"},{"location":"xxcompactstrings/","title":"-XX:[+|-]CompactStrings","text":""},{"location":"xxcompactstrings/#-xx-compactstrings","title":"-XX:[+|-]CompactStrings","text":"<p>This HotSpot option is reimplemented by Eclipse OpenJ9\u2122 and when enabled causes an ISO8859-1 (also known as Latin-1) character representation to be used internally for <code>String</code> objects, while preserving full API compatibility.</p> <p>This feature provides heap space savings by using an 8-bit character set internally. Most benefit is gained when the majority of the <code>String</code> objects that your application uses can be encoded using the ISO8859-1 character encoding. </p> <p>If the option is not enabled, the JIT compiler is nevertheless optimized so that although there is no saving in heap space, there is also no performance penalty.</p> <p>Further details are available at JEP 254: Compact Strings.</p> <p> Note: With OpenJ9, this option is supported on OpenJDK version 8 and later versions, whereas HotSpot supports it only from Java version 9.</p>"},{"location":"xxcompactstrings/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+CompactStrings</code> Enable <code>String</code> compression yes <code>-XX:-CompactStrings</code> Disable <code>String</code> compression yes"},{"location":"xxconcgcthreads/","title":"-XX:ConcGCThreads","text":""},{"location":"xxconcgcthreads/#-xxconcgcthreads","title":"-XX:ConcGCThreads","text":"<p>This Oracle HotSpot option affects the number of threads used by the concurrent garbage collector. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxconcgcthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ConcGCThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of low-priority background threads that are attached to assist the mutator threads in concurrent mark.</p> <p>Within OpenJ9 this option is directly mapped to <code>-Xconcurrentbackground</code>.</p>"},{"location":"xxcontinuationcache/","title":"-XX:ContinuationCache","text":""},{"location":"xxcontinuationcache/#-xxcontinuationcache","title":"-XX:ContinuationCache","text":"<p> This option sets the continuation tier 1 and 2 cache size to optimize virtual thread performance.</p>"},{"location":"xxcontinuationcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:ContinuationCache:t1=&lt;size&gt;,t2=&lt;size&gt;\n</code></pre> Setting Value Default <code>t1=&lt;size&gt;</code> 0 to 2<sup>32</sup> - 1 (4,294,967,295) 1 <code>t2=&lt;size&gt;</code> 0 to 2<sup>32</sup> - 1 (4,294,967,295) Number of processors x 2 <p>Where <code>t1</code> is the tier 1 cache and <code>t2</code> is the tier 2 cache.</p> <p>The tier 1 cache holds data that is not shareable between threads.</p> <p>The tier 2 cache holds data that can be shared globally between threads.</p>"},{"location":"xxcontinuationcache/#explanation","title":"Explanation","text":"<p>When a virtual thread is created, it is associated with a continuation, which holds the target task of the virtual thread. When a virtual thread starts, the VM saves the current thread (carrier thread) state in an internal data structure that is linked with the continuation. When the associated continuation starts, the VM allocates the memory for the internal data structure and stores its reference in the continuation. When the continuation finishes, the VM stores the internal data structure in a cache instead of freeing the associated memory. New continuations can reuse the cached structure instead of allocating new memory for it. The VM can resume thread execution from the saved state later, typically on a different thread.</p> <p>If the virtual thread stops, the VM loads the state of the previous thread from the continuation and runs that thread. When the virtual thread does not complete running, the last state of the virtual thread is stored in the continuation during the stop operation. At a later point, the scheduler runs the incomplete virtual thread using the thread state stored in the continuation.</p> <p>Reusing the cached structure improves the performance of creating virtual threads. The performance benefits are more evident in applications that scale to millions of virtual threads.</p> <p>The continuation cache is implemented in two tiers, tier 1 and tier 2. You can set the maximum size for the two tiers with the <code>-XX:ContinuationCache</code> option. If an application uses more than 10000 virtual threads, setting a larger cache size might improve performance.</p> <p>When the size of the cache increases, the number of allocations reduces but the cache lookup time might also increase. Evaluate both the number of allocations and the optimal lookup time to set the appropriate cache size. </p>"},{"location":"xxcontinuationcache/#see-also","title":"See also","text":"<ul> <li><code>-XX:[+|-]ShowCarrierFrames</code></li> </ul>"},{"location":"xxcriurestorenonportablemode/","title":"-XX:[+|-]CRIURestoreNonPortableMode","text":""},{"location":"xxcriurestorenonportablemode/#-xx-criurestorenonportablemode","title":"-XX:[+|-]CRIURestoreNonPortableMode","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>This option specifies whether the JIT and AOT compilers generate nonportable compiled code on restore.</p> <p> Restrictions:</p> <ul> <li>This option takes effect only when <code>-XX:+EnableCRIUSupport</code> is enabled.</li> <li>When you disable this option,<ul> <li><code>CRIUSECProvider</code> is the only security provider in both checkpoint and restore.</li> <li>JITServer technology is disabled both before you take a checkpoint and after you restore the VM.</li> <li>the VM generates only portable code, both before you take a checkpoint and after you restore the VM.</li> </ul> </li> </ul>"},{"location":"xxcriurestorenonportablemode/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]CRIURestoreNonPortableMode\n</code></pre> Setting Effect Default <code>-XX:+CRIURestoreNonPortableMode</code> Enable yes <code>-XX:-CRIURestoreNonPortableMode</code> Disable"},{"location":"xxcriurestorenonportablemode/#explanation","title":"Explanation","text":"<p>The JIT compiler can exploit hardware features of the system on which it is running, to generate compiled code. That code might therefore fail if it is included in a checkpoint image that you later restore on a different system. For example, the compiled code might try to exploit a hardware feature that doesn't exist on the new machine, then fail. To avoid this problem, the JIT compiler by default generates code that exploits only basic hardware features, therefore portable to different systems.</p> <p>The <code>-XX:+CRIURestoreNonPortableMode</code> option is set by default so that on restore the JIT compiler can start generating nonportable compiled code. Likewise, the VM can also load nonportable AOT code post-restore. Generating nonportable compiled code also means that no further checkpoints are permitted. Only a single checkpoint can be taken in the VM's lifetime.</p> <p>If you require multiple checkpoints, you can use the <code>-XX:-CRIURestoreNonPortableMode</code> option to generate portable JIT compiled code after restore.</p>"},{"location":"xxcriurestorenonportablemode/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxdiagnosesynconvaluebasedclasses/","title":"-XX:DiagnoseSyncOnValueBasedClasses","text":""},{"location":"xxdiagnosesynconvaluebasedclasses/#-xxdiagnosesynconvaluebasedclasses","title":"-XX:DiagnoseSyncOnValueBasedClasses","text":"<p> This HotSpot option provides warnings about improper attempts to synchronize on instances of a value-based class. The option is recognized by Eclipse OpenJ9\u2122 for compatibility.</p>"},{"location":"xxdiagnosesynconvaluebasedclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:DiagnoseSyncOnValueBasedClasses=&lt;number&gt;\n</code></pre> <code>&lt;number&gt;</code> value Effect 1 Generate <code>VirtualMachineError</code> error 2 Print a warning message"},{"location":"xxdisableexplicitgc/","title":"-XX:[+|-]DisableExplicitGC","text":""},{"location":"xxdisableexplicitgc/#-xx-disableexplicitgc","title":"-XX:[+|-]DisableExplicitGC","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122 for compatibility. See \u2011Xenableexplicitgc.md / \u2011Xdisableexplicitgc for details.</p>"},{"location":"xxdisableexplicitgc/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+DisableExplicitGC</code> Enable GC yes <code>-XX:-DisableExplicitGC</code> Disable GC"},{"location":"xxdisclaimjitscratch/","title":"-XX:[+|-]DisclaimJitScratch","text":""},{"location":"xxdisclaimjitscratch/#-xx-disclaimjitscratch","title":"-XX:[+|-]DisclaimJitScratch","text":"<p> Restriction: This option is deprecated; the option is accepted but ignored.</p> <p>(Linux\u00ae only)</p> <p>The <code>-XX:+DisclaimJitScratch</code> option signals to the operating system to discard temporary physical memory that is consumed by the JIT compilation threads.</p>"},{"location":"xxdisclaimjitscratch/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]DisclaimJitScratch\n</code></pre> Setting Effect Default <code>-XX:+DisclaimJitScratch</code> Enable <code>-XX:-DisclaimJitScratch</code> Disable yes"},{"location":"xxdisclaimjitscratch/#explanation","title":"Explanation","text":"<p>Discarding temporary physical memory can reduce the physical memory reported in use by the Java\u2122 application. The physical memory that is released is available to other processes without the operating system needing to search for the least recently used frames.</p> <p>The <code>-XX:-DisclaimJitScratch</code> option turns off a previously enabled <code>-XX:+DisclaimJitScratch</code> option.</p>"},{"location":"xxenable3164interoperability/","title":"-XX:[+|-]Enable3164Interoperability","text":""},{"location":"xxenable3164interoperability/#-xx-enable3164interoperability","title":"-XX:[+|-]Enable3164Interoperability","text":"<p>(z/OS\u00ae only)</p> <p>Enables support for using 31-bit native applications with the 64-bit Java\u2122 virtual machine, where that support is available. For more information, see Using 31-bit native code with the 64-bit Java VM.</p>"},{"location":"xxenablecpumonitor/","title":"-XX:[+|-]EnableCPUMonitor","text":""},{"location":"xxenablecpumonitor/#-xx-enablecpumonitor","title":"-XX:[+|-]EnableCPUMonitor","text":"<p>This option relates to the information about the CPU usage of thread categories that is available with the <code>com.ibm.lang.management.JvmCpuMonitorMXBean</code> application programming interface.</p> <p> Restriction: This option might not be supported in subsequent releases.</p>"},{"location":"xxenablecpumonitor/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]EnableCPUMonitor\n</code></pre> Setting Effect Default <code>-XX:+EnableCPUMonitor</code> Enable yes <code>-XX:-EnableCPUMonitor</code> Disable"},{"location":"xxenablecpumonitor/#explanation","title":"Explanation","text":"<p>The <code>-XX:+EnableCPUMonitor</code> option enables CPU monitoring, which allows a JMX bean to track CPU usage on a per thread basis and attributes the usage against different categories. For more information, see the <code>JvmCpuMonitorMXBean</code> interface in the <code>com.ibm.lang.management</code> API documentation.</p> <p>To turn off CPU monitoring, set the <code>-XX:-EnableCPUMonitor</code> option on the command line.</p>"},{"location":"xxenablecpumonitor/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]ReduceCPUMonitorOverhead</li> </ul>"},{"location":"xxenablecriusupport/","title":"-XX:[+|-]EnableCRIUSupport","text":""},{"location":"xxenablecriusupport/#-xx-enablecriusupport","title":"-XX:[+|-]EnableCRIUSupport","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>This option enables or disables support for Checkpoint/Restore In Userspace (CRIU).</p> <p> Restrictions: If CRIU support is enabled,</p> <ul> <li>you cannot use a Java\u2122 security manager. If you try to specify a Java security manager, for example by using the <code>-Djava.security.manager</code> system property on the Java command line or the <code>java.lang.System.setSecurityManager</code> method in your application, the VM throws the <code>java.lang.UnsupportedOperationException</code> error.</li> <li><code>CRIUSECProvider</code> is the only security provider that is available in the checkpoint phase until restore.</li> <li>JITServer is disabled in the checkpoint phase even if the server exists and you have specified the <code>-XX:+UseJITServer</code> option. When you specify the <code>-XX:+EnableCRIUSupport</code> and <code>-XX:+CRIURestoreNonPortableMode</code> options along with the <code>-XX:+UseJITServer</code> option, and the server exists, the VM enables the JITServer server automatically at the restore point. The VM client connects to a JITServer in the context of CRIU as outlined in the following table (where yes means that the VM connects to a JITServer instance and no means that the VM does not connect to a JITServer instance):</li> </ul> Nonportable mode (default)  Pre-checkpoint Nonportable mode (default)  Post restore Portable mode Pre-checkpoint Portable mode Post restore Pre-checkpoint: No options Post restore: No options no no no no Pre-checkpoint: No options Post restore: <code>-XX:+UseJITServer</code> no yes no yes Pre-checkpoint: <code>-XX:+UseJITServer</code>Post restore: No options no yes yes yes Pre-checkpoint: <code>-XX:+UseJITServer</code>Post restore: <code>-XX:-UseJITServer</code> no no yes no Pre-checkpoint: <code>-XX:-UseJITServer</code>Post restore: <code>-XX:+UseJITServer</code> no no no no <ul> <li> <p>you cannot use the <code>balanced</code> and <code>metronome</code> garbage collection (GC) policies. If you use the <code>-Xgcpolicy:balanced</code> or <code>-Xgcpolicy:metronome</code> options to specify those policies, the VM throws the following errors:</p> <p><code>JVMJ9GC090E -Xgcpolicy:balanced is currently unsupported with -XX:+EnableCRIUSupport   JVMJ9VM007E Command-line option unrecognised: -Xgcpolicy:balanced   Error: Could not create the Java Virtual Machine.   Error: A fatal exception has occurred. Program will exit.</code></p> <p><code>JVMJ9GC090E -Xgcpolicy:metronome is currently unsupported with -XX:+EnableCRIUSupport   JVMJ9VM007E Command-line option unrecognised: -Xgcpolicy:metronome   Error: Could not create the Java Virtual Machine.   Error: A fatal exception has occurred. Program will exit.</code></p> </li> </ul>"},{"location":"xxenablecriusupport/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]EnableCRIUSupport\n</code></pre> Setting Effect Default <code>-XX:+EnableCRIUSupport</code> Enable <code>-XX:-EnableCRIUSupport</code> Disable yes"},{"location":"xxenablecriusupport/#explanation","title":"Explanation","text":"<p>When you enable the option, the VM starts with the support for checkpoint and restore processes. The VM starts the JIT, GC, Security, and other internal components that make the checkpoint and restore points feasible. The option enables the use of <code>org.eclipse.openj9.criu.CRIUSupport</code> APIs. With CRIU support, you can take a checkpoint of the VM and restore the checkpoint image. When you specify the <code>-XX:+EnableCRIUSupport</code> option, the VM generates only those compiled codes that are portable (see <code>-XX:[+|-]PortableSharedCache</code>) to facilitate restoring of the checkpoint image in multiple environments. VM does not load any code from the shared classes cache that is nonportable pre-checkpoint.</p> <p>Taking a checkpoint and restoring the checkpoint image generally happens on different environments with different behaviors. OpenJ9 makes compensations for such differences to ensure successful restore. For example, the VM compensates for the downtime between checkpoint and restore for elapsed time sensitive APIs such as <code>System.nanotime()</code> and <code>java.util.Timer</code>.</p> <p>For more information about the OpenJ9 compensations and Time APIs, see the Compensation section in the OpenJ9 CRIU Support: A look under the hood\u202f(part II) blog post.</p>"},{"location":"xxenablecriusupport/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxenabledynamicagentloading/","title":"-XX:[+|-]EnableDynamicAgentLoading","text":""},{"location":"xxenabledynamicagentloading/#-xx-enabledynamicagentloading","title":"-XX:[+|-]EnableDynamicAgentLoading","text":"<p>This option enables or disables the dynamic loading of agents into a running VM.</p>"},{"location":"xxenabledynamicagentloading/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]EnableDynamicAgentLoading\n</code></pre> Setting Effect Default <code>-XX:+EnableDynamicAgentLoading</code> Enable yes <code>-XX:-EnableDynamicAgentLoading</code> Disable"},{"location":"xxenabledynamicagentloading/#explanation","title":"Explanation","text":"<p>With the Attach API, your application can connect to a running VM and load an agent dynamically into that VM to run tasks. Some libraries misuse the Attach API to dynamically load an agent to run tasks without the approval of the application owner.</p> <p>You can disable the dynamic loading of the agents into a VM after startup with the <code>-XX:-EnableDynamicAgentLoading</code> option.</p> <p> For Java\u2122 21 and later, the following warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the <code>-XX:+EnableDynamicAgentLoading</code> option. These warnings are not issued if the same agents were loaded before either by using the command-line options or an earlier dynamic loading.</p> <pre><code>WARNING: A {Java,JVM TI} agent has been loaded dynamically (file:/u/bob/agent.jar)\nWARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading to hide this warning\nWARNING: If a serviceability tool is not in use, please run with -Djdk.instrument.traceUsage for more information\nWARNING: Dynamic loading of agents will be disallowed by default in a future release\n</code></pre> <p>These warnings are issued only once for the same agent when the <code>-XX:+EnableDynamicAgentLoading</code> option is not specified.</p> <p>If the <code>-XX:+EnableDynamicAgentLoading</code> option is set, all agents that are dynamically loaded are considered as approved by the application owner, and therefore, no warnings are issued.</p> <p>Eclipse OpenJ9\u2122 supported operating systems other than AIX\u00ae have APIs to determine whether the same agent was loaded before or not, even if an agent is loaded with a platform-independent name or an absolute path to the platform-dependent library.</p> <p>AIX systems cannot detect whether an agent was previously loaded or not if the agent was loaded through a platform-independent name or an absolute path to the platform-dependent library. Therefore, on AIX systems, the warnings are issued when an agent is loaded dynamically through the Attach API (<code>VirtualMachine.loadAgentLibrary(agent)</code>) even if the same agent was loaded before through the command-line option (<code>-agentpath:/Absolute/Path/to/agentLibrary</code>) at startup. </p>"},{"location":"xxenabledynamicagentloading/#see-also","title":"See also","text":"<ul> <li>Java Virtual Machine Tool Interface</li> <li>Java Attach API</li> </ul>"},{"location":"xxensurehashed/","title":"-XX:[+|-]EnsureHashed","text":""},{"location":"xxensurehashed/#-xx-ensurehashed","title":"-XX:[+|-]EnsureHashed","text":"<p>This option specifies classes to be pre-hashed. Objects that are created from these classes are hashed and extended with a slot to store the assigned hash value when the object is created or first moved during the garbage collection process. This option might improve performance for applications that frequently hash objects of a certain type.</p>"},{"location":"xxensurehashed/#syntax","title":"Syntax","text":"<pre><code>    -XX:+EnsureHashed:&lt;classes&gt;\n    -XX:-EnsureHashed:&lt;classes&gt;\n</code></pre> Setting Effect <code>-XX:+EnsureHashed:&lt;classes&gt;</code> Specify classes <code>-XX:-EnsureHashed:&lt;classes&gt;</code> Ignore classes <p>Where <code>&lt;classes&gt;</code> is a comma-separated list of fully qualified class names, for example, <code>java/lang/String</code>.</p>"},{"location":"xxensurehashed/#explanation","title":"Explanation","text":"<p>The <code>-XX:+EnsureHashed:&lt;classes&gt;</code> option specifies the classes and the <code>-XX:-EnsureHashed:&lt;classes&gt;</code> option ignores classes that were previously specified. These options are parsed left to right.</p> <p>For example, <code>-XX:+EnsureHashed:Class1,Class2,Class3 -XX:-EnsureHashed:Class2 -XX:+EnsureHashed:Class2,Class4 -XX:-EnsureHashed:Class1,Class3</code> results in the set of <code>EnsureHashed</code> classes {<code>Class2</code>, <code>Class4</code>}.</p> <p>Objects that are created from classes <code>Thread</code> and <code>Class</code> are allocated in the tenure region directly and therefore, do not get moved by the garbage collector often. It takes time for such pre-tenured objects to get hashed and extended with a slot. To pre-hash those objects from the start and hence, improve the performance,<code>-XX:+EnsureHashed:java/lang/Class,java/lang/Thread</code> is added to the list of default options in the <code>options.default</code> file.</p>"},{"location":"xxensurehashed/#see-also","title":"See also","text":"<ul> <li><code>-Xoptionsfile</code></li> <li>GC processing</li> </ul>"},{"location":"xxexitonoutofmemoryerror/","title":"-XX:[+|-]ExitOnOutOfMemoryError","text":""},{"location":"xxexitonoutofmemoryerror/#-xx-exitonoutofmemoryerror","title":"-XX:[+|-]ExitOnOutOfMemoryError","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122. You can use the option to trigger a shut down on VM out-of-memory conditions.</p> <p> Note: Java\u2122, heap, snap, and system dumps are enabled by default but can be disabled by including <code>-XX:-HeapDumpOnOutOfMemoryError</code>.</p>"},{"location":"xxexitonoutofmemoryerror/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ExitOnOutOfMemoryError\n</code></pre> Setting Effect Default <code>-XX:+ExitOnOutOfMemoryError</code> Enable <code>-XX:-ExitOnOutOfMemoryError</code> Disable yes"},{"location":"xxgloballockreservation/","title":"-XX:[+|-]GlobalLockReservation","text":""},{"location":"xxgloballockreservation/#-xx-globallockreservation","title":"-XX:[+|-]GlobalLockReservation","text":"<p>(AIX\u00ae and Linux on Power Systems\u2122 only)</p> <p>The <code>-XX:+GlobalLockReservation</code> option enables an optimization targeted towards more efficient handling of locking and unlocking Java\u2122 objects. The <code>-XX:-GlobalLockReservation</code> option is used to disable this optimization. The optimization is enabled by default.</p>"},{"location":"xxgloballockreservation/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]GlobalLockReservation\n    -XX:+GlobalLockReservation:&lt;parameter&gt;\n</code></pre> Setting Effect Default <code>-XX:+GlobalLockReservation</code> Enable yes <code>-XX:-GlobalLockReservation</code> Disable <p>This optimization is targeted towards applications with lots of uncontended locked objects that are being locked just to be safe. When enabled, heuristics are used to try and determine when an object will be exclusively locked by a single thread so that faster, more specialized code can be used for locking the object. If the heuristics incorrectly identify an object as a target for the optimization, performance might be adversely affected.</p> <p>The <code>-XX:-GlobalLockReservation</code> option turns off global lock reservation.</p> <p>The <code>-XX:+GlobalLockReservation</code> option can be used to enable global lock reservation if it was disabled by an option that occurs earlier in command line processing or to modify some of the global lock reservation related suboptions that are described later in this document.</p>"},{"location":"xxgloballockreservation/#parameters","title":"Parameters","text":"<p>Advanced tuning parameters are shown in the following table:</p> Parameter Effect <code>reservedTransitionThreshold</code> Changes amount of time spent analyzing an object. <code>reservedAbsoluteThreshold</code> Changes amount of time spent analyzing a class for compatibility. <code>minimumReservedRatio</code> Changes aggression level for marking a class as highly compatible. <code>cancelAbsoluteThreshold</code> Changes amount of time spent analyzing a class for incompatibility. <code>minimumLearningRatio</code> Changes aggression level for marking a class as highly incompatible."},{"location":"xxgloballockreservation/#reservedtransitionthreshold","title":"reservedTransitionThreshold","text":"<pre><code>    -XX:+GlobalLockReservation:reservedTransitionThreshold=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 1 <p>Number of times an object is locked by the same thread before it is considered reserved minus a value of 2. So, with a default value of 1, an object can be reserved the third time it is locked. <code>&lt;value&gt;</code> can be 0-3 inclusive. Values of 4 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#reservedabsolutethreshold","title":"reservedAbsoluteThreshold","text":"<pre><code>    -XX:+GlobalLockReservation:reservedAbsoluteThreshold=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 10 <p>Minimum number of objects of a class that get reserved before the class can be considered highly compatible. Objects of that class are reserved the first time they are locked. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#minimumreservedratio","title":"minimumReservedRatio","text":"<pre><code>    -XX:+GlobalLockReservation:minimumReservedRatio=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 1024 <p>Minimum ratio of reserved objects to flat objects before a class can be considered highly compatible. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#cancelabsolutethreshold","title":"cancelAbsoluteThreshold","text":"<pre><code>    -XX:+GlobalLockReservation:cancelAbsoluteThreshold=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 10 <p>Minimum number of objects of a class that get converted to flat before the class can be considered highly incompatible. Objects of that class are never reserved. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxgloballockreservation/#minimumlearningratio","title":"minimumLearningRatio","text":"<pre><code>    -XX:+GlobalLockReservation:minimumLearningRatio=&lt;value&gt;\n</code></pre> Setting Value Default <code>&lt;value&gt;</code> number 256 <p>Minimum ratio of reserved objects to flat objects to prevent class from being considered highly incompatible. Values of 65536 or higher are treated as infinity.</p>"},{"location":"xxhandlesigabrt/","title":"-XX:[+|-]HandleSIGABRT","text":""},{"location":"xxhandlesigabrt/#-xx-handlesigabrt","title":"-XX:[+|-]HandleSIGABRT","text":"<p>This option affects the handling of the operating system signal <code>SIGABRT</code>. This signal represents abnormal termination, and it can either be generated by the <code>abort</code> function or the <code>kill</code> command.</p>"},{"location":"xxhandlesigabrt/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HandleSIGABRT\n</code></pre> Setting Effect Default <code>-XX:+HandleSIGABRT</code> Enable yes <code>-XX:-HandleSIGABRT</code> Disable"},{"location":"xxhandlesigabrt/#explanation","title":"Explanation","text":"<p>When enabled, the VM handles the signal <code>SIGABRT</code> and generates the various dump files. </p> <p>When the option is disabled, the VM does not handle the signal <code>SIGABRT</code>. Generally, this signal is handled by the default operating system handler.</p> <p> Note: Do not use the <code>-XX:+HandleSIGABRT</code> and <code>-Xrs</code> options together. An error is thrown if both options are enabled. To resolve this error, one of the options should be disabled.</p>"},{"location":"xxhandlesigusr2/","title":"-XX:[+|-]HandleSIGUSR2","text":""},{"location":"xxhandlesigusr2/#-xx-handlesigusr2","title":"-XX:[+|-]HandleSIGUSR2","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae only)</p> <p>This option affects the handling of the <code>SIGUSR2</code> signal. This signal is user-defined and triggers the <code>user2</code> event, which is commonly used for taking system dump files with exclusive access. The operating system installs a default signal handler for handling <code>SIGUSR2</code>. If there is no VM or application signal handler, then the operating system's signal handler is used.</p>"},{"location":"xxhandlesigusr2/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HandleSIGAUSR2\n</code></pre> Setting Effect Default <code>-XX:+HandleSIGUSR2</code> Enable yes <code>-XX:-HandleSIGUSR2</code> Disable"},{"location":"xxhandlesigusr2/#explanation","title":"Explanation","text":"<p>When enabled, the VM handles the <code>SIGUSR2</code> signal and generates the <code>user2</code> event, which can be configured with the <code>-Xdump</code> option to trigger a dump agent.</p> <p>When the option is disabled, the VM does not handle the <code>SIGUSR2</code> signal and therefore, the VM signal handler is not installed. Generally, the default operating system handler that is installed for the <code>SIGUSR2</code> signal takes over the handling of the signal.</p> <p>For more information about the signals and signal handling, see Signal handling.</p> <p> Note: Do not use the <code>-XX:+HandleSIGUSR2</code> and <code>-Xrs</code> options together. An error is thrown if both options are enabled. To resolve this error, one of the options should be disabled.</p>"},{"location":"xxhandlesigusr2/#see-also","title":"See also","text":"<ul> <li>-Xdump</li> <li>-Xrs</li> </ul>"},{"location":"xxhandlesigxfsz/","title":"-XX:[+|-]HandleSIGXFSZ","text":""},{"location":"xxhandlesigxfsz/#-xx-handlesigxfsz","title":"-XX:[+|-]HandleSIGXFSZ","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae, and z/OS\u00ae only)</p> <p>This option affects the handling of the operating system signal <code>SIGXFSZ</code>. This signal is generated when a process attempts to write to a file that causes the maximum file size <code>ulimit</code> to be exceeded.</p>"},{"location":"xxhandlesigxfsz/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HandleSIGXFSZ\n</code></pre> Setting Effect Default <code>-XX:+HandleSIGXFSZ</code> Enable yes <code>-XX:-HandleSIGXFSZ</code> Disable"},{"location":"xxhandlesigxfsz/#explanation","title":"Explanation","text":"<p>When enabled, the VM handles the signal <code>SIGXFSZ</code> and continues, without ending. When a file is written from a Java\u2122 API class that exceeds the maximum file size <code>ulimit</code>, an exception is raised. Log files that are created by the VM are silently truncated when they reach the maximum file size <code>ulimit</code>.</p> <p>When the option is disabled, the VM does not handle the signal <code>SIGXFSZ</code>. In this situation, if the maximum file size <code>ulimit</code> for any file is reached, the operating system ends the process with a core dump.</p>"},{"location":"xxheapdumponoutofmemory/","title":"-XX:[+|-]HeapDumpOnOutOfMemory","text":""},{"location":"xxheapdumponoutofmemory/#-xx-heapdumponoutofmemory","title":"-XX:[+|-]HeapDumpOnOutOfMemory","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122. You can use the option to to disable Java\u2122, heap, snap, and system dumps on out-of-memory conditions, which are enabled by default.</p>"},{"location":"xxheapdumponoutofmemory/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HeapDumpOnOutOfMemory\n</code></pre> Setting Effect Default <code>-XX:+HeapDumpOnOutOfMemory</code> Enable yes <code>-XX:-HeapDumpOnOutOfMemory</code> Disable"},{"location":"xxheapdumppath/","title":"-XX:HeapDumpPath","text":""},{"location":"xxheapdumppath/#-xxheapdumppath","title":"-XX:HeapDumpPath","text":"<p>This HotSpot option is recognized by Eclipse OpenJ9\u2122 for compatibility, and you can use it as an alias for <code>-Xdump:directory=&lt;path&gt;</code>.</p> <p>This option sets the directory for all VM dumps including heap dumps, Java\u2122 dumps, and system dumps.</p>"},{"location":"xxheapdumppath/#syntax","title":"Syntax","text":"<pre><code>    -XX:HeapDumpPath=&lt;path&gt;\n</code></pre> <p>where <code>&lt;path&gt;</code> is the directory to which all dump types are written. This directory path is prefixed to the path of all non-absolute dump file names, including the file names for the default dump agents.</p>"},{"location":"xxheapmanagementmxbeancompatibility/","title":"-XX:[+|-]HeapManagementMXBeanCompatibility","text":""},{"location":"xxheapmanagementmxbeancompatibility/#-xx-heapmanagementmxbeancompatibility","title":"-XX:[+|-]HeapManagementMXBeanCompatibility","text":"<p>The MXBean interface now reports more detailed information about memory pools and garbage collectors for a garbage collection policy. In addition, the names of memory pools and garbage collectors are changed to match the naming convention that is used for verbose garbage collection logging. This option provides compatibility with earlier versions of the VM.</p>"},{"location":"xxheapmanagementmxbeancompatibility/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]HeapManagementMXBeanCompatibility\n</code></pre> Setting Effect Default <code>-XX:+HeapManagementMXBeanCompatibility</code> Enable <code>-XX:-HeapManagementMXBeanCompatibility</code> Disable yes <p>Setting <code>-XX:+HeapManagementMXBeanCompatibility</code> on the command line turns on compatibility with earlier versions of the VM. Information about memory pools and garbage collectors are reported in the older format.</p> <p>When compatibility is turned off, the VM reports more detailed information and matches the naming of memory pools and garbage collectors to the naming convention that is used for verbose garbage collection logging.</p>"},{"location":"xxheapmanagementmxbeancompatibility/#explanation","title":"Explanation","text":"<p>The additional information that is available from the MXBean interface for later versions is shown in the following table:</p> Garbage collection policy <code>MemoryPool</code> names <code>GarbageCollector</code> names gencon nursery-allocate, nursery-survivor, tenured-LOA, tenured-SOA, tenured scavenge, global optthruput or optavgpause tenured-LOA, tenured-SOA, tenured global balanced balanced-reserved, balanced-eden, balanced-survivor, balanced-old partial gc, global garbage collect metronome JavaHeap global <p>The <code>MemoryPoolMXBean</code> API reports values for 4 detailed memory pools instead of a single value for the overall Java\u2122 heap. In some cases the total sum of the 4 pools is more than the maximum heap size. This irregularity can be caused if data for each pool is collected between garbage collection cycles, where objects have been moved or reclaimed. If you want to collect memory usage data that is synchronized across the memory pools, use the <code>GarbageCollectionNotificationInfo</code> or <code>GarbageCollectorMXBean.getLastGcInfo</code> extensions.</p> <p>Earlier releases included only the following names:</p> <ul> <li><code>MemoryPool</code> pool name: <code>Java heap</code></li> <li><code>GarbageCollector</code> name: <code>Copy</code> and <code>MarkSweepCompact</code>.</li> </ul>"},{"location":"xxheapmanagementmxbeancompatibility/#see-also","title":"See also","text":"<ul> <li>Verbose garbage collection logging.</li> </ul> <p>For more information about IBM\u00ae MXBeans, see the <code>com.ibm.lang.management</code> API documentation.</p>"},{"location":"xxidletuningcompactonidle/","title":"-XX:[+|-]IdleTuningCompactOnIdle","text":""},{"location":"xxidletuningcompactonidle/#-xx-idletuningcompactonidle","title":"-XX:[+|-]IdleTuningCompactOnIdle","text":"<p>(Linux\u00ae only)</p> <p> Warning: From Eclipse OpenJ9\u2122 version 0.23.0 this option has no effect.</p> <p>In versions of OpenJ9 before 0.23.0, this option controls garbage collection processing with compaction when the state of the OpenJ9 VM is set to idle.</p> <p> Restrictions:</p> <ol> <li>This option was deprecated in release 0.15.0 due to operational changes. A compaction is now triggered by internal heuristics that look into the number of fragmented pages. Typically there is no need to force a compaction. This option will be removed in the future.</li> <li>This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use.</li> <li>This option is not effective if the object heap is configured to use large pages.</li> <li>This option is not effective if -XX:+IdleTuningGcOnIdle is not specified.</li> </ol>"},{"location":"xxidletuningcompactonidle/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IdleTuningCompactOnIdle\n</code></pre> Setting Effect Default Default when running in a docker container <code>-XX:+IdleTuningCompactOnIdle</code> Enable yes <code>-XX:-IdleTuningCompactOnIdle</code> Disable yes <p>The default depends on whether or not the OpenJ9 VM is running in a container. As indicated in the table, when the VM is running in a container and the state is set to idle, the VM attempts to compact the object heap following a garbage collection cycle. The garbage collection cycle is controlled by the <code>-XX:+IdleTuningGcOnIdle</code> option, which is also enabled by default when the OpenJ9 VM is running inside a container.</p> <p>If your application is not running in a container and you want compaction to be attempted every time idle GC happens as part of the idle-tuning process, set the <code>-XX:+IdleTuningCompactOnIdle</code> option on the command line when you start your application.</p> <p>The <code>-XX:+IdleTuningCompactOnIdle</code> option can be used with the <code>-XX:+IdleTuningMinIdleWaitTime</code>, which controls the amount of time that the VM must be idle before an idle state is set. If a value for the <code>-XX:+IdleTuningMinIdleWaitTime</code> option is not explicitly specified, the VM sets a default value of 180 seconds.</p>"},{"location":"xxidletuningcompactonidle/#see-also","title":"See also","text":"<ul> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:[+|-]IdleTuningGcOnIdle</li> </ul>"},{"location":"xxidletuninggconidle/","title":"-XX:[+|-]IdleTuningGcOnIdle","text":""},{"location":"xxidletuninggconidle/#-xx-idletuninggconidle","title":"-XX:[+|-]IdleTuningGcOnIdle","text":"<p>(Linux\u00ae only)</p> <p>This option controls whether a garbage collection cycle takes place when the state of the Eclipse OpenJ9\u2122 VM is set to idle. Compaction of the heap is also attempted during the idle GC when certain triggers are met.</p> <p> Restrictions: This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use. This option is not effective if the object heap is configured to use large pages.</p>"},{"location":"xxidletuninggconidle/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IdleTuningGcOnIdle\n</code></pre> Setting Effect Default Default when running in a docker container <code>-XX:+IdleTuningGcOnIdle</code> Enable yes <code>-XX:-IdleTuningGcOnIdle</code> Disable yes <p>The default depends on whether or not the OpenJ9 VM is running in a docker container. As indicated in the table, when the VM is running in a container and the state is set to idle, this option causes the VM to release free memory pages in the object heap without resizing the Java\u2122 heap and attempts to compact the heap after the garbage collection cycle if certain heuristics are triggered. The pages are reclaimed by the operating system, which reduces the physical memory footprint of the VM.</p> <p>If your application is not running in a container and you want to enable idle-tuning, set the <code>-XX:+IdleTuningGcOnIdle</code> option on the command line when you start your application.</p> <p>When enabled, the <code>-XX:+IdleTuningGcOnIdle</code> option is used with the <code>-XX:IdleTuningMinIdleWaitTime</code> and <code>-XX:IdleTuningMinFreeHeapOnIdle</code> options. If values for these options are not explicitly specified, the VM sets the following defaults:</p> <ul> <li><code>-XX:IdleTuningMinIdleWaitTime</code>=180</li> <li><code>-XX:IdleTuningMinFreeHeapOnIdle</code>=0</li> </ul>"},{"location":"xxidletuninggconidle/#see-also","title":"See also","text":"<ul> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> <li>-XX:[+|-]IdleTuningCompactOnIdle (From OpenJ9 version 0.23.0 this option has no effect.)</li> </ul>"},{"location":"xxidletuningminfreeheaponidle/","title":"-XX:IdleTuningMinFreeHeapOnIdle","text":""},{"location":"xxidletuningminfreeheaponidle/#-xxidletuningminfreeheaponidle","title":"-XX:IdleTuningMinFreeHeapOnIdle","text":"<p>(Linux\u00ae only)</p> <p>This option controls the percentage of free memory pages in the object heap that can be released when the Eclipse OpenJ9\u2122 VM is in an idle state.</p> <p> Restrictions: This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use. This option is not effective if the object heap is configured to use large pages.</p>"},{"location":"xxidletuningminfreeheaponidle/#syntax","title":"Syntax","text":"<pre><code>    -XX:IdleTuningMinFreeHeapOnIdle=&lt;percentage&gt;\n</code></pre> Setting Value Default <code>&lt;percentage&gt;</code> [0 - 100] 0 <p>When used with <code>-XX:+IdleTuningGcOnIdle</code>, this option can be used to place an upper bound on the percentage of free memory pages in the object heap that can be released when the VM is in an idle state. If <code>-XX:IdleTuningMinFreeHeapOnIdle</code> is not specified, the VM uses a default value of 0.</p>"},{"location":"xxidletuningminfreeheaponidle/#example","title":"Example","text":"<p>If you set <code>-XX:IdleTuningMinFreeHeapOnIdle=10</code>, no more than 90% of the free memory pages in the object heap can be released by the VM when it is in an idle state.</p>"},{"location":"xxidletuningminfreeheaponidle/#see-also","title":"See also","text":"<ul> <li>-XX:IdleTuningMinIdleWaitTime</li> <li>-XX:[+|-]IdleTuningGcOnIdle</li> <li>-XX:[+|-]IdleTuningCompactOnIdle (From OpenJ9 version 0.23.0 this option has no effect.)</li> </ul>"},{"location":"xxidletuningminidlewaittime/","title":"-XX:IdleTuningMinIdleWaitTime","text":""},{"location":"xxidletuningminidlewaittime/#-xxidletuningminidlewaittime","title":"-XX:IdleTuningMinIdleWaitTime","text":"<p>** (Linux\u00ae only) **</p> <p>When the Eclipse OpenJ9\u2122 VM is idle, this option controls the minimum length of time that the VM must be idle before the state of the VM is set to idle. When the state changes to idle, a garbage collection cycle runs, the object heap is compacted, and free memory pages are released back to the operating system, which reduces the footprint of the VM. Garbage collection and compaction are controlled by the <code>-XX:+IdleTuningGcOnIdle</code> and <code>-XX:+IdleTuningCompactOnIdle</code> options, which are enabled by default when the OpenJ9 VM is running inside a docker container. (Note that from OpenJ9 version 0.23.0 the <code>-XX:+IdleTuningCompactOnIdle</code> option has no effect.)</p> <p> Restrictions: This option applies only to Linux architectures when the Generational Concurrent (<code>gencon</code>) garbage collection policy is in use. This option is not effective if the object heap is configured to use large pages.</p>"},{"location":"xxidletuningminidlewaittime/#syntax","title":"Syntax","text":"<pre><code>    -XX:IdleTuningMinIdleWaitTime=&lt;secs&gt;\n</code></pre> Setting Value Default Default when running in a docker container <code>&lt;secs&gt;</code> [0 or greater] 0 180 <p>The value used for <code>&lt;secs&gt;</code> specifies the minimum length of time in seconds that the VM is idle before the state is set to idle. Idle tuning is enabled by default when the OpenJ9 VM is running in a docker container and the VM is detected as idle for 180 seconds. </p> <p>Setting the value to 0 disables this feature, which causes the following idle tuning options to have no effect:</p> <ul> <li><code>-XX:+IdleTuningCompactOnIdle</code></li> <li><code>-XX:+IdleTuningGcOnIdle</code></li> <li><code>-XX:IdleTuningMinFreeHeapOnIdle</code></li> </ul>"},{"location":"xxidletuningminidlewaittime/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]IdleTuningGcOnIdle</li> <li>-XX:IdleTuningMinFreeHeapOnIdle</li> <li>-XX:[+|-]IdleTuningCompactOnIdle (From OpenJ9 version 0.23.0 this option has no effect.)</li> </ul>"},{"location":"xxignoreunrecognizedrestoreoptions/","title":"-XX:[+|-]IgnoreUnrecognizedRestoreOptions","text":""},{"location":"xxignoreunrecognizedrestoreoptions/#-xx-ignoreunrecognizedrestoreoptions","title":"-XX:[+|-]IgnoreUnrecognizedRestoreOptions","text":"<p>(Linux\u00ae x86, Linux on POWER\u00ae (Little Endian), Linux on AArch64, and Linux on IBM Z\u00ae only)</p> <p>This option specifies whether the VM ignores any unrecognized options at the time of restore.</p> <p> Restrictions: This option takes effect only when <code>-XX:+EnableCRIUSupport</code> is enabled. This option can be used only on restore.</p>"},{"location":"xxignoreunrecognizedrestoreoptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IgnoreUnrecognizedRestoreOptions\n</code></pre> Setting Effect Default <code>-XX:+IgnoreUnrecognizedRestoreOptions</code> Enable <code>-XX:-IgnoreUnrecognizedRestoreOptions</code> Disable yes"},{"location":"xxignoreunrecognizedrestoreoptions/#explanation","title":"Explanation","text":"<p>When you restore a checkpoint image, you can specify additional command-line options by using the <code>CRIUSupport.registerRestoreOptionsFile</code> API. You can also use the <code>OPENJ9_RESTORE_JAVA_OPTIONS</code> environment variable (<code>CRIUSupport.registerRestoreEnvVariables</code> API) to add the VM options on restore. If you specify options that do not exist, or are unsupported, the VM, by default, fails to start and throws a <code>JVMRestoreException</code> error. The <code>-XX:+IgnoreUnrecognizedRestoreOptions</code> option disables the failure and allows the VM to continue even if some options are not used.</p>"},{"location":"xxignoreunrecognizedrestoreoptions/#see-also","title":"See also","text":"<ul> <li>CRIU support</li> </ul>"},{"location":"xxignoreunrecognizedvmoptions/","title":"-XX:[+|-]IgnoreUnrecognizedVMOptions","text":""},{"location":"xxignoreunrecognizedvmoptions/#-xx-ignoreunrecognizedvmoptions","title":"-XX:[+|-]IgnoreUnrecognizedVMOptions","text":"<p>This Oracle option affects the behavior of the HotSpot JVM when it finds an unrecognized top-level option at startup. This option is implemented in the Eclipse OpenJ9\u2122 VM for compatibility.</p>"},{"location":"xxignoreunrecognizedvmoptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IgnoreUnrecognizedVMOptions\n</code></pre> Setting Effect Default <code>-XX:+IgnoreUnrecognizedVMOptions</code> Enable <code>-XX:-IgnoreUnrecognizedVMOptions</code> Disable yes"},{"location":"xxignoreunrecognizedxxcolonoptions/","title":"-XX:[+|-]IgnoreUnrecognizedXXColonOptions","text":""},{"location":"xxignoreunrecognizedxxcolonoptions/#-xx-ignoreunrecognizedxxcolonoptions","title":"-XX:[+|-]IgnoreUnrecognizedXXColonOptions","text":"<p>By default, any <code>-XX:</code> options that you specify on the command line are ignored if they are not recognized, which prevents an application failing to start. However, if you want to determine whether any of your <code>-XX:</code> options are unrecognized, you can turn off the behavior with this option. You might want to do this, for example, if you are switching to Eclipse OpenJ9\u2122 from an alternative VM implementation where you are using <code>-XX:</code> options to tune the runtime environment.</p>"},{"location":"xxignoreunrecognizedxxcolonoptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]IgnoreUnrecognizedXXColonOptions\n</code></pre> Setting Effect Default <code>-XX:+IgnoreUnrecognizedXXColonOptions</code> Enable yes <code>-XX:-IgnoreUnrecognizedXXColonOptions</code> Disable <p>When you specify <code>-XX:-IgnoreUnrecognizedXXColonOptions</code>, if you also specify a <code>-XX:</code> option that is not recognized, that option is reported and the VM does not start. For example:</p> <pre><code>JVMJ9VM007E Command-line option unrecognised: -XX:InvalidOption\nError: Could not create the Java Virtual Machine.\nError: A fatal exception has occurred. Program will exit.\n</code></pre>"},{"location":"xxinitialheapsize/","title":"-XX:MaxHeapSize","text":""},{"location":"xxinitialheapsize/#-xxinitialheapsize-xxmaxheapsize","title":"-XX:InitialHeapSize / -XX:MaxHeapSize","text":"<p>These HotSpot options for specifying heap size are recognized by Eclipse OpenJ9\u2122 for compatibility. See -Xms / -Xmx for details.</p>"},{"location":"xxinitialheapsize/#syntax","title":"Syntax","text":"Setting Effect <code>-XX:InitialHeapSize&lt;size&gt;</code> Set initial heap size <code>-XX:MaxHeapSize&lt;size&gt;</code> Set maximum heap size"},{"location":"xxinitialrampercentage/","title":"-XX:MaxRAMPercentage","text":""},{"location":"xxinitialrampercentage/#-xxinitialrampercentage-xxmaxrampercentage","title":"-XX:InitialRAMPercentage / -XX:MaxRAMPercentage","text":"<p>These Oracle HotSpot options can be used to specify the initial and maximum size of the Java heap as a percentage of the total memory available to the VM. The options are recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxinitialrampercentage/#syntax","title":"Syntax","text":"Setting Effect <code>-XX:InitialRAMPercentage=N</code> Set initial heap size as a percentage of total memory <code>-XX:MaxRAMPercentage=N</code> Set maximum heap size as a percentage of total memory Where N is a value between 0 and 100, which can be of type \"double\". For example, 12.3456. <p> Note: If you set a value for <code>-Xms</code>, the <code>-XX:InitialRAMPercentage</code> option is ignored. If you set a value for <code>-Xmx</code>, the <code>-XX:MaxRAMPercentage</code> option is ignored.</p> <p>If your application is running in a container and you have specified <code>-XX:+UseContainerSupport</code>, both the default heap size for containers, the <code>-XX:InitialRAMPercentage</code> option, and the <code>-XX:MaxRAMPercentage</code> option are based on the available container memory.</p>"},{"location":"xxinterleavememory/","title":"-XX:[+|-]InterleaveMemory","text":""},{"location":"xxinterleavememory/#-xx-interleavememory","title":"-XX:[+|-]InterleaveMemory","text":"<p>(AIX\u00ae, Linux\u00ae, and Windows\u2122 only, but not Linux on IBM Z\u00ae)</p> <p>Use the <code>-XX:+InterleaveMemory</code> option to enable the interleaving of allocated memory across NUMA nodes.</p>"},{"location":"xxinterleavememory/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]InterleaveMemory\n</code></pre> Setting Effect Default <code>-XX:+InterleaveMemory</code> Enable <code>-XX:-InterleaveMemory</code> Disable yes"},{"location":"xxjitinlinewatches/","title":"-XX:[+|-]JITInlineWatches","text":""},{"location":"xxjitinlinewatches/#-xx-jitinlinewatches","title":"-XX:[+|-]JITInlineWatches","text":"<p>This option controls JIT operations that relate to JVMTI watched fields.</p>"},{"location":"xxjitinlinewatches/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITInlineWatches\n</code></pre> Setting Effect Default <code>-XX:+JITInlineWatches</code> Enable yes <code>-XX:-JITInlineWatches</code> Disable <p>This option enables performance improvements relating to JVMTI watched fields.</p>"},{"location":"xxjitserveraddress/","title":"-XX:JITServerAddress","text":""},{"location":"xxjitserveraddress/#-xxjitserveraddress","title":"-XX:JITServerAddress","text":"<p>This option specifies the JITServer server name or IP address for a JITServer client to connect to.</p>"},{"location":"xxjitserveraddress/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerAddress=&lt;address&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerAddress</code> Set server's name or IP address <code>localhost</code>"},{"location":"xxjitserveraddress/#explanation","title":"Explanation","text":"<p>When you enable this option, the JITServer client sends compilation requests to a server with the provided name or address. If there is no server available at that address, the JIT compiler compiles locally.</p>"},{"location":"xxjitserveraddress/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserveraotcachedir/","title":"-XX:JITServerAOTCacheDir","text":""},{"location":"xxjitserveraotcachedir/#-xxjitserveraotcachedir","title":"-XX:JITServerAOTCacheDir","text":"<p>(Linux\u00ae only)</p> <p>This option specifies the directory to be used for saving and loading JITServer AOT cache files.</p>"},{"location":"xxjitserveraotcachedir/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerAOTCacheDir=&lt;directory&gt;\n</code></pre> <p>If the option is not specified, the cache files are saved in the current working directory of the JITServer server.</p>"},{"location":"xxjitserveraotcachedir/#explanation","title":"Explanation","text":"<p>A JITServer instance can have several AOT caches, each with its own name. To enable reusing of the AOT caches by other JITServer instances (such as the instances started later), you can use the <code>-XX:+JITServerAOTCachePersistence</code> option. With this option enabled, JITServer server periodically saves its AOT caches to files. Other JITServer instances can then load these caches the first time a client requests a particular cache.</p> <p>You can specify the directory for saving the AOT cache files with the <code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code> option. When the server receives the location of the requested AOT cache file through the <code>-XX:JITServerAOTCacheDir</code> option and a request for a specific cache name, if that cache does not exist in-memory, the server searches the specified cache directory for the file with the matching name and loads it, if available.</p> <p>This option is not applicable if the JITServer AOT cache persistence feature is not enabled with the <code>-XX:+JITServerAOTCachePersistence</code> option.</p>"},{"location":"xxjitserveraotcachedir/#see-also","title":"See also","text":"<ul> <li>JITServer AOT cache</li> <li><code>-XX:[+|-]JITServerUseAOTCache</code></li> <li><code>-XX:JITServerAOTCacheName</code></li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code></li> </ul>"},{"location":"xxjitserveraotcachename/","title":"-XX:JITServerAOTCacheName","text":""},{"location":"xxjitserveraotcachename/#-xxjitserveraotcachename","title":"-XX:JITServerAOTCacheName","text":"<p>This option, used at the JITServer client JVMs, specifies the name of the AOT cache to be used at the JITServer server.</p>"},{"location":"xxjitserveraotcachename/#syntax","title":"Syntax","text":"<pre><code>     -XX:JITServerAOTCacheName=&lt;cache_name&gt;\n</code></pre> where <code>&lt;cache_name&gt;</code> specifies the name of the server-side AOT cache to be used."},{"location":"xxjitserveraotcachename/#explanation","title":"Explanation","text":"<p>A single JITServer instance can use multiple AOT caches, which are distinguished by their name.  Clients that are running applications with significantly different execution profiles can, therefore, connect to the same JITServer instance.  Specify this option at the client JVM. If you do not specify this option, the client uses a cache named <code>default</code>.</p> <p> Note: You must specify <code>-XX:+JITServerUseAOTCache</code>, otherwise the <code>-XX:JITServerAOTCacheName</code> option is ignored.</p>"},{"location":"xxjitserveraotcachename/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> <li><code>-XX:[+|-]JITServerUseAOTCache</code></li> <li><code>-XX:JITServerAOTCacheDir</code></li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code></li> </ul>"},{"location":"xxjitserveraotcachepersistence/","title":"-XX:[+|-]JITServerAOTCachePersistence","text":""},{"location":"xxjitserveraotcachepersistence/#-xx-jitserveraotcachepersistence","title":"-XX:[+|-]JITServerAOTCachePersistence","text":"<p>(Linux\u00ae only)</p> <p>This option enables or disables the JITServer server's ability to allow other JITServer instances to reuse AOT caches.</p>"},{"location":"xxjitserveraotcachepersistence/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerAOTCachePersistence\n</code></pre> Setting Effect Default <code>-XX:+JITServerAOTCachePersistence</code> Enable <code>-XX:-JITServerAOTCachePersistence</code> Disable yes"},{"location":"xxjitserveraotcachepersistence/#explanation","title":"Explanation","text":"<p>With the <code>-XX:+JITServerAOTCachePersistence</code> option, the JITServer server periodically saves its AOT caches to files. Other JITServer instances can then load these caches from files the first time a client requests a particular named cache. This feature is useful to improve performance, especially in scenarios where JITServer instances are started up and shut down regularly.</p> <p>This feature depends on the <code>-XX:+JITServerUseAOTCache</code> command-line option, which is used to enable caching of AOT-compiled methods. You must specify this option both at the client JVM and at the server.</p> <p>Use the <code>-XX:JITServerAOTCacheName=&lt;cache_name&gt;</code> option at the client to request a particular AOT cache. If the requested cache does not exist at the server in-memory, but the AOT cache persistence feature is enabled (<code>-XX:+JITServerAOTCachePersistence</code>), the server checks whether a file for that cache exists. If the AOT cache file exists, it is loaded in the background. If the AOT cache file does not exist or the AOT cache persistence feature is disabled (<code>-XX:-JITServerAOTCachePersistence</code>), the server creates an empty AOT cache and gradually populates it with AOT method bodies it compiles.</p> <p>You can use the <code>-XX:JITServerAOTCacheDir=&lt;directory&gt;</code> option to specify the directory where the AOT cache must be saved to or loaded from.</p> <p>The name of an AOT cache file has the following structure:</p> <pre><code>    JITServerAOTCache.&lt;CACHE_NAME&gt;.J&lt;JAVA_VERSION&gt;\n</code></pre> <p>Where,</p> <ul> <li><code>&lt;CACHE_NAME&gt;</code> is the name of the AOT cache requested by the client, and</li> <li><code>&lt;JAVA_VERSION&gt;</code> is the version of Java used by JITServer instance (for example, 17 will be used for Java 17)</li> </ul>"},{"location":"xxjitserveraotcachepersistence/#see-also","title":"See also","text":"<ul> <li><code>-XX:JITServerAOTCacheName</code></li> <li><code>-XX:JITServerAOTCacheDir</code></li> <li><code>-XX:[+|-]JITServerUseAOTCache</code></li> <li>JITServer AOT cache</li> </ul>"},{"location":"xxjitserveraotmx/","title":"-XX:JITServerAOTmx","text":""},{"location":"xxjitserveraotmx/#-xxjitserveraotmx","title":"-XX:JITServerAOTmx","text":"<p>(Linux\u00ae only)</p> <p>This option specifies the maximum amount of memory allocated to the JITServer AOT cache for storing the compiled code and for the associated data structures that are used in the cache's implementation.</p>"},{"location":"xxjitserveraotmx/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerAOTmx=&lt;size&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerAOTmx=&lt;size&gt;</code> Limits the amount of memory used by the JITServer AOT cache 300 MB"},{"location":"xxjitserveraotmx/#explanation","title":"Explanation","text":"<p>When the JITServer receives an AOT compilation request, it checks its AOT cache for a compatible compiled method body. If one is not found, the server performs the AOT compilation, sends the response to the client JVM, then stores the compiled method in its local AOT cache, for future use. Multiple requests and storing of the compiled methods can use a lot of memory and degrade the system's overall performance.</p> <p>You can specify the maximum memory limit for the AOT cache by using the <code>-XX:JITServerAOTmx=&lt;size&gt;</code> option, so that when the JITServer reaches that limit, it will not be able to add new AOT methods to its AOT cache. This will limit the amount of memory used for caching the compiled code and prevent memory shortages at JITServer that could lead to poor performance or even native out-of-memory events.</p>"},{"location":"xxjitserveraotmx/#see-also","title":"See also","text":"<ul> <li>JITServer AOT cache</li> </ul>"},{"location":"xxjitserverlocalsynccompiles/","title":"-XX:[+|-]JITServerLocalSyncCompiles","text":""},{"location":"xxjitserverlocalsynccompiles/#-xx-jitserverlocalsynccompiles","title":"-XX:[+|-]JITServerLocalSyncCompiles","text":"<p>When you specify this JITServer option, synchronous JIT compilations are downgraded to <code>cold</code> optimization level and compiled locally, with a remote asynchronous recompilation scheduled at a later point.</p>"},{"location":"xxjitserverlocalsynccompiles/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerLocalSyncCompiles\n</code></pre> Setting Effect Default <code>-XX:+JITServerLocalSyncCompiles</code> Enable yes <code>-XX:-JITServerLocalSyncCompiles</code> Disable <p>The option <code>-XX:[+|-]JITServerLocalSyncCompiles</code> is enabled by default in most cases. The option remains disabled when you specify <code>-Xjit:count=0</code> and in a few advanced use cases such as running the JVM in debug mode (as described in the Improved JVM debug mode based on OSR post in the Eclipse OpenJ9\u2122 blog).</p>"},{"location":"xxjitserverlocalsynccompiles/#explanation","title":"Explanation","text":"<p>During a synchronous compilation, Java\u2122 application threads have to wait for the compilation to complete. Because remote compilations usually take longer, due to network latency, remote synchronous compilations can result in large pauses in the client application.</p> <p>If you enable this option, the client performs synchronous compilations locally at <code>cold</code> optimization level and later recompiles asynchronously at a higher level remotely. This behavior can be beneficial for real-time applications.</p>"},{"location":"xxjitserverlocalsynccompiles/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserverlogconnections/","title":"-XX:[+|-]JITServerLogConnections","text":""},{"location":"xxjitserverlogconnections/#-xx-jitserverlogconnections","title":"-XX:[+|-]JITServerLogConnections","text":"<p>This option enables the logging of connection/disconnection events between the JITServer server and the JITServer client. You can use the option on both the server and the client sides.</p>"},{"location":"xxjitserverlogconnections/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerLogConnections\n</code></pre> Setting Effect Default <code>-XX:+JITServerLogConnections</code> Enable <code>-XX:-JITServerLogConnections</code> Disable yes"},{"location":"xxjitserverlogconnections/#explanation","title":"Explanation","text":"<p>This option is useful when you need to know when the server and the client successfully establish or terminate connections but verbose logs provide too much information.</p> <p>You can also enable the same logging by specifying the  <code>-Xjit:verbose={JITServerConns}</code> option.</p> <p>If you do not specify a <code>vlog</code> log file (<code>-Xjit:vlog=&lt;vlog_filename&gt;</code>), output is written to <code>stderr</code>, otherwise it is written to the <code>vlog</code> file.</p>"},{"location":"xxjitserverlogconnections/#example","title":"Example","text":"<p>This is what the typical output looks like:</p> <p>On the server side:</p> <pre><code>#JITServer: t=  2318 A new client (clientUID=11937826481210274991) connected. Server allocated a new client session.\n...\n...\n#JITServer: t= 48518 Client (clientUID=4213447851416537492) disconnected. Client session deleted\n</code></pre> <p>On the client side:</p> <pre><code>#JITServer: t=     0 Connected to a server (serverUID=10444660844386807777)\n...\n...\n#JITServer: t=   698 Lost connection to the server (serverUID=10444660844386807777)\n</code></pre>"},{"location":"xxjitserverlogconnections/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> <li>-Xjit / -Xnojit</li> </ul>"},{"location":"xxjitservermetrics/","title":"-XX:JITServerMetrics","text":""},{"location":"xxjitservermetrics/#-xx-jitservermetrics","title":"-XX:[+|-]JITServerMetrics","text":"<p>This option enables the provision of JITServer performance metrics to a monitoring agent that follows the OpenMetrics standard.</p> <p>When you enable this option, the following JITServer metrics are provided:</p> <ul> <li>The CPU utilization of the JITServer</li> <li>The physical memory that is available to the JITServer</li> <li>The number of clients that are connected to the JITServer</li> <li>The number of active compilation threads in the JITServer</li> </ul> <p> Note: You can use the <code>-XX:JITServerMetricsSSLKey</code> and <code>-XX:JITServerMetricsSSLCert</code> options for encrypting the data with SSL or TLS.</p>"},{"location":"xxjitservermetrics/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerMetrics\n</code></pre> Setting Effect Default <code>-XX:+JITServerMetrics</code> Enable <code>-XX:-JITServerMetrics</code> Disable yes"},{"location":"xxjitservermetrics/#explanation","title":"Explanation","text":"<p>When you enable this option, the JITServer process opens a TCP port, which can be used by monitoring agents (like Prometheus) to collect the custom metrics exported by the JITServer. Monitoring agents must issue HTTP <code>GET</code> requests to a URL of the form: <code>http://&lt;jitserveraddress&gt;:&lt;port&gt;/metrics</code>. The path for the HTTP request must be <code>/metrics</code>.</p> <p>The default value of <code>&lt;port&gt;</code> is 38500. You can change this value by using the <code>-XX:JITServerMetricsPort</code> command line option.</p> <p>The format for the metrics returned by the JITServer follows the OpenMetrics protocol.</p>"},{"location":"xxjitservermetrics/#example","title":"Example","text":"<p>The following example shows an HTTP request from a Prometheus monitoring agent and the response from the JITServer:</p> <p>HTTP request:</p> <p><code>GET /metrics HTTP/1.1    Host: 127.0.0.1:9403    User-Agent: Prometheus/2.31.1    Accept: application/openmetrics-text; version=0.0.1,text/plain;version=0.0.4;q=0.5,*/*;q=0.1    Accept-Encoding: gzip    X-Prometheus-Scrape-Timeout-Seconds: 3</code></p> <p>JITServer response:</p> <p><code># HELP jitserver_cpu_utilization Cpu utilization of the JITServer    # TYPE jitserver_cpu_utilization gauge    jitserver_cpu_utilization 12.000000    # HELP jitserver_available_memory Available memory for JITServer    # TYPE jitserver_available_memory gauge    jitserver_available_memory 32036204544.000000    # HELP jitserver_connected_clients Number of connected clients    # TYPE jitserver_connected_clients gauge    jitserver_connected_clients 1.000000    # HELP jitserver_active_threads Number of active compilation threads    # TYPE jitserver_active_threads gauge    jitserver_active_threads 1.000000</code></p>"},{"location":"xxjitservermetrics/#see-also","title":"See also","text":"<ul> <li>-XX:JITServerMetricsPort</li> <li>JITServer technology</li> <li><code>-XX:JITServerMetricsSSLKey</code></li> </ul>"},{"location":"xxjitservermetricsport/","title":"-XX:JITServerMetricsPort","text":""},{"location":"xxjitservermetricsport/#-xxjitservermetricsport","title":"-XX:JITServerMetricsPort","text":"<p>This option specifies the port number on which the JITServer metrics are provided to a monitoring agent.</p> <p>Use this option with the <code>-XX:+JITServerMetrics</code> option, which enables the provision of the JITServer metrics.</p>"},{"location":"xxjitservermetricsport/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerMetricsPort=&lt;port&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerMetricsPort</code> Set JITServer port for metrics 38500"},{"location":"xxjitservermetricsport/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]JITServerMetrics</li> <li>JITServer technology</li> </ul>"},{"location":"xxjitservermetricssslkey/","title":"-XX:JITServerMetricsSSLKey","text":""},{"location":"xxjitservermetricssslkey/#-xxjitservermetricssslkey-xxjitservermetricssslcert","title":"-XX:JITServerMetricsSSLKey / -XX:JITServerMetricsSSLCert","text":"<p>These options specify the names of the files that contain the private TLS or SSL key and certificate that are used for authentication and encryption of the custom metrics.</p>"},{"location":"xxjitservermetricssslkey/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerMetricsSSLKey=&lt;key_file&gt;\n    -XX:JITServerMetricsSSLCert=&lt;cert_file&gt;\n</code></pre> <p>Where <code>&lt;key_file&gt;</code> specifies the name of the file that contains the private TLS or SSL key and <code>&lt;cert_file&gt;</code> specifies the name of the file that contains the private TLS or SSL certificate. The files must all be in <code>.pem</code> file format.</p> Setting Effect Default <code>-XX:JITServerMetricsSSLKey</code> Set metrics SSL key None <code>-XX:JITServerMetricsSSLCert</code> Set metrics SSL certificate None"},{"location":"xxjitservermetricssslkey/#explanation","title":"Explanation","text":"<p>Custom metrics are exported by the JITServer server and collected by a monitoring agent, such as Prometheus. The exported data is sent in clear text by default. To secure this data with TLS or SSL authentication and encryption, specify the private key (<code>&lt;key&gt;.pem</code>) and the certificate (<code>&lt;cert&gt;.pem</code>) at the server:</p> <pre><code>    -XX:JITServerMetricsSSLKey=&lt;key&gt;.pem -XX:JITServerMetricsSSLCert=&lt;cert&gt;.pem\n</code></pre> <p>You must specify both the options for TLS or SSL authentication and encryption.</p> <p> Note: To enable the export of custom metrics, you must specify the <code>-XX:[+|-]JITServerMetrics</code> option.</p>"},{"location":"xxjitservermetricssslkey/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]JITServerMetrics</li> <li>JITServer technology</li> </ul>"},{"location":"xxjitserverport/","title":"-XX:JITServerPort","text":""},{"location":"xxjitserverport/#-xxjitserverport","title":"-XX:JITServerPort","text":"<p>This option specifies the port on which the JITServer server listens for compilation requests.</p> <p>On the JITServer server, this option sets the port that is open for connections.</p> <p>On the JITServer client, this option specifies to which server port the client should send compilation requests.</p>"},{"location":"xxjitserverport/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerPort=&lt;port&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerPort</code> Set JITServer port 38400"},{"location":"xxjitserverport/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitservershareromclasses/","title":"-XX:JITServerShareROMClasses","text":""},{"location":"xxjitservershareromclasses/#-xx-jitservershareromclasses","title":"-XX:[+|-]JITServerShareROMClasses","text":"<p>This option enables the JITServer server to share cached ROM classes between JITServer clients.</p>"},{"location":"xxjitservershareromclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerShareROMClasses\n</code></pre> Setting Effect Default <code>-XX:+JITServerShareROMClasses</code> Enable <code>-XX:-JITServerShareROMClasses</code> Disable yes <p> Note: The <code>-XX:+JITServerShareROMClasses</code> option is enabled by default at the server on specifying the <code>-XX:+JITServerUseAOTCache</code> option.</p>"},{"location":"xxjitservershareromclasses/#explanation","title":"Explanation","text":"<p>Enable this option when multiple clients that are running identical or similar applications connect to a single server.</p> <p>This option enables a caching optimization that allows the server to use ROM classes that are cached for one client while compiling for a different client. This behavior reduces the memory usage at the server because only a single copy of a particular Java\u2122 class is cached.</p>"},{"location":"xxjitservershareromclasses/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserversslcert/","title":"-XX:JITServerSSLRootCerts","text":""},{"location":"xxjitserversslcert/#-xxjitserversslcert-xxjitserversslkey-xxjitserversslrootcerts","title":"-XX:JITServerSSLCert / -XX:JITServerSSLKey / -XX:JITServerSSLRootCerts","text":"<p>Options for encrypting network communication between JITServer servers and JITServer client VMs.</p>"},{"location":"xxjitserversslcert/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerCert=&lt;cert_file&gt;\n    -XX:JITServerKey=&lt;key_file&gt;\n    -XX:JITServerSSLRootCerts=&lt;root_certs_file&gt;\n</code></pre> <p>The files must all be in <code>.pem</code> file format.</p> Setting Effect Default <code>-XX:JITServerSSLCert</code> Set server's SSL certificate None <code>-XX:JITServerSSLKey</code> Set server's SSL key None <code>-XX:JITServerSSLRootCerts</code> Set client's SSL root certificate None"},{"location":"xxjitserversslcert/#explanation","title":"Explanation","text":"<p>You can encrypt network communication by using OpenSSL 1.0.x, 1.1.x, or 3.x. To enable encryption, specify the private key (<code>&lt;key&gt;.pem</code>) and the certificate (<code>&lt;cert&gt;.pem</code>) at the server:</p> <pre><code>-XX:JITServerSSLKey=&lt;key&gt;.pem -XX:JITServerSSLCert=&lt;cert&gt;.pem\n</code></pre> <p>and use the certificate at the client:</p> <pre><code>-XX:JITServerSSLRootCerts=&lt;cert&gt;.pem\n</code></pre> <p>You must specify all three options for the client to be able to connect to the server. If the client cannot connect, it is forced to perform all compilations locally instead.</p> <p>For more details and further discussion about security considerations, see the blog post Free your JVM from the JIT with JITServer Technology.</p>"},{"location":"xxjitserversslcert/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitservertimeout/","title":"-XX:JITServerTimeout","text":""},{"location":"xxjitservertimeout/#-xxjitservertimeout","title":"-XX:JITServerTimeout","text":"<p>This option specifies the socket timeout for JITServer communication.</p> <p>You can specify this option on both the server and the client sides.</p>"},{"location":"xxjitservertimeout/#syntax","title":"Syntax","text":"<pre><code>    -XX:JITServerTimeout=&lt;timeout_ms&gt;\n</code></pre> Setting Effect Default <code>-XX:JITServerTimeout</code> Set the timeout value in milliseconds for socket operations 30000 ms for the JITServer process and 10000 ms when Eclipse OpenJ9\u2122 is launched as a client VM"},{"location":"xxjitservertimeout/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxjitserveruseaotcache/","title":"-XX:[+|-]JITServerUseAOTCache","text":""},{"location":"xxjitserveruseaotcache/#-xx-jitserveruseaotcache","title":"-XX:[+|-]JITServerUseAOTCache","text":"<p>This option enables the caching of AOT-compiled methods in the JITServer server.</p>"},{"location":"xxjitserveruseaotcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]JITServerUseAOTCache\n</code></pre> Setting Effect Default <code>-XX:+JITServerUseAOTCache</code> Enable <code>-XX:-JITServerUseAOTCache</code> Disable yes"},{"location":"xxjitserveruseaotcache/#explanation","title":"Explanation","text":"<p>When you enable this option, the JITServer server caches the AOT-compiled methods. When a JITServer client requests an AOT compilation and the requested method exists in the cache, the server does not have to recompile the method. This feature, therefore, improves the CPU utilization of the JITServer technology and of the cluster.</p> <p> Note: This option has the following requirements:</p> <ul> <li>You must specify this option both at the client JVM and at the server.</li> <li>The client JVM must have the shared classes cache feature enabled and be allowed to generate AOT compilation requests.</li> </ul> <p>The <code>-XX:+JITServerShareROMClasses</code> option is enabled by default at the server on specifying the<code>-XX:+JITServerUseAOTCache</code> option.</p>"},{"location":"xxjitserveruseaotcache/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> <li><code>-XX:JITServerAOTCacheName</code></li> <li><code>-XX:JITServerAOTCacheDir</code></li> <li><code>-XX:[+|-]JITServerAOTCachePersistence</code></li> </ul>"},{"location":"xxlazysymbolresolution/","title":"-XX:[+|-]LazySymbolResolution","text":""},{"location":"xxlazysymbolresolution/#-xx-lazysymbolresolution","title":"-XX:[+|-]LazySymbolResolution","text":"<p>(Linux\u00ae and macOS\u00ae only)</p> <p>This option affects the timing of symbol resolution for functions in user native libraries.</p>"},{"location":"xxlazysymbolresolution/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]LazySymbolResolution\n</code></pre> Setting Effect Default <code>-XX:+LazySymbolResolution</code> Enable yes <code>-XX:-LazySymbolResolution</code> Disable"},{"location":"xxlazysymbolresolution/#explanation","title":"Explanation","text":"<p>Enabling this option forces the VM to delay symbol resolution for each function in a user native library, until the function is called. The <code>-XX:-LazySymbolResolution</code> option forces the VM to immediately resolve symbols for all functions in a user native library when the library is loaded.</p> <p>These options apply only to functions; variable symbols are always resolved immediately when loaded. If you attempt to use these options on an operating system other than Linux or macOS, the options are accepted, but ignored.</p>"},{"location":"xxlegacyxlogoption/","title":"-XX:[+|-]LegacyXLogOption","text":""},{"location":"xxlegacyxlogoption/#-xx-legacyxlogoption","title":"-XX:[+|-]LegacyXlogOption","text":"<p>Controls processing of the <code>-Xlog</code> option.</p>"},{"location":"xxlegacyxlogoption/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+LegacyXlogOption</code> Enable legacy <code>-Xlog</code> behavior <code>-XX:-LegacyXlogOption</code> Process <code>-Xlog</code> requests for GC logging yes"},{"location":"xxlegacyxlogoption/#explanation","title":"Explanation","text":"<p>From Eclipse OpenJ9\u2122 0.24.0, the <code>-Xlog</code> option is replaced by the <code>-Xsyslog</code> option. The <code>-XX:[+|-]LegacyXlogOption</code> controls how the <code>-Xlog</code> option is processed.</p> <ul> <li>When <code>-XX:-LegacyXlogOption</code> is set, the <code>-Xlog</code> option is recognized only when a form of this option is run that requests garbage collection (GC) logging (for example, <code>-Xlog:gc[:stderr|:file=&lt;filename&gt;]</code>). For more information, see <code>-Xlog</code>.</li> <li>When <code>-XX:+LegacyXlogOption</code> is set, the legacy <code>-Xlog</code> behavior is enabled. When enabled, the option is equivalent to the <code>-Xsyslog</code> option. That is, the <code>-Xlog</code> option can be used with the parameters documented in <code>-Xsyslog</code>.</li> </ul>"},{"location":"xxmaxdirectmemorysize/","title":"-XX:MaxDirectMemorySize","text":""},{"location":"xxmaxdirectmemorysize/#-xxmaxdirectmemorysize","title":"-XX:MaxDirectMemorySize","text":"<p>This Oracle HotSpot option sets a limit on the amount of memory that can be reserved for all Direct Byte Buffers.</p>"},{"location":"xxmaxdirectmemorysize/#syntax","title":"Syntax","text":"<pre><code>-XX:MaxDirectMemorySize=&lt;size&gt;\n</code></pre> Setting Value Default <code>&lt;size&gt;</code> [1[k|K|m|M|g|G] or greater] Depends on maximum heap size <p>The value you choose is the limit on memory that can be reserved for all Direct Byte Buffers. If a value is set for this option, the sum of all Direct Byte Buffer sizes cannot exceed the limit. After the limit is reached, a new Direct Byte Buffer can be allocated only when enough old buffers are freed to provide enough space to allocate the new buffer.</p> <p> By default, the amount of native memory used for Direct Byte Buffers is limited to 87.5% of the maximum heap size.</p> <p> By default, the amount of native memory used for Direct Byte Buffers is limited to the maximum heap size.</p>"},{"location":"xxmergecompileroptions/","title":"-XX:[+|-]MergeCompilerOptions","text":""},{"location":"xxmergecompileroptions/#-xx-mergecompileroptions","title":"-XX:[+|-]MergeCompilerOptions","text":"<p>This option enables or disables the merging of multiple <code>-Xjit</code> or <code>-Xaot</code> options into a single <code>-Xjit</code> or <code>-Xaot</code> option.</p>"},{"location":"xxmergecompileroptions/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]MergeCompilerOptions\n</code></pre> Setting Effect Default <code>-XX:+MergeCompilerOptions</code> Enable <code>-XX:-MergeCompilerOptions</code> Disable yes"},{"location":"xxmergecompileroptions/#explanation","title":"Explanation","text":"<p>By default, if you specify <code>-Xjit</code> option (or <code>-Xaot</code> option) multiple times, only the last option takes effect. Therefore, on adding an <code>-Xjit</code> option, the resultant behavior might not be as expected, if any instance of this option already exists. It is time-consuming to find the existing instances and try combining them manually so that the system behaves as required.</p> <p>You can use the <code>-XX:+MergeCompilerOptions</code> option to merge all the existing instances of the <code>-Xjit</code> options logically. To retain the default behavior, whereby only the last option takes effect, you can use the <code>-XX:-MergeCompilerOptions</code> option.</p> <p>If both <code>-Xjit</code> and <code>-Xaot</code> options exist and you use the <code>-XX:+MergeCompilerOptions</code> option, then multiple <code>-Xjit</code> options are merged into a single <code>-Xjit</code> option and multiple <code>-Xaot</code> options are merged into a single <code>-Xaot</code> option.</p>"},{"location":"xxmergecompileroptions/#examples","title":"Examples","text":""},{"location":"xxmergecompileroptions/#one-xjit-option","title":"One <code>-Xjit</code> option","text":"<pre><code>java -Xshareclasses:none  -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:+MergeCompilerOptions -Xshareclasses:none  -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:-MergeCompilerOptions -Xshareclasses:none  -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p>"},{"location":"xxmergecompileroptions/#multiple-xjit-options","title":"Multiple <code>-Xjit</code> options","text":"<pre><code>java -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:+MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> options that are applied - <code>verbose={compilePerformance}</code>,<code>vlog=vlog</code>,<code>version</code></p> <pre><code>java -XX:-MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p>"},{"location":"xxmergecompileroptions/#both-xxmergecompileroptions-and-xx-mergecompileroptions","title":"Both <code>-XX:+MergeCompilerOptions</code> and <code>-XX:-MergeCompilerOptions</code>","text":"<p>If there are multiple <code>-XX:[+|-]MergeCompilerOptions</code> options with multiple <code>-Xjit</code> options, the last <code>-XX:[+|-]MergeCompilerOptions</code> setting takes effect before the <code>-Xjit</code> options are processed.</p> <pre><code>java -XX:+MergeCompilerOptions -XX:-MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> option that is applied - <code>version</code></p> <pre><code>java -XX:-MergeCompilerOptions -XX:+MergeCompilerOptions -Xshareclasses:none '-Xjit:verbose={compilePerformance},vlog=vlog' -Xjit:version -version\n</code></pre> <p><code>-Xjit</code> options that are applied - <code>{compilePerformance}</code>,<code>vlog=vlog</code>,<code>version</code></p>"},{"location":"xxmergecompileroptions/#see-also","title":"See also","text":"<ul> <li>-Xjit</li> <li>-Xaot</li> </ul>"},{"location":"xxnosuballoc32bitmem/","title":"-XXnosuballoc32bitmem","text":""},{"location":"xxnosuballoc32bitmem/#-xxnosuballoc32bitmem","title":"-XXnosuballoc32bitmem","text":"<p>(z/OS\u00ae only)</p> <p>When compressed references are used with a 64-bit Eclipse OpenJ9\u2122 VM on z/OS\u00ae, this option forces the VM to use 31-bit memory allocation functions provided by z/OS.</p>"},{"location":"xxnosuballoc32bitmem/#syntax","title":"Syntax","text":"<pre><code>    -XXnosuballoc32bitmem\n</code></pre> Setting Effect Default <code>-XXnosuballoc32bitmem</code> Enable No setting Disable yes"},{"location":"xxnosuballoc32bitmem/#explanation","title":"Explanation","text":"<p>This option is provided as a workaround for customers who need to use fewer pages of 31-bit virtual storage per VM invocation. Using this option might result in a small increase in the number of frames of central storage used by the VM. However, the option frees 31-bit pages for use by native code or other applications in the same address space.</p> <p>If this option is not specified, the VM uses an allocation strategy for 31-bit memory that reserves a region of 31-bit virtual memory.</p>"},{"location":"xxonoutofmemoryerror/","title":"-XX:OnOutOfMemoryError","text":""},{"location":"xxonoutofmemoryerror/#-xxonoutofmemoryerror","title":"-XX:OnOutOfMemoryError","text":"<p>You can use this Oracle HotSpot option to run commands when a <code>java.lang.OutOfMemoryError</code> is thrown. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxonoutofmemoryerror/#syntax","title":"Syntax","text":"<pre><code>    -XX:OnOutOfMemoryError=\"&lt;command_string&gt;\"\n</code></pre> <p>where <code>&lt;command_string&gt;</code> is a command or list of commands to run when a <code>java.lang.OutOfMemoryError</code> occurs.</p> <p>For example, the following command specifies that the <code>java -version</code> command is run if the <code>Test</code> application throws a <code>java.lang.OutOfMemoryError</code> exception:</p> <p><code>java -XX:OnOutOfMemoryError=\"java -version\" Test</code></p> <p>If you want to run multiple commands, use semicolons to separate them  within <code>&lt;command_string&gt;</code>. For example:</p> <p><code>-XX:OnOutOfMemoryError=\"&lt;java_path&gt; &lt;java_program&gt;; cat file.txt\"</code></p> <p>The <code>-XX:OnOutOfMemoryError</code> option is equivalent to the following <code>-Xdump</code> option:</p> <p><code>-Xdump:tool:events=systhrow,filter=java/lang/OutOfMemoryError,exec=&lt;command_string&gt;</code></p> <p>For more information, see <code>-Xdump</code>.  </p>"},{"location":"xxopenj9commandlineenv/","title":"-XX:[+|-]OpenJ9CommandLineEnv","text":""},{"location":"xxopenj9commandlineenv/#-xx-openj9commandlineenv","title":"-XX:[+|-]OpenJ9CommandLineEnv","text":"<p>This option controls whether the VM captures the command line in the environment variable <code>OPENJ9_JAVA_COMMAND_LINE</code>. If enabled, the variable is set by the VM after it starts. Using this variable, you can find the command-line parameters set when the VM started. It applies not just to launchers (e.g. <code>java</code>) that are included in a JDK, but to any application that uses <code>JNI_CreateJavaVM()</code>.</p>"},{"location":"xxopenj9commandlineenv/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]OpenJ9CommandLineEnv\n</code></pre> Setting Effect Default on z/OS Default on other platforms <code>-XX:+OpenJ9CommandLineEnv</code> Enable yes <code>-XX:-OpenJ9CommandLineEnv</code> Disable yes <p>This option is currently disabled by default on z/OS\u00ae because it might cause the VM to crash.</p>"},{"location":"xxopenj9commandlineenv/#see-also","title":"See also","text":"<ul> <li>Environment variables</li> </ul>"},{"location":"xxoriginaljdk8heapsizecompatibilitymode/","title":"-XX:[+|-]OriginalJDK8HeapSizeCompatibilityMode","text":""},{"location":"xxoriginaljdk8heapsizecompatibilitymode/#-xx-originaljdk8heapsizecompatibilitymode","title":"-XX:[+|-]OriginalJDK8HeapSizeCompatibilityMode","text":"<p> The default value for the maximum heap size (<code>-Xmx</code>) is 25% of the available memory with a maximum of 25 GB. However, where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB. In Eclipse OpenJ9\u2122 0.18.0 and earlier releases the default is half the available memory with a minimum of 16 MB and a maximum of 512 MB. Enable this option to revert to the earlier default value.</p> <p> Restriction: This option is supported only on Java\u2122 8. It is ignored on Java 11 and later versions.</p>"},{"location":"xxoriginaljdk8heapsizecompatibilitymode/#syntax","title":"Syntax","text":"<pre><code>-XX:[+|-]OriginalJDK8HeapSizeCompatibilityMode\n</code></pre> Setting Effect Default -XX:+OriginalJDK8HeapSizeCompatibilityMode Enable -XX:-OriginalJDK8HeapSizeCompatibilityMode Disable yes"},{"location":"xxpagealigndirectmemory/","title":"-XX:[+|-]PageAlignDirectMemory","text":""},{"location":"xxpagealigndirectmemory/#-xx-pagealigndirectmemory","title":"-XX:[+|-]PageAlignDirectMemory","text":"<p>This Oracle HotSpot option affects the alignment of direct byte buffer allocation and is implemented by the Eclipse OpenJ9\u2122 VM for compatibility.</p>"},{"location":"xxpagealigndirectmemory/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PageAlignDirectMemory\n</code></pre> Setting Effect Default <code>-XX:+PageAlignDirectMemory</code> Enable <code>-XX:-PageAlignDirectMemory</code> Disable yes <p>As discussed in the Oracle documentation, before Java\u2122 SE 7, direct buffers that were allocated using <code>java.nio.ByteBuffer.allocateDirect(int)</code> were aligned on a page boundary. This behavior changed in Java SE 7 and the <code>-XX:+PageAlignDirectMemory</code> option is provided to revert to the previous behavior.</p> <p>For more information about the changes, see RFE 4837564, which was introduced in the Java SE 7 release notes.</p>"},{"location":"xxparallelcmsthreads/","title":"-XX:ParallelCMSThreads","text":""},{"location":"xxparallelcmsthreads/#-xxparallelcmsthreads","title":"-XX:ParallelCMSThreads","text":"<p>This Oracle HotSpot option affects the number of threads used by the concurrent garbage collector. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxparallelcmsthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ParallelCMSThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of low-priority background threads that are attached to assist the mutator threads in concurrent mark.</p> <p>Within OpenJ9 this option is directly mapped to <code>-Xconcurrentbackground</code>.</p>"},{"location":"xxparallelgcmaxthreads/","title":"-XX:ParallelGCMaxThreads","text":""},{"location":"xxparallelgcmaxthreads/#-xxparallelgcmaxthreads","title":"-XX:ParallelGCMaxThreads","text":"<p>This option specifies the maximum number of threads that can be used during parallel operations of the garbage collector. Unlike <code>-XX:ParallelGCThreads</code>, this option does not enforce a thread count, but can be used to allow the garbage collector to adjust the number of parallel GC threads, if used with the Adaptive GC Threading option.</p>"},{"location":"xxparallelgcmaxthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ParallelGCMaxThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the maximum number of threads that can be used for parallel operations. </p> <p>This option is directly mapped to <code>-Xgcmaxthreads</code>.</p>"},{"location":"xxparallelgcthreads/","title":"-XX:ParallelGCThreads","text":""},{"location":"xxparallelgcthreads/#-xxparallelgcthreads","title":"-XX:ParallelGCThreads","text":"<p>This Oracle HotSpot option specifies the number of threads that are used during parallel operations of the default garbage collector. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p> <p> Notes:</p> <p>This option enforces the thread count and cannot be used with the <code>-XX:+AdaptiveGCThreading</code> option, which enables the garbage collector to adjust the number of parallel threads based on heuristics. If you want to use <code>-XX:+AdaptiveGCThreading</code>, use <code>-XX:ParallelGCMaxThreads</code> instead of <code>-XX:ParallelGCThreads</code>.</p>"},{"location":"xxparallelgcthreads/#syntax","title":"Syntax","text":"<pre><code>    -XX:ParallelGCThreads=&lt;number&gt;\n</code></pre> <p>Where <code>&lt;number&gt;</code> is the number of threads that are used for parallel operations. </p> <p>Within OpenJ9 this option is directly mapped to <code>-Xgcthreads</code>.</p>"},{"location":"xxperftool/","title":"-XX:[+|-]PerfTool","text":""},{"location":"xxperftool/#-xx-perftool","title":"-XX:[+|-]PerfTool","text":"<p>This option enables or disables JIT support for the <code>perf</code> tool without affecting the existing <code>Xjit</code> options.</p> <p> Restriction: Since this option creates a file that is used by the Linux\u00ae system profiler, <code>perf</code>, it applies only to Linux.</p>"},{"location":"xxperftool/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PerfTool\n</code></pre> Setting Effect Default <code>-XX:+PerfTool</code> Enable <code>-XX:-PerfTool</code> Disable yes"},{"location":"xxperftool/#explanation","title":"Explanation","text":"<p>The <code>-XX:+PerfTool</code> option is a stand-alone alternative for the existing <code>-Xjit:perfTool</code> option. If multiple <code>-Xjit</code> options exist, only the last option takes effect. Therefore, if the <code>-Xjit:perfTool</code> option is added later, it overrides the existing <code>-Xjit</code> options. To overcome this issue, the <code>XX:+PerfTool</code> option enables JIT support for the <code>perf</code> tool without having any impact on the existing <code>Xjit</code> options. This enabling option creates a <code>/tmp/perf-&lt;pid&gt;.map</code> file that is used by the <code>perf</code> tool to map the samples in the JIT-compiled code to the corresponding Java method names.</p> <p>To disable the JIT support for the <code>perf</code> tool, set the <code>-XX:-PerfTool</code> option on the command line.</p>"},{"location":"xxperftool/#see-also","title":"See also","text":"<ul> <li><code>xjit</code></li> </ul>"},{"location":"xxportablesharedcache/","title":"-XX:[+|-]PortableSharedCache","text":""},{"location":"xxportablesharedcache/#-xx-portablesharedcache","title":"-XX:[+|-]PortableSharedCache","text":"<p>Use this command line option to choose whether AOT-compiled code should be portable.</p> <p>This option, when enabled, increases the portability of AOT-compiled code, in the following ways:</p> <ul> <li> <p>The code is generated based on a particular set of processor features that ensures the AOT-compiled code to be portable across processors of different microarchitectures. AOT-compiled code generated with this option is guaranteed to be portable across Intel\u00ae Sandy Bridge or newer microarchitectures on x86 platforms, IBM\u00ae z10 or newer microarchitectures on s390 platforms and IBM POWER8\u00ae or newer microarchitectures on POWER platforms.</p> </li> <li> <p>The code is generated to be portable across Eclipse OpenJ9\u2122 VMs that use compressed references and have a heap size of 1 MB to 28 GB (previously, AOT-compiled code could not be shared between VMs that use compressed references and that have different heap sizes). This feature might introduce a small (1-2%) steady-state throughput penalty when compressed references are used and the heap size is between 1 MB and 3 GB.</p> </li> </ul> <p>This feature is particularly relevant for packaging a shared classes cache into a container image (for example, applications deployed on the cloud in the form of Docker containers) due to the following reasons: - The processor on which the container image is built is likely to be different from the processor on which the container is deployed.  - In a multi-layered container image where the shared classes cache is multi-layered as well, the AOT-compiled code in shared classes cache will likely come from multiple OpenJ9 VMs with different heap size requirements.</p>"},{"location":"xxportablesharedcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PortableSharedCache\n</code></pre> Setting Effect Default <code>-XX:+PortableSharedCache</code> Enable See notes that follow <code>-XX:-PortableSharedCache</code> Disable"},{"location":"xxportablesharedcache/#default-settings","title":"Default settings","text":"<p>This option is enabled by default in containers. To disable the option in a container, specify <code>-XX:-PortableSharedCache</code>.</p> <p>The option is disabled by default outside containers. To enable the option outside a container, specify <code>-XX:+PortableSharedCache</code> for the initial JVM instance (when the creation of the shared classes cache happens) as well as for every subsequent instance that makes use of the same shared classes cache.</p>"},{"location":"xxpositiveidentityhash/","title":"-XX:[+|-]PositiveIdentityHash","text":""},{"location":"xxpositiveidentityhash/#-xx-positiveidentityhash","title":"-XX:[+|-]PositiveIdentityHash","text":"<p>Eclipse OpenJ9\u2122 allows both positive and negative identity hashcodes (<code>System.identityHashCode</code> / <code>Object.hashCode</code>). This is problematic for programs that incorrectly assume hashcodes can only be positive.</p> <p>When enabled, this option limits identity hash codes to non-negative values.</p> <p>Because limiting identity hash codes to non-negative values can have an impact on the performance of hash-intensive operations, this option is not enabled by default.</p>"},{"location":"xxpositiveidentityhash/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PositiveIdentityHash\n</code></pre> Setting Effect Default <code>-XX:+PositiveIdentityHash</code> Enable <code>-XX:-PositiveIdentityHash</code> Disable yes"},{"location":"xxprintcodecache/","title":"-XX:[+|-]PrintCodeCache","text":""},{"location":"xxprintcodecache/#-xx-printcodecache","title":"-XX:[+|-]PrintCodeCache","text":"<p>This Oracle HotSpot option prints the code cache memory usage when the application exits. This option is recognized by Eclipse OpenJ9\u2122 and provided for compatibility.</p>"},{"location":"xxprintcodecache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PrintCodeCache\n</code></pre> Setting Effect Default <code>-XX:+PrintCodeCache</code> Enable <code>-XX:-PrintCodeCache</code> Disable yes <p>As discussed in the Oracle documentation, the code cache usage can be shown when the application exits, by specifying <code>\u2013XX:+PrintCodeCache</code> on the Java launcher command line. The output looks similar to the following: </p> <pre><code>CodeCache: size=262144Kb used=454Kb max_used=457Kb free=261690Kb\n</code></pre> <ul> <li><code>size</code>: The maximum size of the code cache.</li> <li><code>used</code>: The amount of code cache memory actually in use.</li> <li><code>max_used</code>: The high water mark for code cache usage.</li> <li><code>free</code>: <code>size</code> minus <code>used</code>.</li> </ul>"},{"location":"xxprintflagsfinal/","title":"-XX:[+|-]PrintFlagsFinal","text":""},{"location":"xxprintflagsfinal/#-xx-printflagsfinal","title":"-XX:[+|-]PrintFlagsFinal","text":"<p>When enabled, this option outputs the values of a subset of configuration parameters in a format compatible with that produced by HotSpot. The parameters currently output are those expected by various software projects and packages.</p>"},{"location":"xxprintflagsfinal/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]PrintFlagsFinal\n</code></pre> Setting Effect Default <code>-XX:+PrintFlagsFinal</code> Enable <code>-XX:-PrintFlagsFinal</code> Disable yes"},{"location":"xxprintflagsfinal/#example","title":"Example","text":"<p>Here is an example of typical output from <code>-XX:+PrintFlagsFinal</code>:</p> <pre><code>[Global flags]\n   size_t MaxHeapSize              = 4294967296          {product} {ergonomic}\n uint64_t MaxDirectMemorySize      = 3758096384          {product} {ergonomic}\n</code></pre>"},{"location":"xxreadipinfoforras/","title":"-XX:[+|-]ReadIPInfoForRAS","text":""},{"location":"xxreadipinfoforras/#-xx-readipinfoforras","title":"-XX:[+|-]ReadIPInfoForRAS","text":"<p>Use this command-line option to enable and disable network queries from being used to determine the host name and IP address for RAS (reliability, availability, and serviceability) troubleshooting purposes.</p>"},{"location":"xxreadipinfoforras/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ReadIPInfoForRAS\n</code></pre> Setting Effect Default <code>-XX:+ReadIPInfoForRAS</code> Enable yes <code>-XX:-ReadIPInfoForRAS</code> Disable <p>Eclipse OpenJ9\u2122 captures the host name and IP address by default, for use in diagnosing problems. But if a nameserver cannot be contacted when a network query is made, the program will wait until the resolver times out.</p> <p>You can avoid this situation by using the <code>-XX:-ReadIPInfoForRAS</code> command-line option to prevent the query from being performed.</p>"},{"location":"xxreducecpumonitoroverhead/","title":"-XX:[+|-]ReduceCPUMonitorOverhead","text":""},{"location":"xxreducecpumonitoroverhead/#-xx-reducecpumonitoroverhead","title":"-XX:[+|-]ReduceCPUMonitorOverhead","text":"<p>(AIX\u00ae, Linux\u00ae, macOS\u00ae, and Windows\u2122 only)</p> <p>This option relates to the CPU usage of thread categories that can be obtained with the <code>com.ibm.lang.management.JvmCpuMonitorMXBean</code> application programming interface. This option affects the way that the VM records the amount of CPU usage of non-Garbage Collection (GC) threads that do work on behalf of GC.</p> <p>Most GC policies require non-GC threads to do some GC housekeeping work in proportion to the amount of memory allocation that they do. Ideally the exact amount of CPU time that the thread spends doing this housekeeping work should be accounted for in the GC thread category. However there is an overhead that is associated with maintaining the CPU usage data in the correct thread category.</p> <p> Restriction: This option is not supported on z/OS\u00ae. If you attempt to use this option, the following message is generated:</p> <pre><code>JVMJ9VM145E -XX:-ReduceCPUMonitorOverhead is unsupported on z/OS. Error: Could not create the Java Virtual Machine.\n</code></pre>"},{"location":"xxreducecpumonitoroverhead/#syntax","title":"Syntax","text":"<p>-XX:[+|-]ReduceCPUMonitorOverhead</p> Setting Effect Default <code>-XX:+ReduceCPUMonitorOverhead</code> Enable yes <code>-XX:-ReduceCPUMonitorOverhead</code> Disable <p>When you enable this option, the VM does not maintain information on the amount of CPU usage that non-GC threads spend in doing work on behalf of GC. If you set <code>-XX:-ReduceCPUMonitorOverhead</code>, the Eclipse OpenJ9\u2122 VM monitors the amount of GC work that a non-GC thread does and accounts for it in the GC category. This information is made available in the <code>com.ibm.lang.management.JvmCpuMonitorMXBean</code>. Setting this option results in a small increase in application startup time, which varies according to platform.</p>"},{"location":"xxreducecpumonitoroverhead/#see-also","title":"See also","text":"<ul> <li>-XX:[+|-]EnableCPUMonitor</li> </ul>"},{"location":"xxrequirejitserver/","title":"-XX:[+|-]RequireJITServer","text":""},{"location":"xxrequirejitserver/#-xx-requirejitserver","title":"-XX:[+|-]RequireJITServer","text":"<p>When you enable this option, the JITServer client crashes with an assert if it detects that a JITServer server is unavailable.</p>"},{"location":"xxrequirejitserver/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]RequireJITServer\n</code></pre> Setting Effect Default <code>-XX:+RequireJITServer</code> Enable <code>-XX:-RequireJITServer</code> Disable yes"},{"location":"xxrequirejitserver/#explanation","title":"Explanation","text":"<p>This option is for debugging purposes only.</p> <p>When this option is disabled, a server crash forces the client to perform compilations locally. You might want to enable this option if you are running a test suite with JITServer enabled, so that a test fails if the server crashes, instead of switching to local compilations and hiding the failure.</p>"},{"location":"xxrequirejitserver/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxruntimeinstrumentation/","title":"-XX:[+|-]RuntimeInstrumentation","text":""},{"location":"xxruntimeinstrumentation/#-xx-runtimeinstrumentation","title":"-XX:[+|-]RuntimeInstrumentation","text":"<p>(AIX\u00ae, Linux\u00ae, and z/OS\u00ae only)</p> <p>This option controls the use of the Runtime Instrumentation (RI) facility in the virtual machines that support it.</p> <p>The RI facility is a feature that is available in POWER8\u00ae, zEC12, and later processors that offers hardware support for collecting profiling information at run time. The process uses minimal resources. The use of the RI facility is not enabled by default.</p>"},{"location":"xxruntimeinstrumentation/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]RuntimeInstrumentation\n</code></pre> Setting Effect Default <code>-XX:+RuntimeInstrumentation</code> Enable <code>-XX:-RuntimeInstrumentation</code> Disable yes <p> Note: On Linux, the RI facility on Power 8 and later processors uses the Performance Monitoring Unit (PMU) inside the processor. However, the PMU is also used by system profilers like oprofile or perf. Due to the current Linux kernel implementation, a user cannot reliably profile a Java\u2122 application when RI is enabled. Although this limitation might be addressed in future Linux kernels, for reliable profiling on Power systems that use Linux, the <code>-XX:-RuntimeInstrumentation</code> option must be used.</p>"},{"location":"xxsethwprefetch/","title":"-XXsetHWPrefetch","text":""},{"location":"xxsethwprefetch/#-xxsethwprefetch","title":"-XXsetHWPrefetch","text":"<p>(AIX\u00ae only)</p> <p>This option enables or disables hardware prefetch. Hardware prefetch can improve the performance of applications by prefetching memory. However, because of the workload characteristics of many Java\u2122 applications, prefetching often has an adverse effect on performance.</p>"},{"location":"xxsethwprefetch/#syntax","title":"Syntax","text":"<pre><code>    -XXsetHWPrefetch=[none|os-default]\n</code></pre> Setting Effect Default none Disable yes os-default Enable <p>The <code>-XXsetHWPrefetch:none</code> option disables hardware prefetch. Although you can disable hardware prefetch on AIX by issuing the command <code>dscrctl -n -s 1</code>, this command disables hardware prefetch for all processes, and for all future processes, which might not be desirable in a mixed workload environment. The <code>-XXsetHWPrefetch:none</code> option allows hardware prefetch to be disabled for individual VMs.</p> <p>To enable hardware prefetch with the default value for the operating system, specify <code>-XXsetHWPrefetch:os-default</code>. Use this option only for applications that can obtain a performance gain from hardware prefetch.</p>"},{"location":"xxshareanonymousclasses/","title":"-XX:[+|-]ShareAnonymousClasses","text":""},{"location":"xxshareanonymousclasses/#-xx-shareanonymousclasses","title":"-XX:[+|-]ShareAnonymousClasses","text":"<p>This option enables and disables the storage of VM anonymous classes, those created by <code>Unsafe.defineAnonymousClass</code>, in the shared classes cache.</p> <p> In OpenJDK 15 and later versions, this option also enables and disables the storage of hidden classes in the shared classes cache.</p> <p>The option is enabled by default, which means that anonymous classes (and hidden classes, in OpenJDK 15 and later) are stored in the shared classes cache and are therefore available for ahead-of-time (AOT) compilation, potentially improving startup performance.</p>"},{"location":"xxshareanonymousclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShareAnonymousClasses\n</code></pre> Setting Effect Default <code>-XX:+ShareAnonymousClasses</code> Enable yes <code>-XX:-ShareAnonymousClasses</code> Disable"},{"location":"xxshareanonymousclasses/#see-also","title":"See also","text":"<ul> <li>AOT compiler</li> <li>Introduction to class data sharing</li> <li>-Xshareclasses</li> <li>-XX:[+|-]ShareUnsafeClasses</li> </ul>"},{"location":"xxshareclassesenablebci/","title":"-XX:ShareClassesEnableBCI","text":""},{"location":"xxshareclassesenablebci/#-xxshareclassesdisablebci-xxshareclassesenablebci","title":"-XX:ShareClassesDisableBCI /  -XX:ShareClassesEnableBCI","text":"<p>The option <code>-Xshareclasses:enableBCI</code> improves startup performance without using a modification context, when using JVMTI class modification. This suboption allows classes loaded from the shared cache to be modified using a JVMTI <code>ClassFileLoadHook</code>, or a <code>java.lang.instrument</code> agent, and prevents modified classes being stored in the shared classes cache. You can turn off this option by specifying <code>-XX:ShareClassesDisableBCI</code> when you start your Java\u2122 application.</p>"},{"location":"xxshareclassesenablebci/#syntax","title":"Syntax","text":"<pre><code>    -XX:ShareClassesDisableBCI|ShareClassesEnableBCI\n</code></pre> Setting Effect Default <code>-XX:ShareClassesDisableBCI</code> Disable <code>-XX:ShareClassesEnableBCI</code> Enable yes <p>These options are equivalent to <code>-Xshareclasses:disableBCI</code> and <code>-Xshareclasses:enableBCI</code>. For more information, see <code>-Xshareclasses</code>.</p>"},{"location":"xxshareclassesenablebci/#see-also","title":"See also","text":"<ul> <li>Support for bytecode instrumentation</li> </ul>"},{"location":"xxsharedcachehardlimit/","title":"-XX:SharedCacheHardLimit","text":""},{"location":"xxsharedcachehardlimit/#-xxsharedcachehardlimit","title":"-XX:SharedCacheHardLimit","text":"<p>Specifies the size for a new shared classes cache. Use this option together with the <code>-Xscmx</code> option to set actual and soft maximum size limits respectively.</p>"},{"location":"xxsharedcachehardlimit/#syntax","title":"Syntax","text":"<pre><code>    -XX:SharedCacheHardLimit=&lt;size&gt;\n</code></pre> Setting Value Default <code>&lt;size&gt;</code> [1[k|K|m|M|g|G] or greater] <p>See Using -X command-line options for more information about the <code>&lt;size&gt;</code> parameter.</p> <p>When you use this option with the <code>-Xscmx</code> option, the <code>-Xscmx</code> option sets the soft maximum size, and the <code>-XX:SharedCacheHardLimit</code> option sets the actual size, of a new shared classes cache. For more information, see -Xscmx.</p> <p>If you use this option without the <code>-Xscmx</code> option, the behavior is the same as using the <code>-Xscmx</code> option by itself; both options set the actual size of the shared classes cache.</p> <p>For more information about cache sizes, see Cache size limits.</p>"},{"location":"xxsharedcachehardlimit/#example","title":"Example","text":"<p>The following settings, when used together, set the soft maximum size of the shared classes cache to 16 MB and the actual maximum cache size to 64 MB.</p> <pre><code>-XX:SharedCacheHardLimit=64m -Xscmx16m\n</code></pre>"},{"location":"xxsharedcachehardlimit/#see-also","title":"See also","text":"<ul> <li>-Xscmx</li> </ul>"},{"location":"xxshareunsafeclasses/","title":"-XX:[+|-]ShareUnsafeClasses","text":""},{"location":"xxshareunsafeclasses/#-xx-shareunsafeclasses","title":"-XX:[+|-]ShareUnsafeClasses","text":"<p>This option enables and disables the storage of VM classes created through <code>Unsafe.defineClass</code> in the shared classes cache.</p> <p>The option is enabled by default, which means that unsafe classes are stored in the shared classes cache and are therefore available for ahead-of-time (AOT) compilation, potentially improving startup performance.</p>"},{"location":"xxshareunsafeclasses/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShareUnsafeClasses\n</code></pre> Setting Effect Default <code>-XX:+ShareUnsafeClasses</code> Enable yes <code>-XX:-ShareUnsafeClasses</code> Disable"},{"location":"xxshareunsafeclasses/#see-also","title":"See also","text":"<ul> <li>AOT compiler</li> <li>Introduction to class data sharing</li> <li>-Xshareclasses</li> <li>-XX:[+|-]ShareAnonymousClasses</li> </ul>"},{"location":"xxshowcarrierframes/","title":"-XX:[+|-]ShowCarrierFrames","text":""},{"location":"xxshowcarrierframes/#-xx-showcarrierframes","title":"-XX:[+|-]ShowCarrierFrames","text":"<p> This option controls the addition of the carrier threads' stack trace to the <code>Throwable.getStackTrace()</code> method. You can add the stack trace of the carrier threads to facilitate the debugging process.</p> <p> Notes:</p> <ul> <li>The platform thread that runs a virtual thread is that virtual thread's carrier thread.</li> <li>The <code>-XX:[+|-]ShowCarrierFrames</code> option is applicable only if the current thread is a virtual thread.</li> <li>If you specify the <code>-XX:-StackTraceInThrowable</code> option, the <code>-XX:[+|-]ShowCarrierFrames</code> option has no effect. The <code>-XX:-StackTraceInThrowable</code> option removes stack trace of all threads from exceptions.</li> </ul>"},{"location":"xxshowcarrierframes/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShowCarrierFrames\n</code></pre> Setting Effect Default <code>-XX:+ShowCarrierFrames</code> Enable <code>-XX:-ShowCarrierFrames</code> Disable yes"},{"location":"xxshowcarrierframes/#explanation","title":"Explanation","text":"<p>Virtual threads require platform threads to run because the operating system identifies only platform threads. Therefore, a VM maintains multiple platform threads that are used as carrier threads to run the virtual threads. The VM assigns a virtual thread to a platform thread in a process called mounting.</p> <p>Although the virtual thread runs on a carrier thread, the stack trace of the virtual thread and its carrier thread are separate. If an exception occurs on running the virtual threads, the thread dumps do not include stack frames from the carrier thread's stack.</p> <p>You can use the <code>-XX:+ShowCarrierFrames</code> option to add the stack trace of the carrier thread in addition to the virtual thread stack trace to the <code>Throwable.getStackTrace()</code> method, if an exception occurs. </p>"},{"location":"xxshowhiddenframes/","title":"-XX:[+|-]ShowHiddenFrames","text":""},{"location":"xxshowhiddenframes/#-xx-showhiddenframes","title":"-XX:[+|-]ShowHiddenFrames","text":"<p>This reimplementation of the Oracle HotSpot diagonostic option enables or disables the display of generated hidden <code>MethodHandle</code> frames in a stack trace.</p> <p>This option doesn't affect the contents of dump files.</p> <p>Unlike the HotSpot implementation, this option doesn't require the <code>+UnlockDiagnosticVMOptions</code> option.</p>"},{"location":"xxshowhiddenframes/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]ShowHiddenFrames\n</code></pre> Setting Effect Default <code>-XX:+ShowHiddenFrames</code> Enable <code>-XX:-ShowHiddenFrames</code> Disable yes When disabled, this option causes the VM to hide generated hidden <code>MethodHandle</code> frames in a stacktrace."},{"location":"xxshownativestacksymbols/","title":"-XX:[+|-]ShowNativeStackSymbols","text":""},{"location":"xxshownativestacksymbols/#-xx-shownativestacksymbols","title":"-XX:[+|-]ShowNativeStackSymbols","text":"<p>This option controls whether Java\u00ae dumps show the names of functions in native call stacks.</p>"},{"location":"xxshownativestacksymbols/#syntax","title":"Syntax","text":"<pre><code>    -XX:-ShowNativeStackSymbols\n    -XX:+ShowNativeStackSymbols=&lt;value&gt;\n</code></pre> Setting Value Effect Default <code>-XX:-ShowNativeStackSymbols</code> Don't show native stack symbols, not even in response to a signal, such as a fault signal <code>-XX:+ShowNativeStackSymbols</code> basic Show all the available native stack symbols for a signaled or faulting thread, but only easily acquired native stack symbols for other threads yes <code>-XX:+ShowNativeStackSymbols</code> all Show all the available native stack symbols for all threads"},{"location":"xxshownativestacksymbols/#explanation","title":"Explanation","text":"<p>Java dumps take longer to produce when the native stack symbols are included. If your Java application has a lot of threads, you might get an incomplete Java dump. You can avoid this situation by reducing the number of native stack symbols in the Java dump or by omitting them altogether.</p>"},{"location":"xxstacktraceinthrowable/","title":"-XX:-StackTraceInThrowable","text":""},{"location":"xxstacktraceinthrowable/#-xx-stacktraceinthrowable","title":"-XX:-StackTraceInThrowable","text":"<p>This option removes stack traces from exceptions.</p>"},{"location":"xxstacktraceinthrowable/#syntax","title":"Syntax","text":"<pre><code>    -XX:-StackTraceInThrowable\n</code></pre> Setting Effect Default <code>-XX:-StackTraceInThrowable</code> Disable No <p>While stack traces are included in exceptions by default, recording them can have a negative impact on performance. Use this option if you want to remove stack traces, although this might cause difficulties with problem determination.</p> <p>When this option is enabled, <code>Throwable.getStackTrace()</code> returns an empty array and the stack trace is displayed when an uncaught exception occurs. <code>Thread.getStackTrace()</code> and <code>Thread.getAllStackTraces()</code> are not affected by this option.</p>"},{"location":"xxstacktraceinthrowable/#see-also","title":"See also","text":"<ul> <li><code>-XX:\\[+|-\\]ShowCarrierFrames</code></li> </ul>"},{"location":"xxtransparenthugepage/","title":"-XX:[+|-]TransparentHugePage","text":""},{"location":"xxtransparenthugepage/#-xx-transparenthugepage","title":"-XX:[+|-]TransparentHugePage","text":"<p>(Linux\u00ae systems only: x86, POWER\u00ae, and IBM Z\u00ae)</p> <p>If Transparent Huge Pages (THP) is set to <code>madvise</code> on your system, this option, when enabled, promotes all memory allocated to huge pages. On systems without THP, or if THP is set to <code>always</code> or <code>never</code> on your system, this option is ignored. When transparent huge pages are used, your application footprint might increase.</p>"},{"location":"xxtransparenthugepage/#syntax","title":"Syntax","text":"Setting Effect Default <code>-XX:+TransparentHugePage</code> Enable yes <code>-XX:-TransparentHugePage</code> Disable"},{"location":"xxusecompressedoops/","title":"-XX:[+|-]UseCompressedOops","text":""},{"location":"xxusecompressedoops/#-xx-usecompressedoops","title":"-XX:[+|-]UseCompressedOops","text":"<p>(64-bit only)</p> <p>This Oracle HotSpot option enables or disables compressed references in 64-bit JVMs. The option is recognized by the Eclipse OpenJ9\u2122 VM and is provided to help when porting applications from the HotSpot JVM to the OpenJ9 VM. This option might not be supported in subsequent releases.</p>"},{"location":"xxusecompressedoops/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseCompressedOops\n</code></pre> Setting Effect Default <code>-XX:+UseCompressedOops</code> Enable <code>-XX:-UseCompressedOops</code> Disable <p>The <code>-XX:+UseCompressedOops</code> option is similar to specifying <code>-Xcompressedrefs</code>. Compressed references are used by default when the maximum memory size for an application is set above a platform-specific value. For more information, see <code>-Xcompressedrefs</code>.  </p>"},{"location":"xxusecontainersupport/","title":"-XX:[+|-]UseContainerSupport","text":""},{"location":"xxusecontainersupport/#-xx-usecontainersupport","title":"-XX:[+|-]UseContainerSupport","text":"<p>(Linux\u00ae only)</p> <p>If your application is running in a container that imposes a memory limit, the VM allocates a larger fraction of memory to the Java heap. To turn off this behavior, set the <code>-XX:-UseContainerSupport</code> option on the command line.</p>"},{"location":"xxusecontainersupport/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseContainerSupport\n</code></pre> Setting Effect Default <code>-XX:-UseContainerSupport</code> Disable <code>-XX:+UseContainerSupport</code> Enable yes <p>When using container technology, applications are typically run on their own and do not need to compete for memory. The Eclipse OpenJ9\u2122 VM detects when it is running inside a container that imposes a memory limit, and adjusts the maximum Java heap size appropriately.</p> <p>The following table shows the values that are used when <code>-XX:+UseContainerSupport</code> is set:</p> Container memory limit &lt;size&gt; Maximum Java heap size Less than 1 GB 50% &lt;size&gt; 1 GB - 2 GB &lt;size&gt; - 512 MB Greater than 2 GB 75% &lt;size&gt; <p>The default heap size is capped at 25 GB, which is the limit of heap size for 3-bit shift of compressed references (see -Xcompressedrefs), to prevent silent switching to 4-bit shift of compressed references, which has possible performance penalties. You can use the <code>-Xmx</code> option or the <code>-XX:MaxRAMPercentage</code> option to overwrite the 25 GB limit.</p> <p>The default heap size for containers takes affect only when the following conditions are met:</p> <ol> <li>The application is running in a container environment.</li> <li>The memory limit for the container is set.</li> <li>The <code>-XX:+UseContainerSupport</code> option is set, which is the default behavior.</li> </ol> <p>To prevent the VM adjusting the maximum heap size when running in a container, set <code>-XX:-UseContainerSupport</code>.</p> <p>When <code>-XX:MaxRAMPercentage</code> / <code>-XX:InitialRAMPercentage</code> are used with <code>-XX:+UseContainerSupport</code>, the corresponding heap setting is determined based on the memory limit of the container. For example, to set the maximum heap size to 80% of the container memory, specify the following options:</p> <pre><code>-XX:+UseContainerSupport -XX:MaxRAMPercentage=80\n</code></pre> <p> Note: If you set a value for <code>-Xms</code>, the <code>-XX:InitialRAMPercentage</code> option is ignored. If you set a value for <code>-Xmx</code>, the <code>-XX:MaxRAMPercentage</code> option is ignored.</p>"},{"location":"xxusegcstartuphints/","title":"-XX:[+|-]UseGCStartupHints","text":""},{"location":"xxusegcstartuphints/#-xx-usegcstartuphints","title":"-XX:[+|-]UseGCStartupHints","text":"<p>When this option is enabled, the VM calculates, over several application restarts, an appropriate startup heap size for your application. You can therefore use this option instead of calculating and setting an <code>-Xms</code> value yourself. Setting an initial size for the heap that is larger than the default helps to avoid frequent garbage collections during the startup phase of an application.</p>"},{"location":"xxusegcstartuphints/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseGCStartupHints\n</code></pre> Setting Effect Default <code>-XX:+UseGCStartupHints</code> Enable yes <code>-XX:-UseGCStartupHints</code> Disable <p>When enabled, the VM records the heap size when a startup complete event occurs, storing the value into the shared classes cache. On subsequent restarts, the garbage collector (GC) reads this value early in startup processing and expands the heap to an appropriate value. For accuracy and stability, averages are taken over a few restarts to stabilize the value used. The heap size recorded is specific to the application command line, therefore a different hint is stored for every unique command line.</p> <p>You can check the value used by the garbage collector for heap expansion by inspecting verbose GC output. The following example shows heap expansion based on hints from the previous run when using the <code>gencon</code> policy:</p> <pre><code>&lt;heap-resize id=\"2\" type=\"expand\" space=\"nursery\" amount=\"205258752\" count=\"1\" timems=\"0.328\" reason=\"hint from previous runs\" timestamp=\"2019-06-05T13:26:32.021\" /&gt;\n&lt;heap-resize id=\"3\" type=\"expand\" space=\"tenure\" amount=\"692649984\" count=\"1\" timems=\"0.326\" reason=\"hint from previous runs\" timestamp=\"2019-06-05T13:26:32.022\" /&gt;\n</code></pre> <p>The final value stored to the shared cache is not recorded in the verbose GC output.</p> <p> Notes:</p> <ul> <li>When enabled, this option overrides any initial heap size that is specified on the command line, for example by using the <code>-Xms</code> option.</li> <li>Because the shared classes cache is used to store heap size information, this option does not work if class data sharing (<code>-Xshareclasses</code>) is disabled.</li> </ul> <p> Restriction: This feature is not currently available with the Balanced GC policy.</p>"},{"location":"xxusejitserver/","title":"-XX:[+|-]UseJITServer","text":""},{"location":"xxusejitserver/#-xx-usejitserver","title":"-XX:[+|-]UseJITServer","text":"<p>This option starts the Eclipse OpenJ9\u2122 VM in JITServer client mode.</p>"},{"location":"xxusejitserver/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseJITServer\n</code></pre> Setting Effect Default <code>-XX:+UseJITServer</code> Enable <code>-XX:-UseJITServer</code> Disable yes"},{"location":"xxusejitserver/#explanation","title":"Explanation","text":"<p>When you enable this option, the VM tries to connect to a server and send all JIT compilation requests to it. For more information, see JITServer Technology.</p> <p>You must specify this option for any other <code>-XX:*JITServer*</code> options to take effect.</p>"},{"location":"xxusejitserver/#see-also","title":"See also","text":"<ul> <li>JITServer technology</li> </ul>"},{"location":"xxusenogc/","title":"-XX:[+|-]UseNoGC","text":""},{"location":"xxusenogc/#-xx-usenogc","title":"-XX:[+|-]UseNoGC","text":"<p>The <code>-XX:+UseNoGC</code> option enables a garbage collection policy that expands the Java object heap in the normal way until the limit is reached, but memory is not reclaimed through garbage collection.</p>"},{"location":"xxusenogc/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseNoGC\n</code></pre> Setting Effect Default <code>-XX:+UseNoGC</code> Enable <code>-XX:-UseNoGC</code> Disable yes"},{"location":"xxusenogc/#explanation","title":"Explanation","text":"<p>This policy can be useful for test purposes and for short-lived applications. When the limit is reached an <code>OutOfMemory</code> error is generated and the VM shuts down.</p> <p>The <code>-XX:-UseNoGC</code> option turns off a previously enabled <code>-XX:+UseNoGC</code> option.</p> <p>This policy can also be enabled with the <code>-Xgcpolicy:nogc</code> option. See <code>-Xgcpolicy:nogc</code> for more details about this policy and when it is appropriate to use it.</p>"},{"location":"xxusezlibnx/","title":"-XX:[+|-]UseZlibNX","text":""},{"location":"xxusezlibnx/#-xx-usezlibnx","title":"-XX:[+|-]UseZlibNX","text":"<p>AIX\u00ae with IBM POWER9\u00ae and later only</p> <p>This option enables or disables the adding of the <code>zlibNX</code> library directory location to the <code>LIBPATH</code> environment variable.</p>"},{"location":"xxusezlibnx/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UseZlibNX\n</code></pre> Setting Effect Default <code>-XX:+UseZlibNX</code> Enable yes <code>-XX:-UseZlibNX</code> Disable"},{"location":"xxusezlibnx/#explanation","title":"Explanation","text":"<p>AIX system adds the <code>zlibNX</code> library location, if available, to the <code>LIBPATH</code> variable by default. But having the <code>zlibNX</code> library directory location in the <code>LIBPATH</code> variable might cause some issues. For example, Git clone fails when executed from Java\u00ae when <code>zlibNX</code> is on the <code>LIBPATH</code> in the environment.</p> <p>You can disable adding of the <code>zlibNX</code> library location to the <code>LIBPATH</code> variable with the <code>-XX:-UseZlibNX</code> option.</p>"},{"location":"xxusezlibnx/#see-also","title":"See also","text":"<ul> <li>Hardware acceleration</li> <li>Configuring your system</li> </ul>"},{"location":"xxutfcache/","title":"-XX:[+|-]UTFCache","text":""},{"location":"xxutfcache/#-xx-utfcache","title":"-XX:[+|-]UTFCache","text":"<p>This option enables or disables the UTF to String cache used to enhance reflection performance.</p>"},{"location":"xxutfcache/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]UTFCache\n</code></pre> Setting Effect Default <code>-XX:+UTFCache</code> Enable yes <code>-XX:-UTFCache</code> Disable <p>The option, <code>-XX:+UTFCache</code>, causes the VM to cache the conversion of UTF8 data to java String objects during reflection. This is the default option.</p> <p>When specifying the <code>-XX:-UTFCache</code> option, the VM does not performing this caching.</p>"},{"location":"xxverboseverification/","title":"-XX:[+|-]VerboseVerification","text":""},{"location":"xxverboseverification/#-xx-verboseverification","title":"-XX:[+|-]VerboseVerification","text":"<p>You can use this option to control the output of verbose diagnostic data that relates to verification.</p> <p>The Oracle documentation to support this option is no longer available, because it is no longer used by the HotSpot VM. An explanation is provided here.</p>"},{"location":"xxverboseverification/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]VerboseVerification\n</code></pre> Setting Effect Default <code>-XX:-VerboseVerification</code> Disable yes <code>-XX:+VerboseVerification</code> Enable <p>Use  <code>-XX:-VerboseVerification</code> to enable the output of verbose diagnostic data to <code>stderr</code> that is generated during verification from the class file <code>StackMapTable</code> attribute. The data provides extra contextual information about bytecode verification, which helps diagnose bytecode or stackmap deficiencies in the field.</p> <p>Class files that have <code>StackMapTable</code> attributes (that is, class files that conform to version 50.0 or later of the class file format specification), are introduced in Java\u2122 V6. Class files with <code>StackMapTable</code> attributes are marked as <code>new format</code> in the verbose output, as shown in the example. Class files without the <code>StackMapTable</code> attributes are marked as <code>old format</code>. The <code>StackMapTable</code> diagnostic information is available only to classes verified with the new format.</p> <p>Here is an example of <code>StackMapTable</code> diagnostic output:</p> <pre><code>Verifying class java.example.ibm.com with new format\nVerifying method java.example.ibm.com.foo(Ljava/lang/String;Ljava/lang/Class;[Ljava/lang/String;Ljava/io/PrintStream;)I\nStackMapTable: frame_count = 3\ntable = {\n  bci: @37\n  flags: { }\n  locals: { 'java/lang/String', 'java/lang/Class', '[Ljava/lang/String;', 'java/io/PrintStream', 'java/lang/Class' }\n  stack: { 'java/lang/ThreadDeath' }\n  bci: @42\n  flags: { }\n  locals: { 'java/lang/String', 'java/lang/Class', '[Ljava/lang/String;', 'java/io/PrintStream', 'java/lang/Class' }\n  stack: { 'java/lang/Throwable' }\n  bci: @79\n  flags: { }\n  locals: { 'java/lang/String', 'java/lang/Class', '[Ljava/lang/String;', 'java/io/PrintStream', 'java/lang/Class',\n        'java/lang/Throwable' }\n  stack: { }\n }\nEnd class verification for: java.example.ibm.com\n</code></pre>"},{"location":"xxvmlockclassloader/","title":"-XX:[+|-]VMLockClassLoader","text":""},{"location":"xxvmlockclassloader/#-xx-vmlockclassloader","title":"-XX:[+|-]VMLockClassLoader","text":"<p>This option affects synchronization on class loaders that are not parallel-capable class loaders, during class loading.</p>"},{"location":"xxvmlockclassloader/#syntax","title":"Syntax","text":"<pre><code>    -XX:[+|-]VMLockClassLoader\n</code></pre> Setting Effect Default <code>-XX:+VMLockClassLoader</code> Enable yes <code>-XX:-VMLockClassLoader</code> Disable <p>The option, <code>-XX:+VMLockClassLoader</code>, causes the VM to force synchronization on a class loader that is not a parallel capable class loader during class loading. This action occurs even if the <code>loadClass()</code> method for that class loader is not synchronized. For information about parallel capable class loaders, see <code>java.lang.ClassLoader.registerAsParallelCapable()</code>. Note that this option might cause a deadlock if class loaders use non-hierarchical delegation. For example, setting the system property <code>osgi.classloader.lock=classname</code> with Equinox is known to cause a deadlock. This is the default option.</p> <p>When specifying the <code>-XX:-VMLockClassLoader</code> option, the VM does not force synchronization on a class loader during class loading. The class loader still conforms to class library synchronization, such as a synchronized <code>loadClass()</code> method.</p>"},{"location":"xzero/","title":"-Xzero","text":""},{"location":"xzero/#-xzero","title":"-Xzero","text":"<p>Enables reduction of the memory footprint of the Java\u2122 runtime environment when concurrently running multiple Java invocations.</p> <p>This option is deprecated and will be removed in a future release.</p> <p> This option can be used only with Java SE version 8 runtime environments. </p> <p><code>-Xzero</code> might not be appropriate for all types of applications because it changes the implementation of <code>java.util.ZipFile</code>, which might cause extra memory usage.</p>"},{"location":"xzero/#syntax","title":"Syntax","text":"Setting Effect <code>-Xzero:none</code> Disable all sub options <code>-Xzero:describe</code> Prints the sub options in effect <code>-Xzero:sharebootzip</code> Enables the sharebootzip sub option <code>-Xzero:nosharebootzip</code> Disables the sharebootzip sub option <p>The following parameters are no longer supported. The options are parsed but do nothing:</p> Setting Effect <code>-Xzero:j9zip</code> Enables the j9zip sub option <code>-Xzero:noj9zip</code> Disables the j9zip sub option <code>-Xzero:sharezip</code> Enables the sharezip sub option <code>-Xzero:nosharezip</code> Disables the sharezip sub option"}]}
\ No newline at end of file
diff --git a/shrc/index.html b/shrc/index.html
index ce2df0aafe..0993449777 100644
--- a/shrc/index.html
+++ b/shrc/index.html
@@ -8429,7 +8429,7 @@ <h2 id="enabling-class-data-sharing">Enabling class data sharing</h2>
 <p>For a set of best practices when using class data sharing, see <a href="#creating-a-shared-classes-cache">Creating a shared classes cache</a>.</p>
 <h2 id="class-data-sharing-operations">Class data sharing operations</h2>
 <p>When a VM loads a class and the class loader is enabled for class sharing, the VM looks in the shared classes cache to see if the class is already present. If the class is present and the classpath or URL to load the class is a match, the VM loads the class from the cache. Otherwise, it loads the class from the file system and writes it into the cache.</p>
-<p>The VM detects file system updates by storing timestamp values into the cache and comparing the cached values with actual values. In this way, the VM detects when a class might be invalidated and can mark the class as <em>stale</em>. These operations happen transparently when classes are loaded, so users can modify and update as many classes as they like during the lifetime of a shared class cache, knowing that the correct classes are always loaded. Stale classes are <em>redeemed</em> if the same class is subsequently fetched by the class loader from another VM and checked against the stale class in the cache.</p>
+<p>The VM detects file system updates by storing timestamp values into the cache and comparing the cached values with actual values. In this way, the VM detects when a class might be invalidated and can mark the class as <em>stale</em>. These operations happen transparently when classes are loaded, so users can modify and update as many classes as they like during the lifetime of a shared classes cache, knowing that the correct classes are always loaded. Stale classes are <em>redeemed</em> if the same class is subsequently fetched by the class loader from another VM and checked against the stale class in the cache.</p>
 <p>Occasionally, caches that are created from one version of the VM might not be compatible with caches that are created from a different version. This situation typically occurs when an update is made in OpenJ9 that changes the internal cache data structure. If a VM detects an incompatible cache at start up, it creates a new cache that can coexist, even if it has the same name. The VM detects a conflict by checking an internal shared classes cache generation number.</p>
 <p>Caches are not compatible between VMs that are using different object storage modes. For example, a 64-bit VM that uses compressed references to store 64-bit objects in a 32-bit representation, cannot share a cache with a 64-bit VM that is not using compressed references. For more information about object storage options, see <a href="../allocation/#compressed-references">Compressed references</a>.</p>
 <p>In the OpenJ9 implementation of <code>java.net.URLClassLoader</code>, classes are read from and written to the cache using the public Helper API. Therefore, any class loader that extends <code>java.net.URLClassLoader</code> gets class sharing support for free provided that it continues to use the methods in <code>java.net.URLClassLoader</code> to load classes. Custom class loaders that do not extend <code>java.net.URLClassLoader</code> must be adapted to share class data as described in <a href="#support-for-custom-class-loaders">Support for custom class loaders</a>.</p>
diff --git a/sitemap.xml b/sitemap.xml
index 49bf0c9f44..768c5c38d4 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,1552 +2,1552 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://www.eclipse.org/openj9/docs/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/allocation/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/aot/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-conditionhandling/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-cuda/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-daa/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-dtfj/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-gpu/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-jdk11/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-jdk17/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-jdk21/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-jvm/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-langmgmt/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-overview/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/api-shrc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/attachapi/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/builds/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/cmdline_general/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/cmdline_migration/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/cmdline_specifying/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/configuring/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/criusupport/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/d_jvm_commands/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmenableclasscaching/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmenablelegacydumpsecurity/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmenablelegacylogsecurity/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmenablelegacytracesecurity/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmgpudisable/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmgpuenable/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmgpuverbose/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmlangmanagementosmxbeaniscputime100ns/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmlangmanagementverbose/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmotisharedsharedclassglobalfilterclass/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachcommand_timeout/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachdirectory/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachdisplayname/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachenable/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachid/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachlogging/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachlogname/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachshutdown_timeout/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dcomibmtoolsattachtimeout/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dfileencoding/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/diag_overview/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djavacompiler/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djavalangstringbuffergrowaggressively/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djavalangstringsubstringnocopy/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativecbc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativechacha20/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativecrypto/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativedigest/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativeec/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativeeckeygen/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativegcm/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativersa/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativexdhkeyagreement/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/djdknativexdhkeygen/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dorgeclipseopenj9criuimmutableenvvars/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dump_heapdump/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dump_javadump/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/dump_systemdump/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/enhancementstoopenjdksecurity/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/env_var/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/gc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/gc_overview/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/interface_dtfj/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/interface_jvmti/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/interface_lang_management/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/introduction/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/jit/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/jitserver/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/jitserver_tuning/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/legal/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/messages_intro/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/migrating11to17/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/migrating8to11/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/openj9_defaults/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/openj9_directories/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/openj9_newuser/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/openj9_releases/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/openj9_signals/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/openj9_support/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/openssl/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/shrc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/shrc_diag_util/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_builder/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_jcmd/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_jdmpview/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_jextract/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_jmap/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_jps/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_jstack/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_jstat/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_migration/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/tool_traceformat/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.10/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.11/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.12/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.13/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.14/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.15/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.16/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.17/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.18/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.19/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.20/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.21/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.22/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.23/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.24/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.25/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.26/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.27/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.29.1/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.29/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.30.1/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.30/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.32/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.33/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.35/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.36/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.37/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.38/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.39/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.40/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.41/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.42/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.8/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/version0.9/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/vgclog/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/vgclog_examples/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/x/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/x_jvm_commands/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xaggressive/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xalwaysclassgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xaot/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xargencoding/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xbootclasspath/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xceehdlr/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcheck/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xclassgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcodecache/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcodecachetotal/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcomp/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcompactexplicitgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcompactgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcompilationthreads/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xcompressedrefs/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xconcurrentbackground/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xconcurrentlevel/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xconcurrentslack/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xconmeter/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xdisablejavadump/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xdump/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xenableexcessivegc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xenableexplicitgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xenablestringconstantgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xfastresolve/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xfuture/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xgcmaxthreads/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xgcpolicy/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xgcsplitheap/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xgcthreads/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xgcworkpackets/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xint/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xjit/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xjni/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xlinenumbers/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xloa/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xloaminimum/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xlockreservation/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xlockword/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xlog/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xlp/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xlpcodecache/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xlpobjectheap/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmca/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmcrs/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmine/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xminf/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmint/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmn/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmo/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmoi/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmr/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xms/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xmso/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xnumanone/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xoptionsfile/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xquickstart/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xrs/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xrsonrestoresynconrestore/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xsamplingexpirationtime/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xscdmx/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xscminaot/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xscminjitdata/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xscmx/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xshareclasses/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xshareclassesdisableonrestore/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xsigcatch/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xsigchain/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xsignal/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xsoftmx/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xsoftrefthreshold/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xss/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xsyslog/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xtgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xthr/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xtlhprefetch/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xtrace/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xtunevirtualized/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xverbosegclog/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xverify/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xx_jvm_commands/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxactiveprocessorcount/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxadaptivegcthreading/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxallowvmshutdown/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxalwayspretouch/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxcheckpointgcthread/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxclassrelationshipverifier/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxcodecachetotal/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxcodecachetotalmaxrampercentage/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxcompactstrings/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxconcgcthreads/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxcontinuationcache/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxcriurestorenonportablemode/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxdiagnosesynconvaluebasedclasses/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxdisableexplicitgc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxdisclaimjitscratch/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxenable3164interoperability/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxenablecpumonitor/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxenablecriusupport/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxenabledynamicagentloading/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxensurehashed/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxexitonoutofmemoryerror/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxgloballockreservation/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxhandlesigabrt/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxhandlesigusr2/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxhandlesigxfsz/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxheapdumponoutofmemory/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxheapdumppath/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxheapmanagementmxbeancompatibility/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxidletuningcompactonidle/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxidletuninggconidle/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxidletuningminfreeheaponidle/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxidletuningminidlewaittime/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxignoreunrecognizedrestoreoptions/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxignoreunrecognizedvmoptions/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxignoreunrecognizedxxcolonoptions/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxinitialheapsize/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxinitialrampercentage/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxinterleavememory/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitinlinewatches/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserveraddress/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserveraotcachedir/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserveraotcachename/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserveraotcachepersistence/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserveraotmx/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserverlocalsynccompiles/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserverlogconnections/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitservermetrics/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitservermetricsport/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitservermetricssslkey/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserverport/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitservershareromclasses/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserversslcert/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitservertimeout/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxjitserveruseaotcache/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxlazysymbolresolution/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxlegacyxlogoption/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxmaxdirectmemorysize/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxmergecompileroptions/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxnosuballoc32bitmem/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxonoutofmemoryerror/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxopenj9commandlineenv/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxoriginaljdk8heapsizecompatibilitymode/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxpagealigndirectmemory/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxparallelcmsthreads/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxparallelgcmaxthreads/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxparallelgcthreads/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxperftool/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxportablesharedcache/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxpositiveidentityhash/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxprintcodecache/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxprintflagsfinal/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxreadipinfoforras/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxreducecpumonitoroverhead/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxrequirejitserver/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxruntimeinstrumentation/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxsethwprefetch/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxshareanonymousclasses/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxshareclassesenablebci/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxsharedcachehardlimit/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxshareunsafeclasses/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxshowcarrierframes/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxshowhiddenframes/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxshownativestacksymbols/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxstacktraceinthrowable/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxtransparenthugepage/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxusecompressedoops/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxusecontainersupport/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxusegcstartuphints/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxusejitserver/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxusenogc/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxusezlibnx/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxutfcache/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxverboseverification/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xxvmlockclassloader/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.eclipse.org/openj9/docs/xzero/</loc>
-         <lastmod>2023-10-18</lastmod>
+         <lastmod>2023-10-25</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index f94703419de07bb87ca5c6fbb953845ff44d711e..722ed8bb696701146a9ff230ae39b79db84366cd 100644
GIT binary patch
delta 1397
zcmV-*1&aE`6U7q;ABzYGh(I}!2OnJ1-Boi^>0N(8&)NqfA&E90YJ#-oeEoou@~EEO
zEam`Nr2J4+*EES20r2^cIruLZ%;Zx1aksmFy!(RDB<tev<L=*o{rUCV-5)Q%JlE_A
z%NM>l(vQ2bl<8lQf>3{d<x95LK3!%;hy(T+|9-LH{O$SS(<>{{!#mRd3J0FAgu){y
zoHG^SfRp=bQnap(CEwn9o_-3Ds|ER#7BoPX{v@Arn5ulplRfWtIxv4%fw|W(nwKCS
z((_%z5ELk*#1_%T;Z;5<joApNECu+slar0vRp+g6gVTg&8R36%z=#>V4%py^tiVWq
z!=(w0>u=%>P_~zQH`FX2G`mW5no<@n`0bIk=+UGQ*aHzR2`po}E?|Vt^EE(ZSjdW>
z3qN6d9KhUc4Sc2HiCk{#;C&j@vX=}7RnfEiWgWFopapjwZ!NTJ^md7K;4Z!dL>Q1K
zbx9QF4k0=+Q!Rfk;O_A;lEM$7=_^RZ(Fhss`g_qrgHIj!-uZ%gc|pY|DJgkc{gh4p
zAKN5KwP?e)E~6<a-}Hgg<lz<}pf+?xLjDuAv)YK+*c!B0xIbfSoYgeeV$(Hhm4rI5
zSySTMeyea)2g6ZET-2W60z4rm9^9+|wV8laS|q2deUE>6$mt5hkdeq;(BD*j1ghQo
zASRP0@$B{-q3|f1&Zt2hTReULsD?M+rjoSKS~nmSEwpI#ke=~2VAR4pn4kqU6KFx5
z?a0#rShp?V4qe#tXD`37y|=#H_Fh~FwKNYE<K+TbdPJs%={O=x?STT+X8b5Yr5hCt
z@?o*10GfYAJ`g)}?Hzm8u~ETG?8s|OHsoNW^C|H&T`ZV;FnE-ozWBj<x`g7iz&5|~
z_^~}A9y=#njr?SnlPlr@iA8|)@Xb5svD7F&gxB`{g(r;#B;vJB$7L-EXI&H9;;`G5
zBt4h;9rhcu3QuTWA0I9DP<<gCu-nF~Lmj*kua$qKi`R`cqembm150j*;FYjyNXu-G
ziG=Gd`Dyr#@VIQ^)#8MYX4}R+E(!V4CDcNCGQn!Vv|*C(RIjKwxAfGa0ksu6E5Mvc
z10@wOXC<H-W~Y+kn}u~rNbge)(noe{m+*MMd(;BD(*nBJ0(#H_`lJQ)S1q8wX#xFR
z3+S`V1H}OWcaxF@@&O-{g$7&!+mqr3_<#R`o?6#hDj1C_cJXOqAGG`@;9F#RZ6~Hk
zc=*&T?1)B%+J46lSh6$fcs0aI|H(|`&v;Wqt!jvu-0hr#l1;1+Zt?~djdSy6Q`N&;
z3Ez~rbY>5)H@bx``K6mz)et`SIDomemJqAEDxEjL%*Hb7=+%?b;IRhG18&w(R(}!{
zh>7aD7j)Qnt_`+yVtw0f>$5GZwRzhZFXEZA8(ai`vgdDa5u=}W0W{>#OfVpLH^k49
zL_T!p^@!dCQj!t&My#ma;U{J-z?l1X2)uaCEx&Ft^Q{VVZc5}@PQ0@i3yZdvdLo`V
zyI8cerdnxx4+Hg1e!b?r6h=%g_J65QIRnY(wbgverAzEijS5ov`EHdp^ScWup0_Ry
zCS0VFYs-#MkvK(I#;cMN#kI1(waH-vvyze+(dTvqYuaUJoC@ewLGvT_OM>{`wJURt
z1U;&m8tG~vXUFDShM)s@be2saJ-iW``9=lIc@4|Sr*5oEJ+^CS@T6-K8g9~|nKu$U
zPOSLGI^d)rA)^w093GU?L@I#Uuy7Hxl0t*p3gDMEY;_uWI%^nXH6|ys#w5RTiZNfk
z>!SGdg<5(Q9`n{&Vy$g9D*TK~XcZ-kUDhg%#ILPa%>Rd$q02w)g1!6)Q;54ANzwoS
D{MEd#

delta 1397
zcmV-*1&aE`6U7q;ABzYG0yr>{2OnHB-Boi^>D_!m_u2;{A&E90YJ#-oeEoou@~H0J
zEam`Nr2J4+*EES20r2_vIruLZ%;Zx1aksmFy!(RDB<tev<L=Kt{`2+Q-S02IJlE_A
z%NM>l(vQ2bl<D7*f>3|H@g>`9pDr^a!~y$^f4x|6{`UOv>6Mk};T`FJg#*u5LgA4U
z&Y6mEz{!0zDO%UYl5cN4Pd^37)q;FV3mPCxf09o*OjSPQ$)0yR9hkqVz}#yX%}bCE
z>G`f<2nv)@VvFeF@G75_#%zRBmI8d+$;rm-s`FO3!D&LXjPQRrV8jew2W)UdR$wH*
z;nIZ0^*8YbDBH`u8)}vhnq8$jO(_c({PxIN^k`BD?12cE1eP&f7cfHS`5GWHEM&#c
zg`coJ4q$G!2ENkpL@qaV@IDP{*-Hk4s_5DMvX0s((1N>;w-#D9db>nAa2H<!A`Hlr
zx+Ds7hY%f^sTO}1aQFBaN#O_4^cAGyXoQS*{k>?R!KV&<?|i|$yrANfl$1QJe#)l)
zk8KjATD0L?m(i4zZ~DM#@^Fg~P#d};A^(ZmS#88@Yz<m0+@G;E&T1NKvFRGMN<tmj
ztSRwrzg0M@gW;$nE^1G30iF;O4{la~+Dt$yEt1pKzQ=z&<aC8$$VlWa=x?e%0@ZGP
z5R*xhcy@b^P<WJ0XVjpMEuOxARKuHZQ%PEAts9Vv7FslVNY8j1Flyl)OwfXw3ACWj
zcI0UQtlO4whc0aSvzK4k-dkU8doM18TAGK7@p6GIJt9-XbQ}?;_CNt@Gk%ny(v1oR
z`LNhh0L_0QABY{g_KrR4*r?zocH}iC8*(tx`IPvXE*8u^7(B{PU;JP_T|#kMV4Gig
z{Ma55kDZgPMt-u($rbT{#3Dd?_~sq+SZWj>!fX5f!jr}V67gE6<Fb~7v#yD4aoFuj
zlAg=_4*QK+g(ozxkB=66sJ@U6*lpw0p$^`N*GhlV#p}kJ(Ib$Ofh9LY@Jd)Uq-D0p
zM8fr!{51SVcw9E|YH`9xvu)!ZmxO%j5^5nmnP4?w+Azs?s#jE;TY75IfZ7V36<|)J
zfszWCvl37Zvr|d&&BD4Qr1vQY=_9+fOL)BBJ!%2nX#w490X=8|ebNH@FD;<IY61OC
z3+S`V1H}OWSCf(j@&Rv?g$7&!>yzRJ_<w&uPpxY$6^up|yZAJ*4_f{c@GUaEwi8n%
zJbY>vc0{8>ZNFm&EZG@#yc%Mqe`hB0XS}JQRyD*+?siT=$tKnZH+h4K#<_X3sp{da
zgm21QI<tq@8{I;e{L;;<Y6zcu9KhUKONiB7mChSrW@DLk^y*1z@K^)p0XJ(XD}M<J
z#6)%73p(sO*9KcUvA*rL_1Tuy+PrOy7xB#54K9K|+4Hxzh|y2G02=aVCKwRB8{%h4
zA|E>QdPHvmDai<XBUaSz@DsBZV9b3x1YSJnmS4A+`BsHFHzjf{C*E0%g+*ISJrU2G
zT`XE!Q?0bUhk<%0zg}}*3L_>L`+wA@oPp%?+G;-K(j|7MMg^(-e7DM)`P~H+&s&!U
z6E0H8wPi=BNSq=p<5fwC;#%3?+T^f-SxHHZ=yN-QHSMx9P6hO;p!pH|B|&`e+LgIR
zf*#dOjdV4Tvt#ouL(l;{I?JYz9^MGee4_&9yoTlEQ#aP79^17uc+#~A4Q}bs%o~Xv
zCsur89dJ^RkWmRg4i8FcA{D@FSh$E;Nufb)1@KE7wmOYGoi&WH8k3V*W0GGv#h9<&
zby0l!LM^=tk9q4XvDP*l6@JDgw2G3&E^C!W;@8$I=Kn*>(B&U?!Cw9ge)*;9NzwoS
DQHin~

diff --git a/version0.41/index.html b/version0.41/index.html
index 6049d92f56..730f740bbc 100644
--- a/version0.41/index.html
+++ b/version0.41/index.html
@@ -8268,7 +8268,7 @@ <h3 id="-xxcompactstrings-option-enabled-by-default"><img alt="Start of content
 <p>For more information, see <a href="../xxcompactstrings/"><code>-XX:[+|-]CompactStrings</code></a>. <img alt="End of content that applies only to Java 11 and later" src="../cr/java_close_lts.png" /></p>
 <h3 id="change-in-behavior-of-xshareclassesreadonly">Change in behavior of <code>-Xshareclasses:readonly</code></h3>
 <p>In the earlier releases, if the <code>-Xshareclasses:readonly</code> option and the JITServer AOT cache feature were both enabled at the same time at a JITServer client, the client could not use the JITServer AOT cache because the cache for storing data that the JITServer AOT cache needed was read-only.</p>
-<p>Now, with the change in behavior of the <a href="../xshareclasses/#readonly"><code>-Xshareclasses:readonly</code></a> option, the shared class cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p>
+<p>Now, with the change in behavior of the <a href="../xshareclasses/#readonly"><code>-Xshareclasses:readonly</code></a> option, the shared classes cache startup creates a temporary new (writable) top layer that the JITServer AOT cache can use to store data that it needs to function.</p>
 <h3 id="new-xx-enabledynamicagentloading-option-added">New <code>-XX:[+|-]EnableDynamicAgentLoading</code> option added</h3>
 <p>This option enables or disables the dynamic loading of agents into a running VM. The <code>-XX:+EnableDynamicAgentLoading</code> option is the default setting.</p>
 <p><img alt="Start of content that applies to Java 21 (LTS) and later" src="../cr/java21plus.png" /> For Java 21 and later, warnings are issued when the agents are loaded dynamically into a running VM after startup without specifying the <code>-XX:+EnableDynamicAgentLoading</code> option and the same agents were not loaded before. <img alt="End of content that applies to Java 21 (LTS) and later" src="../cr/java_close_lts.png" /></p>
diff --git a/xshareclasses/index.html b/xshareclasses/index.html
index b692acff80..2515e5e0eb 100644
--- a/xshareclasses/index.html
+++ b/xshareclasses/index.html
@@ -9357,13 +9357,13 @@ <h3 id="persistent"><code>persistent</code></h3>
 <dd><span aria-hidden="true" class="twemoji note"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="m410.3 231 11.3-11.3-33.9-33.9-62.1-62.1-33.9-33.9-11.3 11.3-22.6 22.6L58.6 322.9c-10.4 10.4-18 23.3-22.2 37.4L1 480.7c-2.5 8.4-.2 17.5 6.1 23.7s15.3 8.5 23.7 6.1l120.3-35.4c14.1-4.2 27-11.8 37.4-22.2l199.2-199.2 22.6-22.7zM160 399.4l-9.1 22.7c-4 3.1-8.5 5.4-13.3 6.9l-78.2 23 23-78.1c1.4-4.9 3.8-9.4 6.9-13.3l22.7-9.1v32c0 8.8 7.2 16 16 16h32zM362.7 18.7l-14.4 14.5-22.6 22.6-11.4 11.3 33.9 33.9 62.1 62.1 33.9 33.9 11.3-11.3 22.6-22.6 14.5-14.5c25-25 25-65.5 0-90.5l-39.3-39.4c-25-25-65.5-25-90.5 0zm-47.4 168-144 144c-6.2 6.2-16.4 6.2-22.6 0s-6.2-16.4 0-22.6l144-144c6.2-6.2 16.4-6.2 22.6 0s6.2 16.4 0 22.6z"/></svg></span> <strong>Notes:</strong></dd>
 <dd>
 <ul>
-<li>With the 31-bit VM on all versions of z/OS, the shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared class cache is limited by the system limit <code>MAXMMAPAREA</code>. For more information about the suggested value for the <code>MAXMMAPAREA</code> limit, see <a href="https://www.eclipse.org/openj9/docs/configuring/#setting-resource-limits-zos">Setting resource limits (z/OS)</a>.</li>
+<li>With the 31-bit VM on all versions of z/OS, the shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit <code>MAXMMAPAREA</code>. For more information about the suggested value for the <code>MAXMMAPAREA</code> limit, see <a href="https://www.eclipse.org/openj9/docs/configuring/#setting-resource-limits-zos">Setting resource limits (z/OS)</a>.</li>
 <li>
 <p>With the 64-bit VM, the shared cache is mapped as follows:</p>
 <ul>
-<li>On z/OS version 2.3 and earlier, the persistent shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared class cache is limited by the system limit <code>MAXMMAPAREA</code>.</li>
+<li>On z/OS version 2.3 and earlier, the persistent shared cache is memory mapped within the 0-2 GB address range. The maximum size of the persistent shared classes cache is limited by the system limit <code>MAXMMAPAREA</code>.</li>
 <li>
-<p>On z/OS version 2.4 and later, the persistent shared cache is mapped above the 2 GB address range. The maximum size of persistent shared class cache is limited by the <code>MAXSHARE</code> value within the <code>SMFLIMxx</code> member of <code>SYS1.PARMLIB</code>. You can use the following machine configuration to create up to 1 GB shared class cache mapped above the 2 GB address range:</p>
+<p>On z/OS version 2.4 and later, the persistent shared cache is mapped above the 2 GB address range. The maximum size of persistent shared classes cache is limited by the <code>MAXSHARE</code> value within the <code>SMFLIMxx</code> member of <code>SYS1.PARMLIB</code>. You can use the following machine configuration to create up to 1 GB shared classes cache mapped above the 2 GB address range:</p>
 <ol>
 <li>Add the following line in the SMFLIMxx member of SYS1.PARMLIB.</li>
 </ol>
@@ -9414,11 +9414,11 @@ <h3 id="readonly"><code>readonly</code></h3>
 <li>The VM is running in a container.</li>
 <li>AOT compilation is enabled.<br>
 For more information about AOT compilation, see the <a href="../aot/">Ahead-Of-Time (AOT) compiler</a> topic.</li>
-<li>The shared class cache is persistent. (<a href="./#persistent"><code>-Xshareclasses:persistent</code></a>)</li>
+<li>The shared classes cache is persistent. (<a href="./#persistent"><code>-Xshareclasses:persistent</code></a>)</li>
 </ul>
 </dd>
 <dd>
-<p>If a persistent shared class cache is started under the mentioned conditions, the cache startup creates a temporary new (writable) top layer. The JITServer AOT cache uses the new top layer to store a small amount of metadata that the cache needs to function. With this top layer, the JITServer AOT cache can be used without modifying the existing layers.</p>
+<p>If a persistent shared classes cache is started under the mentioned conditions, the cache startup creates a temporary new (writable) top layer. The JITServer AOT cache uses the new top layer to store a small amount of metadata that the cache needs to function. With this top layer, the JITServer AOT cache can be used without modifying the existing layers.</p>
 </dd>
 </dl>
 <h3 id="reset"><code>reset</code></h3>
diff --git a/xxjitserveruseaotcache/index.html b/xxjitserveruseaotcache/index.html
index 62e9e71408..19339c4f9f 100644
--- a/xxjitserveruseaotcache/index.html
+++ b/xxjitserveruseaotcache/index.html
@@ -8164,7 +8164,7 @@ <h2 id="explanation">Explanation</h2>
 <p><span aria-hidden="true" class="twemoji note"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.4.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="m410.3 231 11.3-11.3-33.9-33.9-62.1-62.1-33.9-33.9-11.3 11.3-22.6 22.6L58.6 322.9c-10.4 10.4-18 23.3-22.2 37.4L1 480.7c-2.5 8.4-.2 17.5 6.1 23.7s15.3 8.5 23.7 6.1l120.3-35.4c14.1-4.2 27-11.8 37.4-22.2l199.2-199.2 22.6-22.7zM160 399.4l-9.1 22.7c-4 3.1-8.5 5.4-13.3 6.9l-78.2 23 23-78.1c1.4-4.9 3.8-9.4 6.9-13.3l22.7-9.1v32c0 8.8 7.2 16 16 16h32zM362.7 18.7l-14.4 14.5-22.6 22.6-11.4 11.3 33.9 33.9 62.1 62.1 33.9 33.9 11.3-11.3 22.6-22.6 14.5-14.5c25-25 25-65.5 0-90.5l-39.3-39.4c-25-25-65.5-25-90.5 0zm-47.4 168-144 144c-6.2 6.2-16.4 6.2-22.6 0s-6.2-16.4 0-22.6l144-144c6.2-6.2 16.4-6.2 22.6 0s6.2 16.4 0 22.6z"/></svg></span> <strong>Note:</strong> This option has the following requirements:</p>
 <ul>
 <li>You must specify this option both at the client JVM and at the server.</li>
-<li>The client JVM must have the <a href="https://www.eclipse.org/openj9/docs/shrc/">shared class cache</a> feature enabled and be allowed to generate AOT compilation requests.</li>
+<li>The client JVM must have the <a href="https://www.eclipse.org/openj9/docs/shrc/">shared classes cache</a> feature enabled and be allowed to generate AOT compilation requests.</li>
 </ul>
 <p>The <a href="../xxjitservershareromclasses/"><code>-XX:+JITServerShareROMClasses</code></a> option is enabled by default at the server on specifying the<code>-XX:+JITServerUseAOTCache</code> option.</p>
 <h2 id="see-also">See also</h2>
diff --git a/xxportablesharedcache/index.html b/xxportablesharedcache/index.html
index 4fa4625604..bc728b3827 100644
--- a/xxportablesharedcache/index.html
+++ b/xxportablesharedcache/index.html
@@ -8171,7 +8171,7 @@ <h2 id="syntax">Syntax</h2>
 </table>
 <h3 id="default-settings">Default settings</h3>
 <p>This option is <em>enabled</em> by default in containers. To disable the option in a container, specify <code>-XX:-PortableSharedCache</code>.</p>
-<p>The option is <em>disabled</em> by default outside containers. To enable the option outside a container, specify <code>-XX:+PortableSharedCache</code> for the initial JVM instance (when the creation of the shared class cache happens) as well as for every subsequent instance that makes use of the same shared class cache.</p>
+<p>The option is <em>disabled</em> by default outside containers. To enable the option outside a container, specify <code>-XX:+PortableSharedCache</code> for the initial JVM instance (when the creation of the shared classes cache happens) as well as for every subsequent instance that makes use of the same shared classes cache.</p>
 <!-- ==== END OF TOPIC ==== xxportablesharedcache.md ==== -->