From ad33af1a1ca1ce716b5ccbb4dab993a4ace01c14 Mon Sep 17 00:00:00 2001
From: John R Rose <jrose@openjdk.org>
Date: Fri, 3 Jun 2011 11:20:20 -0700
Subject: [PATCH] 7051206: JSR 292 method name SwitchPoint.isValid is
 misleading to unwary users; should be hasBeenInvalidated

Reviewed-by: kvn, never, ysr
---
 .../classes/java/lang/invoke/SwitchPoint.java | 34 +++++++++++++------
 .../java/lang/invoke/JavaDocExamplesTest.java |  4 +--
 2 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java b/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java
index 11d8018c076..7469e408dd6 100644
--- a/jdk/src/share/classes/java/lang/invoke/SwitchPoint.java
+++ b/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);
     }
 
     /**
diff --git a/jdk/test/java/lang/invoke/JavaDocExamplesTest.java b/jdk/test/java/lang/invoke/JavaDocExamplesTest.java
index 0e373c1e773..ba1eed5e757 100644
--- a/jdk/test/java/lang/invoke/JavaDocExamplesTest.java
+++ b/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"));
 {}
             }}