Home » openjdk-7 » java.lang.invoke » [javadoc | source]

    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   }

Home » openjdk-7 » java.lang.invoke » [javadoc | source]