InvokeDynamic support

The Groovy distribution comes with two jars:

As Groovy core and the Groovy modules are sometimes written in Groovy, we currently have no choice but to distribute two distinct versions of Groovy. This means that if you pick the "normal" jar, the Groovy classes of Groovy itself are compiled with call site caching (1.6+), while if you use the "indy" jar, the Groovy classes of Groovy itself are compiled using invokedynamic.

Both jars contain a fully working Groovy implementation that is capable of compiling user supplied Groovy sources using either invokedynamic or call site caching. The sets of jars are mutually exclusive (don’t put both on classpath) and the key difference between them has to do with how the Groovy source files that make up Groovy itself are compiled.

If you download the distribution and use the command line, it’s always the "normal" version of Groovy which is picked up in classpath. This means that whatever command you use (groovy, groovyc, groovysh or groovyConsole), invokedynamic support is not available out of the box. To use a Groovy distribution that was compiled with invokedynamic for its Groovy sources you have to switch the jars manually. The distribution makes use of the jars in the lib directory, while the indy jars are available in the indy directory. You have three things to do:

Here’s a bash script that would do it all at once:

Each dynamic call site is linked lazily. Normally even the first calls at a site run through a fully guarded MethodHandle chain, so nothing but hidden LambdaForm frames sits between the calling method and the target. The reflective cold tier (groovy.indy.cold.reflection) instead dispatches plain instance method calls through java.lang.reflect.Method.invoke until the site has been hit groovy.indy.optimize.threshold times (default 1000), and only then builds the MethodHandle chain. It saves the one-time LambdaForm cost of shapes that are never hot.

The default depends on where the site links:

Setting the property explicitly overrides the default in either environment:

The property is read once when IndyInterface initialises, so pass it on the command line rather than setting it from code.

JDK 25 can archive the classes an application loads and links, together with the lambda and string concatenation call sites in them, into an AOT cache (JEP 514, building on JEP 483) that later runs map in instead of loading, verifying and linking the same classes again. Groovy’s runtime is a good candidate: a dynamic program links a few thousand runtime classes before it does any work. Nothing in Groovy needs configuring; the recipe is the JDK’s own:

Three constraints come from the JDK. The class path must consist of jars: a populated directory makes the training run fail with Cannot have non-empty directory in paths. The same jars, unchanged, must be on the class path when the cache is used, and a mismatch makes the JVM silently run without it; add -XX:AOTMode=on to turn that into an error, or -Xlog:aot to see why. And classes the Groovy compiler defines at run time, a script run through the groovy command or code compiled by GroovyShell, cannot be archived, so compile the application with groovyc and put the classes in a jar for the cache to cover it. JDK 24 needs the two-step form, -XX:AOTMode=record -XX:AOTConfiguration=app.aotconf for the training run followed by -XX:AOTMode=create -XX:AOTConfiguration=app.aotconf -XX:AOTCache=app.aot -XX:+AOTClassLinking.

What the cache does for a Groovy program, measured on the small dynamic program the build uses to check native images: nearly every class comes from the cache rather than the jars, the hidden classes for the lambdas in the runtime’s own classes come with them, and startup plus run drops by roughly 40%. What it does not do: Groovy’s dynamic call sites are bootstrapped by IndyInterface, and JDK 25 archives only call sites the JDK’s own bootstrap methods link, so every dynamic site still links on its first call in each run, with the method selection and the MethodHandle chain built then. Those chains are the LambdaForm classes a run with the cache still spins. The reflective cold tier makes no measurable difference to that, so its default can stay.

Every method Groovy adds to the JDK classes (the default Groovy methods, or DGM) is dispatched through a small generated adapter class, org.codehaus.groovy.runtime.dgm$N, about two thousand of them, created the first time the method is selected. A generated factory constructs them directly, so nothing in this path is reflective: on a JVM the first use of a DGM method costs a switch and a constructor call, and in a GraalVM native image the adapters need no reflection metadata because static analysis reaches all of them through the factory. That is the default, and it means every adapter is part of the image whether the application uses it or not, at a cost of a few megabytes.

The groovy.dgm.factory property turns the factory off, in which case adapters are resolved by class name with reflection, as they were before Groovy 6. In a native image that makes the factory, and with it every adapter the image does not otherwise know about, disappear: only the adapters the native-image agent recorded are kept. The image is smaller, but a DGM method the agent run did not exercise fails at run time with ClassNotFoundException. The switch is evaluated at image build time, so pass it to native-image rather than to the application:

Groovy ships the native-image.properties that makes this work; nothing else is needed. On a JVM the property is read once at start-up and only changes how an adapter is created the first time it is used, so there is no reason to set it there.

Groovy 6 needs GraalVM for JDK 25.0.4 or later. Earlier releases carry a built-in substitution for Groovy’s invokedynamic support that targets a method Groovy 6 no longer has, and native-image fails with Could not find target method …​ IndyInterface_invalidateSwitchPoints before it reads any metadata; their agent also writes the older split configuration files rather than the single reachability-metadata.json.

Besides the adapters, the groovy jar carries reachability metadata for what the runtime does on its own behalf, under META-INF/native-image/org.apache.groovy/groovy/, where native-image and the GraalVM build plugins pick it up automatically. The build generates it from what the runtime is known to do rather than from an agent recording:

Each Groovy module that registers extension methods through a descriptor (groovy-nio, groovy-xml, groovy-dateutil, groovy-datetime, groovy-sql, groovy-swing, groovy-jsr223, groovy-ginq, groovy-macro and groovy-macro-library) ships the equivalent for itself under META-INF/native-image/org.apache.groovy/<module>/: the extension classes the registry loads by name and scans, and the types in their signatures. groovy-xml adds what FactorySupport does for every XML user: the JAXP factory lookups, a ServiceLoader resource read that an exact-mode image must allow even though the JDK ships no such file, and the JDK’s default implementations it then instantiates by name. groovy-json ships only the ServiceLoader-loaded string service its parser uses. groovy-concurrent-java, which repackages the async runtime for use without the groovy jar, carries that runtime’s entries so a pure-Java image gets them too. Modules that reflect over nothing but the application’s data, groovy-http-builder among them, need none.

Every entry is conditional on the class that performs the access being reached, so an image pays only for what it uses; a statically compiled program that never links a dynamic call site carries none of the invokedynamic entries. Reflection over the application’s classes and the JDK types it uses dynamically, Groovy API classes it calls dynamically, java.lang.reflect.Proxy instances for closures coerced to interfaces, and serialization depend on the application, and the native-image agent remains the way to record them. Run the agent with -Dgroovy.indy.aot.link=true, which makes the JVM link call sites as the image will: the image dispatches through the reflective cold tier, which creates metaclasses a JIT-linked call site never touches, and a recording made without the property misses them. One thing the agent does not see either way: a closure passed where a dynamic call expects a single-abstract-method interface is coerced through a method handle, so the proxy entry for that interface ({"type": {"proxy": ["java.util.function.Function"]}}) has to be added by hand, or the call fails with MissingMethodException in the image. The same applies to a method pointer such as Integer::sum passed as a functional interface, and the JDK’s Gatherer factories take up to four such closures at once.

A recording made with the agent contains Groovy’s own needs alongside the application’s, and it is tempting to drop everything in a Groovy package to leave only the application’s share. Do not filter by package name: keep an entry unless the metadata the Groovy jars ship covers that type and its members. Two kinds of entry are the application’s even though their names look like Groovy’s: third-party libraries that live in groovy.* packages, such as an extension module’s extension class loaded by name, and Groovy API classes the application itself reaches reflectively, such as groovy.servlet.GroovyServlet constructed from dynamic code. The build’s native probe (subprojects/tests-native) shows the coverage check in updateProbeMetadata.

The JDK side of the type hierarchies is the one of the JDK Groovy was built with, plus the sequenced collection interfaces JDK 21 added. That only matters under --exact-reachability-metadata, where a supertype a later JDK introduces above a JDK type would have to be registered by the application.