Signature Polymorphic

The methods for access modes in VarHandle are signature polymorphic. Even though all these methods have the same signature of Object methodName(Object... args), a runtime check is done to make sure the runtime types of arguments match the requirements of the access modes. If the argument matching fails, JVM throws a java.lang.invoke.WrongMethodTypeException. Because the compiler doesn’t check the arity and types of arguments statically, it’s the developers’ responsibility to make sure that the correct number of arguments with the correct types are passed when invoking those methods.

The list of arguments consists of between zero and many objects of coordinate types and optional arguments that are required by different access modes:

• These coordinate types are used to locate the variable you want to access. For example, when accessing an element in the array, the coordinate types are the type of the array and the type of the array index. You can use the method List<Class<?>> coordinateTypes() of VarHandle to get the list of coordinate types.

• Different access modes may require extra arguments. For example, the method compareAndSet() requires the expected value to compare and the new value to set.

These access modes can be grouped into five categories: read access, write access, atomic update, numeric atomic update, and bitwise atomic update. The class HandleTarget in Listing 8-4 contains different static variables for testing. I’ll use these variables in following sections.

Listing 8-4. HandleTarget for Testing

public class HandleTarget {
    public int count = 1;

    public String[] names = new String[]{"Alex", "Bob", "David"};

    public byte[] data = new byte[]{1, 0, 0, 0, 1, 0, 0, 0};

    public ByteBuffer dataBuffer = ByteBuffer.wrap(this.data);
}

Now let’s discuss all five categories of methods.

Read Access

This category includes the get(), getVolatile(), getOpaque(), and getAcquire() methods with memory ordering effects specified by the suffix. The method get() has th e plain memory ordering effect (see Table 8-1). Listing 8-5 shows the usage of different read access methods. The variable handle varHandle references the variable count in the class HandleTarget of Listing 8-4. Because the test case is not multithreaded, all these read access modes return the same result.

Listing 8-5. Read Access

public class VarHandleTest {

  private HandleTarget handleTarget = new HandleTarget();
  private VarHandle varHandle;

  @Before
  public void setUp() throws Exception {
    this.handleTarget = new HandleTarget();
    this.varHandle = MethodHandles
        .lookup()
        .findVarHandle(HandleTarget.class, "count", int.class);
  }

  @Test
  public void testGet() throws Exception {
    assertEquals(1, this.varHandle.get(this.handleTarget));
    assertEquals(1, this.varHandle.getVolatile(this.handleTarget));
    assertEquals(1, this.varHandle.getOpaque(this.handleTarget));
    assertEquals(1, this.varHandle.getAcquire(this.handleTarget));
  }
}

All these read access methods only require one parameter, which is the target object that contains this variable. The class HandleTarget is the only coordinate type.

Write Access

This category includes the set(), setVolatile(), setOpaque(), and setRelease() methods with memory ordering effects specified by the suffix. The method set() has the plain memory ordering effect (see Table 8-1). Listing 8-6 shows the usage of different write access methods.

Listing 8-6. Write Access

@Test
public void testSet() throws Exception {
  final int newValue = 2;
  this.varHandle.set(this.handleTarget, newValue);
  assertEquals(newValue, this.varHandle.get(this.handleTarget));
  this.varHandle.setVolatile(this.handleTarget, newValue + 1);
  assertEquals(newValue + 1, this.varHandle.get(this.handleTarget));
  this.varHandle.setOpaque(this.handleTarget, newValue + 2);
  assertEquals(newValue + 2, this.varHandle.get(this.handleTarget));
  this.varHandle.setRelease(this.handleTarget, newValue + 3);
  assertEquals(newValue + 3, this.varHandle.get(this.handleTarget));
}

All these write access methods takes two parameters. The first parameter is the target object, the second is the new value to set.

Atomic Update

This category includes methods from four subcategories with memory ordering effects specified by the suffix. All the methods perform both read and write access to a variable, which may have different memory ordering effects for read and write access.

The method compareAndSet() atomically sets the value of a variable if the variable’s current value equals the expected value with the volatile memory ordering for both read and write access. The returned boolean value indicates if the operation successfully updates the value.

The weakCompareAndSet(), weakCompareAndSetPlain(), weakCompareAndSetAcquire(), and weakCompareAndSetRelease() methods could atomically set the value of a variable if the variable’s current value equals the expected value. The returned Boolean value indicates if the operation successfully updated the value. This operation may fail even if the variable’s current value does match the expected value. This is why they are called weak operations.

The compareAndExchange(), compareAndExchangeAcquire(), and compareAndExchangeRelease() methods atomically set the value of a variable if the variable’s current value is equal to the expected value. The return value is the current value, which will be the same as the expected value if the operation is successful.

The getAndSet(), getAndSetAcquire(), and getAndSetRelease() methods atomically set the value of a variable to the new value and return the variable’s previous value.

Table 8-2 shows each method’s memory ordering for read and write access.

Listing 8-7 shows how to use the different atomic update methods.

Listing 8-7. Atomic Update Methods

@Test
public void testAtomicUpdate() throws Exception {
  final int expectedValue = 1;
  final int newValue = 2;
  assertEquals(true,
      this.varHandle.compareAndSet(this.handleTarget, expectedValue, newValue));
  assertEquals(newValue,
      this.varHandle.compareAndExchange(this.handleTarget, newValue, newValue + 1));
  assertEquals(newValue + 1, this.varHandle.getAndSet(this.handleTarget, newValue + 2));
}

Numeric Atomic Update

The getAndAdd(), getAndAddAcquire(), and getAndAddRelease() methods atomically add the value to the current value of a variable a nd return the variable’s previous value. Table 8-3 shows the memory ordering for read and write access of these methods.

Listing 8-8 shows how to use different numeric atomic update methods.

Listing 8-8. Numeric Atomic Update Methods

@Test
public void testNumericAtomicUpdate() throws Exception {
  final int expectedValue = 1;
  assertEquals(expectedValue,
      this.varHandle.getAndAdd(this.handleTarget, 1));
  assertEquals(expectedValue + 1,
      this.varHandle.getAndAddAcquire(this.handleTarget, 1));
  assertEquals(expectedValue + 2,
      this.varHandle.getAndAddRelease(this.handleTarget, 1));
}

Bitwise Atomic Update

The getAndBitwiseAnd(), getAndBitwiseAndAcquire(), getAndBitwiseAndRelease(), getAndBitwiseOr(), getAndBitwiseOrAcquire(), getAndBitwiseOrRelease(), getAndBitwiseXor(), getAndBitwiseXorAcquire(), and getAndBitwiseXorRelease() methods atomically set the value of a variable to the result of a bitwise AND/OR/XOR between the variable’s current value and the mask value and return the variable’s previous value. Table 8-4 shows the memory ordering for read and write access of these methods.

Listing 8-9 shows how to use different bitwise numeric atomic update methods.

Listing 8-9. Bitwise Atomic Update Methods

@Test
public void testBitwiseAtomicUpdate() throws Exception {
  final int mask = 1;
  assertEquals(1, this.varHandle.getAndBitwiseAnd(this.handleTarget, mask));
  assertEquals(1, this.varHandle.get(this.handleTarget));
  assertEquals(1, this.varHandle.getAndBitwiseOr(this.handleTarget, mask));
  assertEquals(1, this.varHandle.get(this.handleTarget));
  assertEquals(1, this.varHandle.getAndBitwiseXor(this.handleTarget, mask));
  assertEquals(0, this.varHandle.get(this.handleTarget));
}