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 */ 44 public class VolatileCallSite extends CallSite { 45 /** 46 * Creates a call site with a volatile binding to its target. 47 * The initial target is set to a method handle 48 * of the given type which will throw an {@code IllegalStateException} if called. 49 * @param type the method type that this call site will have 50 * @throws NullPointerException if the proposed type is null 51 */ 52 public VolatileCallSite(MethodType type) { 53 super(type); 54 } 55 56 /** 57 * Creates a call site with a volatile binding to its target. 58 * The target is set to the given value. 59 * @param target the method handle that will be the initial target of the call site 60 * @throws NullPointerException if the proposed target is null 61 */ 62 public VolatileCallSite(MethodHandle target) { 63 super(target); 64 } 65 66 /** 67 * Returns the target method of the call site, which behaves 68 * like a {@code volatile} field of the {@code VolatileCallSite}. 69 * <p> 70 * The interactions of {@code getTarget} with memory are the same 71 * as of a read from a {@code volatile} field. 72 * <p> 73 * In particular, the current thread is required to issue a fresh 74 * read of the target from memory, and must not fail to see 75 * a recent update to the target by another thread. 76 * 77 * @return the linkage state of this call site, a method handle which can change over time 78 * @see #setTarget 79 */ 80 @Override public final MethodHandle getTarget() { 81 return getTargetVolatile(); 82 } 83 84 /** 85 * Updates the target method of this call site, as a volatile variable. 86 * The type of the new target must agree with the type of the old target. 87 * <p> 88 * The interactions with memory are the same as of a write to a volatile field. 89 * In particular, any threads is guaranteed to see the updated target 90 * the next time it calls {@code getTarget}. 91 * @param newTarget the new target 92 * @throws NullPointerException if the proposed new target is null 93 * @throws WrongMethodTypeException if the proposed new target 94 * has a method type that differs from the previous target 95 * @see #getTarget 96 */ 97 @Override public void setTarget(MethodHandle newTarget) { 98 checkTargetChange(getTargetVolatile(), newTarget); 99 setTargetVolatile(newTarget); 100 } 101 102 /** 103 * {@inheritDoc} 104 */ 105 @Override 106 public final MethodHandle dynamicInvoker() { 107 return makeDynamicInvoker(); 108 } 109 }