Package com.oracle.truffle.api.object
Class Shape
java.lang.Object
com.oracle.truffle.api.object.Shape
A Shape is an immutable descriptor of the current object "shape" of a DynamicObject, i.e., object
layout, metadata (type, flags),
and a mapping of properties to storage locations. This allows cached
DynamicObjectLibrary
to do a simple shape check to determine the contents of an object
and do fast, constant-time property accesses.
Shapes are shared between objects that assume the same shape if they follow the same shape transitions, like adding the same properties in the same order, starting from a common root shape. Shape transitions are automatically, weakly cached.
Dynamic objects start off with an initial shape that has no instance properties (but may have
constant properties that are stored in the shape). Initial shapes are created via
newBuilder()
.
- Since:
- 0.8 or earlier
- See Also:
-
Nested Class Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected abstract Shape
addProperty
(Property property) Add a new property in the map, yielding a new or cached Shape object.boolean
allPropertiesMatch
(Predicate<Property> predicate) Tests if all properties in the shape match the provided predicate.abstract boolean
check
(DynamicObject subject) Checks whether the given object's shape is identical to this shape.abstract Shape
defineProperty
(Object key, Object value, int propertyFlags) Deprecated.protected abstract Shape
defineProperty
(Object key, Object value, int propertyFlags, int putFlags) Add or change property in the map, yielding a new or cached Shape object.Get the shape's dynamic object type identifier.int
getFlags()
Returns the language-specific shape flags previously set usingDynamicObjectLibrary.setShapeFlags(DynamicObject, int)
orShape.Builder.shapeFlags(int)
.Get a list of all property keys in insertion order.getKeys()
Get all property keys in insertion order.abstract Property
Get the last property.protected abstract Layout
Get the shape's layout.Class
<? extends DynamicObject> Get the shape's layout class.abstract Assumption
Get an assumption that the shape is a leaf.AnIterable
over the shape's properties in insertion order.abstract Property
getProperty
(Object key) Get a property entry by key.Gets a stable property assumption for the given property key.abstract int
Returns the number of properties in this shape.Get a list of all properties that this Shape stores.getPropertyListInternal
(boolean ascending) Returns all (also hidden) property objects in this shape.abstract Shape
getRoot()
Get the root shape.abstract Object
Get the shape's shared data.abstract Assumption
Get an assumption that the shape is valid.protected boolean
Returnstrue
if this shape has instance properties (i.e., stored in the object).abstract boolean
hasProperty
(Object key) Check whether the shape has a property with the given key.abstract boolean
isLeaf()
Check whether this shape is a leaf in the transition graph, i.e.boolean
isShared()
Returnstrue
if this shape is marked as shared.abstract boolean
isValid()
Check whether this shape is valid.makePropertyGetter
(Object key) Makes a property getter for this shape and the given property key, if it exists.Make a shared variant of this shape, to allow safe usage of this object between threads.static Shape.Builder
Creates a new initial shape builder.static Shape.DerivedBuilder
newBuilder
(Shape baseShape) Creates a new derived shape builder that allows changing a root shape's flags and dynamic type and adding constant properties.protected abstract Shape
removeProperty
(Property property) Remove the given property from the shape.protected abstract Shape
replaceProperty
(Property oldProperty, Property newProperty) Replace a property in the shape.protected Shape
setDynamicType
(Object dynamicType) Returns a copy of the shape, with the dynamic object type identifier set todynamicType
.protected Shape
setFlags
(int newFlags) Returns a copy of the shape, with the shape flags set tonewFlags
.abstract Shape
Try to merge two related shapes to a more general shape that has the same properties and can store at least the values of both shapes.
-
Constructor Details
-
Shape
protected Shape()Constructor for subclasses.- Since:
- 0.8 or earlier
-
-
Method Details
-
newBuilder
Creates a new initial shape builder. The builder instance is not thread-safe and must not be used from multiple threads at the same time.- Since:
- 20.2.0
-
newBuilder
Creates a new derived shape builder that allows changing a root shape's flags and dynamic type and adding constant properties. The builder instance is not thread-safe and must not be used from multiple threads at the same time.- Parameters:
baseShape
- the shape to be modified- Since:
- 20.2.0
- See Also:
-
getProperty
Get a property entry by key.- Parameters:
key
- the identifier to look up- Returns:
- a Property object, or
null
if not found - Since:
- 0.8 or earlier
-
addProperty
Add a new property in the map, yielding a new or cached Shape object.- Parameters:
property
- the property to add- Returns:
- the new Shape
- Since:
- 0.8 or earlier
-
defineProperty
@Deprecated(since="22.2") public abstract Shape defineProperty(Object key, Object value, int propertyFlags) Deprecated.Add or change property in the map, yielding a new or cached Shape object.- Returns:
- the shape after defining the property
- Since:
- 0.8 or earlier
-
defineProperty
Add or change property in the map, yielding a new or cached Shape object.- Returns:
- the shape after defining the property
- Since:
- 24.1
-
getProperties
AnIterable
over the shape's properties in insertion order.- Since:
- 0.8 or earlier
-
getPropertyList
Get a list of all properties that this Shape stores. Properties with aHiddenKey
are not included.- Returns:
- list of properties
- Since:
- 0.8 or earlier
-
getPropertyListInternal
Returns all (also hidden) property objects in this shape.- Parameters:
ascending
- desired order (true
for insertion order,false
for reverse insertion order)- Since:
- 0.8 or earlier
-
getKeyList
Get a list of all property keys in insertion order. Properties with aHiddenKey
are not included.- Since:
- 0.8 or earlier
-
getKeys
Get all property keys in insertion order.- Since:
- 0.8 or earlier
-
getValidAssumption
Get an assumption that the shape is valid.- Since:
- 0.8 or earlier
-
isValid
public abstract boolean isValid()Check whether this shape is valid.- Since:
- 0.8 or earlier
-
getLeafAssumption
Get an assumption that the shape is a leaf.- Since:
- 0.8 or earlier
-
isLeaf
public abstract boolean isLeaf()Check whether this shape is a leaf in the transition graph, i.e. transitionless.- Since:
- 0.8 or earlier
-
hasProperty
Check whether the shape has a property with the given key.- Since:
- 0.8 or earlier
-
removeProperty
Remove the given property from the shape.- Since:
- 0.8 or earlier
-
replaceProperty
Replace a property in the shape.- Since:
- 0.8 or earlier
-
getLastProperty
Get the last property.- Since:
- 0.8 or earlier
-
getFlags
public int getFlags()Returns the language-specific shape flags previously set usingDynamicObjectLibrary.setShapeFlags(DynamicObject, int)
orShape.Builder.shapeFlags(int)
. If no shape flags were explicitly set, the default of 0 is returned. These flags may be used to tag objects that possess characteristics that need to be queried efficiently on fast and slow paths. For example, they can be used to mark objects as frozen.- Since:
- 20.2.0
- See Also:
-
setFlags
Returns a copy of the shape, with the shape flags set tonewFlags
.- Parameters:
newFlags
- the new shape flags; an int value in the range from 0 to 65535 (inclusive)- Throws:
IllegalArgumentException
- if the flags value is not in the supported range- Since:
- 20.2.0
- See Also:
-
getPropertyCount
public abstract int getPropertyCount()Returns the number of properties in this shape.- Since:
- 0.8 or earlier
-
getDynamicType
Get the shape's dynamic object type identifier.- Since:
- 20.2.0
-
setDynamicType
Returns a copy of the shape, with the dynamic object type identifier set todynamicType
.- Parameters:
dynamicType
- the new dynamic object type identifier- Throws:
NullPointerException
- if the argument is null.- Since:
- 20.2.0
- See Also:
-
getRoot
Get the root shape. Planned to be deprecated.- Since:
- 0.8 or earlier
-
check
Checks whether the given object's shape is identical to this shape.- Since:
- 0.8 or earlier
-
getLayout
Get the shape's layout.- Since:
- 0.8 or earlier
- See Also:
-
getLayoutClass
Get the shape's layout class.- Since:
- 21.1
- See Also:
-
tryMerge
Try to merge two related shapes to a more general shape that has the same properties and can store at least the values of both shapes.- Returns:
- this, other, or a new shape that is compatible with both shapes
- Since:
- 0.8 or earlier
-
hasInstanceProperties
protected boolean hasInstanceProperties()Returnstrue
if this shape has instance properties (i.e., stored in the object).- Since:
- 20.2.0
-
getPropertyAssumption
Gets a stable property assumption for the given property key. May be invalid. If a valid assumption is returned, it may be used to assume this particular property is still absent or present at the current storage location in objects of this shape. The assumption is invalidated if a shape change is triggered because of a property with the given key was added, removed, or changed, or aresetShape
.Only applicable if property assumptions are enabled for this shape, otherwise always returns an invalid assumption.
- Parameters:
key
- the property key of interest- Returns:
- an assumption that the property is stable or an invalid assumption
- Since:
- 20.2.0
- See Also:
-
allPropertiesMatch
Tests if all properties in the shape match the provided predicate. May not evaluate the predicate on all properties if a predicate did not match. If the shape does not contain any properties, returnstrue
and does not evaluate the predicate.- Returns:
true
if the all properties match the predicate, elsefalse
- Since:
- 20.2.0
-
makePropertyGetter
Makes a property getter for this shape and the given property key, if it exists. Otherwise, returnsnull
. Note that the returnedPropertyGetter
only accepts objects of this particularShape
.- Parameters:
key
- the identifier to look up- Returns:
- a
PropertyGetter
, ornull
if the property was not found in this shape - Since:
- 22.2
-
DynamicObjectLibrary.put(DynamicObject, Object, Object)
orDynamicObjectLibrary.putWithFlags(DynamicObject, Object, Object, int)
.