Package org.jruby.runtime

Class Frame

java.lang.Object
org.jruby.runtime.Frame
public final class Frame extends Object
A Frame holds per-call information that needs to persist outside the execution of a given method. Currently a frame holds the following:
  • The class against which this method is being invoked. This is usually (always?) the class of "self" within this call.
  • The current "self" for the call.
  • The name of the method being invoked during this frame, used for backtraces and "super" invocations.
  • The block passed to this invocation. If the given code body can't accept a block, it will be Block.NULL_BLOCK.
  • Whether this is the frame used for a binding-related call like eval. This is used to determine where to terminate evaled code's backtrace.
  • The current visibility for methods defined during this call. Starts out as PUBLIC by default (in most cases) and can be modified by appropriate Kernel.public/private/protected calls.
  • The jump target marker for non-local returns.
Frames are allocated for all Ruby methods (in compatibility mode, default) and for some core methods. In general, a frame is required for a method to show up in a backtrace, and so some methods only use frame for backtrace information (so-called "backtrace frames").
See Also:

  • Field Details

    • klazz

      private RubyModule klazz
      The class against which this call is executing.

    • self

      private IRubyObject self
      The 'self' for this frame.

    • name

      private String name
      The name of the method being invoked in this frame.

    • block

      private Block block
      The block that was passed in for this frame (as either a block or a &block argument). The frame captures the block for super/zsuper, but also for Proc.new (with no arguments) and also for block_given?. Both of those methods needs access to the block of the previous frame to work.

    • visibility

      private Visibility visibility
      The current visibility for anything defined under this frame

    • backRef

      private IRubyObject backRef
      backref

    • lastLine

      private IRubyObject lastLine
      lastline

    • captured

      boolean captured
      whether this frame has been captured into a binding

    • DUMMY

      @Deprecated public static final Frame DUMMY
      Deprecated.

  • Constructor Details

    • Frame

      public Frame()
      Empty constructor, since Frame objects are pre-allocated and updated when needed.

    • Frame

      private Frame(Block nullBlock)
      Used only by static init to avoid accessing NULL_BLOCK before initialized.
      Parameters:
      nullBlock -

    • Frame

      private Frame(Frame frame)
      Copy constructor, since Frame objects are pre-allocated and updated when needed.

  • Method Details

    • updateFrame

      public void updateFrame()
      Update the frame with just filename and line, used for top-level frames and method.

    • updateFrame

      public void updateFrame(String name)
      Update the frame with caller information and method name, so it will show up correctly in call stacks.
      Parameters:
      name - The name of the method being called

    • updateFrame

      public void updateFrame(Frame frame)
      Update the frame based on information from another frame. Used for cloning frames (for blocks, usually) and when entering class bodies.
      Parameters:
      frame - The frame whose data to duplicate in this frame

    • updateFrame

      public void updateFrame(RubyModule klazz, IRubyObject self, String name, Block block)
      Update the frame based on the given values.
      Parameters:
      klazz - The class against which the method is being called
      self - The 'self' for the method
      name - The name under which the method is being invoked
      block - The block passed to the method

    • updateFrame

      public void updateFrame(RubyModule klazz, IRubyObject self, String name, Visibility visibility, Block block)
      Update the frame based on the given values.
      Parameters:
      klazz - The class against which the method is being called
      self - The 'self' for the method
      name - The name under which the method is being invoked
      block - The block passed to the method

    • updateFrameForEval

      public void updateFrameForEval(IRubyObject self)
      Update the frame based on the given values.
      Parameters:
      self - The 'self' for the method

    • updateFrameForBackref

      public void updateFrameForBackref()

    • clearFrameForBackref

      public void clearFrameForBackref()

    • clear

      public Frame clear()
      Clear the frame, as when the call completes. Clearing prevents cached frames from holding references after the call is done.

    • duplicate

      public Frame duplicate()
      Clone this frame.
      Returns:
      A new frame with duplicate information to the target frame

    • duplicateForBacktrace

      public Frame duplicateForBacktrace()
      Clone this frame for use in backtraces only (avoiding long-lived references to other elements.
      Returns:
      A new frame with identical backtrace information to this frame

    • getKlazz

      public RubyModule getKlazz()
      Return class that we are calling against
      Returns:
      The class we are calling against

    • setKlazz

      public void setKlazz(RubyModule klazz)
      Set the class we are calling against.
      Parameters:
      klazz - the new class

    • setName

      public void setName(String name)
      Set the method name associated with this frame
      Parameters:
      name - the new name

    • getName

      public String getName()
      Get the method name associated with this frame
      Returns:
      the method name

    • getSelf

      public IRubyObject getSelf()
      Get the self associated with this frame
      Returns:
      The self for the frame

    • setSelf

      public void setSelf(IRubyObject self)
      Set the self associated with this frame
      Parameters:
      self - The new value of self

    • getVisibility

      public Visibility getVisibility()
      Get the visibility at the time of this frame
      Returns:
      The visibility

    • setVisibility

      public void setVisibility(Visibility visibility)
      Change the visibility associated with this frame
      Parameters:
      visibility - The new visibility

    • getBlock

      public Block getBlock()
      Retrieve the block associated with this frame.
      Returns:
      The block of this frame or NULL_BLOCK if no block given

    • getBackRef

      public IRubyObject getBackRef(IRubyObject nil)

    • setBackRef

      public IRubyObject setBackRef(IRubyObject backRef)

    • getLastLine

      public IRubyObject getLastLine(IRubyObject nil)

    • setLastLine

      public IRubyObject setLastLine(IRubyObject lastLine)

    • setCaptured

      public void setCaptured(boolean captured)

    • capture

      public Frame capture()

    • isCaptured

      public boolean isCaptured()

    • toString

      public String toString()
      Overrides:
      toString in class Object