Main

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.

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

   $ 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:

      $ 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

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