Class DynamicObject.PutConstantNode

java.lang.Object
com.oracle.truffle.api.nodes.Node
com.oracle.truffle.api.object.DynamicObject.PutConstantNode
All Implemented Interfaces:
NodeInterface, Cloneable
Enclosing class:
DynamicObject
public abstract static class DynamicObject.PutConstantNode extends Node
Sets the value of an existing property or adds a new property if no such property exists. Additional variants allow setting property flags, only setting the property if it's either absent or present, and setting constant properties stored in the shape.
Since:
25.1
See Also:

  • Method Details

    • execute

      public final void execute(DynamicObject receiver, Object key, Object value)
      Same as executeWithFlags(DynamicObject, Object, Object, int), except the property is added with 0 flags, and if the property already exists, its flags will not be updated.

    • executeIfPresent

      public final boolean executeIfPresent(DynamicObject receiver, Object key, Object value)
      Like execute(DynamicObject, Object, Object) but only if the property is present.

    • executeIfAbsent

      public final boolean executeIfAbsent(DynamicObject receiver, Object key, Object value)
      Like execute(DynamicObject, Object, Object) but only if the property is absent.

    • executeWithFlags

      public final void executeWithFlags(DynamicObject receiver, Object key, Object value, int propertyFlags)
      Adds a property with a constant value or replaces an existing one. If the property already exists, its flags will be updated. The constant value is stored in the shape rather than the object instance and a new shape will be allocated if it does not already exist. A typical use case for this method is setting the initial default value of a declared, but yet uninitialized, property. This defers storage allocation and type speculation until the first actual value is set.

      Warning: this method will lead to a shape transition every time a new value is set and should be used sparingly (with at most one constant value per property) since it could cause an excessive amount of shapes to be created.

      Note: the value is strongly referenced from the shape property map. It should ideally be a value type or light-weight object without any references to guest language objects in order to prevent potential memory leaks from holding onto the Shape in inline caches. The Shape transition itself is weak, so the previous shapes will not hold strongly on the value.

      Usage example:

      abstract static class DeclarePropertyNode extends Node {
    abstract void execute(DynamicObject receiver, Object key);

    @Specialization
    static void doCached(MyDynamicObjectSubclass receiver, Symbol key,
                    @Cached DynamicObject.PutConstantNode putConstantNode) {
        // declare property
        putConstantNode.execute(receiver, key, NULL_VALUE);
    }
}

      abstract static class InitializePropertyNode extends Node {
    abstract void execute(DynamicObject receiver, Object key, Object value);

    @Specialization
    static void doCached(MyDynamicObjectSubclass receiver, Symbol key, Object value,
                    @Cached DynamicObject.PutNode putNode) {
        // initialize property
        putNode.execute(receiver, key, value);
    }
}
      Parameters:
      key - property identifier
      value - the constant value to be set
      propertyFlags - property flags or 0
      See Also:

    • executeWithFlagsIfPresent

      public final boolean executeWithFlagsIfPresent(DynamicObject receiver, Object key, Object value, int propertyFlags)
      Like executeWithFlags(DynamicObject, Object, Object, int) but only if the property is present.

    • executeWithFlagsIfAbsent

      public final boolean executeWithFlagsIfAbsent(DynamicObject receiver, Object key, Object value, int propertyFlags)
      Like executeWithFlags(DynamicObject, Object, Object, int) but only if the property is absent.

    • create

      public static DynamicObject.PutConstantNode create()
      Since:
      25.1

    • getUncached

      public static DynamicObject.PutConstantNode getUncached()
      Since:
      25.1