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:

  • Method Details

    • layout

      @Deprecated(since="24.2") public Shape.Builder layout(Class<? extends DynamicObject> layoutClass)
      Deprecated.
      Use layout(Class, MethodHandles.Lookup) instead.
      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

    • layout

      public Shape.Builder layout(Class<? extends DynamicObject> layoutClass, MethodHandles.Lookup layoutClassLookup)
      Sets a custom object layout class (default: DynamicObject.class) and a corresponding MethodHandles.Lookup created by the layout class, or a class in the same module, that has full privilege access in order to provide access to its fields.

      Enables the allocation of any additional DynamicField-annotated fields declared in the DynamicObject layout subclass as storage locations. By default, only extension array based storage locations in the DynamicObject base class are used.

      Also restricts the shape to a specific DynamicObject subclass and subclasses thereof, i.e. shapes created for a DynamicObject layout subclass, and any derived shapes, can only be used to instantiate, and be assigned to, instances of that class (regardless of whether the class actually contains any dynamic fields).

      Example: 

       
 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);
     }

     static MethodHandles.Lookup lookup() {
         return MethodHandles.lookup();
     }
 }


 Shape myObjShape = Shape.newBuilder().layout(MyObject.class, MyObject.lookup()).build();
 MyObject obj = new MyObject(myObjShape);
      Parameters:
      layoutClass - a DynamicObject layout subclass or the default DynamicObject.class.
      layoutClassLookup - a MethodHandles.Lookup that has full privilege access, created using MethodHandles.lookup(), either by the layout class itself, or a class in the same module. If layoutClass == DynamicObject.class, and only then, this parameter is ignored and may be null.
      Throws:
      IllegalArgumentException - if layoutClass != DynamicObject.class and the lookup does not have full privilege access or is not from the layout class or a class within the same module as the layout class.
      NullPointerException - if layoutClass == null, or lookup == null and layoutClass != DynamicObject.class.
      Since:
      24.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
      Since:
      20.2.0
      See Also:

    • shapeFlags

      public Shape.Builder shapeFlags(int flags)
      Sets initial shape flags (default: 0). Currently limited to 16 bits. See DynamicObjectLibrary.setShapeFlags(DynamicObject, int) for more information.
      Parameters:
      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:

    • shared

      public Shape.Builder shared(boolean isShared)
      If true, makes the object shared (default: false).
      Since:
      20.2.0
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

    • 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

    • build

      public Shape build()
      Builds a new shape using the configuration of this builder.
      Since:
      20.2.0