# HG changeset patch
# User jrose
# Date 1307125220 25200
# Node ID 802994506203b7216f56f306e7e1666a2d5b1045
# Parent  34481a4012c38bc1331626b519e116bac6b2fc5f
7051206: JSR 292 method name SwitchPoint.isValid is misleading to unwary users; should be hasBeenInvalidated
Reviewed-by: kvn, never, ysr

diff -r 34481a4012c3 -r 802994506203 src/share/classes/java/lang/invoke/SwitchPoint.java
--- a/src/share/classes/java/lang/invoke/SwitchPoint.java	Wed Jun 01 23:56:51 2011 -0700
+++ b/src/share/classes/java/lang/invoke/SwitchPoint.java	Fri Jun 03 11:20:20 2011 -0700
@@ -59,14 +59,14 @@
 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 @@
     }
 
     /**
-     * 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 -r 34481a4012c3 -r 802994506203 test/java/lang/invoke/JavaDocExamplesTest.java
--- a/test/java/lang/invoke/JavaDocExamplesTest.java	Wed Jun 01 23:56:51 2011 -0700
+++ b/test/java/lang/invoke/JavaDocExamplesTest.java	Fri Jun 03 11:20:20 2011 -0700
@@ -477,14 +477,14 @@
 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"));
 {}
             }}