com.oracle.truffle.api.object

Class Shape.Builder

java.lang.Object

com.oracle.truffle.api.object.Shape.Builder

Enclosing class:

Shape

public static final class Shape.Builder
extends Object

Builder class to construct initial Shape instances. The builder instance is not thread-safe and must not be used from multiple threads at the same time.

Since:

20.2.0

See Also:

Shape.newBuilder()

Method Summary

Modifier and Type	Method and Description
Shape.Builder	addConstantProperty(Object key, Object value, int flags) Adds a property with a constant value to the shape.
Shape.Builder	allowImplicitCastIntToDouble(boolean allow) Allows values to be implicitly cast from int to double in this shape and any derived shapes.
Shape.Builder	allowImplicitCastIntToLong(boolean allow) Allows values to be implicitly cast from int to long in this shape and any derived shapes.
Shape	build() Builds a new shape using the configuration of this builder.
Shape.Builder	dynamicType(Object dynamicType) Sets initial dynamic object type identifier.
Shape.Builder	layout(Class<? extends DynamicObject> layoutClass) Sets custom object layout class (default: DynamicObject base class).
Shape.Builder	propertyAssumptions(boolean enable) If true, enables the use of property assumptions for this object shape and any derived shapes (default: false).
Shape.Builder	shapeFlags(int flags) Sets initial shape flags (default: 0).
Shape.Builder	shared(boolean isShared) If true, makes the object shared (default: false).
Shape.Builder	sharedData(Object sharedData) Sets shared data to be associated with the root shape and any derived shapes (e.g.
Shape.Builder	singleContextAssumption(Assumption assumption) Sets an assumption that allows specializations on constant object instances with this shape, as long as the assumption is valid.

Methods inherited from class java.lang.Object

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

Method Detail

layout

public Shape.Builder layout(Class<? extends DynamicObject> layoutClass)

Sets custom object layout class (default: DynamicObject base class). Enables the use of dynamic object fields declared in subclasses using the DynamicField annotation.

Examples:

 
 public class MyObject extends DynamicObject implements TruffleObject {

     @DynamicField private Object _obj1;
     @DynamicField private Object _obj2;
     @DynamicField private long _long1;
     @DynamicField private long _long2;

     public MyObject(Shape shape) {
         super(shape);
     }
 }


 Shape myObjShape = Shape.newBuilder().layout(MyObject.class).build();
 MyObject obj = new MyObject(myObjShape);
 
 

Parameters:

layoutClass - custom object layout class

Since:

20.2.0

dynamicType

public Shape.Builder dynamicType(Object dynamicType)

Sets initial dynamic object type identifier. See DynamicObjectLibrary.setDynamicType(DynamicObject, Object) for more information.

Parameters:

dynamicType - a non-null object type identifier

Throws:

NullPointerException - if the type is null

IllegalArgumentException

Since:

20.2.0

See Also:

DynamicObjectLibrary.getDynamicType(DynamicObject), DynamicObjectLibrary.setDynamicType(DynamicObject, Object)

shapeFlags

public Shape.Builder shapeFlags(int flags)

Sets initial shape flags (default: 0). Currently limited to 8 bits. See DynamicObjectLibrary.setShapeFlags(DynamicObject, int) for more information.

Parameters:

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:

DynamicObjectLibrary.getShapeFlags(DynamicObject), DynamicObjectLibrary.setShapeFlags(DynamicObject, int)

shared

public Shape.Builder shared(boolean isShared)

If true, makes the object shared (default: false).

Since:

20.2.0

See Also:

Shape.isShared(), DynamicObjectLibrary.isShared(DynamicObject), DynamicObjectLibrary.markShared(DynamicObject)

propertyAssumptions

public Shape.Builder propertyAssumptions(boolean enable)

If true, enables the use of property assumptions for this object shape and any derived shapes (default: false). Property assumptions allow speculating on select properties being absent or stable across shape changes.

Use of property assumptions can be beneficial in single-context mode for long-lived objects with stable properties but recurrent shape changes due to properties being added (e.g. global objects of a context), in which case a shape cache would be unstable while the property assumption allows for a stable cache.

Since:

20.2.0

See Also:

Shape.getPropertyAssumption(Object)

sharedData

public Shape.Builder sharedData(Object sharedData)

Sets shared data to be associated with the root shape and any derived shapes (e.g. a TruffleLanguage instance). May be null (the default).

Since:

20.2.0

See Also:

Shape.getSharedData()

singleContextAssumption

public Shape.Builder singleContextAssumption(Assumption assumption)

Sets an assumption that allows specializations on constant object instances with this shape, as long as the assumption is valid. The assumption should be valid only if code is not shared across contexts and invalidated when this is not longer true. The assumption may be null in which case this feature is disabled (the default).

Since:

20.2.0

See Also:

Shape.Builder.propertyAssumptions(boolean)

addConstantProperty

public Shape.Builder addConstantProperty(Object key,
                                         Object value,
                                         int flags)

Adds a property with a constant value to the shape. The key must not be null and must not be equal to any previously added property's key.

Parameters:

key - the property's key

value - the property's value

flags - the property's flags

Throws:

NullPointerException - if the key is null

IllegalArgumentException - if a property with the key already exists

Since:

20.2.0

See Also:

DynamicObjectLibrary.putConstant(DynamicObject, Object, Object, int)

allowImplicitCastIntToLong

public Shape.Builder allowImplicitCastIntToLong(boolean allow)

Allows values to be implicitly cast from int to long in this shape and any derived shapes.

Since:

20.2.0

See Also:

Shape.Builder.layout(Class)

allowImplicitCastIntToDouble

public Shape.Builder allowImplicitCastIntToDouble(boolean allow)

Allows values to be implicitly cast from int to double in this shape and any derived shapes.

Since:

20.2.0

See Also:

Shape.Builder.layout(Class)

build

public Shape build()

Builds a new shape using the configuration of this builder.

Since:

20.2.0