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`):
 +