Shenandoah GC in JDK 13, Part III: Architectures and Operating Systems

In this miniseries, I’d like to introduce a couple of new developments of the Shenandoah GC that are upcoming in JDK 13. This here is about a new architecture and a new operating system that Shenandoah will be working with.

Solaris

Only about a few days ago, Bellsoft contributed a change that allowed Shenandoah to build and run on Solaris. Shenandoah itself has zero operating-system-specific code in it, and is therefore relatively easy to port to new operating systems. In this case, it mostly amounts to a batch of fixes to make the Solaris compiler happy, like removing a trailing comma in enums.

One notable gotcha that we hit was with Solaris 10. Contrary to what later versions of Solaris do, and what basically all relevant other operating systems do, Solaris 10 maps user memory to upper address ranges, e.g. to addresses starting with 0xff… instead of 0x7f. Other operating systems reserve the upper half of the address space to kernel memory. This conflicted with an optimization of Shenandoah’s task queues, which would encode pointers assuming it has some spare space in the upper address range. It was easy enough to disable via build-time-flag, and so Aleksey did. The fix is totally internal to Shenandoah GC and does not affect the representation of Java references in heap. With this change, Shenandoah can be built and run on Solaris 10 and newer (and possibly older, but we haven’t tried). This is not only interesting for folks who want Shenandoah to run on Solaris, but also for us, because it requires the extra bit of cleanliness to make non-mainline toolchains happy.

The changes for Solaris support are already in JDK 13 development repositories, and are in-fact already backported to Shenandoah’s JDK 11 and JDK 8 backports repositories.

x86_32

Shenandoah used to support x86_32 in “passive” mode long time ago. This mode relies only on stop-the-world GC to avoid implementing barriers (basically, runs Degenerated GC all the time). It was an interesting mode to see the footprint numbers you can get with uncommits and slimmer native pointers with really small microservice-size VMs. This mode was dropped before integration upstream, because many Shenandoah tests expect all heuristics/modes to work properly, and having the rudimentary x86_32 support was breaking tier1 tests. So we disabled it.

Today, we have significantly simplified runtime interface thanks to load-reference-barriers and elimination of separate forwarding pointer slot, and we can build the fully concurrent x86_32 on top of that. This allows us to maintain 32-bit cleanness in Shenandoah code (we have fixed >5 bugs ahead of this change!), plus serves as proof of concept that Shenandoah can be implemented on 32-bit platforms. It is interesting in scenarios where the extra footprint savings are important like in containers or embedded systems. The combination of LRB+no more forwarding pointer+32bit support gives us the current lowest bounds for footprint that would be possible with Shenandoah.

The changes for x86_32 bit support are done and ready to be integrated into JDK 13. However, they are currently waiting for the elimination-of-forwarding-pointer change, which in turn is waiting for a nasty C2 bug fix. The plan is to later backport it to Shenandoah JDK 11 and JDK 8 backports – after load-reference-barriers and elimination-of-forwarding-pointer changes have been backported.

Other arches and OSes

With those two additions to OS and architecturs support, Shenandoah will soon be available (e.g. known to build and run) on four operating systems: Linux, Windows, MacOS and Solaris, plus 3 architectures: x86_64, arm64 and x86_32. Given Shenandoah’s design with zero OS specific code, and not overly complex architecture-specific code, we may be looking at more OSes or architectures to join the flock in future releases, if anybody finds it interesting enough to implement.

As always, if you don’t want to wait for releases, you can already have everything and help sort out problems: check out The Shenandoah GC Wiki.

Advertisements

Shenandoah GC in JDK 13, Part II: Eliminating Forward Pointer Word

In this miniseries, I’d like to introduce a couple of new developments of the Shenandoah GC that are upcoming in JDK 13. The change I want to talk about here addresses another very frequent, perhaps *the* most frequent concern about Shenandoah GC: the need for an extra word per object. Many believe this is a core requirement for Shenandoah, but it is actually not, as you would see below.

Let’s first look at the usual object layout of an object in the Hotspot JVM:

 0: [mark-word  ]
 8: [class-word ]
16: [field 1    ]
24: [field 3    ]
32: [field 3    ]

Each section here marks a heap-word. That would be 64 bits on 64 bit architectures and 32 bits on 32 bit architectures.

The first word is the so-called mark-word, or header of the object. It is used for a variety of purposes: it can keep the hash-code of an object, it has 3 bits that are used for various locking states, some GCs use it to track object age and marking status, and it can be ‘overlaid’ with a pointer to the ‘displaced’ mark, to an ‘inflated’ lock or, during GC, the forwarding pointer.

The second word is reserved for the klass-pointer. This is simply a pointer to the Hotspot-internal data-structure that represents the class of the object.

Arrays would have an additional word next to store the arraylength. What follows afterwards is the actual ‘payload’ of the object, i.e. fields and array elements.

When running with Shenandoah enabled, the layout would look like this instead:

-8: [fwd pointer]
 0: [mark-word  ]
 8: [class-word ]
16: [field 1    ]
24: [field 3    ]
32: [field 3    ]

The forward pointer is used for Shenandoah’s concurrent evacuation protocol:

  • Normally it points to itself -> the object is not evacuated yet
  • When evacuating (by the GC or via a write-barrier), we first copy the object, then install new forwarding pointer to that copy using an atomic compare-and-swap, possibly yielding a pointer to an offending copy. Only one copy wins.
  • Now, the canonical copy to read-from or write-to can be found simply by reading this forwarding pointer.

The advantage of this protocol is that it’s simple and cheap. The cheap aspect is important here, because, remember, Shenandoah needs to resolve the forwardee for every single read or write, even primitive ones. And using this protocol, the read-barrier for this would be a single instruction:

mov %rax, (%rax, -8)

That’s about as simple as it gets.

The disadvantage is obviously that it requires more memory. In the worst case, for objects without any payload, one more word for otherwise two-word object. That’s 50% more. With more realistic object size distributions, you’d still end up with 5%-10% more overhead, YMMV. This also results in reduced performance: allocating the same number of objects would hit the ceiling faster than without that overhead, prompting GCs more often, and therefore reduce throughput.

If you’ve read the above paragraphs carefully, you will have noticed that the mark-word is also used/overlaid by some GCs to carry the forwarding pointer. So why not do the same in Shenandoah? The answer is (or used to be), that reading the forwarding pointer requires a little more work. We need to somehow distinguish a true mark-word from a forwarding pointer. That is done by setting the lowest two bits in the mark-word. Those are usually used as locking bits, but the combination 0b11 is not a legal combination of lock bits. In other words: when they are set, the mark-word, with the lowest bits masked to 0, is to be interpreted as forwarding pointer. This decoding of the mark word is significantly more complex than the above simple read of the forwarding pointer. I did in-fact build a prototype a while ago, and the additional cost of the read-barriers was prohibitive and did not justify the savings.

All of this changed with the recent arrival of load reference barriers:

  • We no longer require read-barriers, especially not on (very frequent) primitive reads
  • The load-reference-barriers are conditional, which means their slow-path (actual resolution) is only activated when 1. GC is active and 2. the object in question is in the collection set. This is fairly infrequent. Compare that to the previous read-barriers which would be always-on.
  • We no longer allow any access to from-space copies. The strong invariant guarantees us that we only ever read from and write to to-space copies.

Two consequences of these are: the from-space copy is not actually used for anything, we can use that space to put the forwarding pointer, instead of reserving an extra word for it. We can basically nuke the whole contents of the from-space copy, and put the forwarding pointer anywhere. We only need to be able to distinguish between ‘not forwarded’ (and we don’t care about other contents) and ‘forwarded’ (the rest is forwarding pointer).

It also means that the actual mid- and slow-paths of the load-reference-barriers are not all that hot, and we can easily afford to do a little bit of decoding there. It amounts to something like (in pseudocode):

oop decode_forwarding(oop obj) {
  mark m = obj->load_mark();
  if ((m & 0b11) == 0b11) {
    return (oop) (m & ~0b11);
  } else {
    return obj;
  }
}

While this looks noticably more complicated than the above simple load of the forwarding pointer, it is still basically a free lunch because it’s only ever executed in the not-very-hot mid-path of the load-reference-barrier. With this, the new object layout would be:

  0: [mark word (or fwd pointer)]
  8: [class word]
 16: [field 1]
 24: [field 2]
 32: [field 3]

Doing so has a number of advantages:

  • Obviously, it reduces Shenandoah’s memory footprint by putting away with the extra word.
  • Not quite as obviously, this results in increased throughput: we can now allocate more objects before hitting the GC trigger, resulting in fewer cycles spent in actual GC.
  • Objects are packed more tightly, which results in improved CPU cache pressure.
  • Again, the required GC interfaces are simpler: where we needed special implementations of the allocation paths (to reserve and initialize the extra word), we can now use the same allocation code as any other GC

To give you an idea of the throughput improvements: all the GC sensitive benchmarks that I have tried showed gains between 10% and 15%. Others benefited less or not at all, but that is not surprising for benchmarks that don’t do any GC at all. But it is important to note that the extra decoding cost does not actually show up anywhere, it is basically negligible. It probably would show up on heavily evacuating workloads. But most applications don’t evacuate that much, and most of the work is done by GC threads anyway, making midpath decoding cheap enough.

The implementation of this has recently been pushed to the shenandoah/jdk repository. We are currently shaking out one last known bug, and then it’s ready to go upstream into JDK 13 repository. The plan is to eventually backport it to Shenandoah’s JDK 11 and JDK 8 backports repositories, and from there into RPMs. If you don’t want to wait, you can already have it: check out The Shenandoah GC Wiki.

Shenandoah GC in JDK 13, Part I: Load Reference Barriers

In this miniseries, I’d like to introduce a couple of new developments of the Shenandoah GC that are upcoming in JDK 13. Perhaps the most significant, even though not directly user-visible, change is the switch of Shenandoah’s barrier model to load reference barriers. It resolves one major point of criticism against Shenandoah, that is their expensive primitive read-barriers.

Shenandoah (as well as other collectors) employ barriers in order to ensure heap consistency. More specifically, Shenandoah GC employs barriers to ensure what we call ‘to-space-invariant’. What it means is this: when Shenandoah is collecting, it is copying objects from so-called ‘from-space’ to ‘to-space’, and it does so while Java threads are running (concurrently). This means that there may be two copies of any object floating around in the JVM. In order to maintain heap consistency, we need to ensure either of:

  • writes happen into to-space copy + reads can happen from both copies, subject to memory model constraints = weak to-space invariant

  • writes and reads always happen into/from the to-space copy = strong to-space invariant

And the way we ensure that is by employing the corresponding type of barriers whenever reads and writes happen. Consider this pseudocode:

void example(Foo foo) {
  Bar b1 = foo.bar;             // Read
  while (..) {
    Baz baz = b1.baz;           // Read
    b1.x = makeSomeValue(baz);  // Write
}

Employing the Shenandoah barriers, it would look like this (what the JVM+GC would do under the hood):

void example(Foo foo) {
  Bar b1 = readBarrier(foo).bar;             // Read
  while (..) {
    Baz baz = readBarrier(b1).baz;           // Read
    X value = makeSomeValue(baz);
    writeBarrier(b1).x = readBarrier(value); // Write
}

I.e. whereever we read from an object, we first resolve the object via a read-barrier, and wherever we write to an object, we possibly copy the object to to-space. I won’t go into the details of this here, let’s just say that both operations are somewhat costly. Notice also that we need a read-barrier on the value of the write here to ensure we only ever write to-space-references into fields while heap references get updated (another nuisance of Shenandoah’s old barrier model).

Seeing that those barriers are a costly affair, we worked quite hard to optimize them. A very important optimization is to hoist barriers out of loops. We see that b1 is defined outside the loop, but only used inside the loop. We can just as well do the barriers outside the loop, once, instead of many times inside the loop:

void example(Foo foo) {
  Bar b1 = readBarrier(foo).bar;  // Read
  Bar b1' = readBarrier(b1);
  Bar b1'' = writeBarrier(b1);
  while (..) {
    Baz baz = b1'.baz;            // Read
    X value = makeSomeValue(baz);
    b1''.x = readBarrier(value);  // Write
}

And because write-barriers are stronger than read-barriers, we can fold the two up:

void example(Foo foo) {
  Bar b1 = readBarrier(foo).bar; // Read
  Bar b1' = writeBarrier(b1);
  while (..) {
    Baz baz = b1'.baz;           // Read
    X value = makeSomeValue(baz);
    b1'.x = readBarrier(value);  // Write
}

This is all nice and works fairly well, but it is also troublesome: the optimization passes for this are very complex. The fact that both from-space and two-space-copies of any objects can float around the JVM at any time is a major source of headaches and complexity. For example, we need extra barriers for comparing objects in case we compare an object to a different copy of itself. Read-barriers and write-barriers need to be inserted for *any* read or write, including primitive reads or writes. And those are very frequent, especially reads.

So why not short-cut this, and strongly ensure to-space-invariance right when an object is loaded from memory? That is where load-reference-barriers come in. They work mostly like our previous write-barriers, but are not employed at use-sites (when reading from or storing to the object), but instead much earlier when objects are loaded (at their definition-site):

void example(Foo foo) {
  Bar b1' = loadReferenceBarrier(foo.bar);
  while (..) {
    Baz baz = loadReferenceBarrier(b1'.baz); // Read
    X value = makeSomeValue(baz);
    b1'.x = value;                           // Write
}

You can see that the code is basically the same as before – after our optimizations- , except that we didn’t need to optimize anything yet. Also, the read-barrier for the store-value is gone, because we now know (because of the strong to-space-invariant) that whatever makeSomeValue() did, it must already have employed the load-reference-barrier if needed. The new load-reference-barrier is almost 100% the same as our previous write-barrier.

The advantages of this barrier model are many (for us GC developers):

  • Strong invariant means it’s a lot easier to reason about the state of GC and objects
  • Much simpler barrier interface. Infact, a lot of stuff that we added to GC barrier interfaces after JDK11 will now become unused: no need for barriers on primitives, no need for object equality barriers, etc.
  • Optimization is much easier (see above). Barriers are naturally placed at the least-hot locations: their def-sites, instead of their most-hot locations: their use-sites, and then attempted to optimize them away from there (and not always successfully).
  • No more need for object equals barriers
  • No more need for ‘resolve’ barriers (a somewhat exotic kind of barriers used mostly in intrinsics and places that do read-like or write-like operations)
  • All barriers are now conditional, which opens up opportunities for further optimization later on
  • We can re-enable a bunch of optimizations like fast JNI getters that needed to be disabled before because they did not play well with possible from-space references

For users, this is mostly invisible, and the bottom line is that this improves overall Shenandoah’s performance. It also opens the way for follow-up improvements like elimination of the forwarding pointer, which I’ll get to in a follow-up article.

Load reference barriers have been integrated into JDK 13 development repository in April 2019. We will start backporting it to Shenandoah’s JDK 11 and JDK 8 backports soon. If you don’t want to wait, you can already have it: check out The Shenandoah GC Wiki.

Introducing Shenandoah Traversal mode – part I

In this post I want to introduce a (not so very) new GC mode that we call “Traversal GC”. It all started over a year ago when I implemented the ‘partial’ mode. The major feature of the partial mode is that it can concurrently collect a part of the heap, without the need to traverse all live objects, hence the name partial GC. I will go into details of how that works in a later post. First I would like to explain another foundation of Shenandoah’s partial GC, which is the single-traversal-GC, or short Traversal GC.

Let me first show some pictures that explain how Shenandoah works (and in-fact, more or less how other collectors work):

Shenandoah usually runs in one of two modes (switched dynamically depending on automatic ergonomic decisions): First the 3-phase mode:

The cycles are:

  1. Concurrent mark: traversal all live objects, starting from roots, and mark each visited object as live.
  2. Concurrent evacuation: based on liveness information from concurrent marking, select a number of regions, compact all live objects in that region into fresh regions.
  3. Concurrent update-refs: scan all live objects and update their references to point to the new copies of the compacted objects.

Each concurrent phase is book-ended by a stop-the-world phase to safely scan GC roots (thread stacks) and do some housekeeping. That makes 4 (very short, but still measurable) pauses during which no Java thread can make progress.

When GC pressure is high, and GC cycles run close to back-to-back, Shenandoah switches to 2-phase operation. The idea is to skip concurrent update-refs phase, and instead piggy-back it on subsequent concurrent marking cycle:

In other words, we now have:

  1. Concurrent mark: traversal all live objects, starting from roots, and mark each visited object as live. At the same time, when encountering references to from-space, update the to point to the to-space copy.
  2. Concurrent evacuation: based on liveness information from concurrent marking, select a number of regions, compact all live objects in that region into fresh regions.

As before, we still have pauses before and after each phase, now totalling 3 stop-the-world pauses per cycle.

Can we do better? Turns out that we can:

Now we only have one concurrent phase during which we:

  1. Visit each live object, starting from roots
  2. When encountering an object that is in the collection-set, evacuate it to a fresh compaction region
  3. Update all references to point to the new copies.

The single concurrent phase is book-ended by 2 very short stop-the-world phases.

This probably sounds easy and obvious, but the devil lies, as usual, in some interesting details:

  • How to select the collection-set? We have no liveness information when we start traversing.
  • How to ensure consistencies:
    • Traversal consistency: how to deal with changing graph shape during traversal
    • Data consistency: how to ensure writes go to the correct copy of objects, how to ensure reads don’t read stale data, etc
    • Update consistency: how to avoid races between updating of references and ordinary field updates

I will go into those details in a later post.

If you’re interested in trying out the traversal mode, it’s all already in Shenandoah (jdk10, jdk11 and dev branches) and stable enough to use. Simply pass -XX:ShenandoahGCHeuristics=traversal in addition to the usual -XX:+UseShenandoahHeap on the command line. More information about how to get and run Shenandoah GC can be found in our Shenandoah wiki.

How to set up Conversations as alternative to WhatsApp

Note: this article is also available in German.

What is Conversations?

Conversations is an app for Android Smartphones for sending each other messages, pictures, etc, much like WhatsApp. However, there are a number of important differences to WhatsApp:

  • Conversations does not use your phone number for identification, and doesn’t read your address book to find contacts. It uses an ID that looks much like an email address (the so-called Jabber-ID), and you can find contacts by exchanging Jabber-IDs with people, just like you do with email addresses, phone numbers, etc.
  • Conversations uses an open protocol called XMPP, that is used by many other programs on a wide range of systems, for example on desktop PCs.
  • Converations is Open Source, i.e. everybody can inspect the source code, check it for security issues, see what the program actually does, or even modify and distribute it.
  • XMPP builds on a decentralized infrastructure. This means that not one company is in control of it, but instead there are many providers, or you can even run your own server if you want.
  • Conversations does not collect and sell any information from you or your contacts.

There are more differences, but I don’t want to go into detail here, others have already done it, and better (German).

Install Conversations

From Google Play

Conversations is easily installed from Google Play. However, it currently costs 2,39€. I’d recommend everybody who can to buy the it, it supports development of this really good app.

Alternative: From F-Droid

For all those who cannot or don’t want to spend the money, there is another way to get it for free. It is available in the F-Droid. It is an alternative app store, that only distributes Open Source software. In order to do that, you first need to install F-Droid. Then you can start F-Droid and search for Conversations and install it.

Set-up Jabber account

Next step is to set up a Jabber account. You need two things: an ID, and a provider. The first part, the ID, you can choose freely, e.g. a fantasy name or something like firstname.surname, but this is really up to you. In order to find a provider, I recommend this list https://gultsch.de/compliance_ranked.html. The providers at the top of the list have best support for the XMPP features that are relevant for smartphone users. I’d recommend trashserver.net because this supports in-band registration (directly from Conversations) and is very well maintained. If you want to further support the developer of Conversations, I’d recommend an account on conversations.im, this currently costs 8€/year. I think it is worth it, but you have the choice.

If you choose, for example, the ID ‘joe.example’ on the provider ‘provider.org’, then your Jabber-ID is joe.example@provider.org. When you’re decided on a Jabber-ID, you can easily register an account by starting Conversations, entering the Jabber-ID in the set-up screen, check the box ‘register new account on server’, enter your preferred password 2x and confirm it.

Adding contacts

Adding contacts is different than WhatsApp. You have to manually add contacts to your roster. Tap on the ‘+’ symbol next to the little people icon, enter your contact’s Jabber-ID and confirm it. Now you’re ready to start chatting. Have fun!

Conversations mit Jabber als Alternative zu WhatsApp einrichten

Diesen Artikel gibt es auch in Englisch.

Was ist Conversations?

Conversations ist eine App für Android Smartphones, mit der man sich gegenseitig Nachrichten, Bilder, etc schicken kann, sehr ähnlich wie WhatsApp. Es gibt allerdings ein paar wichtige Unterschiede zu WhatsApp:

  • Conversations verwendet nicht Deine Telefon-Nummer zur Identifikation, und nicht Dein Adressbuch um Kontakte zu finden. Deine ID sieht aus wie eine Email-Adresse (Deine sogenannte Jabber-ID), und Kontakte findest Du indem Du Deine Jabber-ID mit Bekannten austauschst, genau wie bei Email-Adressen oder Telefonnummern auch.
  • Conversations benutzt ein offenes Protokoll, genannt XMPP, das von vielen anderen Programmen auf vielen verschiedenen Systemen genutzt werden kann, z.B. auch auf Desktop PCs.
  • Conversations ist Open Source, d.h. jeder kann den Quellcode einsehen, und z.B. auf Sicherheitsprobleme überprüfen, oder sich vergewissern was das Programm eigentlich macht, oder es ändern, etc.
  • XMPP baut auf eine dezentrale Infrastruktur, das bedeutet daß nicht ein Unternehmen alles kontrolliert, sondern daß es viele verschiedene Anbieter gibt, oder man z.B. selbst entsprechende Server betreiben kann, wenn man möchte.
  • Conversations sammelt und verkauft keinerlei Informationen über Dich und Deine Kontakte.

Es gibt noch einige andere Unterschiede, aber ich will hier nicht im Detail darauf eingehen, das haben andere schon viel besser getan.

Conversations installieren

Von Google Play

Conversations lässt sich ganz einfach von Google Play installieren. Es kostet dort allerdings momentan 2,39€. Ich möchte allen, die die Möglichkeit haben empfehlen, die App zu kaufen, ihr unterstützt damit die Entwicklung dieser wirklich guten App.

Alternative: Von F-Droid

Allen, die Google Play nicht nutzen können, oder die aus welchen Gründen auch immer nicht 2,39€ dafür zahlen können oder möchten, sei die Installation über F-Droid ans Herz gelegt. F-Droid ist ein alternativer App Store, der aussschliesslich Open Source Software bereitstellt. Dazu muss man sich zunächst F-Droid installieren. Dann kann man in der F-Droid App nach ‘Conversations’ suchen, und dort installieren. Das ist kostenlos und legal.

Jabber-Account einrichten

Als nächstes musst Du einen Jabber Account einrichten. Dazu benötigst Du zwei Dinge: eine ID, und einen Anbieter. Den ersten Teil, die ID, kannst Du selbst wählen, z.B. einen Phantasienamen, oder etwas wie vorname.nachname, aber das ist wirklich Dir überlassen. Um einen Anbieter zu finden, empfehle ich diese Liste: https://gultsch.de/compliance_ranked.html. Die Anbieter ganz oben unterstützen die meisten Features die für Smartphone-Nutzer wichtig sind. Ich kann trashserver.net empfehlen, da dieser Server die Registrierung direkt aus der Conversations-App heraus unterstützt, und auch sonst sehr gut gewartet wird. Wenn Du dem Entwickler von Conversations zusätzlich Unterstützung zukommen lassen möchtest, dann ist ein Account auf conversations.im empfehlenswert, dies kostet aber momentan 8 Euro im Jahr. Ich finde, das ist es wert, aber das muss jeder selbst entscheiden.

Wenn Du z.B. die ID ‘max.mustermann’ auf dem Anbieter ‘anbieter.de’ aussuchst, ist Deine Jabber-ID: max.mustermann@anbieter.de . Wenn Du Dich für eine ID und einen Anbieter entschieden hast, dann kannst Du ganz einfach einen Account einrichten, indem Du Conversations startest und im Einrichtungs-Bildschirm die gewünschte Jabber-ID eingibst, das Häkchen bei ‘Neues Konto auf Server erstellen’ aktivierst, Dein gewünschtest Passwort 2x eingibst und dann auf ‘Weiter’ tippst.

Kontakte hinzufügen

Anders als in WhatsApp musst Du in Conversations Deine Kontakte selbst hinzufügen. Dazu einfach auf das Symbol mit dem ‘+’ neben Männchen tippen, die Jabber-ID des Kontaktes eingeben, fertig. Und dann kannst Du loschatten! Viel Spaß!

Shenandoah GC in Fedora 24

About a month ago, Fedora 24 has been released. This is an important milestone for Christine and myself, because it includes Shenandoah in its Java VM by default. We consider this our first official release!

If you want to try it out, it’s very simple: pass -XX:+UseShenandoahGC at the cmd line, and your favorite application runs with Shenandoah!

Please report back any issues that you find to the shenandoah-dev mailing list.