com.oracle.truffle.api.frame

Class FrameDescriptor

java.lang.Object

com.oracle.truffle.api.frame.FrameDescriptor

All Implemented Interfaces:

Cloneable

public final class FrameDescriptor
extends Object
implements Cloneable

Descriptor of the slots of frame objects. Multiple frame instances are associated with one such descriptor. The FrameDescriptor is thread-safe.

Since:

0.8 or earlier

Constructor Summary

Constructors

Constructor and Description
FrameDescriptor() Constructs empty descriptor.
FrameDescriptor(Object defaultValue) Constructs new descriptor with specified FrameDescriptor.getDefaultValue().

Method Summary

Modifier and Type	Method and Description
FrameSlot	addFrameSlot(Object identifier) Adds frame slot.
FrameSlot	addFrameSlot(Object identifier, FrameSlotKind kind) Adds frame slot.
FrameSlot	addFrameSlot(Object identifier, Object info, FrameSlotKind kind) Adds new frame slot to FrameDescriptor.getSlots() list.
FrameDescriptor	copy() Deeper copy of the descriptor.
FrameSlot	findFrameSlot(Object identifier) Finds an existing slot.
FrameSlot	findOrAddFrameSlot(Object identifier) Finds an existing slot or creates new one.
FrameSlot	findOrAddFrameSlot(Object identifier, FrameSlotKind kind) Finds an existing slot or creates new one.
FrameSlot	findOrAddFrameSlot(Object identifier, Object info, FrameSlotKind kind) Finds an existing slot or creates new one.
Object	getDefaultValue() Default value for the created slots.
FrameSlotKind	getFrameSlotKind(FrameSlot frameSlot) Kind of the provided slot.
Set<Object>	getIdentifiers() Retrieve the current set of all the identifiers associated with this frame descriptor.
Assumption	getNotInFrameAssumption(Object identifier) Make an assumption that no slot with the specified identifier is present in this frame descriptor.
int	getSize() Returns the size of an array which is needed for storing all the frame slots.
List<? extends FrameSlot>	getSlots() Retrieve the current list of slots in the descriptor.
Assumption	getVersion() Returns an assumption reflecting the frame's current version, which is updated every time a slot is added or removed, or an existing slot's kind is changed.
void	removeFrameSlot(Object identifier) Removes a slot.
void	setFrameSlotKind(FrameSlot frameSlot, FrameSlotKind kind) Changes the kind of the provided slot.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

FrameDescriptor

public FrameDescriptor()

Constructs empty descriptor. The FrameDescriptor.getDefaultValue() is null.

Since:

0.8 or earlier

FrameDescriptor

public FrameDescriptor(Object defaultValue)

Constructs new descriptor with specified FrameDescriptor.getDefaultValue().

Parameters:

defaultValue - to be returned from FrameDescriptor.getDefaultValue()

Since:

0.8 or earlier

Method Detail

addFrameSlot

public FrameSlot addFrameSlot(Object identifier)

Adds frame slot. Delegates to addFrameSlot (identifier, null, FrameSlotKind.Illegal). This is a slow operation that switches to interpreter mode. Note that even if it is checked that the FrameDescriptor does not have the slot for a given identifier before adding the slot for the given identifier it can still fail with an IllegalArgumentException since the FrameDescriptor can be modified concurrently. In such case consider using FrameDescriptor.findOrAddFrameSlot(Object) instead.

Parameters:

identifier - key for the slot - must not be null and needs proper Object.equals(java.lang.Object) and Object.hashCode() implementations

Returns:

the newly created slot

Throws:

IllegalArgumentException - if a frame slot with the same identifier exists

NullPointerException - if identifier is null

Since:

0.8 or earlier

addFrameSlot

public FrameSlot addFrameSlot(Object identifier,
                              FrameSlotKind kind)

Adds frame slot. Delegates to addFrameSlot (identifier, null, kind). This is a slow operation that switches to interpreter mode. Note that even if it is checked that the FrameDescriptor does not have the slot for a given identifier before adding the slot for the given identifier it can still fail with an IllegalArgumentException since the FrameDescriptor can be modified concurrently. In such case consider using FrameDescriptor.findOrAddFrameSlot(Object, FrameSlotKind) instead.

Parameters:

identifier - key for the slot - must not be null and needs proper Object.equals(java.lang.Object) and Object.hashCode() implementations

kind - the kind of the new slot

Returns:

the newly created slot

Throws:

IllegalArgumentException - if a frame slot with the same identifier exists

NullPointerException - if identifier or kind is null

Since:

0.8 or earlier

addFrameSlot

public FrameSlot addFrameSlot(Object identifier,
                              Object info,
                              FrameSlotKind kind)

Adds new frame slot to FrameDescriptor.getSlots() list. This is a slow operation that switches to interpreter mode. Note that even if it is checked that the FrameDescriptor does not have the slot for a given identifier before adding the slot for the given identifier it can still fail with an IllegalArgumentException since the FrameDescriptor can be modified concurrently. In such case consider using FrameDescriptor.findOrAddFrameSlot(Object, Object, FrameSlotKind) instead.

Parameters:

identifier - key for the slot - must not be null and needs proper Object.equals(java.lang.Object) and Object.hashCode() implementations

info - additional information for the slot, may be null

kind - the kind of the new slot

Returns:

the newly created slot

Throws:

IllegalArgumentException - if a frame slot with the same identifier exists

NullPointerException - if identifier or kind is null

Since:

0.8 or earlier

findFrameSlot

public FrameSlot findFrameSlot(Object identifier)

Finds an existing slot. This is a slow operation.

Parameters:

identifier - the key of the slot to search for

Returns:

the slot or null

Since:

0.8 or earlier

findOrAddFrameSlot

public FrameSlot findOrAddFrameSlot(Object identifier)

Finds an existing slot or creates new one. This is a slow operation.

Parameters:

identifier - the key of the slot to search for

Returns:

the found or newly created slot

Throws:

NullPointerException - if identifier is null

Since:

0.8 or earlier

findOrAddFrameSlot

public FrameSlot findOrAddFrameSlot(Object identifier,
                                    FrameSlotKind kind)

Finds an existing slot or creates new one. This is a slow operation.

Parameters:

identifier - the key of the slot to search for

kind - the kind for the newly created slot

Returns:

the found or newly created slot

Throws:

NullPointerException - if identifier or kind is null

Since:

0.8 or earlier

findOrAddFrameSlot

public FrameSlot findOrAddFrameSlot(Object identifier,
                                    Object info,
                                    FrameSlotKind kind)

Finds an existing slot or creates new one. This is a slow operation.

Parameters:

identifier - the key of the slot to search for

info - info for the newly created slot

kind - the kind for the newly created slot

Returns:

the found or newly created slot

Throws:

NullPointerException - if identifier or kind is null

Since:

0.8 or earlier

removeFrameSlot

public void removeFrameSlot(Object identifier)

Removes a slot. If the identifier is found, its slot is removed from this descriptor. This is a slow operation.

Parameters:

identifier - identifies the slot to remove

Throws:

IllegalArgumentException - if no such frame slot exists

Since:

0.8 or earlier

getFrameSlotKind

public FrameSlotKind getFrameSlotKind(FrameSlot frameSlot)

Kind of the provided slot. Specified either at creation time or updated via FrameDescriptor.setFrameSlotKind(FrameSlot, FrameSlotKind) method.

Parameters:

frameSlot - the slot

Returns:

current kind of this slot

Since:

19.0

setFrameSlotKind

public void setFrameSlotKind(FrameSlot frameSlot,
                             FrameSlotKind kind)

Changes the kind of the provided slot. Change of the slot kind is done on slow path and invalidates assumptions about version of this descriptor.

Parameters:

frameSlot - the slot

kind - new kind of the slot

Since:

19.0

getSize

public int getSize()

Returns the size of an array which is needed for storing all the frame slots. (The number may be bigger than the number of slots, if some slots are removed.)

Returns:

the size of the frame

Since:

0.8 or earlier

getSlots

public List<? extends FrameSlot> getSlots()

Retrieve the current list of slots in the descriptor. Further changes are not reflected in the returned collection.

Returns:

the unmodifiable snapshot list of FrameSlot

Since:

0.8 or earlier

getIdentifiers

public Set<Object> getIdentifiers()

Retrieve the current set of all the identifiers associated with this frame descriptor. Further changes are not reflected in the returned collection.

Returns:

the unmodifiable snapshot set of all the identifiers in this frame descriptor

Since:

0.8 or earlier

copy

public FrameDescriptor copy()

Deeper copy of the descriptor. Copies all slots in the descriptor, but only their identifier and info but not their kind!

Returns:

new instance of a descriptor with copies of values from this one

Since:

0.8 or earlier

getVersion

public Assumption getVersion()

Returns an assumption reflecting the frame's current version, which is updated every time a slot is added or removed, or an existing slot's kind is changed. This assumption is associated with compiled code that depends on the internal frame layout.

Returns:

an assumption invalidated when a slot is added or removed, or a slot kind changed.

Since:

0.8 or earlier

getDefaultValue

public Object getDefaultValue()

Default value for the created slots.

Returns:

value provided to FrameDescriptor.FrameDescriptor(java.lang.Object)

Since:

0.8 or earlier

getNotInFrameAssumption

public Assumption getNotInFrameAssumption(Object identifier)

Make an assumption that no slot with the specified identifier is present in this frame descriptor. Invalidated when a frame slot with the identifier is added.

Parameters:

identifier - frame slot identifier

Returns:

an assumption that this frame descriptor does not contain a slot with the identifier

Throws:

IllegalArgumentException - if the frame descriptor contains a slot with the identifier

Since:

0.8 or earlier

toString

public String toString()

Overrides:

toString in class Object

Since:

0.8 or earlier