Welcome to the Shenandoah Project!
Shenandoah is an ultra-low pause time garbage collector that reduces GC pause times by performing more garbage collection work concurrently with the running Java program. CMS and G1 both perform concurrent marking of live objects. Shenandoah adds concurrent compaction.
Build and Run
Shenandoah is under development. There are several ways to try it:
Build the bleeding edge from the JDK 9 source. This would guarantee you run the latest and greatest version. Adding --enable-debug to configure would produce the "fastdebug" build.
Build the JDK 8 backport: same as above, but change "jdk9" to "jdk8u" in the paths above. The advantage is that you don't need to figure out JDK 9 compatibility issues for your application first (although it is a good idea to try JDK 9 now anyway). The downside is, that forest may easily be several months behind the JDK 9 version. If you encounter trouble with JDK 8 version, please try JDK 9 version.
- In some Linux distros, Shenandoah is available within the IcedTea binaries. The caveat is that those may lag behind the current development version even more.
Gentoo ebuilds for IcedTea have Shenandoah USE flag.
Helpful Hints for Early Adopters/Developers
- Shenandoah performance, like the performance of almost all other GCs, depends on heap size. We expect it to perform better in cases when there is enough heap space to accommodate allocations while concurrent phases are running. The time for concurrent phases correlates with the live data set size (LDS) -- the space taken by live data. Therefore, the reasonable heap size is dependent on LDS in the workload: larger LDS-es require proportionally larger heap sizes. For some workloads with minuscule live data sets, 1...2 GB heaps performs well. We routinely test on 4...128 GB heaps on various workloads with up to 80% LDS size. Don't be shy to try different heap sizes to see what fits your workload.
- -Xlog:gc=info would print the individual GC timings. This is not specific to Shenandoah, most recent GCs with JDK 9 Unified Logging would work like that.
- -Xlog:gc+stats would print the summary table on Shenandoah internal timings at the end of the run. This summary table conveys important information about GC performance, and we would almost inevitably ask for one in a performance bug report. It is a good idea to always run with it enabled.
- If you suspect a GC bug, it is a very good idea to run with "fastdebug" builds. These can be produced by adding --enable-debug to configure, and building. Shenandoah asserts a lot of things, and it usually reveals a lot about the issue.
- If you suspect a JIT bug (and there are lots of Shenandoah-specific optimizations), it is a very good idea to try bisect which compiler failed by trying several VM modes: -Xint (interpreter only), -XX:TieredStopAtLevel=1 (C1 only), -XX:-TieredCompilation (interpreter and C2 only), default (interpreter, tiered C1, tiered C2).
- If you suspect a bug in concurrent phases, read/write barriers, etc., try running with -XX:ShenandoahGCHeuristics=passive, which will do the stop-the-world mark-compact GCs only, and avoid doing most of concurrent work.
- GC bugs can be shaken out more quickly with -XX:ShenandoahGCHeuristics=aggressive, which runs back-to-back GCs. Since Shenandoah does most GC heavy-lifting concurrently, this does not block application from executing, although GC would consume much more cycles in this mode and slow the application down.
- Shenandoah supports several options that add even more verifications: -XX:+ShenandoahStoreCheck lets C2 compile machine code that checks that writes happen in tospace only. -XX:+ShenandoahVerify runs verification passes across the heap during collection. -XX:+ShenandoahVerifyOptoBarriers verifies barriers in C2's ideal graph. -XX:VerifyStrictOopOperations performs additional checks to verify that oop comparisons are done correctly (fastdebug only).
Bug reports are welcome at the mailing list.