7051206: JSR 292 method name SwitchPoint.isValid is misleading to unwary...

7051206: JSR 292 method name SwitchPoint.isValid is misleading to unwary users; should be hasBeenInvalidated
Reviewed-by: kvn, never, ysr

jdk/src/share/classes/java/lang/invoke/SwitchPoint.java

@@ -59,14 +59,14 @@ package java.lang.invoke;
 MethodHandle MH_strcat = MethodHandles.lookup()
     .findVirtual(String.class, "concat", MethodType.methodType(String.class, String.class));
 SwitchPoint spt = new SwitchPoint();
-assert(spt.isValid());
+assert(!spt.hasBeenInvalidated());
 // the following steps may be repeated to re-use the same switch point:
 MethodHandle worker1 = MH_strcat;
 MethodHandle worker2 = MethodHandles.permuteArguments(MH_strcat, MH_strcat.type(), 1, 0);
 MethodHandle worker = spt.guardWithTest(worker1, worker2);
 assertEquals("method", (String) worker.invokeExact("met", "hod"));
 SwitchPoint.invalidateAll(new SwitchPoint[]{ spt });
-assert(!spt.isValid());
+assert(spt.hasBeenInvalidated());
 assertEquals("hodmet", (String) worker.invokeExact("met", "hod"));
  * </pre></blockquote>
  * <p style="font-size:smaller;">
@@ -126,16 +126,30 @@ public class SwitchPoint {
     }
 
     /**
-     * Determines if this switch point is still valid.
-     * <p>
+     * Determines if this switch point has been invalidated yet.
+     *
+     * <p style="font-size:smaller;">
+     * <em>Discussion:</em>
+     * Because of the one-way nature of invalidation, once a switch point begins
+     * to return true for {@code hasBeenInvalidated},
+     * it will always do so in the future.
+     * On the other hand, a valid switch point visible to other threads may
+     * invalidated at any moment, due to a request by another thread.
+     * <p style="font-size:smaller;">
      * Since invalidation is a global and immediate operation,
-     * this query must be sequenced with any
-     * other threads that could invalidate this switch point.
-     * It may therefore be expensive.
-     * @return true if this switch point has never been invalidated
+     * the execution of this query, on a valid switchpoint,
+     * must be internally sequenced with any
+     * other threads that could cause invalidation.
+     * This query may therefore be expensive.
+     * The recommended way to build a boolean-valued method handle
+     * which queries the invalidation state of a switch point {@code s} is
+     * to call {@code s.guardWithTest} on
+     * {@link MethodHandles#constant constant} true and false method handles.
+     *
+     * @return true if this switch point has been invalidated
      */
-    public boolean isValid() {
-        return (mcs.getTarget() == K_true);
+    public boolean hasBeenInvalidated() {
+        return (mcs.getTarget() != K_true);
     }
 
     /**

jdk/test/java/lang/invoke/JavaDocExamplesTest.java

@@ -477,14 +477,14 @@ assertEquals("Wilma, dear?", (String) worker2.invokeExact());
 MethodHandle MH_strcat = MethodHandles.lookup()
     .findVirtual(String.class, "concat", MethodType.methodType(String.class, String.class));
 SwitchPoint spt = new SwitchPoint();
-assert(spt.isValid());
+assert(!spt.hasBeenInvalidated());
 // the following steps may be repeated to re-use the same switch point:
 MethodHandle worker1 = MH_strcat;
 MethodHandle worker2 = MethodHandles.permuteArguments(MH_strcat, MH_strcat.type(), 1, 0);
 MethodHandle worker = spt.guardWithTest(worker1, worker2);
 assertEquals("method", (String) worker.invokeExact("met", "hod"));
 SwitchPoint.invalidateAll(new SwitchPoint[]{ spt });
-assert(!spt.isValid());
+assert(spt.hasBeenInvalidated());
 assertEquals("hodmet", (String) worker.invokeExact("met", "hod"));
 {}
             }}