jdk/src/java.base/share/classes/java/lang/invoke/MutableCallSite.java
author mli
Tue, 14 Mar 2017 19:23:37 -0700
changeset 44255 515cf13d7791
parent 29094 a4fd2b5e49f8
permissions -rw-r--r--
8176566: @since value errors in types of java.base module Reviewed-by: martin, psandoz
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     1
/*
23010
6dadb192ad81 8029235: Update copyright year to match last edit in jdk8 jdk repository for 2013
lana
parents: 22581
diff changeset
     2
 * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     4
 *
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    10
 *
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    15
 * accompanied this code).
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    16
 *
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 4537
diff changeset
    23
 * questions.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    24
 */
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    25
8822
8145ab9f5f86 7012648: move JSR 292 to package java.lang.invoke and adjust names
jrose
parents: 8821
diff changeset
    26
package java.lang.invoke;
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    27
29094
a4fd2b5e49f8 8073479: Replace obj.getClass hacks with Objects.requireNonNull
shade
parents: 25859
diff changeset
    28
import java.util.Objects;
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    29
import java.util.concurrent.atomic.AtomicInteger;
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    30
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    31
/**
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    32
 * A {@code MutableCallSite} is a {@link CallSite} whose target variable
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    33
 * behaves like an ordinary field.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    34
 * An {@code invokedynamic} instruction linked to a {@code MutableCallSite} delegates
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7052
diff changeset
    35
 * all calls to the site's current target.
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    36
 * The {@linkplain CallSite#dynamicInvoker dynamic invoker} of a mutable call site
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    37
 * also delegates each call to the site's current target.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    38
 * <p>
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    39
 * Here is an example of a mutable call site which introduces a
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    40
 * state variable into a method handle chain.
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 8822
diff changeset
    41
 * <!-- JavaDocExamplesTest.testMutableCallSite -->
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 18569
diff changeset
    42
 * <blockquote><pre>{@code
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    43
MutableCallSite name = new MutableCallSite(MethodType.methodType(String.class));
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    44
MethodHandle MH_name = name.dynamicInvoker();
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 8822
diff changeset
    45
MethodType MT_str1 = MethodType.methodType(String.class);
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    46
MethodHandle MH_upcase = MethodHandles.lookup()
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 8822
diff changeset
    47
    .findVirtual(String.class, "toUpperCase", MT_str1);
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    48
MethodHandle worker1 = MethodHandles.filterReturnValue(MH_name, MH_upcase);
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    49
name.setTarget(MethodHandles.constant(String.class, "Rocky"));
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    50
assertEquals("ROCKY", (String) worker1.invokeExact());
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    51
name.setTarget(MethodHandles.constant(String.class, "Fred"));
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    52
assertEquals("FRED", (String) worker1.invokeExact());
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    53
// (mutation can be continued indefinitely)
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 18569
diff changeset
    54
 * }</pre></blockquote>
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
    55
 * <p>
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    56
 * The same call site may be used in several places at once.
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 18569
diff changeset
    57
 * <blockquote><pre>{@code
9752
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 8822
diff changeset
    58
MethodType MT_str2 = MethodType.methodType(String.class, String.class);
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 8822
diff changeset
    59
MethodHandle MH_cat = lookup().findVirtual(String.class,
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 8822
diff changeset
    60
  "concat", methodType(String.class, String.class));
88ab34b6da6d 7032323: code changes for JSR 292 EG adjustments to API, through Public Review
jrose
parents: 8822
diff changeset
    61
MethodHandle MH_dear = MethodHandles.insertArguments(MH_cat, 1, ", dear?");
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    62
MethodHandle worker2 = MethodHandles.filterReturnValue(MH_name, MH_dear);
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    63
assertEquals("Fred, dear?", (String) worker2.invokeExact());
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    64
name.setTarget(MethodHandles.constant(String.class, "Wilma"));
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    65
assertEquals("WILMA", (String) worker1.invokeExact());
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    66
assertEquals("Wilma, dear?", (String) worker2.invokeExact());
20535
cc85c8626435 8024438: JSR 292 API specification maintenance for JDK 8
jrose
parents: 18569
diff changeset
    67
 * }</pre></blockquote>
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    68
 * <p>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    69
 * <em>Non-synchronization of target values:</em>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    70
 * A write to a mutable call site's target does not force other threads
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    71
 * to become aware of the updated value.  Threads which do not perform
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    72
 * suitable synchronization actions relative to the updated call site
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    73
 * may cache the old target value and delay their use of the new target
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    74
 * value indefinitely.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    75
 * (This is a normal consequence of the Java Memory Model as applied
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    76
 * to object fields.)
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    77
 * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    78
 * The {@link #syncAll syncAll} operation provides a way to force threads
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    79
 * to accept a new target value, even if there is no other synchronization.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    80
 * <p>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    81
 * For target values which will be frequently updated, consider using
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    82
 * a {@linkplain VolatileCallSite volatile call site} instead.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    83
 * @author John Rose, JSR 292 EG
44255
515cf13d7791 8176566: @since value errors in types of java.base module
mli
parents: 29094
diff changeset
    84
 * @since 1.7
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
    85
 */
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    86
public class MutableCallSite extends CallSite {
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
    87
    /**
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    88
     * Creates a blank call site object with the given method type.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    89
     * The initial target is set to a method handle of the given type
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    90
     * which will throw an {@link IllegalStateException} if called.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    91
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    92
     * The type of the call site is permanently set to the given type.
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7052
diff changeset
    93
     * <p>
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7052
diff changeset
    94
     * Before this {@code CallSite} object is returned from a bootstrap method,
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    95
     * or invoked in some other manner,
7555
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7052
diff changeset
    96
     * it is usually provided with a more useful target method,
a279ebc3b25c 6981777: implement JSR 292 EG adjustments from summer 2010
jrose
parents: 7052
diff changeset
    97
     * via a call to {@link CallSite#setTarget(MethodHandle) setTarget}.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
    98
     * @param type the method type that this call site will have
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
    99
     * @throws NullPointerException if the proposed type is null
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   100
     */
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   101
    public MutableCallSite(MethodType type) {
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   102
        super(type);
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   103
    }
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   104
2763
172d44ffd1e5 6839802: java.dyn needs to be on the CORE_PKGS list
jrose
parents: 2707
diff changeset
   105
    /**
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   106
     * Creates a call site object with an initial target method handle.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   107
     * The type of the call site is permanently set to the initial target's type.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   108
     * @param target the method handle that will be the initial target of the call site
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   109
     * @throws NullPointerException if the proposed target is null
5722
4ada807383c8 6939134: JSR 292 adjustments to method handle invocation
jrose
parents: 4537
diff changeset
   110
     */
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   111
    public MutableCallSite(MethodHandle target) {
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   112
        super(target);
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   113
    }
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   114
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   115
    /**
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   116
     * Returns the target method of the call site, which behaves
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   117
     * like a normal field of the {@code MutableCallSite}.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   118
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   119
     * The interactions of {@code getTarget} with memory are the same
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   120
     * as of a read from an ordinary variable, such as an array element or a
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   121
     * non-volatile, non-final field.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   122
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   123
     * In particular, the current thread may choose to reuse the result
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   124
     * of a previous read of the target from memory, and may fail to see
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   125
     * a recent update to the target by another thread.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   126
     *
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   127
     * @return the linkage state of this call site, a method handle which can change over time
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   128
     * @see #setTarget
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   129
     */
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   130
    @Override public final MethodHandle getTarget() {
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   131
        return target;
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   132
    }
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   133
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   134
    /**
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   135
     * Updates the target method of this call site, as a normal variable.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   136
     * The type of the new target must agree with the type of the old target.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   137
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   138
     * The interactions with memory are the same
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   139
     * as of a write to an ordinary variable, such as an array element or a
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   140
     * non-volatile, non-final field.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   141
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   142
     * In particular, unrelated threads may fail to see the updated target
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   143
     * until they perform a read from memory.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   144
     * Stronger guarantees can be created by putting appropriate operations
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   145
     * into the bootstrap method and/or the target methods used
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   146
     * at any given call site.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   147
     *
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   148
     * @param newTarget the new target
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   149
     * @throws NullPointerException if the proposed new target is null
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   150
     * @throws WrongMethodTypeException if the proposed new target
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   151
     *         has a method type that differs from the previous target
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   152
     * @see #getTarget
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   153
     */
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   154
    @Override public void setTarget(MethodHandle newTarget) {
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   155
        checkTargetChange(this.target, newTarget);
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   156
        setTargetNormal(newTarget);
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   157
    }
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   158
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   159
    /**
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   160
     * {@inheritDoc}
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   161
     */
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   162
    @Override
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   163
    public final MethodHandle dynamicInvoker() {
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   164
        return makeDynamicInvoker();
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   165
    }
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   166
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   167
    /**
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   168
     * Performs a synchronization operation on each call site in the given array,
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   169
     * forcing all other threads to throw away any cached values previously
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   170
     * loaded from the target of any of the call sites.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   171
     * <p>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   172
     * This operation does not reverse any calls that have already started
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   173
     * on an old target value.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   174
     * (Java supports {@linkplain java.lang.Object#wait() forward time travel} only.)
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   175
     * <p>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   176
     * The overall effect is to force all future readers of each call site's target
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   177
     * to accept the most recently stored value.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   178
     * ("Most recently" is reckoned relative to the {@code syncAll} itself.)
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   179
     * Conversely, the {@code syncAll} call may block until all readers have
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   180
     * (somehow) decached all previous versions of each call site's target.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   181
     * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   182
     * To avoid race conditions, calls to {@code setTarget} and {@code syncAll}
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   183
     * should generally be performed under some sort of mutual exclusion.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   184
     * Note that reader threads may observe an updated target as early
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   185
     * as the {@code setTarget} call that install the value
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   186
     * (and before the {@code syncAll} that confirms the value).
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   187
     * On the other hand, reader threads may observe previous versions of
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   188
     * the target until the {@code syncAll} call returns
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   189
     * (and after the {@code setTarget} that attempts to convey the updated version).
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   190
     * <p>
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   191
     * This operation is likely to be expensive and should be used sparingly.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   192
     * If possible, it should be buffered for batch processing on sets of call sites.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   193
     * <p>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   194
     * If {@code sites} contains a null element,
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   195
     * a {@code NullPointerException} will be raised.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   196
     * In this case, some non-null elements in the array may be
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   197
     * processed before the method returns abnormally.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   198
     * Which elements these are (if any) is implementation-dependent.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   199
     *
18569
0e46c17766b7 8019357: Fix doclint warnings in java.lang.invoke
darcy
parents: 9752
diff changeset
   200
     * <h1>Java Memory Model details</h1>
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   201
     * In terms of the Java Memory Model, this operation performs a synchronization
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   202
     * action which is comparable in effect to the writing of a volatile variable
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   203
     * by the current thread, and an eventual volatile read by every other thread
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   204
     * that may access one of the affected call sites.
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   205
     * <p>
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   206
     * The following effects are apparent, for each individual call site {@code S}:
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   207
     * <ul>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   208
     * <li>A new volatile variable {@code V} is created, and written by the current thread.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   209
     *     As defined by the JMM, this write is a global synchronization event.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   210
     * <li>As is normal with thread-local ordering of write events,
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   211
     *     every action already performed by the current thread is
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   212
     *     taken to happen before the volatile write to {@code V}.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   213
     *     (In some implementations, this means that the current thread
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   214
     *     performs a global release operation.)
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   215
     * <li>Specifically, the write to the current target of {@code S} is
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   216
     *     taken to happen before the volatile write to {@code V}.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   217
     * <li>The volatile write to {@code V} is placed
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   218
     *     (in an implementation specific manner)
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   219
     *     in the global synchronization order.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   220
     * <li>Consider an arbitrary thread {@code T} (other than the current thread).
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   221
     *     If {@code T} executes a synchronization action {@code A}
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   222
     *     after the volatile write to {@code V} (in the global synchronization order),
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   223
     *     it is therefore required to see either the current target
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   224
     *     of {@code S}, or a later write to that target,
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   225
     *     if it executes a read on the target of {@code S}.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   226
     *     (This constraint is called "synchronization-order consistency".)
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   227
     * <li>The JMM specifically allows optimizing compilers to elide
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   228
     *     reads or writes of variables that are known to be useless.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   229
     *     Such elided reads and writes have no effect on the happens-before
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   230
     *     relation.  Regardless of this fact, the volatile {@code V}
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   231
     *     will not be elided, even though its written value is
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   232
     *     indeterminate and its read value is not used.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   233
     * </ul>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   234
     * Because of the last point, the implementation behaves as if a
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   235
     * volatile read of {@code V} were performed by {@code T}
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   236
     * immediately after its action {@code A}.  In the local ordering
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   237
     * of actions in {@code T}, this read happens before any future
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   238
     * read of the target of {@code S}.  It is as if the
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   239
     * implementation arbitrarily picked a read of {@code S}'s target
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   240
     * by {@code T}, and forced a read of {@code V} to precede it,
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   241
     * thereby ensuring communication of the new target value.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   242
     * <p>
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   243
     * As long as the constraints of the Java Memory Model are obeyed,
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   244
     * implementations may delay the completion of a {@code syncAll}
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   245
     * operation while other threads ({@code T} above) continue to
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   246
     * use previous values of {@code S}'s target.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   247
     * However, implementations are (as always) encouraged to avoid
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   248
     * livelock, and to eventually require all threads to take account
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   249
     * of the updated target.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   250
     *
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   251
     * <p style="font-size:smaller;">
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   252
     * <em>Discussion:</em>
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   253
     * For performance reasons, {@code syncAll} is not a virtual method
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   254
     * on a single call site, but rather applies to a set of call sites.
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   255
     * Some implementations may incur a large fixed overhead cost
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   256
     * for processing one or more synchronization operations,
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   257
     * but a small incremental cost for each additional call site.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   258
     * In any case, this operation is likely to be costly, since
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   259
     * other threads may have to be somehow interrupted
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   260
     * in order to make them notice the updated target value.
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   261
     * However, it may be observed that a single call to synchronize
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   262
     * several sites has the same formal effect as many calls,
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   263
     * each on just one of the sites.
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   264
     *
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   265
     * <p style="font-size:smaller;">
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   266
     * <em>Implementation Note:</em>
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   267
     * Simple implementations of {@code MutableCallSite} may use
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   268
     * a volatile variable for the target of a mutable call site.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   269
     * In such an implementation, the {@code syncAll} method can be a no-op,
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   270
     * and yet it will conform to the JMM behavior documented above.
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   271
     *
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   272
     * @param sites an array of call sites to be synchronized
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   273
     * @throws NullPointerException if the {@code sites} array reference is null
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   274
     *                              or the array contains a null
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   275
     */
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   276
    public static void syncAll(MutableCallSite[] sites) {
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   277
        if (sites.length == 0)  return;
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   278
        STORE_BARRIER.lazySet(0);
22581
e868cde95050 8032779: Update code in java.lang to use newer language features
psandoz
parents: 20535
diff changeset
   279
        for (MutableCallSite site : sites) {
29094
a4fd2b5e49f8 8073479: Replace obj.getClass hacks with Objects.requireNonNull
shade
parents: 25859
diff changeset
   280
            Objects.requireNonNull(site); // trigger NPE on first null
8346
3b891698c4ec 7012650: implement JSR 292 EG adjustments through January 2010
jrose
parents: 7562
diff changeset
   281
        }
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   282
        // FIXME: NYI
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   283
    }
7562
a0ad195efe2c 7001424: implement JSR 292 EG adjustments, November 2010
jrose
parents: 7555
diff changeset
   284
    private static final AtomicInteger STORE_BARRIER = new AtomicInteger();
2707
5a17df307cbc 6829144: JSR 292 JVM features need a provisional Java API
jrose
parents:
diff changeset
   285
}