/*
 * Copyright (c) 2015, 2017, 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 com.oracle.svm.core.deopt;

import com.oracle.svm.core.code.CodeInfo;
import com.oracle.svm.core.code.CodeInfoAccess;
import com.oracle.svm.core.code.RuntimeCodeCache;

import jdk.vm.ci.code.InstalledCode;
import jdk.vm.ci.meta.ResolvedJavaMethod;

Interface for objects representing runtime-compiled code that can be installed in the runtime code cache. This interface is intentionally compatible with the class InstalledCode, but can be implemented in an existing class hierarchy. Code also has native structures associated with it, see CodeInfo and CodeInfoAccess. 
 Assume that methods such as isValid, isAlive or getEntryPoint return stale values because generally, their internal state can change at any safepoint. Consistent reads of such values require ensuring the absence of safepoint checks and preventing floating reads and read elimination. /**
 * Interface for objects representing runtime-compiled code that can be installed in the
 * {@linkplain RuntimeCodeCache runtime code cache}. This interface is intentionally compatible with
 * the class {@link InstalledCode}, but can be implemented in an existing class hierarchy. Code also
 * has native structures associated with it, see {@link CodeInfo} and {@link CodeInfoAccess}.
 * <p>
 * Assume that methods such as {@link #isValid}, {@link #isAlive} or {@link #getEntryPoint} return
 * stale values because generally, their internal state can change at any safepoint. Consistent
 * reads of such values require ensuring the absence of safepoint checks and preventing floating
 * reads and read elimination.
 */
public interface SubstrateInstalledCode {

    String getName();

    
The entry point address of this code if valid, or 0 otherwise. /** The entry point address of this code if {@linkplain #isValid valid}, or 0 otherwise. */
    long getEntryPoint();

    
The address of this code if alive, or 0 otherwise. /** The address of this code if {@linkplain #isAlive alive}, or 0 otherwise. */
    long getAddress();

    
Returns the last method object passed to setAddress. The return value might be passed as the argument to future calls to setAddress. 
 May return null if the subclass does not have a use for the method object (also not in setAddress) and therefore no need to retain it. Expected to return null if setAddress has never been called, or after clearAddress has been called. /**
     * Returns the last method object passed to {@link #setAddress}. The return value might be
     * passed as the argument to future calls to {@link #setAddress}.
     * <p>
     * May return {@code null} if the subclass does not have a use for the method object (also not
     * in {@link #setAddress}) and therefore no need to retain it. Expected to return {@code null}
     * if {@link #setAddress} has never been called, or after {@link #clearAddress} has been called.
     */
    ResolvedJavaMethod getMethod();

    
Called during code installation: initialize this instance with the given address where its instructions are, and the method it was compiled from. Afterwards, getAddress() and getEntryPoint() return the given address, and isValid() and isAlive() return true. /**
     * Called during code installation: initialize this instance with the given address where its
     * instructions are, and the method it was compiled from. Afterwards, {@link #getAddress()} and
     * {@link #getEntryPoint()} return the given address, and {@link #isValid()} and
     * {@link #isAlive()} return {@code true}.
     */
    void setAddress(long address, ResolvedJavaMethod method);

    
This method is called during code uninstallation. Consider invalidate() instead. 
 Reset this instance so that getAddress() and getEntryPoint() return 0, and isValid() and isAlive() return false. /**
     * This method is called during code uninstallation. Consider {@link #invalidate()} instead.
     * <p>
     * Reset this instance so that {@link #getAddress()} and {@link #getEntryPoint()} return 0, and
     * {@link #isValid()} and {@link #isAlive()} return {@code false}.
     */
    void clearAddress();

    
Whether the code represented by this object exists and can be invoked. /** Whether the code represented by this object exists and can be invoked. */
    boolean isValid();

    
Invalidates this installed code and deoptimizes all live invocations, after which both isValid and isAlive return false. /**
     * Invalidates this installed code and deoptimizes all live invocations, after which both
     * {@link #isValid} and {@link #isAlive} return {@code false}.
     */
    void invalidate();

    
Whether the code represented by this object exists and could have live invocations. /** Whether the code represented by this object exists and could have live invocations. */
    boolean isAlive();

    
Make this code non-entrant, but let live invocations continue execution. Afterwards, isValid() returns false, isAlive() returns true, and getEntryPoint() returns 0. /**
     * Make this code non-entrant, but let live invocations continue execution. Afterwards,
     * {@link #isValid()} returns {@code false}, {@link #isAlive()} returns {@code true}, and
     * {@link #getEntryPoint()} returns 0.
     */
    void invalidateWithoutDeoptimization();

    SubstrateSpeculationLog getSpeculationLog();

    
Provides access to a SubstrateInstalledCode. Introduced when OptimizedCallTarget was changed to no longer extend InstalledCode. /**
     * Provides access to a {@link SubstrateInstalledCode}.
     *
     * Introduced when {@code OptimizedCallTarget} was changed to no longer extend
     * {@link InstalledCode}.
     */
    interface Factory {
        SubstrateInstalledCode createSubstrateInstalledCode();
    }
}