Frame.java

  1. /***** BEGIN LICENSE BLOCK *****
  2.  * Version: EPL 1.0/GPL 2.0/LGPL 2.1
  3.  *
  4.  * The contents of this file are subject to the Eclipse Public
  5.  * License Version 1.0 (the "License"); you may not use this file
  6.  * except in compliance with the License. You may obtain a copy of
  7.  * the License at http://www.eclipse.org/legal/epl-v10.html
  8.  *
  9.  * Software distributed under the License is distributed on an "AS
  10.  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  11.  * implied. See the License for the specific language governing
  12.  * rights and limitations under the License.
  13.  *
  14.  * Copyright (C) 2001-2004 Jan Arne Petersen <jpetersen@uni-bonn.de>
  15.  * Copyright (C) 2002 Benoit Cerrina <b.cerrina@wanadoo.fr>
  16.  * Copyright (C) 2002-2004 Anders Bengtsson <ndrsbngtssn@yahoo.se>
  17.  * Copyright (C) 2004-2007 Thomas E Enebo <enebo@acm.org>
  18.  * Copyright (C) 2006 Charles O Nutter <headius@headius.com>
  19.  * Copyright (C) 2006 Miguel Covarrubias <mlcovarrubias@gmail.com>
  20.  * 
  21.  * Alternatively, the contents of this file may be used under the terms of
  22.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  23.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  24.  * in which case the provisions of the GPL or the LGPL are applicable instead
  25.  * of those above. If you wish to allow use of your version of this file only
  26.  * under the terms of either the GPL or the LGPL, and not to allow others to
  27.  * use your version of this file under the terms of the EPL, indicate your
  28.  * decision by deleting the provisions above and replace them with the notice
  29.  * and other provisions required by the GPL or the LGPL. If you do not delete
  30.  * the provisions above, a recipient may use your version of this file under
  31.  * the terms of any one of the EPL, the GPL or the LGPL.
  32.  ***** END LICENSE BLOCK *****/
  33. package org.jruby.runtime;

  35. import org.jruby.RubyModule;
  36. import org.jruby.runtime.builtin.IRubyObject;

  38. /**
  39.  * A Frame holds per-call information that needs to persist outside the
  40.  * execution of a given method. Currently a frame holds the following:
  41.  * <ul>
  42.  * <li>The class against which this method is being invoked. This is usually
  43.  * (always?) the class of "self" within this call.</li>
  44.  * <li>The current "self" for the call.</li>
  45.  * <li>The name of the method being invoked during this frame, used for
  46.  * backtraces and "super" invocations.</li>
  47.  * <li>The block passed to this invocation. If the given code body can't
  48.  * accept a block, it will be Block.NULL_BLOCK.</li>
  49.  * <li>Whether this is the frame used for a binding-related call like eval. This
  50.  * is used to determine where to terminate evaled code's backtrace.</li>
  51.  * <li>The current visibility for methods defined during this call. Starts out
  52.  * as PUBLIC by default (in most cases) and can be modified by appropriate
  53.  * Kernel.public/private/protected calls.</li>
  54.  * <li>The jump target marker for non-local returns.</li>
  55.  * </ul>
  56.  * Frames are allocated for all Ruby methods (in compatibility mode, default)
  57.  * and for some core methods. In general, a frame is required for a method to
  58.  * show up in a backtrace, and so some methods only use frame for backtrace
  59.  * information (so-called "backtrace frames").
  60.  * 
  61.  * @see ThreadContext
  62.  */
  63. public final class Frame {
  64.     /** The class against which this call is executing. */
  65.     private RubyModule klazz;
  66.     
  67.     /** The 'self' for this frame. */
  68.     private IRubyObject self;
  69.     
  70.     /** The name of the method being invoked in this frame. */
  71.     private String name;

  73.     /**
  74.      * The block that was passed in for this frame (as either a block or a &amp;block argument).
  75.      * The frame captures the block for super/zsuper, but also for Proc.new (with no arguments)
  76.      * and also for block_given?.  Both of those methods needs access to the block of the 
  77.      * previous frame to work.
  78.      */ 
  79.     private Block block = Block.NULL_BLOCK;

  81.     /** The current visibility for anything defined under this frame */
  82.     private Visibility visibility = Visibility.PUBLIC;
  83.     
  84.     /** backref **/
  85.     private IRubyObject backRef;
  86.     
  87.     /** lastline **/
  88.     private IRubyObject lastLine;
  89.     
  90.     /** whether this frame has been captured into a binding **/
  91.     private boolean captured;
  92.     
  93.     /**
  94.      * Empty constructor, since Frame objects are pre-allocated and updated
  95.      * when needed.
  96.      */
  97.     public Frame() {
  98.     }
  99.     
  100.     /**
  101.      * Copy constructor, since Frame objects are pre-allocated and updated
  102.      * when needed.
  103.      */
  104.     private Frame(Frame frame) {
  105.         assert frame.block != null : "Block uses null object pattern.  It should NEVER be null";

  107.         this.self = frame.self;
  108.         this.name = frame.name;
  109.         this.klazz = frame.klazz;
  110.         this.block = frame.block;
  111.         this.visibility = frame.visibility;
  112.     }

  114.     /**
  115.      * Update the frame with just filename and line, used for top-level frames
  116.      * and method.
  117.      */
  118.     public void updateFrame() {
  119.         updateFrame(null, null, null, Block.NULL_BLOCK, 0);
  120.     }

  122.     /**
  123.      * Update the frame with caller information and method name, so it will
  124.      * show up correctly in call stacks.
  125.      * 
  126.      * @param name The name of the method being called
  127.      */
  128.     public void updateFrame(String name) {
  129.         this.name = name;
  130.     }

  132.     /**
  133.      * Update the frame based on information from another frame. Used for
  134.      * cloning frames (for blocks, usually) and when entering class bodies.
  135.      * 
  136.      * @param frame The frame whose data to duplicate in this frame
  137.      */
  138.     public void updateFrame(Frame frame) {
  139.         assert frame.block != null : "Block uses null object pattern.  It should NEVER be null";

  141.         this.self = frame.self;
  142.         this.name = frame.name;
  143.         this.klazz = frame.klazz;
  144.         this.block = frame.block;
  145.         this.visibility = frame.visibility;
  146.     }

  148.     /**
  149.      * Update the frame based on the given values.
  150.      * 
  151.      * @param klazz The class against which the method is being called
  152.      * @param self The 'self' for the method
  153.      * @param name The name under which the method is being invoked
  154.      * @param block The block passed to the method
  155.      * @param jumpTarget The target for non-local jumps (return in block)
  156.      */
  157.     public void updateFrame(RubyModule klazz, IRubyObject self, String name,
  158.                  Block block, int jumpTarget) {
  159.         assert block != null : "Block uses null object pattern.  It should NEVER be null";

  161.         this.self = self;
  162.         this.name = name;
  163.         this.klazz = klazz;
  164.         this.block = block;
  165.         this.visibility = Visibility.PUBLIC;
  166.     }

  168.     /**
  169.      * Update the frame based on the given values.
  170.      * 
  171.      * @param self The 'self' for the method
  172.      * @param jumpTarget The target for non-local jumps (return in block)
  173.      */
  174.     public void updateFrameForEval(IRubyObject self, int jumpTarget) {
  175.         this.self = self;
  176.         this.name = null;
  177.         this.visibility = Visibility.PRIVATE;
  178.     }

  180.     /**
  181.      * Clear the frame, as when the call completes. Clearing prevents cached
  182.      * frames from holding references after the call is done.
  183.      */
  184.     public Frame clear() {
  185.         this.self = null;
  186.         this.klazz = null;
  187.         this.block = Block.NULL_BLOCK;
  188.         this.backRef = null;
  189.         this.lastLine = null;
  190.         
  191.         return this;
  192.     }
  193.     
  194.     /**
  195.      * Clone this frame.
  196.      * 
  197.      * @return A new frame with duplicate information to the target frame
  198.      */
  199.     public Frame duplicate() {
  200.         return new Frame(this);
  201.     }

  203.     /**
  204.      * Clone this frame for use in backtraces only (avoiding long-lived
  205.      * references to other elements.
  206.      *
  207.      * @return A new frame with identical backtrace information to this frame
  208.      */
  209.     public Frame duplicateForBacktrace() {
  210.         Frame backtraceFrame = new Frame();
  211.         backtraceFrame.name = name;
  212.         return backtraceFrame;
  213.     }

  215.     /** 
  216.      * Return class that we are calling against
  217.      * 
  218.      * @return The class we are calling against
  219.      */
  220.     public RubyModule getKlazz() {
  221.         return klazz;
  222.     }

  224.     /**
  225.      * Set the class we are calling against.
  226.      * 
  227.      * @param klazz the new class
  228.      */
  229.     public void setKlazz(RubyModule klazz) {
  230.         this.klazz = klazz;
  231.     }

  233.     /**
  234.      * Set the method name associated with this frame
  235.      * 
  236.      * @param name the new name
  237.      */
  238.     public void setName(String name) {
  239.         this.name = name;
  240.     }

  242.     /** 
  243.      * Get the method name associated with this frame
  244.      * 
  245.      * @return the method name
  246.      */
  247.     public String getName() {
  248.         return name;
  249.     }

  251.     /**
  252.      * Get the self associated with this frame
  253.      * 
  254.      * @return The self for the frame
  255.      */
  256.     public IRubyObject getSelf() {
  257.         return self;
  258.     }

  260.     /** 
  261.      * Set the self associated with this frame
  262.      * 
  263.      * @param self The new value of self
  264.      */
  265.     public void setSelf(IRubyObject self) {
  266.         this.self = self;
  267.     }
  268.     
  269.     /**
  270.      * Get the visibility at the time of this frame
  271.      * 
  272.      * @return The visibility
  273.      */
  274.     public Visibility getVisibility() {
  275.         return visibility;
  276.     }
  277.     
  278.     /**
  279.      * Change the visibility associated with this frame
  280.      * 
  281.      * @param visibility The new visibility
  282.      */
  283.     public void setVisibility(Visibility visibility) {
  284.         this.visibility = visibility;
  285.     }
  286.     
  287.     /**
  288.      * Retrieve the block associated with this frame.
  289.      * 
  290.      * @return The block of this frame or NULL_BLOCK if no block given
  291.      */
  292.     public Block getBlock() {
  293.         return block;
  294.     }
  295.     
  296.     public IRubyObject getBackRef(IRubyObject nil) {
  297.         IRubyObject backRef = this.backRef;
  298.         return backRef == null ? nil : backRef;
  299.     }
  300.     
  301.     public IRubyObject setBackRef(IRubyObject backRef) {
  302.         return this.backRef = backRef;
  303.     }
  304.     
  305.     public IRubyObject getLastLine(IRubyObject nil) {
  306.         IRubyObject lastLine = this.lastLine;
  307.         return lastLine == null ? nil : lastLine;
  308.     }
  309.     
  310.     public IRubyObject setLastLine(IRubyObject lastLine) {
  311.         return this.lastLine = lastLine;
  312.     }
  313.     
  314.     public void setCaptured(boolean captured) {
  315.         this.captured = captured;
  316.     }
  317.     
  318.     public Frame capture() {
  319.         captured = true;
  320.         return this;
  321.     }
  322.     
  323.     public boolean isCaptured() {
  324.         return captured;
  325.     }

  327.     /* (non-Javadoc)
  328.      * @see java.lang.Object#toString()
  329.      */
  330.     @Override
  331.     public String toString() {
  332.         StringBuilder sb = new StringBuilder(50);
  333.         
  334.         sb.append(klazz);
  335.         if (name != null) sb.append(" in ").append(name);

  337.         return sb.toString();
  338.     }
  339. }
Created with JaCoCo 0.7.3.201501050207