Vendor org.graalvm.collections

Motivation:
Package org.graalvm.collections is used throughout the Pkl codebase.
It is most heavily used in the Truffle interpreter,
which requires putting most collection methods behind @TruffleBoundary.
At the moment, this is done by wrapping collection methods
with static methods declared in classes EconomicMaps and EconomicSets.
However, static wrapper methods are inconvenient to use,
decrease code readability, add some overhead, and are easy to forget about.

Changes:
- vendor package org.graalvm.collections into org.pkl.core.collection
  - org.graalvm.collections is licensed under:
    The Universal Permissive License (UPL), Version 1.0
  - vendored version:
    https://github.com/oracle/graal/tree/graal-23.0.3/sdk/src/org.graalvm.collections/src/org/graalvm/collections
  - add package-info.java with original license
  - annotate most public methods with @TruffleBoundary
  - add @nullable annotations
    - switching to JSpecify will enable more accurate nullability checks
  - remove prefix tree classes (not used in Pkl)
  - make no other code changes to simplify review/updates
- inline and remove EconomicMaps/Sets wrapper methods
- replace usages of EconomicMaps.equals/hashCode with EconomicMapUtil.equals/hashCode
- fix ProjectDeps.hashCode()

Result:
Cleaner, safer, and more efficient code.

Author: odenix

pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java

@@ -32,7 +32,6 @@
 import org.antlr.v4.runtime.Token;
 import org.antlr.v4.runtime.tree.ParseTree;
 import org.antlr.v4.runtime.tree.TerminalNode;
-import org.graalvm.collections.EconomicMap;
 import org.pkl.core.PClassInfo;
 import org.pkl.core.SecurityManagerException;
 import org.pkl.core.TypeParameter;
@@ -55,6 +54,7 @@
 import org.pkl.core.ast.lambda.ApplyVmFunction1NodeGen;
 import org.pkl.core.ast.member.*;
 import org.pkl.core.ast.type.*;
+import org.pkl.core.collection.EconomicMap;
 import org.pkl.core.externalreader.ExternalReaderProcessException;
 import org.pkl.core.module.ModuleKey;
 import org.pkl.core.module.ModuleKeys;
@@ -68,7 +68,6 @@
 import org.pkl.core.stdlib.registry.ExternalMemberRegistry;
 import org.pkl.core.stdlib.registry.MemberRegistryFactory;
 import org.pkl.core.util.CollectionUtils;
-import org.pkl.core.util.EconomicMaps;
 import org.pkl.core.util.IoUtils;
 import org.pkl.core.util.Nullable;
 import org.pkl.core.util.Pair;
@@ -217,7 +216,7 @@ public PklRootNode visitModule(ModuleContext ctx) {
 
     for (var methodCtx : ctx.ms) {
       var localMethod = doVisitObjectMethod(methodCtx.methodHeader(), methodCtx.expr(), true);
-      EconomicMaps.put(moduleProperties, localMethod.getName(), localMethod);
+      moduleProperties.put(localMethod.getName(), localMethod);
     }
 
     var moduleNode =
@@ -302,7 +301,7 @@ public ObjectMember visitClazz(ClazzContext ctx) {
                   typeParameters,
                   null,
                   supertypeNode,
-                  EconomicMaps.create(),
+                  EconomicMap.create(),
                   doVisitClassProperties(propertyCtxs, propertyNames),
                   doVisitMethodDefs(methodCtxs));
 
@@ -1065,7 +1064,7 @@ private ExpressionNode doVisitObjectBody(ObjectBodyContext ctx, ExpressionNode p
           var parametersDescriptorBuilder = createFrameDescriptorBuilder(ctx);
           var parameterTypes = doVisitParameterTypes(ctx);
 
-          var members = EconomicMaps.<Object, ObjectMember>create();
+          var members = EconomicMap.<Object, ObjectMember>create();
           var elements = new ArrayList<ObjectMember>();
           var keyNodes = new ArrayList<ExpressionNode>();
           var values = new ArrayList<ObjectMember>();
@@ -1188,7 +1187,7 @@ private void addConstantEntries(
     for (var i = 0; i < keyNodes.size(); i++) {
       var key = ((ConstantNode) keyNodes.get(i)).getValue();
       var value = values.get(i);
-      var previousValue = EconomicMaps.put(members, key, value);
+      var previousValue = members.put(key, value);
       if (previousValue != null) {
         CompilerDirectives.transferToInterpreter();
         throw exceptionBuilder()
@@ -1310,7 +1309,7 @@ public ExpressionNode visitAnnotation(AnnotationContext ctx) {
           currentScope.isCustomThisScope(),
           null,
           new UnresolvedTypeNode[0],
-          EconomicMaps.create(),
+          EconomicMap.create(),
           verifyNode);
     }
 
@@ -2606,12 +2605,12 @@ private EconomicMap<Object, ObjectMember> doVisitModuleProperties(
       ModuleInfo moduleInfo) {
 
     var totalSize = importCtxs.size() + classCtxs.size() + typeAliasCtxs.size();
-    var result = EconomicMaps.<Object, ObjectMember>create(totalSize);
+    var result = EconomicMap.<Object, ObjectMember>create(totalSize);
 
     for (var ctx : importCtxs) {
       var member = visitImportClause(ctx);
       checkDuplicateMember(member.getName(), member.getHeaderSection(), propertyNames);
-      EconomicMaps.put(result, member.getName(), member);
+      result.put(member.getName(), member);
     }
 
     for (var ctx : classCtxs) {
@@ -2625,7 +2624,7 @@ private EconomicMap<Object, ObjectMember> doVisitModuleProperties(
       }
 
       checkDuplicateMember(member.getName(), member.getHeaderSection(), propertyNames);
-      EconomicMaps.put(result, member.getName(), member);
+      result.put(member.getName(), member);
     }
 
     for (TypeAliasContext ctx : typeAliasCtxs) {
@@ -2639,7 +2638,7 @@ private EconomicMap<Object, ObjectMember> doVisitModuleProperties(
       }
 
       checkDuplicateMember(member.getName(), member.getHeaderSection(), propertyNames);
-      EconomicMaps.put(result, member.getName(), member);
+      result.put(member.getName(), member);
     }
 
     for (var ctx : propertyCtxs) {
@@ -2660,7 +2659,7 @@ private EconomicMap<Object, ObjectMember> doVisitModuleProperties(
       }
 
       checkDuplicateMember(member.getName(), member.getHeaderSection(), propertyNames);
-      EconomicMaps.put(result, member.getName(), member);
+      result.put(member.getName(), member);
     }
 
     return result;
@@ -2684,7 +2683,7 @@ private void checkDuplicateMember(
   // TODO: use Set<String> and checkDuplicateMember() to find duplicates between local and non-local
   // properties
   private void addProperty(EconomicMap<Object, ObjectMember> objectMembers, ObjectMember property) {
-    if (EconomicMaps.put(objectMembers, property.getName(), property) != null) {
+    if (objectMembers.put(property.getName(), property) != null) {
       throw exceptionBuilder()
           .evalError("duplicateDefinition", property.getName())
           .withSourceSection(property.getHeaderSection())

pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorElementNode.java

@@ -24,7 +24,6 @@
 import org.pkl.core.runtime.VmClass;
 import org.pkl.core.runtime.VmDynamic;
 import org.pkl.core.runtime.VmListing;
-import org.pkl.core.util.EconomicMaps;
 
 @ImportStatic(BaseModule.class)
 public abstract class GeneratorElementNode extends GeneratorMemberNode {
@@ -68,7 +67,7 @@ void fallback(Object parent, ObjectData data) {
 
   private void addElement(ObjectData data) {
     long index = data.length;
-    EconomicMaps.put(data.members, index, element);
+    data.members.put(index, element);
     data.length += 1;
     data.persistForBindings(index);
   }

pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorEntryNode.java

@@ -25,7 +25,6 @@
 import org.pkl.core.ast.member.ObjectMember;
 import org.pkl.core.runtime.*;
 import org.pkl.core.runtime.VmException.ProgramValue;
-import org.pkl.core.util.EconomicMaps;
 
 @ImportStatic(BaseModule.class)
 public abstract class GeneratorEntryNode extends GeneratorMemberNode {
@@ -112,7 +111,7 @@ private void addListingEntry(VirtualFrame frame, ObjectData data, int parentLeng
   }
 
   private void doAdd(Object key, ObjectData data) {
-    if (EconomicMaps.put(data.members, key, member) != null) {
+    if (data.members.put(key, member) != null) {
       CompilerDirectives.transferToInterpreter();
       throw duplicateDefinition(key, member);
     }

pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorMemberNode.java

@@ -22,14 +22,13 @@
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.source.SourceSection;
 import java.util.Arrays;
-import org.graalvm.collections.EconomicMap;
 import org.pkl.core.ast.PklNode;
 import org.pkl.core.ast.member.ObjectMember;
+import org.pkl.core.collection.EconomicMap;
 import org.pkl.core.runtime.Identifier;
 import org.pkl.core.runtime.VmClass;
 import org.pkl.core.runtime.VmException;
 import org.pkl.core.runtime.VmException.ProgramValue;
-import org.pkl.core.util.EconomicMaps;
 import org.pkl.core.util.Nullable;
 
 public abstract class GeneratorMemberNode extends PklNode {
@@ -81,7 +80,7 @@ protected boolean checkIsValidTypedProperty(VmClass clazz, ObjectMember member)
   public static final class ObjectData {
     // member count is exact iff every for/when body has exactly one member
     ObjectData(int minMemberCount, int length) {
-      this.members = EconomicMaps.create(minMemberCount);
+      this.members = EconomicMap.create(minMemberCount);
       this.length = length;
     }
 
@@ -122,7 +121,7 @@ public static final class ObjectData {
     }
 
     void persistForBindings(Object key) {
-      EconomicMaps.put(forBindings, key, currentForBindings);
+      forBindings.put(key, currentForBindings);
     }
 
     void resetForBindings(Object @Nullable [] bindings) {

pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorPredicateMemberNode.java

@@ -24,9 +24,8 @@
 import org.pkl.core.ast.ExpressionNode;
 import org.pkl.core.ast.builder.SymbolTable.CustomThisScope;
 import org.pkl.core.ast.member.ObjectMember;
+import org.pkl.core.collection.EconomicSet;
 import org.pkl.core.runtime.*;
-import org.pkl.core.util.EconomicMaps;
-import org.pkl.core.util.EconomicSets;
 
 public abstract class GeneratorPredicateMemberNode extends GeneratorMemberNode {
   @Child private ExpressionNode predicateNode;
@@ -81,15 +80,15 @@ private void addMembers(VirtualFrame frame, VmObject parent, ObjectData data) {
     initThisSlot(frame);
 
     var previousValue = frame.getAuxiliarySlot(customThisSlot);
-    var visitedKeys = EconomicSets.create();
+    var visitedKeys = EconomicSet.create();
 
     // do our own traversal instead of relying on `VmAbstractObject.force/iterateMemberValues`
     // (more efficient and we don't want to execute `predicateNode` behind Truffle boundary)
     for (var owner = parent; owner != null; owner = owner.getParent()) {
-      var entries = EconomicMaps.getEntries(owner.getMembers());
+      var entries = owner.getMembers().getEntries();
       while (entries.advance()) {
         var key = entries.getKey();
-        if (!EconomicSets.add(visitedKeys, key)) continue;
+        if (!visitedKeys.add(key)) continue;
 
         var member = entries.getValue();
         if (member.isProp() || member.isLocal()) continue;
@@ -136,7 +135,7 @@ private void initThisSlot(VirtualFrame frame) {
   }
 
   private void doAdd(Object key, ObjectData data) {
-    if (EconomicMaps.put(data.members, key, member) != null) {
+    if (data.members.put(key, member) != null) {
       CompilerDirectives.transferToInterpreter();
       throw duplicateDefinition(key, member);
     }

pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorPropertyNode.java

@@ -22,7 +22,6 @@
 import com.oracle.truffle.api.dsl.Specialization;
 import org.pkl.core.ast.member.ObjectMember;
 import org.pkl.core.runtime.*;
-import org.pkl.core.util.EconomicMaps;
 
 @ImportStatic({BaseModule.class, GeneratorObjectLiteralNode.class})
 public abstract class GeneratorPropertyNode extends GeneratorMemberNode {
@@ -118,7 +117,7 @@ protected boolean checkIsValidMappingProperty() {
   }
 
   private void addProperty(ObjectData data) {
-    if (EconomicMaps.put(data.members, member.getName(), member) == null) return;
+    if (data.members.put(member.getName(), member) == null) return;
 
     CompilerDirectives.transferToInterpreter();
     throw duplicateDefinition(member.getName(), member);

pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorSpreadNode.java

@@ -41,7 +41,6 @@
 import org.pkl.core.runtime.VmObject;
 import org.pkl.core.runtime.VmTyped;
 import org.pkl.core.runtime.VmUtils;
-import org.pkl.core.util.EconomicMaps;
 import org.pkl.core.util.MutableLong;
 
 @ImportStatic(BaseModule.class)
@@ -179,9 +178,9 @@ protected void doEvalDynamic(ObjectData data, VmObject iterable) {
     iterable.forceAndIterateMemberValues(
         (key, member, value) -> {
           if (member.isElement()) {
-            EconomicMaps.put(data.members, length.getAndIncrement(), createMember(member, value));
+            data.members.put(length.getAndIncrement(), createMember(member, value));
           } else {
-            if (EconomicMaps.put(data.members, key, createMember(member, value)) != null) {
+            if (data.members.put(key, createMember(member, value)) != null) {
               duplicateMember(key, member);
             }
           }
@@ -196,7 +195,7 @@ private void doEvalMapping(ObjectData data, VmObject iterable) {
           if (member.isElement() || member.isProp()) {
             cannotHaveMember(BaseModule.getMappingClass(), member);
           }
-          if (EconomicMaps.put(data.members, key, createMember(member, value)) != null) {
+          if (data.members.put(key, createMember(member, value)) != null) {
             duplicateMember(key, member);
           }
           return true;
@@ -210,7 +209,7 @@ private void doEvalListing(ObjectData data, VmObject iterable) {
           if (member.isEntry() || member.isProp()) {
             cannotHaveMember(getListingClass(), member);
           }
-          EconomicMaps.put(data.members, length.getAndIncrement(), createMember(member, value));
+          data.members.put(length.getAndIncrement(), createMember(member, value));
           return true;
         });
     data.length = (int) length.get();
@@ -223,7 +222,7 @@ private void doEvalTyped(VmClass clazz, ObjectData data, VmObject iterable) {
             cannotHaveMember(clazz, member);
           }
           checkTypedProperty(clazz, member);
-          if (EconomicMaps.put(data.members, key, createMember(member, value)) != null) {
+          if (data.members.put(key, createMember(member, value)) != null) {
             duplicateMember(key, member);
           }
           return true;
@@ -255,7 +254,7 @@ private void doEvalMap(VmClass parent, ObjectData data, VmMap iterable) {
     }
     for (var entry : iterable) {
       var member = VmUtils.createSyntheticObjectEntry("", VmUtils.getValue(entry));
-      if (EconomicMaps.put(data.members, VmUtils.getKey(entry), member) != null) {
+      if (data.members.put(VmUtils.getKey(entry), member) != null) {
         duplicateMember(VmUtils.getKey(entry), member);
       }
     }
@@ -337,7 +336,7 @@ private void spreadIterable(ObjectData data, Iterable<?> iterable) {
     for (var elem : iterable) {
       var index = length++;
       var member = VmUtils.createSyntheticObjectElement(String.valueOf(index), elem);
-      EconomicMaps.put(data.members, (long) index, member);
+      data.members.put((long) index, member);
     }
     data.length = length;
   }

pkl-core/src/main/java/org/pkl/core/ast/expression/generator/WriteForVariablesNode.java

@@ -17,10 +17,9 @@
 
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.nodes.ExplodeLoop;
-import org.graalvm.collections.UnmodifiableEconomicMap;
 import org.pkl.core.ast.ExpressionNode;
+import org.pkl.core.collection.UnmodifiableEconomicMap;
 import org.pkl.core.runtime.VmUtils;
-import org.pkl.core.util.EconomicMaps;
 
 public final class WriteForVariablesNode extends ExpressionNode {
   private final int[] auxiliarySlots;
@@ -39,7 +38,7 @@ public Object executeGeneric(VirtualFrame frame) {
 
     @SuppressWarnings("unchecked")
     var forBindings = (UnmodifiableEconomicMap<Object, Object[]>) extraStorage;
-    var bindings = EconomicMaps.get(forBindings, VmUtils.getMemberKey(frame));
+    var bindings = forBindings.get(VmUtils.getMemberKey(frame));
     assert bindings != null;
     assert bindings.length == auxiliarySlots.length;
 

pkl-core/src/main/java/org/pkl/core/ast/expression/literal/AmendModuleNode.java

@@ -20,10 +20,10 @@
 import com.oracle.truffle.api.dsl.Specialization;
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.source.SourceSection;
-import org.graalvm.collections.EconomicMap;
 import org.pkl.core.ast.ExpressionNode;
 import org.pkl.core.ast.member.ObjectMember;
 import org.pkl.core.ast.type.UnresolvedTypeNode;
+import org.pkl.core.collection.EconomicMap;
 import org.pkl.core.runtime.ModuleInfo;
 import org.pkl.core.runtime.VmLanguage;
 import org.pkl.core.runtime.VmTyped;

pkl-core/src/main/java/org/pkl/core/ast/expression/literal/ConstantEntriesLiteralNode.java

@@ -21,10 +21,10 @@
 import com.oracle.truffle.api.frame.FrameDescriptor;
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.source.SourceSection;
-import org.graalvm.collections.UnmodifiableEconomicMap;
 import org.pkl.core.ast.ExpressionNode;
 import org.pkl.core.ast.member.ObjectMember;
 import org.pkl.core.ast.type.UnresolvedTypeNode;
+import org.pkl.core.collection.UnmodifiableEconomicMap;
 import org.pkl.core.runtime.*;
 import org.pkl.core.util.Nullable;
 

pkl-core/src/main/java/org/pkl/core/ast/expression/literal/ElementsEntriesLiteralNode.java

@@ -24,12 +24,12 @@
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.nodes.ExplodeLoop;
 import com.oracle.truffle.api.source.SourceSection;
-import org.graalvm.collections.UnmodifiableEconomicMap;
 import org.pkl.core.ast.ExpressionNode;
 import org.pkl.core.ast.member.ObjectMember;
 import org.pkl.core.ast.type.UnresolvedTypeNode;
+import org.pkl.core.collection.EconomicMap;
+import org.pkl.core.collection.UnmodifiableEconomicMap;
 import org.pkl.core.runtime.*;
-import org.pkl.core.util.EconomicMaps;
 import org.pkl.core.util.Nullable;
 
 /**
@@ -152,15 +152,15 @@ protected void fallback(Object parent) {
   protected UnmodifiableEconomicMap<Object, ObjectMember> createMembers(
       VirtualFrame frame, int parentLength) {
     var result =
-        EconomicMaps.<Object, ObjectMember>create(
-            EconomicMaps.size(members) + keyNodes.length + elements.length);
+        EconomicMap.<Object, ObjectMember>create(
+            members.size() + keyNodes.length + elements.length);
 
-    EconomicMaps.putAll(result, members);
+    result.putAll(members);
 
     addListEntries(frame, parentLength, result, keyNodes, values);
 
     for (var i = 0; i < elements.length; i++) {
-      EconomicMaps.put(result, (long) (parentLength + i), elements[i]);
+      result.put((long) (parentLength + i), elements[i]);
     }
 
     return result;