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 }