/*
 * 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.runtime;

import java.lang.invoke.MethodHandle;
import jdk.nashorn.internal.objects.annotations.SpecializedFunction;
import jdk.nashorn.internal.objects.annotations.SpecializedFunction.LinkLogic;

Specialization info for a SpecializedFunction /**
 * Specialization info for a {@link SpecializedFunction}
 */
public final class Specialization {
    private final MethodHandle mh;
    private final Class<? extends LinkLogic> linkLogicClass;
    private final boolean isOptimistic;
    private final boolean convertsNumericArgs;

    
Constructor
Params:
mh –  invoker method handler/**
     * Constructor
     *
     * @param mh  invoker method handler
     */
    public Specialization(final MethodHandle mh) {
        this(mh, false, true);
    }

    
Constructor
Params:
mh –  invoker method handler
isOptimistic – is this an optimistic native method, i.e. can it throw UnwarrantedOptimismException which would have to lead to a relink and return value processing
convertsNumericArgs – true if it is safe to convert arguments to numbers/**
     * Constructor
     *
     * @param mh  invoker method handler
     * @param isOptimistic is this an optimistic native method, i.e. can it throw {@link UnwarrantedOptimismException}
     *   which would have to lead to a relink and return value processing
     * @param convertsNumericArgs true if it is safe to convert arguments to numbers
     */
    public Specialization(final MethodHandle mh, final boolean isOptimistic, final boolean convertsNumericArgs) {
        this(mh, null, isOptimistic, convertsNumericArgs);
    }

    
Constructor
Params:
mh –  invoker method handler
linkLogicClass – extra link logic needed for this function. Instances of this class also contains logic for checking
 if this can be linked on its first encounter, which is needed as per our standard linker semantics
isOptimistic – is this an optimistic native method, i.e. can it throw UnwarrantedOptimismException which would have to lead to a relink and return value processing
convertsNumericArgs – true if it is safe to convert arguments to numbers/**
     * Constructor
     *
     * @param mh  invoker method handler
     * @param linkLogicClass extra link logic needed for this function. Instances of this class also contains logic for checking
     *  if this can be linked on its first encounter, which is needed as per our standard linker semantics
     * @param isOptimistic is this an optimistic native method, i.e. can it throw {@link UnwarrantedOptimismException}
     *   which would have to lead to a relink and return value processing
     * @param convertsNumericArgs true if it is safe to convert arguments to numbers
     */
    public Specialization(final MethodHandle mh, final Class<? extends LinkLogic> linkLogicClass,
                          final boolean isOptimistic, final boolean convertsNumericArgs) {
        this.mh             = mh;
        this.isOptimistic   = isOptimistic;
        this.convertsNumericArgs = convertsNumericArgs;
        if (linkLogicClass != null) {
            //null out the "empty" link logic class for optimization purposes
            //we only use the empty instance because we can't default class annotations
            //to null
            this.linkLogicClass = LinkLogic.isEmpty(linkLogicClass) ? null : linkLogicClass;
        } else {
            this.linkLogicClass = null;
        }
     }

    
Get the method handle for the invoker of this ScriptFunction
Returns:
the method handle/**
     * Get the method handle for the invoker of this ScriptFunction
     * @return the method handle
     */
    public MethodHandle getMethodHandle() {
        return mh;
    }

    
Get the link logic class for this ScriptFunction
Returns:
link logic class info, i.e. one whose instance contains stuff like
 "do we need exception check for every call", and logic to check if we may link/**
     * Get the link logic class for this ScriptFunction
     * @return link logic class info, i.e. one whose instance contains stuff like
     *  "do we need exception check for every call", and logic to check if we may link
     */
    public Class<? extends LinkLogic> getLinkLogicClass() {
        return linkLogicClass;
    }

    
An optimistic specialization is one that can throw UnwarrantedOptimismException.
This is allowed for native methods, as long as they are functional, i.e. don't change
any state between entering and throwing the UOE. Then we can re-execute a wider version
of the method in the continuation. Rest-of method generation for optimistic builtins is
of course not possible, but this approach works and fits into the same relinking
framework
Returns:
true if optimistic/**
     * An optimistic specialization is one that can throw UnwarrantedOptimismException.
     * This is allowed for native methods, as long as they are functional, i.e. don't change
     * any state between entering and throwing the UOE. Then we can re-execute a wider version
     * of the method in the continuation. Rest-of method generation for optimistic builtins is
     * of course not possible, but this approach works and fits into the same relinking
     * framework
     *
     * @return true if optimistic
     */
    public boolean isOptimistic() {
        return isOptimistic;
    }

    
Check if this function converts arguments for numeric parameters to numbers
so it's safe to pass booleans as 0 and 1
Returns:
true if it is safe to convert arguments to numbers/**
     * Check if this function converts arguments for numeric parameters to numbers
     * so it's safe to pass booleans as 0 and 1
     *
     * @return true if it is safe to convert arguments to numbers
     */
    public boolean convertsNumericArgs() {
        return convertsNumericArgs;
    }

}