Shape (GraalVM Truffle Java API Reference)

java.lang.Object
- com.oracle.truffle.api.object.Shape

```
public abstract class Shape
extends Object
```
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 Shape.newBuilder().

Since:

0.8 or earlier

See Also:

DynamicObject, Shape.newBuilder(), Property

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Shape.Builder` Builder class to construct initial `Shape` instances.
`static class`	`Shape.DerivedBuilder` Builder class to construct derived `Shape` instances.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Shape()
Constructor for subclasses.

Constructors
Modifier	Constructor and Description
`protected`	`Shape()` Constructor for subclasses.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`Object`	`getDynamicType()` Get the shape's dynamic object type identifier.
`int`	`getFlags()` Returns the language-specific shape flags previously set using `DynamicObjectLibrary.setShapeFlags(DynamicObject, int)` or `Shape.Builder.shapeFlags(int)`.
`abstract List<Object>`	`getKeyList()` Get a list of all property keys in insertion order.
`abstract Iterable<Object>`	`getKeys()` Get all property keys in insertion order.
`abstract Property`	`getLastProperty()` Get the last property.
`Class<? extends DynamicObject>`	`getLayoutClass()` Get the shape's layout class.
`abstract Assumption`	`getLeafAssumption()` Get an assumption that the shape is a leaf.
`abstract Iterable<Property>`	`getProperties()` An `Iterable` over the shape's properties in insertion order.
`abstract Property`	`getProperty(Object key)` Get a property entry by key.
`Assumption`	`getPropertyAssumption(Object key)` Gets a stable property assumption for the given property key.
`abstract int`	`getPropertyCount()` Returns the number of properties in this shape.
`abstract List<Property>`	`getPropertyList()` Get a list of all properties that this Shape stores.
`abstract List<Property>`	`getPropertyListInternal(boolean ascending)` Returns all (also hidden) property objects in this shape.
`abstract Shape`	`getRoot()` Get the root shape.
`abstract Object`	`getSharedData()` Get the shape's shared data.
`abstract Assumption`	`getValidAssumption()` Get an assumption that the shape is valid.
`protected boolean`	`hasInstanceProperties()` Returns `true` 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()` Returns `true` if this shape is marked as shared.
`abstract boolean`	`isValid()` Check whether this shape is valid.
`PropertyGetter`	`makePropertyGetter(Object key)` Makes a property getter for this shape and the given property key, if it exists.
`Shape`	`makeSharedShape()` Make a shared variant of this shape, to allow safe usage of this object between threads.
`static Shape.Builder`	`newBuilder()` 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 Shape`	`setDynamicType(Object dynamicType)` Returns a copy of the shape, with the dynamic object type identifier set to `dynamicType`.
`protected Shape`	`setFlags(int newFlags)` Returns a copy of the shape, with the shape flags set to `newFlags`.
`abstract Shape`	`tryMerge(Shape other)` 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.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Shape
```
protected Shape()
```
    Constructor for subclasses.
    
    Since:
    
    0.8 or earlier
- Method Detail
  - newBuilder
```
public static Shape.Builder 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
```
public 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. 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:
    
    Shape.newBuilder()
  - getProperty
```
public abstract Property getProperty(Object key)
```
    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
  - getProperties
```
public abstract Iterable<Property> getProperties()
```
    An Iterable over the shape's properties in insertion order.
    
    Since:
    
    0.8 or earlier
  - getPropertyList
```
public abstract List<Property> getPropertyList()
```
    Get a list of all properties that this Shape stores. Properties with a HiddenKey are not included.
    
    Returns:
    
    list of properties
    
    Since:
    
    0.8 or earlier
  - getPropertyListInternal
```
public abstract List<Property> getPropertyListInternal(boolean ascending)
```
    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
```
public abstract List<Object> getKeyList()
```
    Get a list of all property keys in insertion order. Properties with a HiddenKey are not included.
    
    Since:
    
    0.8 or earlier
  - getKeys
```
public abstract Iterable<Object> getKeys()
```
    Get all property keys in insertion order.
    
    Since:
    
    0.8 or earlier
  - getValidAssumption
```
public abstract Assumption 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
```
public abstract Assumption 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
```
public abstract boolean hasProperty(Object key)
```
    Check whether the shape has a property with the given key.
    
    Since:
    
    0.8 or earlier
  - getLastProperty
```
public abstract Property getLastProperty()
```
    Get the last property.
    
    Since:
    
    0.8 or earlier
  - getFlags
```
public int getFlags()
```
    Returns the language-specific shape flags previously set using DynamicObjectLibrary.setShapeFlags(DynamicObject, int) or Shape.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:
    
    DynamicObjectLibrary.getShapeFlags(DynamicObject), DynamicObjectLibrary.setShapeFlags(DynamicObject, int), Shape.Builder.shapeFlags(int)
  - setFlags
```
protected Shape setFlags(int newFlags)
```
    Returns a copy of the shape, with the shape flags set to newFlags.
    
    Parameters:
    
    newFlags - the new shape flags; an int value in the range from 0 to 255 (inclusive)
    
    Throws:
    
    IllegalArgumentException - if the flags value is not in the supported range
    
    Since:
    
    20.2.0
    
    See Also:
    
    Shape.Builder.shapeFlags(int)
  - getPropertyCount
```
public abstract int getPropertyCount()
```
    Returns the number of properties in this shape.
    
    Since:
    
    0.8 or earlier
  - getDynamicType
```
public Object getDynamicType()
```
    Get the shape's dynamic object type identifier.
    
    Since:
    
    20.2.0
  - setDynamicType
```
protected Shape setDynamicType(Object dynamicType)
```
    Returns a copy of the shape, with the dynamic object type identifier set to dynamicType.
    
    Parameters:
    
    dynamicType - the new dynamic object type identifier
    
    Throws:
    
    NullPointerException - if the argument is null.
    
    Since:
    
    20.2.0
    
    See Also:
    
    Shape.Builder.dynamicType(Object)
  - getRoot
```
public abstract Shape getRoot()
```
    Get the root shape. Planned to be deprecated.
    
    Since:
    
    0.8 or earlier
  - check
```
public abstract boolean check(DynamicObject subject)
```
    Checks whether the given object's shape is identical to this shape.
    
    Since:
    
    0.8 or earlier
  - getLayoutClass
```
public Class<? extends DynamicObject> getLayoutClass()
```
    Get the shape's layout class.
    
    Since:
    
    21.1
    
    See Also:
    
    Shape.Builder.layout(Class)
  - getSharedData
```
public abstract Object getSharedData()
```
    Get the shape's shared data.
    
    Since:
    
    0.8 or earlier
    
    See Also:
    
    Shape.Builder.sharedData(Object)
  - tryMerge
```
public abstract Shape tryMerge(Shape other)
```
    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
  - isShared
```
public boolean isShared()
```
    Returns true if this shape is marked as shared.
    
    Since:
    
    0.18
    
    See Also:
    
    DynamicObjectLibrary.isShared(DynamicObject), DynamicObjectLibrary.markShared(DynamicObject), Shape.Builder.shared(boolean)
  - makeSharedShape
```
public Shape makeSharedShape()
```
    Make a shared variant of this shape, to allow safe usage of this object between threads. Shared shapes will not reuse storage locations for other fields. In combination with careful synchronization on writes, this can prevent reading out-of-thin-air values.
    Note: Where possible, avoid using this method and use DynamicObjectLibrary.markShared(DynamicObject) instead.
    
    Returns:
    
    a cached and shared variant of this shape
    
    Since:
    
    0.18
    
    See Also:
    
    Shape.isShared(), DynamicObjectLibrary.markShared(DynamicObject)
  - hasInstanceProperties
```
protected boolean hasInstanceProperties()
```
    Returns true if this shape has instance properties (i.e., stored in the object).
    
    Since:
    
    20.2.0
  - getPropertyAssumption
```
public Assumption getPropertyAssumption(Object key)
```
    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 a resetShape.
    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:
    
    Shape.Builder.propertyAssumptions(boolean)
  - allPropertiesMatch
```
public boolean allPropertiesMatch(Predicate<Property> predicate)
```
    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, returns true and does not evaluate the predicate.
    
    Returns:
    
    true if the all properties match the predicate, else false
    
    Since:
    
    20.2.0
  - makePropertyGetter
```
public PropertyGetter makePropertyGetter(Object key)
```
    Makes a property getter for this shape and the given property key, if it exists. Otherwise, returns null. Note that the returned PropertyGetter only accepts objects of this particular Shape.
    
    Parameters:
    
    key - the identifier to look up
    
    Returns:
    
    a PropertyGetter, or null if the property was not found in this shape
    
    Since:
    
    22.2

Class Shape

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Shape

Method Detail

newBuilder

newBuilder

getProperty

getProperties

getPropertyList

getPropertyListInternal

getKeyList

getKeys

getValidAssumption

isValid

getLeafAssumption

isLeaf

hasProperty

getLastProperty

getFlags

setFlags

getPropertyCount

getDynamicType

setDynamicType

getRoot

check

getLayoutClass

getSharedData

tryMerge

isShared

makeSharedShape

hasInstanceProperties

getPropertyAssumption

allPropertiesMatch

makePropertyGetter