jaroslav@1981: /*
jaroslav@1981:  * Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.
jaroslav@1981:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
jaroslav@1981:  *
jaroslav@1981:  * This code is free software; you can redistribute it and/or modify it
jaroslav@1981:  * under the terms of the GNU General Public License version 2 only, as
jaroslav@1981:  * published by the Free Software Foundation.  Oracle designates this
jaroslav@1981:  * particular file as subject to the "Classpath" exception as provided
jaroslav@1981:  * by Oracle in the LICENSE file that accompanied this code.
jaroslav@1981:  *
jaroslav@1981:  * This code is distributed in the hope that it will be useful, but WITHOUT
jaroslav@1981:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
jaroslav@1981:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
jaroslav@1981:  * version 2 for more details (a copy is included in the LICENSE file that
jaroslav@1981:  * accompanied this code).
jaroslav@1981:  *
jaroslav@1981:  * You should have received a copy of the GNU General Public License version
jaroslav@1981:  * 2 along with this work; if not, write to the Free Software Foundation,
jaroslav@1981:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
jaroslav@1981:  *
jaroslav@1981:  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
jaroslav@1981:  * or visit www.oracle.com if you need additional information or have any
jaroslav@1981:  * questions.
jaroslav@1981:  */
jaroslav@1981: 
jaroslav@1981: package java.lang;
jaroslav@1981: 
jaroslav@1985: import java.lang.Class;
jaroslav@1985: import org.apidesign.bck2brwsr.core.JavaScriptBody;
jaroslav@1981: 
jaroslav@1981: /**
jaroslav@1981:  * Lazily associate a computed value with (potentially) every type.
jaroslav@1981:  * For example, if a dynamic language needs to construct a message dispatch
jaroslav@1981:  * table for each class encountered at a message send call site,
jaroslav@1981:  * it can use a {@code ClassValue} to cache information needed to
jaroslav@1981:  * perform the message send quickly, for each class encountered.
jaroslav@1981:  * @author John Rose, JSR 292 EG
jaroslav@1981:  * @since 1.7
jaroslav@1981:  */
jaroslav@1981: public abstract class ClassValue<T> {
jaroslav@1981:     /**
jaroslav@1981:      * Sole constructor.  (For invocation by subclass constructors, typically
jaroslav@1981:      * implicit.)
jaroslav@1981:      */
jaroslav@1981:     protected ClassValue() {
jaroslav@1981:     }
jaroslav@1981: 
jaroslav@1981:     /**
jaroslav@1981:      * Computes the given class's derived value for this {@code ClassValue}.
jaroslav@1981:      * <p>
jaroslav@1981:      * This method will be invoked within the first thread that accesses
jaroslav@1981:      * the value with the {@link #get get} method.
jaroslav@1981:      * <p>
jaroslav@1981:      * Normally, this method is invoked at most once per class,
jaroslav@1981:      * but it may be invoked again if there has been a call to
jaroslav@1981:      * {@link #remove remove}.
jaroslav@1981:      * <p>
jaroslav@1981:      * If this method throws an exception, the corresponding call to {@code get}
jaroslav@1981:      * will terminate abnormally with that exception, and no class value will be recorded.
jaroslav@1981:      *
jaroslav@1981:      * @param type the type whose class value must be computed
jaroslav@1981:      * @return the newly computed value associated with this {@code ClassValue}, for the given class or interface
jaroslav@1981:      * @see #get
jaroslav@1981:      * @see #remove
jaroslav@1981:      */
jaroslav@1981:     protected abstract T computeValue(Class<?> type);
jaroslav@1981: 
jaroslav@1981:     /**
jaroslav@1981:      * Returns the value for the given class.
jaroslav@1981:      * If no value has yet been computed, it is obtained by
jaroslav@1981:      * an invocation of the {@link #computeValue computeValue} method.
jaroslav@1981:      * <p>
jaroslav@1981:      * The actual installation of the value on the class
jaroslav@1981:      * is performed atomically.
jaroslav@1981:      * At that point, if several racing threads have
jaroslav@1981:      * computed values, one is chosen, and returned to
jaroslav@1981:      * all the racing threads.
jaroslav@1981:      * <p>
jaroslav@1981:      * The {@code type} parameter is typically a class, but it may be any type,
jaroslav@1981:      * such as an interface, a primitive type (like {@code int.class}), or {@code void.class}.
jaroslav@1981:      * <p>
jaroslav@1981:      * In the absence of {@code remove} calls, a class value has a simple
jaroslav@1981:      * state diagram:  uninitialized and initialized.
jaroslav@1981:      * When {@code remove} calls are made,
jaroslav@1981:      * the rules for value observation are more complex.
jaroslav@1981:      * See the documentation for {@link #remove remove} for more information.
jaroslav@1981:      *
jaroslav@1981:      * @param type the type whose class value must be computed or retrieved
jaroslav@1981:      * @return the current value associated with this {@code ClassValue}, for the given class or interface
jaroslav@1981:      * @throws NullPointerException if the argument is null
jaroslav@1981:      * @see #remove
jaroslav@1981:      * @see #computeValue
jaroslav@1981:      */
jaroslav@1981:     public T get(Class<?> type) {
jaroslav@1985:         T value = access(type, id, false, null);
jaroslav@1985:         if (value == undefined()) {
jaroslav@1985:             value = access(type, id, true, computeValue(type));
jaroslav@1981:         }
jaroslav@1985:         return value;
jaroslav@1981:     }
jaroslav@1981: 
jaroslav@1981:     /**
jaroslav@1981:      * Removes the associated value for the given class.
jaroslav@1981:      * If this value is subsequently {@linkplain #get read} for the same class,
jaroslav@1981:      * its value will be reinitialized by invoking its {@link #computeValue computeValue} method.
jaroslav@1981:      * This may result in an additional invocation of the
jaroslav@1981:      * {@code computeValue} method for the given class.
jaroslav@1981:      * <p>
jaroslav@1981:      * In order to explain the interaction between {@code get} and {@code remove} calls,
jaroslav@1981:      * we must model the state transitions of a class value to take into account
jaroslav@1981:      * the alternation between uninitialized and initialized states.
jaroslav@1981:      * To do this, number these states sequentially from zero, and note that
jaroslav@1981:      * uninitialized (or removed) states are numbered with even numbers,
jaroslav@1981:      * while initialized (or re-initialized) states have odd numbers.
jaroslav@1981:      * <p>
jaroslav@1981:      * When a thread {@code T} removes a class value in state {@code 2N},
jaroslav@1981:      * nothing happens, since the class value is already uninitialized.
jaroslav@1981:      * Otherwise, the state is advanced atomically to {@code 2N+1}.
jaroslav@1981:      * <p>
jaroslav@1981:      * When a thread {@code T} queries a class value in state {@code 2N},
jaroslav@1981:      * the thread first attempts to initialize the class value to state {@code 2N+1}
jaroslav@1981:      * by invoking {@code computeValue} and installing the resulting value.
jaroslav@1981:      * <p>
jaroslav@1981:      * When {@code T} attempts to install the newly computed value,
jaroslav@1981:      * if the state is still at {@code 2N}, the class value will be initialized
jaroslav@1981:      * with the computed value, advancing it to state {@code 2N+1}.
jaroslav@1981:      * <p>
jaroslav@1981:      * Otherwise, whether the new state is even or odd,
jaroslav@1981:      * {@code T} will discard the newly computed value
jaroslav@1981:      * and retry the {@code get} operation.
jaroslav@1981:      * <p>
jaroslav@1981:      * Discarding and retrying is an important proviso,
jaroslav@1981:      * since otherwise {@code T} could potentially install
jaroslav@1981:      * a disastrously stale value.  For example:
jaroslav@1981:      * <ul>
jaroslav@1981:      * <li>{@code T} calls {@code CV.get(C)} and sees state {@code 2N}
jaroslav@1981:      * <li>{@code T} quickly computes a time-dependent value {@code V0} and gets ready to install it
jaroslav@1981:      * <li>{@code T} is hit by an unlucky paging or scheduling event, and goes to sleep for a long time
jaroslav@1981:      * <li>...meanwhile, {@code T2} also calls {@code CV.get(C)} and sees state {@code 2N}
jaroslav@1981:      * <li>{@code T2} quickly computes a similar time-dependent value {@code V1} and installs it on {@code CV.get(C)}
jaroslav@1981:      * <li>{@code T2} (or a third thread) then calls {@code CV.remove(C)}, undoing {@code T2}'s work
jaroslav@1981:      * <li> the previous actions of {@code T2} are repeated several times
jaroslav@1981:      * <li> also, the relevant computed values change over time: {@code V1}, {@code V2}, ...
jaroslav@1981:      * <li>...meanwhile, {@code T} wakes up and attempts to install {@code V0}; <em>this must fail</em>
jaroslav@1981:      * </ul>
jaroslav@1981:      * We can assume in the above scenario that {@code CV.computeValue} uses locks to properly
jaroslav@1981:      * observe the time-dependent states as it computes {@code V1}, etc.
jaroslav@1981:      * This does not remove the threat of a stale value, since there is a window of time
jaroslav@1981:      * between the return of {@code computeValue} in {@code T} and the installation
jaroslav@1981:      * of the the new value.  No user synchronization is possible during this time.
jaroslav@1981:      *
jaroslav@1981:      * @param type the type whose class value must be removed
jaroslav@1981:      * @throws NullPointerException if the argument is null
jaroslav@1981:      */
jaroslav@1981:     public void remove(Class<?> type) {
jaroslav@1985:         access(type, id, true, undefined());
jaroslav@1981:     }
jaroslav@1981: 
jaroslav@1981:     /// Implementation...
jaroslav@1981: 
jaroslav@1985:     private static int COUNTER = 0;
jaroslav@1985:     private final int id = COUNTER++;
jaroslav@1981: 
jaroslav@1985:     @JavaScriptBody(args = {}, body = "return undefined;")
jaroslav@1985:     private static native Object undefined();
jaroslav@1981: 
jaroslav@1985:     @JavaScriptBody(args = { "where", "index", "set", "newValue" }, body =
jaroslav@1985:         "var data = where['values'];\n" +
jaroslav@1985:         "if (!data) {\n" +
jaroslav@1985:         "  data = where['values'] = [];\n" +
jaroslav@1985:         "}\n" +
jaroslav@1985:         "if (set) {\n" +
jaroslav@1985:         "  data[index] = newValue;\n" +
jaroslav@1985:         "}\n" +
jaroslav@1985:         "return data[index];\n" +
jaroslav@1985:         ""
jaroslav@1985:     )
jaroslav@1985:     private static native <T> T access(Class<?> where, int index, boolean set, T newValue);
jaroslav@1981: }