Vendor org.graalvm.collections

[odenix]

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.

[bioball]

I am not sure we want to do this. This makes it hard to upgrade the collections library, and I'm not sure how much of a performance gain we get out of this.

and are easy to forget about

Thankfully, our CI builds (on main) will catch these errors if they are forgotten.

Curious about @holzensp and @stackoverflow's thoughts

[odenix]

Owning the collection library(s) used by a Truffle language implementation makes a lot of sense:

• it is desirable for performance reasons (can optimize for partial evaluation, etc.)
• it avoids ugly wrapper code (invocations)

org.graalvm.collections is a tiny (essentially one class, namely EconomicMapImpl) and very mature library. It hasn't had significant changes in years, except for some recent additions (LockFreePool, etc.) that aren't used in Pkl.

Vendoring EconomicMap(Impl) feels natural to me, even just to improve code readability/writability.

[odenix]

I just stumbled upon the following conversation in the GraalVM Slack, where a Truffle committer argues for owning the collection library used in the Pkl interpreter. He's talking about Paguro, but it's the same thing, except that Paguro, or its future replacement, is way more challenging to own than EconomicMap(Impl).

Christian Humer Apr 5th at 7:36 AM
Looking at the Pkl types a bit. I think RrbTree could be a good candidate to make partial evaluatable. Atm it looks as if there all just boundaries, which hinders optimizations. Do you have any experience trying this?

yeah you need to manually profile and specialize for recursions and things like that. that typically involves owning the library you are using.

By the way, his latest announcement could be huge for Pkl performance, but is years away unless Pkl changes its versioning strategy:

Christian Humer 3:21 PM
At long last the Bytecode DSL was merged and will be shipped with 24.2 as experimental.

In short, the Bytecode DSL allows you to generate bytecode interpreters from an AST-like specification.
This makes building bytecode interpreters as simple probably even simpler than building AST interpreters in Truffle.
The generated interpreters automatically come with batteries included:
[...]

[stackoverflow]

I wasn't too keen on this change initially. But the library is tiny and allows us to further improve on performance (not only partial evaluation).
Was discussing some other day with @holzensp exactly about EconomicMaps and how we could improve the performance of some specific use cases, if only we could patch the implementation.
So, I'm for it.

[holzensp]

I also see the benefits (and the low risk, due to the stability of this library). It would require a further update to NOTICE.txt, btw.

[odenix]

It would require a further update to NOTICE.txt, btw.

done