Document new -XX:[+|-]ShowUnmountedThreadStacks option

[fengxue-IS]

Issue or pull request number:
eclipse-openj9/openj9#18218

Overview:
Option controls if unmounted virtual thread stacks are included in java core file.

Release target:
Eclipse OpenJ9 0.44.0

Applies to the following JDK versions:
21 and later

Applies to the following platforms:
All platforms

For new command line options:

• Option name and syntax: -XX:[+|-]ShowUnmountedThreadStacks
• Default value: disabled
• Purpose: Allow unmounted virtual thread stack to be include in java core file.

[pshipton]

Modified the target to 0.44 as the change isn't released in 0.43 atm and we are after M2.

[Sreekala-Gopakumar]

@fengxue-IS - What was the problem because of which this option was required? What was happening without the unmounted virtual thread stack in the Java core file? Thanks!

@fengxue-IS - Could you please clarify? Thanks!

[Sreekala-Gopakumar]

@fengxue-IS - What was the problem because of which this option was required? What was happening without the unmounted virtual thread stack in the Java core file? Thanks!

@fengxue-IS - Could you please clarify? Thanks!

@pshipton - Anybody else who can clarify, in case Jack is busy? Thanks!

[pshipton]

I poked Jack.

[fengxue-IS]

@fengxue-IS - What was the problem because of which this option was required? What was happening without the unmounted virtual thread stack in the Java core file? Thanks!

This option is added because current javacore only lists the threads that have a J9VMThread associated. in the case of virtual threads, any unmounted virtual threads have their stack data stored in a J9VMContinuation structure which will not be included in the javacore by default, so there will be incomplete virtual thread info (only mounted thread stack trace) in the javacore file.

Setting this option will go through all Continuations in the javacore dumper to include thread data that VM is aware of (both regular Java threads and unmounted virtual threads).

this options is default to false since the chance of having issue with unmounted virtual threads is low (usually the running/mounted threads are what causes failure) and the nature of virtual threads means there could be too much info included in javacore unintentionally.

[Sreekala-Gopakumar]

@fengxue-IS - What was the problem because of which this option was required? What was happening without the unmounted virtual thread stack in the Java core file? Thanks!

This option is added because current javacore only lists the threads that have a J9VMThread associated. in the case of virtual threads, any unmounted virtual threads have their stack data stored in a J9VMContinuation structure which will not be included in the javacore by default, so there will be incomplete virtual thread info (only mounted thread stack trace) in the javacore file.

Setting this option will go through all Continuations in the javacore dumper to include thread data that VM is aware of (both regular Java threads and unmounted virtual threads).

this options is default to false since the chance of having issue with unmounted virtual threads is low (usually the running/mounted threads are what causes failure) and the nature of virtual threads means there could be too much info included in javacore unintentionally.

@fengxue-IS -

• Will it be correct if we say "This option controls the addition of the unmounted virtual thread stack trace to the Throwable.getStackTrace() method, if an exception occurs."?
• Is the '-XX:[+|-]ShowUnmountedThreadStacks' related to -XX:[+|-]ShowCarrierFrames (https://eclipse.dev/openj9/docs/xxshowcarrierframes/) ? If yes, how is it related?

[fengxue-IS]

@Sreekala-Gopakumar

• Will it be correct if we say "This option controls the addition of the unmounted virtual thread stack trace to the Throwable.getStackTrace() method, if an exception occurs."?

No, Throwable.getStackTrace() is a Java level API, this option only controls the javacore output which is part of Java's Xdump feature.

• Is the '-XX:[+|-]ShowUnmountedThreadStacks' related to -XX:[+|-]ShowCarrierFrames (https://eclipse.dev/openj9/docs/xxshowcarrierframes/) ? If yes, how is it related?

No, -XX:[+|-]ShowCarrierFrames basically would fuse the stack trace of the mounted virtual thread with the unmounted carrier thread's stack trace together in Throwable.getStackTrace() output, but this have no effect on javacore file. '-XX:[+|-]ShowUnmountedThreadStacks' is specifically used to add all unmounted threads's (threads data which aren't stored on a J9VMThread) stack trace into javacore file.

[Sreekala-Gopakumar]

@fengxue-IS - What was the problem because of which this option was required? What was happening without the unmounted virtual thread stack in the Java core file? Thanks!

This option is added because current javacore only lists the threads that have a J9VMThread associated. in the case of virtual threads, any unmounted virtual threads have their stack data stored in a J9VMContinuation structure which will not be included in the javacore by default, so there will be incomplete virtual thread info (only mounted thread stack trace) in the javacore file.

Setting this option will go through all Continuations in the javacore dumper to include thread data that VM is aware of (both regular Java threads and unmounted virtual threads).

this options is default to false since the chance of having issue with unmounted virtual threads is low (usually the running/mounted threads are what causes failure) and the nature of virtual threads means there could be too much info included in javacore unintentionally.

@fengxue-IS - What do you mean by "...only lists the threads that have a J9VMThread associated" ?

[fengxue-IS]

in the jvm, a java thread is represented by a java thread object with a native allocated java stack. before virtual thread, every java thread is mapped to a native os thread (represented by a J9VMThread).
in this case, javacore just looped through and printed all the J9VMThreads.
with virtual threads, a virtual thread object is not associated with a native thread, instead it it only mounted to a native thread when needed (ie. mounted). when virtual thread is unmounted, it is detached from the J9VMThread and cannot be found loop through them.