Page History

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:

1. 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.

   Code Block
   language bash
   $ hg clone http://hg.openjdk.java.net/shenandoah/jdk9 shenandoah-jdk9 $ cd shenandoah-jdk9/ $ sh ./get_sources.sh $ sh ./configure $ make images $ build/linux-x86_64-normal-server-release/images/jdk/bin/java -XX:+UseShenandoahGC -Xlog:gc [...][info][gc] Using Shenandoah

2. 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. 

   Code Block
   language bash
   $ hg clone http://hg.openjdk.java.net/shenandoah/jdk8u shenandoah-jdk8u $ cd shenandoah-jdk8u/ $ sh ./get_sources.sh $ sh ./configure $ make images $ build/linux-x86_64-normal-server-release/j2sdk-image/bin/java -XX:+UseShenandoahGC -version openjdk version "1.8.0-internal" OpenJDK Runtime Environment (build 1.8.0-internal-shade_2016_12_19_15_52-b00) OpenJDK 64-Bit Server VM (build 25.71-b00, mixed mode)

3. Pick up the binary build from AdoptOpenJDK (jdk8, jdk9 – look at the publish dates, the builds might be outdated), or others (e.g. builds.shipilev.net).
    

4. 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.
   
   

   1. Fedora 24/25:

      Code Block
      language bash
      $ cat /etc/redhat-release Fedora release 25 (Twenty Five) $ java -XX:+UseShenandoahGC -version OpenJDK 64-Bit Server VM warning: Compressed Oops not supported with ShenandoahGC openjdk version "1.8.0_111" OpenJDK Runtime Environment (build 1.8.0_111-b16) OpenJDK 64-Bit Server VM (build 25.111-b16, mixed mode)

   2. 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.
   
• Many odd performance potholes are solved by giving the collector enough heap. Try to see how GC performs on different heap sizes.
• -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.

Resources

• Shenandoah Project
• Repositories
• Mailing list: shenandoah-dev
• Members