1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/lang/invoke/SwitchPoint.java Sun Aug 17 20:09:05 2014 +0200
1.3 @@ -0,0 +1,228 @@
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 +}