1.1 --- a/rt/emul/compact/src/main/java/java/lang/invoke/SwitchPoint.java Sun Aug 17 20:09:05 2014 +0200
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,228 +0,0 @@
1.4 -/*
1.5 - * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
1.6 - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 - *
1.8 - * This code is free software; you can redistribute it and/or modify it
1.9 - * under the terms of the GNU General Public License version 2 only, as
1.10 - * published by the Free Software Foundation. Oracle designates this
1.11 - * particular file as subject to the "Classpath" exception as provided
1.12 - * by Oracle in the LICENSE file that accompanied this code.
1.13 - *
1.14 - * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 - * version 2 for more details (a copy is included in the LICENSE file that
1.18 - * accompanied this code).
1.19 - *
1.20 - * You should have received a copy of the GNU General Public License version
1.21 - * 2 along with this work; if not, write to the Free Software Foundation,
1.22 - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 - *
1.24 - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 - * or visit www.oracle.com if you need additional information or have any
1.26 - * questions.
1.27 - */
1.28 -
1.29 -package java.lang.invoke;
1.30 -
1.31 -/**
1.32 - * <p>
1.33 - * A {@code SwitchPoint} is an object which can publish state transitions to other threads.
1.34 - * A switch point is initially in the <em>valid</em> state, but may at any time be
1.35 - * changed to the <em>invalid</em> state. Invalidation cannot be reversed.
1.36 - * A switch point can combine a <em>guarded pair</em> of method handles into a
1.37 - * <em>guarded delegator</em>.
1.38 - * The guarded delegator is a method handle which delegates to one of the old method handles.
1.39 - * The state of the switch point determines which of the two gets the delegation.
1.40 - * <p>
1.41 - * A single switch point may be used to control any number of method handles.
1.42 - * (Indirectly, therefore, it can control any number of call sites.)
1.43 - * This is done by using the single switch point as a factory for combining
1.44 - * any number of guarded method handle pairs into guarded delegators.
1.45 - * <p>
1.46 - * When a guarded delegator is created from a guarded pair, the pair
1.47 - * is wrapped in a new method handle {@code M},
1.48 - * which is permanently associated with the switch point that created it.
1.49 - * Each pair consists of a target {@code T} and a fallback {@code F}.
1.50 - * While the switch point is valid, invocations to {@code M} are delegated to {@code T}.
1.51 - * After it is invalidated, invocations are delegated to {@code F}.
1.52 - * <p>
1.53 - * Invalidation is global and immediate, as if the switch point contained a
1.54 - * volatile boolean variable consulted on every call to {@code M}.
1.55 - * The invalidation is also permanent, which means the switch point
1.56 - * can change state only once.
1.57 - * The switch point will always delegate to {@code F} after being invalidated.
1.58 - * At that point {@code guardWithTest} may ignore {@code T} and return {@code F}.
1.59 - * <p>
1.60 - * Here is an example of a switch point in action:
1.61 - * <blockquote><pre>{@code
1.62 -MethodHandle MH_strcat = MethodHandles.lookup()
1.63 - .findVirtual(String.class, "concat", MethodType.methodType(String.class, String.class));
1.64 -SwitchPoint spt = new SwitchPoint();
1.65 -assert(!spt.hasBeenInvalidated());
1.66 -// the following steps may be repeated to re-use the same switch point:
1.67 -MethodHandle worker1 = MH_strcat;
1.68 -MethodHandle worker2 = MethodHandles.permuteArguments(MH_strcat, MH_strcat.type(), 1, 0);
1.69 -MethodHandle worker = spt.guardWithTest(worker1, worker2);
1.70 -assertEquals("method", (String) worker.invokeExact("met", "hod"));
1.71 -SwitchPoint.invalidateAll(new SwitchPoint[]{ spt });
1.72 -assert(spt.hasBeenInvalidated());
1.73 -assertEquals("hodmet", (String) worker.invokeExact("met", "hod"));
1.74 - * }</pre></blockquote>
1.75 - * <p style="font-size:smaller;">
1.76 - * <em>Discussion:</em>
1.77 - * Switch points are useful without subclassing. They may also be subclassed.
1.78 - * This may be useful in order to associate application-specific invalidation logic
1.79 - * with the switch point.
1.80 - * Notice that there is no permanent association between a switch point and
1.81 - * the method handles it produces and consumes.
1.82 - * The garbage collector may collect method handles produced or consumed
1.83 - * by a switch point independently of the lifetime of the switch point itself.
1.84 - * <p style="font-size:smaller;">
1.85 - * <em>Implementation Note:</em>
1.86 - * A switch point behaves as if implemented on top of {@link MutableCallSite},
1.87 - * approximately as follows:
1.88 - * <blockquote><pre>{@code
1.89 -public class SwitchPoint {
1.90 - private static final MethodHandle
1.91 - K_true = MethodHandles.constant(boolean.class, true),
1.92 - K_false = MethodHandles.constant(boolean.class, false);
1.93 - private final MutableCallSite mcs;
1.94 - private final MethodHandle mcsInvoker;
1.95 - public SwitchPoint() {
1.96 - this.mcs = new MutableCallSite(K_true);
1.97 - this.mcsInvoker = mcs.dynamicInvoker();
1.98 - }
1.99 - public MethodHandle guardWithTest(
1.100 - MethodHandle target, MethodHandle fallback) {
1.101 - // Note: mcsInvoker is of type ()boolean.
1.102 - // Target and fallback may take any arguments, but must have the same type.
1.103 - return MethodHandles.guardWithTest(this.mcsInvoker, target, fallback);
1.104 - }
1.105 - public static void invalidateAll(SwitchPoint[] spts) {
1.106 - List<MutableCallSite> mcss = new ArrayList<>();
1.107 - for (SwitchPoint spt : spts) mcss.add(spt.mcs);
1.108 - for (MutableCallSite mcs : mcss) mcs.setTarget(K_false);
1.109 - MutableCallSite.syncAll(mcss.toArray(new MutableCallSite[0]));
1.110 - }
1.111 -}
1.112 - * }</pre></blockquote>
1.113 - * @author Remi Forax, JSR 292 EG
1.114 - */
1.115 -public class SwitchPoint {
1.116 - private static final MethodHandle
1.117 - K_true = MethodHandles.constant(boolean.class, true),
1.118 - K_false = MethodHandles.constant(boolean.class, false);
1.119 -
1.120 - private final MutableCallSite mcs;
1.121 - private final MethodHandle mcsInvoker;
1.122 -
1.123 - /**
1.124 - * Creates a new switch point.
1.125 - */
1.126 - public SwitchPoint() {
1.127 - this.mcs = new MutableCallSite(K_true);
1.128 - this.mcsInvoker = mcs.dynamicInvoker();
1.129 - }
1.130 -
1.131 - /**
1.132 - * Determines if this switch point has been invalidated yet.
1.133 - *
1.134 - * <p style="font-size:smaller;">
1.135 - * <em>Discussion:</em>
1.136 - * Because of the one-way nature of invalidation, once a switch point begins
1.137 - * to return true for {@code hasBeenInvalidated},
1.138 - * it will always do so in the future.
1.139 - * On the other hand, a valid switch point visible to other threads may
1.140 - * be invalidated at any moment, due to a request by another thread.
1.141 - * <p style="font-size:smaller;">
1.142 - * Since invalidation is a global and immediate operation,
1.143 - * the execution of this query, on a valid switchpoint,
1.144 - * must be internally sequenced with any
1.145 - * other threads that could cause invalidation.
1.146 - * This query may therefore be expensive.
1.147 - * The recommended way to build a boolean-valued method handle
1.148 - * which queries the invalidation state of a switch point {@code s} is
1.149 - * to call {@code s.guardWithTest} on
1.150 - * {@link MethodHandles#constant constant} true and false method handles.
1.151 - *
1.152 - * @return true if this switch point has been invalidated
1.153 - */
1.154 - public boolean hasBeenInvalidated() {
1.155 - return (mcs.getTarget() != K_true);
1.156 - }
1.157 -
1.158 - /**
1.159 - * Returns a method handle which always delegates either to the target or the fallback.
1.160 - * The method handle will delegate to the target exactly as long as the switch point is valid.
1.161 - * After that, it will permanently delegate to the fallback.
1.162 - * <p>
1.163 - * The target and fallback must be of exactly the same method type,
1.164 - * and the resulting combined method handle will also be of this type.
1.165 - *
1.166 - * @param target the method handle selected by the switch point as long as it is valid
1.167 - * @param fallback the method handle selected by the switch point after it is invalidated
1.168 - * @return a combined method handle which always calls either the target or fallback
1.169 - * @throws NullPointerException if either argument is null
1.170 - * @throws IllegalArgumentException if the two method types do not match
1.171 - * @see MethodHandles#guardWithTest
1.172 - */
1.173 - public MethodHandle guardWithTest(MethodHandle target, MethodHandle fallback) {
1.174 - if (mcs.getTarget() == K_false)
1.175 - return fallback; // already invalid
1.176 - return MethodHandles.guardWithTest(mcsInvoker, target, fallback);
1.177 - }
1.178 -
1.179 - /**
1.180 - * Sets all of the given switch points into the invalid state.
1.181 - * After this call executes, no thread will observe any of the
1.182 - * switch points to be in a valid state.
1.183 - * <p>
1.184 - * This operation is likely to be expensive and should be used sparingly.
1.185 - * If possible, it should be buffered for batch processing on sets of switch points.
1.186 - * <p>
1.187 - * If {@code switchPoints} contains a null element,
1.188 - * a {@code NullPointerException} will be raised.
1.189 - * In this case, some non-null elements in the array may be
1.190 - * processed before the method returns abnormally.
1.191 - * Which elements these are (if any) is implementation-dependent.
1.192 - *
1.193 - * <p style="font-size:smaller;">
1.194 - * <em>Discussion:</em>
1.195 - * For performance reasons, {@code invalidateAll} is not a virtual method
1.196 - * on a single switch point, but rather applies to a set of switch points.
1.197 - * Some implementations may incur a large fixed overhead cost
1.198 - * for processing one or more invalidation operations,
1.199 - * but a small incremental cost for each additional invalidation.
1.200 - * In any case, this operation is likely to be costly, since
1.201 - * other threads may have to be somehow interrupted
1.202 - * in order to make them notice the updated switch point state.
1.203 - * However, it may be observed that a single call to invalidate
1.204 - * several switch points has the same formal effect as many calls,
1.205 - * each on just one of the switch points.
1.206 - *
1.207 - * <p style="font-size:smaller;">
1.208 - * <em>Implementation Note:</em>
1.209 - * Simple implementations of {@code SwitchPoint} may use
1.210 - * a private {@link MutableCallSite} to publish the state of a switch point.
1.211 - * In such an implementation, the {@code invalidateAll} method can
1.212 - * simply change the call site's target, and issue one call to
1.213 - * {@linkplain MutableCallSite#syncAll synchronize} all the
1.214 - * private call sites.
1.215 - *
1.216 - * @param switchPoints an array of call sites to be synchronized
1.217 - * @throws NullPointerException if the {@code switchPoints} array reference is null
1.218 - * or the array contains a null
1.219 - */
1.220 - public static void invalidateAll(SwitchPoint[] switchPoints) {
1.221 - if (switchPoints.length == 0) return;
1.222 - MutableCallSite[] sites = new MutableCallSite[switchPoints.length];
1.223 - for (int i = 0; i < switchPoints.length; i++) {
1.224 - SwitchPoint spt = switchPoints[i];
1.225 - if (spt == null) break; // MSC.syncAll will trigger a NPE
1.226 - sites[i] = spt.mcs;
1.227 - spt.mcs.setTarget(K_false);
1.228 - }
1.229 - MutableCallSite.syncAll(sites);
1.230 - }
1.231 -}