1 /*
   2  * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.nashorn.internal.codegen.types;
  27 
  28 import jdk.internal.org.objectweb.asm.MethodVisitor;
  29 
  30 
  31 /**
  32  * Interface for byte code generation for all runtime types. Each
  33  * type implements this interface and provides the type specific
  34  * operations to do the generic things described herein.
  35  *
  36  * The bytecode ops are coupled to a MethodVisitor from ASM for
  37  * byte code generation. They know nothing about our MethodGenerator,
  38  * which is the abstraction for working with Nashorn JS types
  39  * For example, anything like "two or one slots" for a type, which
  40  * is represented in bytecode and ASM, is abstracted away in the
  41  * MethodGenerator. There you just say "dup" or "store".
  42  *
  43  * @see Type
  44  * @see MethodVisitor
  45  */
  46 interface BytecodeOps {
  47 
  48     /**
  49      * Duplicate top entry of stack. If a too large depth is
  50      * given, so that there are no possible bytecode instructions
  51      * available to generate the dup sequence, null is returned.
  52      *
  53      * @param method  method visitor
  54      * @param depth   how far should the copy be pushed down
  55      *
  56      * @return        the type at the top of the stack or null
  57      */
  58     Type dup(MethodVisitor method, int depth);
  59 
  60     /**
  61      * Pop an entry of this type from the top of the bytecode
  62      * stack. This works regardless of what category this type
  63      * is
  64      *
  65      * @param method  method visitor
  66      *
  67      * @return the popped type
  68      */
  69     Type pop(MethodVisitor method);
  70 
  71     /**
  72      * Swap this type with the bytecode stack with the one below
  73      * Generate appropriate code no matter the categories of the
  74      * two types
  75      *
  76      * @param method  method visitor
  77      * @param other   the type below this one on the stack
  78      *
  79      * @return        the other type
  80      */
  81     Type swap(MethodVisitor method, Type other);
  82 
  83     /**
  84      * Pop two values on top of the stack and add the
  85      * first to the second, pushing the result on the stack
  86      *
  87      * @param method  method visitor
  88      * @param programPoint program point id
  89      * @return result type
  90      */
  91     Type add(MethodVisitor method, int programPoint);
  92 
  93     /**
  94      * Load a variable from a local slot to the stack
  95      *
  96      * @param method method visitor
  97      * @param slot   the slot to load
  98      *
  99      * @return       the type that was loaded
 100      */
 101     Type load(MethodVisitor method, int slot);
 102 
 103     /**
 104      * Store a variable from the stack to a local slot
 105      *
 106      * @param method  method visitor
 107      * @param slot    the slot to store to
 108      */
 109     void store(MethodVisitor method, int slot);
 110 
 111     /**
 112      * Load a constant to the stack.
 113      *
 114      * @param method  method visitor
 115      * @param c       the value of the constant
 116      *
 117      * @return        the type at the top of the stack after load
 118      */
 119     Type ldc(MethodVisitor method, Object c);
 120 
 121     /**
 122      * Load the "undefined" value to the stack. Note that
 123      * there may be different representations of this for
 124      * e.g. doubles and objects. Abstraction removes this
 125      *
 126      * @param  method  method visitor.
 127      *
 128      * @return the undefined type at the top of the stack
 129      */
 130     Type loadUndefined(MethodVisitor method);
 131 
 132     /**
 133      * Load the "forced initializer" value to the stack, used to ensure that a local variable has a value when it is
 134      * read by the unwarranted optimism catch block.
 135      *
 136      * @param  method  method visitor.
 137      *
 138      * @return the forced initialization type at the top of the stack
 139      */
 140     Type loadForcedInitializer(MethodVisitor method);
 141 
 142 
 143     /**
 144      * Load the "empty" value to the stack.
 145      *
 146      * @param  method  method visitor.
 147      * @return the undefined type at the top of the stack
 148      */
 149     Type loadEmpty(MethodVisitor method);
 150 
 151     /**
 152      * Generate code that pops and casts the element on top of the
 153      * stack to another type, given as parameter
 154      *
 155      * @param method  method visitor
 156      * @param to      the type to cast to
 157      *
 158      * @return the to type
 159      */
 160     Type convert(MethodVisitor method, Type to);
 161 
 162     /**
 163      * Return the parameter on top of the stack
 164      * from a method
 165      *
 166      * @param method the method visitor
 167      */
 168     void _return(MethodVisitor method);
 169 
 170 }