objects/annotations/SpecializedFunction.java

/*
 * Copyright (c) 2010, 2014, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package jdk.nashorn.internal.objects.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.lang.invoke.MethodHandle;
import java.lang.invoke.SwitchPoint;
import jdk.internal.dynalink.CallSiteDescriptor;
import jdk.internal.dynalink.linker.LinkRequest;
import jdk.nashorn.internal.runtime.ScriptFunction;

/**
 * The SpecializedFunction annotation is used to flag more type specific
 * functions than the standard one in the native objects
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface SpecializedFunction {

    /**
     * Functionality for testing if we are allowed to link a specialized
     * function the first time we encounter it. Then the guard will handle the
     * rest of the invocations
     *
     * This is the same for all callsites in Nashorn, the first time callsite is
     * linked, we have to manually check that the linkage is OK. Even if we add
     * a guard and it fails upon the first try, this is not good enough.
     * (Symmetrical to how it works everywhere else in the Nashorn runtime).
     *
     * Here we abstract out a few of the most common link guard checks.
     */
    public static abstract class LinkLogic {
        /**
         * Empty link logic instance - this is the default
         * "no special linking or runtime guard behavior"
         */
        public static final LinkLogic EMPTY_INSTANCE = new Empty();

        private static final SwitchPoint[] INVALIDATED_SWITCHPOINTS = new SwitchPoint[0];

        private SwitchPoint[] modificationSwitchPoints; //cache

        /** Empty link logic class - allow all linking, no guards */
        private static final class Empty extends LinkLogic {
            @Override
            public boolean canLink(final Object self, final CallSiteDescriptor desc, final LinkRequest request) {
                return true;
            }

            @Override
            public boolean isEmpty() {
                return true;
            }
        }

        /**
         * Get the class representing the empty link logic
         * @return class representing empty link logic
         */
        public static Class<? extends LinkLogic> getEmptyLinkLogicClass() {
            return Empty.class;
        }

        /**
         * Should this callsite relink when an exception is thrown
         *
         * @return the relink exception, or null if none
         */
        public Class<? extends Throwable> getRelinkException() {
            return null;
        }

        /**
         * Is this link logic class empty - i.e. no special linking logic
         * supplied
         *
         * @param clazz class to check
         *
         * @return true if this link logic is empty
         */
        public static boolean isEmpty(final Class<? extends LinkLogic> clazz) {
            return clazz == Empty.class;
        }

        /**
         * Is this link logic instance empty - i.e. no special linking logic
         * supplied
         *
         * @return true if this link logic instance is empty
         */
        public boolean isEmpty() {
            return false;
        }

        /**
         * Given a callsite, can we link this method based on the receiver and
         * parameters?
         *
         * @param self    receiver
         * @param desc    callsite descriptor
         * @param request link request
         *
         * @return true if we can link this callsite at this time
         */
        public abstract boolean canLink(final Object self, final CallSiteDescriptor desc, final LinkRequest request);

        /**
         * Given a callsite, do we require an extra guard for specialization to
         * go through?
         *
         * @param self receiver
         *
         * @return true if a guard is to be woven into the callsite
         */
        public boolean needsGuard(final Object self) {
            return true;
        }

        /**
         * Given a callsite, and optional arguments, do we need an extra guard
         * for specialization to go through - this guard can be a function of
         * the arguments too
         *
         * @param self receiver
         * @param args arguments
         *
         * @return true if a guard is to be woven into the callsite
         */
        public boolean needsGuard(final Object self, final Object... args) {
            return true;
        }

        /**
         * Given a callsite, and optional arguments, return any extra guard we
         * might need for specialization as a method handle.
         *
         * @return methodhandle for guard, or null if no guard is needed
         */
        public MethodHandle getGuard() {
            return null;
        }

        /**
         * Return the modification SwitchPoint of a particular index from this OptimisticBuiltins
         * If none exists, one is created and that one is return.
         *
         * The implementor must map indexes to specific SwitchPoints for specific events and keep
         * track of what they mean, for example NativeArray.LENGTH_NOT_WRITABLE_SWITCHPOINT
         * might be a useful index mapping
         *
         * @param index index for SwitchPoint to get or create
         * @return modification SwitchPoint of particular index for the receiver
         */
        public SwitchPoint getOrCreateModificationSwitchPoint(final int index) {
            return null;
        }

        /**
         * Return the modification SwitchPoint from this OptimisticBuiltins. If none
         * exists, one is created and that one is return.
         *
         * @return modification SwitchPoint for the receiver
         */
        public SwitchPoint[] getOrCreateModificationSwitchPoints() {
            return null;
        }

        /**
         * Hook to invalidate a modification SwitchPoint by index.
         *
         * @param index index for SwitchPoint to invalidate
         */
        public void invalidateModificationSwitchPoint(final int index) {
            //empty
        }

        /**
         * Hook to invalidate all modification SwitchPoints for a receiver
         */
        public void invalidateModificationSwitchPoints() {
            //empty
        }

        /**
         * Check whether the receiver has an invalidated modification SwitchPoint.
         *
         * @param  index index for the modification SwitchPoint
         * @return true if the particular SwitchPoint at the index is invalidated
         */
        public boolean hasInvalidatedModificationSwitchPoint(final int index) {
            return false;
        }

        /**
         * Check whether at least one of the modification SwitchPoints has been
         * invalidated
         * @return true if one of the SwitchPoints has been invalidated
         */
        public boolean hasInvalidatedModificationSwitchPoints() {
            return false;
        }

        /**
         * Check whether this OptimisticBuiltins has a SwitchPoints of particular
         * index.
         *
         * As creation overhead for a SwitchPoint is non-zero, we have to create them lazily instead of,
         * e.g. in the constructor of every subclass.
         *
         * @param index index for the modification SwitchPoint
         * @return true if a modification SwitchPoint exists, no matter if it has been invalidated or not
         */
        public boolean hasModificationSwitchPoint(final int index) {
            return false;
        }

        /**
         * Check whether this OptimisticBuiltins has SwitchPoints.
         *
         * As creation overhead for a SwitchPoint is non-zero, we have to create them lazily instead of,
         * e.g. in the constructor of every subclass.
         *
         * @return true if a modification SwitchPoint exists, no matter if it has been invalidated or not
         */
        public boolean hasModificationSwitchPoints() {
            return false;
        }

        /**
         * Check, given a link request and a receiver, if this specialization
         * fits This is used by the linker in {@link ScriptFunction} to figure
         * out if an optimistic builtin can be linked when first discovered
         *
         * @param self receiver
         * @param desc callsite descriptor
         * @param request link request

         * @return true if we can link, false otherwise - that means we have to
         *         pick a non specialized target
         */
        public boolean checkLinkable(final Object self, final CallSiteDescriptor desc, final LinkRequest request) {
            // no matter what the modification switchpoints are, if any of them are invalidated,
            // we can't link. Side effect is that if it's the first time we see this callsite,
            // we have to create the SwitchPoint(s) so future modification switchpoint invalidations
            // relink it
            final SwitchPoint[] sps = getOrCreateModificationSwitchPoints(self);
            if (sps == INVALIDATED_SWITCHPOINTS) {
                // nope, can't do the fast link as this assumption
                // has been invalidated already, e.g. length of an
                // array set to not writable
                return false;
            }
            modificationSwitchPoints = sps; //cache

            // check the link guard, if it says we can link, go ahead
            return canLink(self, desc, request);
        }

        private SwitchPoint[] getOrCreateModificationSwitchPoints(final Object self) {
            final SwitchPoint[] sps = getOrCreateModificationSwitchPoints(); //ask for all my switchpoints
            if (sps != null) { //switchpoint exists, but some may be invalidated
                for (final SwitchPoint sp : sps) {
                    if (sp.hasBeenInvalidated()) {
                        return INVALIDATED_SWITCHPOINTS;
                    }
                }
            }
            return sps;
        }

        /**
         * Get the cached modification switchpoints. Only possible to do after a link
         * check call has been performed, one that has answered "true", or you will get the
         * wrong information.
         *
         * Should be used only from {@link ScriptFunction#findCallMethod}
         *
         * @return cached modification switchpoints for this callsite, null if none
         */
        public SwitchPoint[] getModificationSwitchPoints() {
            return modificationSwitchPoints == null ? null : modificationSwitchPoints.clone();
        }
    }

    /**
     * name override for return value polymorphism, for example we can't have
     * pop(V)I and pop(V)D in the same Java class, so they need to be named,
     * e.g. popInt(V)I and popDouble(V)D for disambiguation, however, their
     * names still need to resolve to "pop" to JavaScript so we can still
     * specialize on return values and so that the linker can find them
     *
     * @return name, "" means no override, use the Java function name, e.g.
     *         "push"
     */
    String name() default "";

    /**
     * Return the guard for this specialized function. The default is no guard.
     *
     * @return guard
     */
    Class<?> linkLogic() default LinkLogic.Empty.class;

    /**
     * Is this a specialized constructor?
     */
    boolean isConstructor() default false;

    /**
     * Can this function throw UnwarrantedOptimismExceptions? This works just
     * like the normal functions, but we need the function to be
     * immutable/non-state modifying, as we can't generate continuations for
     * native code. Luckily a lot of the methods we want to specialize have this
     * property
     */
    boolean isOptimistic() default false;
}