1 /* 2 * Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang.invoke; 27 28 /** 29 * A {@code VolatileCallSite} is a {@link CallSite} whose target acts like a volatile variable. 30 * An {@code invokedynamic} instruction linked to a {@code VolatileCallSite} sees updates 31 * to its call site target immediately, even if the update occurs in another thread. 32 * There may be a performance penalty for such tight coupling between threads. 33 * <p> 34 * Unlike {@code MutableCallSite}, there is no 35 * {@linkplain MutableCallSite#syncAll syncAll operation} on volatile 36 * call sites, since every write to a volatile variable is implicitly 37 * synchronized with reader threads. 38 * <p> 39 * In other respects, a {@code VolatileCallSite} is interchangeable 40 * with {@code MutableCallSite}. 41 * @see MutableCallSite 42 * @author John Rose, JSR 292 EG 43 * @since 1.7 44 */ 45 public class VolatileCallSite extends CallSite { 46 /** 47 * Creates a call site with a volatile binding to its target. 48 * The initial target is set to a method handle 49 * of the given type which will throw an {@code IllegalStateException} if called. 50 * @param type the method type that this call site will have 51 * @throws NullPointerException if the proposed type is null 52 */ VolatileCallSite(MethodType type)53 public VolatileCallSite(MethodType type) { 54 super(type); 55 } 56 57 /** 58 * Creates a call site with a volatile binding to its target. 59 * The target is set to the given value. 60 * @param target the method handle that will be the initial target of the call site 61 * @throws NullPointerException if the proposed target is null 62 */ VolatileCallSite(MethodHandle target)63 public VolatileCallSite(MethodHandle target) { 64 super(target); 65 } 66 67 /** 68 * Returns the target method of the call site, which behaves 69 * like a {@code volatile} field of the {@code VolatileCallSite}. 70 * <p> 71 * The interactions of {@code getTarget} with memory are the same 72 * as of a read from a {@code volatile} field. 73 * <p> 74 * In particular, the current thread is required to issue a fresh 75 * read of the target from memory, and must not fail to see 76 * a recent update to the target by another thread. 77 * 78 * @return the linkage state of this call site, a method handle which can change over time 79 * @see #setTarget 80 */ getTarget()81 @Override public final MethodHandle getTarget() { 82 return getTargetVolatile(); 83 } 84 85 /** 86 * Updates the target method of this call site, as a volatile variable. 87 * The type of the new target must agree with the type of the old target. 88 * <p> 89 * The interactions with memory are the same as of a write to a volatile field. 90 * In particular, any threads is guaranteed to see the updated target 91 * the next time it calls {@code getTarget}. 92 * @param newTarget the new target 93 * @throws NullPointerException if the proposed new target is null 94 * @throws WrongMethodTypeException if the proposed new target 95 * has a method type that differs from the previous target 96 * @see #getTarget 97 */ setTarget(MethodHandle newTarget)98 @Override public void setTarget(MethodHandle newTarget) { 99 setTargetVolatile(newTarget); 100 } 101 102 /** 103 * {@inheritDoc} 104 */ 105 @Override dynamicInvoker()106 public final MethodHandle dynamicInvoker() { 107 return makeDynamicInvoker(); 108 } 109 } 110