Visit Azul.com Support

@Contended

This tutorial provides a description of Azul Zing Builds of OpenJDK (Zing) advanced tuning use of the @sun.misc.Contended annotation to reduce cache contention across multiple threads.

  • Caution: The suggestions presented in this guide are intended for expert users. Applying these suggestions inappropriately can have unintended consequences on your Java application performance.
    You must use discretion when applying the @Contended annotation.
    Contact your Azul Field Consultant or Azul Customer Support for additional information.

@Contended Overview

The Java SE 8 platform introduced [0] a new annotation called @Contended [1] to reduce "False Sharing" [2],[3],[4]. False sharing is a term to describe performance degradation when several threads are modifying independent variable(s) sharing the same cache line.

@Contended is applied as a conventional Java language annotation to fields in a class. It specifies that some field(s) in an object are probably highly contended across processor cores.

At runtime the VM optimizes field layout. At the VM’s discretion, those fields annotated as contended are given extra padding so they do not share cache lines with other fields that are likely to be independently accessed. This helps to avoid cache contention across multiple threads.

Note

Applying @Contended to a class, field, or group:

  • Does not force the VM to add padding or optimize the field layout in a specific way. Can substantially increase the size of a given object.

  • Because the increase in size can be double or more, use @Contended sparingly.

Zing provides an implementation of this feature for JDK 7.

Using @Contended Annotation

To use the @Contended annotation:

  1. In your Java application, add the @Contended annotation to denote the specific classes and/or their instance fields that are eligible for padding to avoid cache contention. See the following sections for examples. Marking a static field with @Contended is a non-operational (noop) action.

  2. Select and apply the Zing flags and options at your Java application runtime.

Marking a Class as Contended

To mark a class as contended, precede the class with @Contended. In this example, both field1 and field2 are padded from the both sides.

 
@Contended public class ContendedClass { private int field1; private Object field2; }

Marking an Instance Field as Contended

To mark an instance field as contended, precede the field with @Contended. In this example, the padding is applied to field1 only.

 
public class ContendedField { @Contended private int field1; private Object field2; }

Marking Multiple Fields as Contended

To mark multiple fields as contended, precede each field with @Contended. In this example, both fields have separate padding.

 
public class ContendedFields { @Contended private int field1; @Contended private Object field2; }

Marking Groups as Contended

To mark a group as contended, include the optional @Contended parameter in the @Contended annotation to describe the equivalence class for contention group. In this example, The contendedField1 and contendedField2 fields are padded from everything else, but are still densely packed with each other.

 
public class ContendedGroups { @Contended("updater1") private Object contendedField1; @Contended("updater1") private Object contendedField2; @Contended("updater2") private Object contendedField3; private Object plainField5; private Object plainField6; }

Zing @Contended Options

After applying @Contended annotation to your Java application, include the Zing launch and configuration options in your Java command. Zing @Contended options and flags are:

  • To enable (disable) @Contended annotation support.

     
    -XX:+EnableContended [<--default] -XX:-EnableContended
  • To restrict (not restrict) @Contended to trusted classes only. This applies to classes loaded by bootstrap or extension classloaders.

     
    -XX:+RestrictContended [<--default] -XX:-RestrictContended
  • To specify the number of bytes used to pad the fields/classes marked @Contended. Default value is 128. The value must be in between 0 and 8192 (inclusive) and be a multiple of 8.

     
    -XX:ContendedPaddingWidth=128 [<--default]