org.jruby.runtime

Class Frame

java.lang.Object

org.jruby.runtime.Frame

public final class Frame
extends java.lang.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:

ThreadContext

Field Summary

Fields

Modifier and Type	Field and Description
private IRubyObject	backRef backref
private Block	block The block that was passed in for this frame (as either a block or a &block argument).
private boolean	captured whether this frame has been captured into a binding
private int	jumpTarget The target for non-local jumps, like return from a block
private RubyModule	klazz The class against which this call is executing.
private IRubyObject	lastLine lastline
private java.lang.String	name The name of the method being invoked in this frame.
private IRubyObject	self The 'self' for this frame.
private Visibility	visibility The current visibility for anything defined under this frame

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
Frame	capture()
Frame	clear() Clear the frame, as when the call completes.
Frame	duplicate() Clone this frame.
Frame	duplicateForBacktrace() Clone this frame for use in backtraces only (avoiding long-lived references to other elements.
IRubyObject	getBackRef(IRubyObject nil)
Block	getBlock() Retrieve the block associated with this frame.
int	getJumpTarget() Get the jump target for non-local returns in this frame.
RubyModule	getKlazz() Return class that we are calling against
IRubyObject	getLastLine(IRubyObject nil)
java.lang.String	getName() Get the method name associated with this frame
IRubyObject	getSelf() Get the self associated with this frame
Visibility	getVisibility() Get the visibility at the time of this frame
boolean	isCaptured()
IRubyObject	setBackRef(IRubyObject backRef)
void	setCaptured(boolean captured)
void	setKlazz(RubyModule klazz) Set the class we are calling against.
IRubyObject	setLastLine(IRubyObject lastLine)
void	setName(java.lang.String name) Set the method name associated with this frame
void	setSelf(IRubyObject self) Set the self associated with this frame
void	setVisibility(Visibility visibility) Change the visibility associated with this frame
java.lang.String	toString()
void	updateFrame() Update the frame with just filename and line, used for top-level frames and method.
void	updateFrame(Frame frame) Update the frame based on information from another frame.
void	updateFrame(RubyModule klazz, IRubyObject self, java.lang.String name, Block block, int jumpTarget) Update the frame based on the given values.
void	updateFrame(java.lang.String name) Update the frame with caller information and method name, so it will show up correctly in call stacks.
void	updateFrameForEval(IRubyObject self, int jumpTarget) Update the frame based on the given values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

klazz

private RubyModule klazz

The class against which this call is executing.

self

private IRubyObject self

The 'self' for this frame.

name

private java.lang.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

jumpTarget

private int jumpTarget

The target for non-local jumps, like return from a block

backRef

private IRubyObject backRef

backref

lastLine

private IRubyObject lastLine

lastline

captured

private boolean captured

whether this frame has been captured into a binding

Constructor Detail

Frame

public Frame()

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

Frame

private Frame(Frame frame)

Copy constructor, since Frame objects are pre-allocated and updated when needed.

Method Detail

updateFrame

public void updateFrame()

Update the frame with just filename and line, used for top-level frames and method.

Parameters:

fileName - The file where the calling method is located

line - The line number in the calling method where the call is made

updateFrame

public void updateFrame(java.lang.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

fileName - The file of the calling method

line - The line number of the call to this method

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,
                        java.lang.String name,
                        Block block,
                        int jumpTarget)

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

fileName - The filename of the calling method

line - The line number where the call is being made

jumpTarget - The target for non-local jumps (return in block)

updateFrameForEval

public void updateFrameForEval(IRubyObject self,
                               int jumpTarget)

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

fileName - The filename of the calling method

line - The line number where the call is being made

jumpTarget - The target for non-local jumps (return in block)

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

getJumpTarget

public int getJumpTarget()

Get the jump target for non-local returns in this frame.

Returns:

The jump target for non-local returns

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(java.lang.String name)

Set the method name associated with this frame

Parameters:

name - the new name

getName

public java.lang.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 java.lang.String toString()

Overrides:

toString in class java.lang.Object