Java Variable Handles Demystified

1. Introduction

Java 9 brought a number of new useful features for developers.

One of those is the java.lang.invoke.VarHandle API – representing variable handles – which we’re going to explore in this article.

2. What Are Variable Handles?

Generally, a variable handle is just a typed reference to a variable. The variable can be an array element, instance, or static field of the class.

The VarHandle class provides write and read access to variables under specific conditions.

VarHandles are immutable and have no visible state. What’s more, they cannot be sub-classed.

Each VarHandle has :

• a generic type T, which is the type of every variable represented by this VarHandle
• a list of coordinate types CT, which are types of coordinate expressions, that allow locating variable referenced by this VarHandle

The list of coordinate types may be empty.

The goal of VarHandle is to define a standard for invoking equivalents of java.util.concurrent.atomic and sun.misc.Unsafe operations on fields and array elements.

Those operations are mostly atomic or ordered operations — for example, atomic field incrementation.

3. Creating Variable Handles

To use VarHandle, we need to have variables first.

Let’s declare a simple class with different variables of type int that we’ll use in our examples:

public class VariableHandlesUnitTest {
    public int publicTestVariable = 1;
    private int privateTestVariable = 1;
    public int variableToSet = 1;
    public int variableToCompareAndSet = 1;
    public int variableToGetAndAdd = 0;
    public byte variableToBitwiseOr = 0;
}

3.1. Guidelines and Conventions

As a convention, we should declare VarHandles as static final fields and explicitly initialize them in static blocks. Also, we usually use the uppercase version of the corresponding field name as their name. 

For instance, here’s how Java itself is using VarHandles internally to implement the AtomicReference:

private volatile V value;
private static final VarHandle VALUE;
static {
    try {
        MethodHandles.Lookup l = MethodHandles.lookup();
        VALUE = l.findVarHandle(AtomicReference.class, "value", Object.class);
    } catch (ReflectiveOperationException e) {
        throw new ExceptionInInitializerError(e);
    }
}

Most of the time, we can use the same pattern when using VarHandles.

Now that we know this, let’s move on and see how can we use them in practice.

3.2. Variable Handles for Public Variables

Now we can get a VarHandle for our publicTestVariable using the findVarHandle() method:

VarHandle PUBLIC_TEST_VARIABLE = MethodHandles
  .lookup()
  .in(VariableHandlesUnitTest.class)
  .findVarHandle(VariableHandlesUnitTest.class, "publicTestVariable", int.class);

assertEquals(1, PUBLIC_TEST_VARIABLE.coordinateTypes().size());
assertEquals(VariableHandlesUnitTest.class, PUBLIC_TEST_VARIABLE.coordinateTypes().get(0));

We can see that the coordinateTypes property of this VarHandle isn’t empty and has one element, which is our VariableHandlesUnitTest class.

3.3. Variable Handles for Private Variables

If we have a private member and we need a variable handle for such variable, we can obtain this using the privateLookupIn() method:

VarHandle PRIVATE_TEST_VARIABLE = MethodHandles
  .privateLookupIn(VariableHandlesUnitTest.class, MethodHandles.lookup())
  .findVarHandle(VariableHandlesUnitTest.class, "privateTestVariable", int.class);

assertEquals(1, PRIVATE_TEST_VARIABLE.coordinateTypes().size());
assertEquals(VariableHandlesUnitTest.class, PRIVATE_TEST_VARIABLE.coordinateTypes().get(0));

Here, we chose the privateLookupIn() method which has broader access than the normal lookup(). This allows us to get access to private, public, or protected variables.

Before Java 9, the equivalent API for this operation was the Unsafe class and the setAccessible() method from the Reflection API.

However, this approach has its disadvantages. For example, it will only work for the specific instance of the variable.

VarHandle is a better and faster solution in such cases.

3.4. Variable Handles for Arrays

We could use the previous syntax to obtain array fields.

However, we can also get the VarHandle for an array of a specific type:

VarHandle arrayVarHandle = MethodHandles.arrayElementVarHandle(int[].class);

assertEquals(2, arrayVarHandle.coordinateTypes().size());
assertEquals(int[].class, arrayVarHandle.coordinateTypes().get(0));

We can now see that such VarHandle has two coordinate types int and [], which represent an array of int primitives.

4. Invoking VarHandle Methods

Most of the VarHandle methods expect a variable number of arguments of type Object. Using Object… as an argument disables static argument checking.

All the argument checking is done at runtime. Also, different methods expect to have a different number of arguments of different types.

If we fail to give a proper number of arguments with proper types, the method call will throw a WrongMethodTypeException.

For example, get() will expect at least one argument, which helps to locate variable, but set() expects one more argument, which is the value to be assigned to the variable.

5. Variable Handles Access Modes

Generally, all the methods of the VarHandle class fall to five different access modes.

Let’s go through each of them in the next sub-sections.

5.1. Read Access

Methods with reading access level allow getting the value of the variable under specified memory ordering effects. There are several methods with this access mode like: get(), getAcquire(), getVolatile() and getOpaque().

We can easily use the get() method on our VarHandle:

assertEquals(1, (int) PUBLIC_TEST_VARIABLE.get(this));

The get() method takes only CoordinateTypes as parameters, so we can simply use this in our case.

5.2. Write Access

Methods with writing access level allow us to set the value of the variable under specific memory ordering effects.

Similarly to methods with read access, we have several methods with write access: set(), setOpaque(), setVolatile(), and setRelease().

We can use the set() method on our VarHandle:

VARIABLE_TO_SET.set(this, 15);
assertEquals(15, (int) VARIABLE_TO_SET.get(this));

The set() method expects at least two arguments. The first one will help locate the variable, while the second is the value to be set to the variable.

5.3. Atomic Update Access

Methods with this access level can be used to atomically update the value of the variable.

Let’s use the compareAndSet() method to see the effects:

VARIABLE_TO_COMPARE_AND_SET.compareAndSet(this, 1, 100);
assertEquals(100, (int) VARIABLE_TO_COMPARE_AND_SET.get(this));

Apart from the CoordinateTypes, the compareAndSet() method takes two additional values: oldValue and newValue. The method sets the value of the variable if it was equal to oldVariable or leaves it unchanged otherwise.

5.4. Numeric Atomic Update Access

These methods allow performing numeric operations such as getAndAdd() under specific memory ordering effects.

Let’s see how we can perform atomic operations using a VarHandle:

int before = (int) VARIABLE_TO_GET_AND_ADD.getAndAdd(this, 200);

assertEquals(0, before);
assertEquals(200, (int) VARIABLE_TO_GET_AND_ADD.get(this));

Here, the getAndAdd() method first returns the value of the variable, then adds the provided value.

5.5. Bitwise Atomic Update Access

Methods with this access allow us to atomically perform bitwise operations under specific memory ordering effects.

Let’s see an example of using the getAndBitwiseOr() method:

byte before = (byte) VARIABLE_TO_BITWISE_OR.getAndBitwiseOr(this, (byte) 127);

assertEquals(0, before);
assertEquals(127, (byte) VARIABLE_TO_BITWISE_OR.get(this));

This method will get the value of our variable and perform a bitwise OR operation on it.

The method call will throw an IllegalAccessException if it fails to match the access mode required by the method with the one allowed by the variable.

For example, this will happen if we try to use a set() method on a final variable.

6. Memory Ordering Effects

We previously mentioned that VarHandle methods allow access to variables under specific memory ordering effects.

For most of the methods there are 4 memory ordering effects:

• Plain reads and writes guarantee bitwise atomicity for references and primitives under 32 bits. Also, they impose no ordering constraints with respect to the other traits.
• Opaque operations are bitwise atomic and coherently ordered with respect to access to the same variable.
• Acquire and Release operations obey Opaque properties. Also, Acquire reads will be ordered only after matching Release mode writes.
• Volatile operations are fully ordered with respect to each other.

It’s very important to remember that access modes will override previous memory ordering effects. This means that, for example, if we use get(), it will be a plain read operation, even if we declared our variable as volatile.

Because of that, developers must use extreme caution when they use VarHandle operations.

7. Conclusion

In this tutorial, we presented variable handles and how to use them.

This topic is quite complicated since variable handles aim to allow low-level manipulation and they should not be used unless necessary.