You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by pa...@apache.org on 2026/08/24 21:15:48 UTC
(groovy) branch master updated: GROOVY-12281: document the soft GroovyClassValue mode in the integration guide
This is an automated email from the ASF dual-hosted git repository.
paulk-asert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/master by this push:
new 56964ab775 GROOVY-12281: document the soft GroovyClassValue mode in the integration guide
56964ab775 is described below
commit 56964ab775786f5be385d4feb2aab9df028813d1
Author: Paul King <pa...@asert.com.au>
AuthorDate: Tue Aug 25 07:06:36 2026 +1000
GROOVY-12281: document the soft GroovyClassValue mode in the integration guide
The class-loader-release section still described two measures and called
the escape hatch's dispatch cost "not measurable". Add the shipped soft
mode as a third measure — ClassValue fast path retained, associations
held softly, non-reconstructible state strong-rooted while in use — and
state the measured escape-hatch numbers (57 classic-dispatch JMH
benchmarks: +4.8% geomean, hot platform-receiver idioms up to ~1.4x,
compile time within 1%) so integrators can decide with their own
workload in mind.
Completes the documentation side of the GROOVY-12281 merge; the guide
wording for the escape hatch matches the quantification recorded on the
groovy12281-investigation branch.
---
src/spec/doc/guide-integrating.adoc | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/src/spec/doc/guide-integrating.adoc b/src/spec/doc/guide-integrating.adoc
index a7f930091f..b5f6efca1c 100644
--- a/src/spec/doc/guide-integrating.adoc
+++ b/src/spec/doc/guide-integrating.adoc
@@ -393,11 +393,23 @@ so an association on a long-lived class such as `String` never releases its valu
holds the Groovy class loader the value belongs to. In a container this shows up as metaspace
growth on every redeployment, even after the old application is undeployed.
-Two supported measures release the class loader; either one suffices:
-
+Three supported measures release the class loader; any one suffices:
+
+* Start the JVM with `-Dgroovy.use.classvalue=soft`. Groovy keeps the `ClassValue` per-class
+ fast path but holds each association through a `SoftReference`, so immortal JDK classes no
+ longer hold a strong chain to the Groovy class loader. Metadata carrying state that cannot
+ be rebuilt — an installed or per-instance metaclass, registry-written extension methods —
+ is strong-rooted while in use, and associations cleared under memory pressure are rebuilt
+ on demand, with call-site guards remaining sound for `invokedynamic` and classic call sites
+ alike. This preserves default-mode dispatch performance while letting the collector reclaim
+ the loader.
* Start the JVM with `-Dgroovy.use.classvalue=false`. Groovy then stores the associations in a
weak-key map instead of `ClassValue`. The trade-off is a hash lookup where `ClassValue` has a
- per-class fast path; for most applications the difference is not measurable.
+ per-class fast path. Compilation speed is unaffected (within 1% in our measurements), and for
+ applications that are not dispatch-heavy the difference is unlikely to be noticed; heavily
+ dynamic code, however, can see a few percent overall, with hot dynamic idioms on JDK-class
+ receivers (string coercions, ranges, safe navigation, map property access) up to roughly
+ 1.4 times slower. Measure with your own workload if dispatch performance matters.
* Clean up explicitly when the application is discarded (for example from
`ServletContextListener#contextDestroyed`):
+