Summary

The JDWP and JDI specs need to clarify the type of situations that can lead to a deadlock when using the method invocation APIs.

Problem

The following is replicated in the JDI and JDWP specs for all APIs that do method invocation:

"By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by VirtualMachine.suspend() or ThreadReference.suspend(). This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method."

"The resumption of other threads during the invocation can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options argument; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution."

The reference to deadlocks due to "monitors" needed during the invoke is too specific. There are other types of resources that the invoked method might need and can result in a deadlock if all threads are not resumed. We can't even know all the types due some of them potentially being native, but a common one would be j.u.concurrent locks. The spec language should be more generic to cover these types of resources.

This spec clarification is needed for the following JDI methods:

ClassType.invokeMethod()
ClassType.newInstance()
InterfaceType.invokeMethod()
ObjectReference.invokeMethod()

And the following JDWP commands:

ClassType.InvokeMethod
ClassType.NewInstance
InterfaceType.InvokeMethod
ObjectReference.InvokeMethod 

Solution

The following diff is recommended for clarification:

         "This is done to prevent the deadlocks "
-        "that will occur if any of the threads own monitors "
+        "that will occur if any of the threads own resources, such as monitors, "
         "that will be needed by the invoked method. It is possible that "

Specification

diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ClassType.java b/src/jdk.jdi/share/classes/com/sun/jdi/ClassType.java
index 952651d8e0c5..8ee6ed575bb7 100644
--- a/src/jdk.jdi/share/classes/com/sun/jdi/ClassType.java
+++ b/src/jdk.jdi/share/classes/com/sun/jdi/ClassType.java
@@ -173,7 +173,7 @@ void setValue(Field field, Value value)
      * the method is being invoked if they were previously
      * suspended by an event or by {@link VirtualMachine#suspend} or
      * {@link ThreadReference#suspend}. This is done to prevent the deadlocks
-     * that will occur if any of the threads own monitors
+     * that will occur if any of the threads own resources, such as monitors,
      * that will be needed by the invoked method.
      * Note, however, that this implicit resume acts exactly like
      * {@link ThreadReference#resume}, so if the thread's suspend
@@ -284,7 +293,7 @@ Value invokeMethod(ThreadReference thread, Method method,
      * the method is being invoked if they were previously
      * suspended by an event or by {@link VirtualMachine#suspend} or
      * {@link ThreadReference#suspend}. This is done to prevent the deadlocks
-     * that will occur if any of the threads own monitors
+     * that will occur if any of the threads own resources, such as monitors,
      * that will be needed by the invoked method. It is possible that
      * breakpoints or other events might occur during the invocation.
      * Note, however, that this implicit resume acts exactly like

diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/InterfaceType.java b/src/jdk.jdi/share/classes/com/sun/jdi/InterfaceType.java
index f54c7bb391be..da95bd67dbfb 100644
--- a/src/jdk.jdi/share/classes/com/sun/jdi/InterfaceType.java
+++ b/src/jdk.jdi/share/classes/com/sun/jdi/InterfaceType.java
@@ -124,7 +124,7 @@ public interface InterfaceType extends ReferenceType {
      * the method is being invoked if they were previously
      * suspended by an event or by {@link VirtualMachine#suspend} or
      * {@link ThreadReference#suspend}. This is done to prevent the deadlocks
-     * that will occur if any of the threads own monitors
+     * that will occur if any of the threads own resources, such as monitors,
      * that will be needed by the invoked method.
      * Note, however, that this implicit resume acts exactly like
      * {@link ThreadReference#resume}, so if the thread's suspend

diff --git a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java
index 13662aa252b0..dcada00d99b5 100644
--- a/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java
+++ b/src/jdk.jdi/share/classes/com/sun/jdi/ObjectReference.java
@@ -205,7 +205,7 @@ void setValue(Field field, Value value)
      * the method is being invoked if they were previously
      * suspended by an event or by {@link VirtualMachine#suspend} or
      * {@link ThreadReference#suspend}. This is done to prevent the deadlocks
-     * that will occur if any of the threads own monitors
+     * that will occur if any of the threads own resources, such as monitors,
      * that will be needed by the invoked method.
      * Note, however, that this implicit resume acts exactly like
      * {@link ThreadReference#resume}, so if the thread's suspend

diff --git a/src/java.se/share/data/jdwp/jdwp.spec b/src/java.se/share/data/jdwp/jdwp.spec
index 6d4319596522..47a83270536d 100644
--- a/src/java.se/share/data/jdwp/jdwp.spec
+++ b/src/java.se/share/data/jdwp/jdwp.spec
@@ -1145,9 +1145,9 @@ JDWP "Java(tm) Debug Wire Protocol"
         "<p>"
         "By default, all threads in the target VM are resumed while "
         "the method is being invoked if they were previously "
         "This is done to prevent the deadlocks "
-        "that will occur if any of the threads own monitors "
+        "that will occur if any of the threads own resources, such as monitors, "
         "that will be needed by the invoked method. It is possible that "
         "breakpoints or other events might occur during the invocation. "
         "Note, however, that this implicit resume acts exactly like "
@@ -1221,9 +1221,9 @@ JDWP "Java(tm) Debug Wire Protocol"
         "<p>"
         "By default, all threads in the target VM are resumed while "
         "the method is being invoked if they were previously "
         "This is done to prevent the deadlocks "
-        "that will occur if any of the threads own monitors "
+        "that will occur if any of the threads own resources, such as monitors, "
         "that will be needed by the invoked method. It is possible that "
         "breakpoints or other events might occur during the invocation. "
         "Note, however, that this implicit resume acts exactly like "
@@ -1321,7 +1321,7 @@ JDWP "Java(tm) Debug Wire Protocol"
         "the method is being invoked if they were previously "
         "suspended by an event or by a command. "
         "This is done to prevent the deadlocks "
-        "that will occur if any of the threads own monitors "
+        "that will occur if any of the threads own resources, such as monitors, "
         "that will be needed by the invoked method. It is possible that "
         "breakpoints or other events might occur during the invocation. "
         "Note, however, that this implicit resume acts exactly like "
@@ -1662,7 +1662,7 @@ JDWP "Java(tm) Debug Wire Protocol"
         "the method is being invoked if they were previously "
         "suspended by an event or by a command. "
         "This is done to prevent the deadlocks "
-        "that will occur if any of the threads own monitors "
+        "that will occur if any of the threads own resources, such as monitors, "
         "that will be needed by the invoked method. It is possible that "
         "breakpoints or other events might occur during the invocation. "
         "Note, however, that this implicit resume acts exactly like "