JEP 193: Variable Handles
Summary
Define a standard means to invoke the equivalents of various java.util.concurrent.atomic
and sun.misc.Unsafe
operations upon object fields and array elements, a standard set of fence operations for fine-grained control of memory ordering, and a standard reachability-fence operation to ensure that a referenced object remains strongly reachable.
Goals
The following are required goals:
-
Safety. It must not be possible to place the Java Virtual Machine in a corrupt memory state. For example, a field of an object can only be updated with instances that are castable to the field type, or an array element can only be accessed within an array if the array index is within the array bounds.
-
Integrity. Access to a field of an object follows the same access rules as with
getfield
andputfield
byte codes in addition to the constraint that afinal
field of an object cannot be updated. (Note: such safety and integrity rules also apply toMethodHandles
giving read or write access to a field.) -
Performance. The performance characteristics must be the same as or similar to equivalent
sun.misc.Unsafe
operations (specifically, generated assembler code should be almost identical modulo certain safety checks that cannot be folded away). -
Usability. The API must be better than the
sun.misc.Unsafe
API.
It is desirable, but not required, that the API be as good as the java.util.concurrent.atomic
API.
Motivation
As concurrent and parallel programming in Java continue to expand, programmers are increasingly frustrated by not being able to use Java constructs to arrange atomic or ordered operations on the fields of individual classes; for example, atomically incrementing a count
field. Until now the only ways to achieve these effects were to use a stand-alone AtomicInteger
(adding both space overhead and additional concurrency issues to manage indirection) or, in some situations, to use atomic FieldUpdater
s (often encountering more overhead than the operation itself), or to use the unsafe (and unportable and unsupported) sun.misc.Unsafe
API for JVM intrinsics. Intrinsics are faster, so they have become widely used, to the detriment of safety and portability.
Without this JEP, these problems are expected to become worse as atomic APIs expand to cover additional access-consistency policies (aligned with the recent C++11 memory model) as part of Java Memory Model revisions.
Description
A variable handle is a typed reference to a variable, which supports read and write access to the variable under a variety of access modes. Supported variable kinds include instance fields, static fields and array elements. Other variable kinds are being considered and may be supported such as array views, viewing a byte or char array as a long array, and locations in off-heap regions described by ByteBuffer
s.
Variable handles require library enhancements, JVM enhancements, and compiler support. Additionally, it requires minor updates to the Java Language Specification and the Java Virtual Machine Specification. Minor language enhancements, that enhance compile-time type checking and complement existing syntax, are also considered.
The resulting specifications are expected to be extensible in natural ways to additional primitive-like value types or additional array-like types, if they are ever added to Java. This is not, however, a general-purpose transaction mechanism for controlling accesses and updates to multiple variables. Alternative forms for expressing and implementing such constructs may be explored in the course of this JEP, and may be the subject of further JEPs.
Variable handles are modelled by a single abstract class, java.lang.invoke.VarHandle
, where each variable access mode is represented by a signature-polymorphic method.
The set of access modes represents a minimal viable set and are designed to be compatible with C/C++11 atomics without depending on a revised update to the Java Memory Model. Additional access modes will be added if required. Some access modes may not be applicable for certain variable types and, if so, when invoked on an associated VarHandle
instance will throw an UnsupportedOperationException
.
The access modes are grouped into the following categories:
-
read access modes, such as reading a variable with volatile memory ordering effects;
-
write access modes, such as updating a variable with release memory ordering effects;
-
atomic update access modes, such as a compare-and-set on a variable with volatile memory order effects for both read and writing;
-
numeric atomic update access modes, such as get-and-add with plain memory order effects for writing and acquire memory order effects for reading.
-
bitwise atomic update access modes, such as get-and-bitwise-and with release memory order effects for writing and plain memory order effects for reading.
The later three categories are commonly referred to as read-modify-write modes.
The signature-polymorphic characteristic of the access mode methods enables variable handles to support many variable kinds and variable types using just one abstract class. This avoids an explosion of variable kind and type-specific classes. Furthermore, even though the access mode method signatures are declared as a variable argument array of Object
, such signature-polymorphic characteristics ensure there will be no boxing of primitive value arguments and no packing of arguments into an array. This enables predictable behaviour and performance at runtime for the HotSpot interpreter and C1/C2 compilers.
Methods to create VarHandle
instances are located in the same area as that to produce MethodHandle
instances which access equivalent or similar variable kinds.
Methods to create VarHandle
instances for instance and static field variable kinds are located in java.lang.invoke.MethodHandles.Lookup
and are created by a process of looking up the field within the associated receiving class. For example, such lookup to obtain a VarHandle
for a field named i
of type int
on a receiver class Foo
might be performed as follows:
class Foo {
int i;
...
}
...
class Bar {
static final VarHandle VH_FOO_FIELD_I;
static {
try {
VH_FOO_FIELD_I = MethodHandles.lookup().
in(Foo.class).
findVarHandle(Foo.class, "i", int.class);
} catch (Exception e) {
throw new Error(e);
}
}
}
The lookup of a VarHandle
that accesses a field will, before producing and returning the VarHandle
, perform the exact same access control checks (on behalf of the lookup class) as those performed by the lookup up of a MethodHandle
that gives read and write access to that same field (see the find{,Static}{Getter,Setter}
methods in the MethodHandles.Lookup
class).
Access mode methods will throw UnsupportedOperationException
when invoked under the following conditions:
-
Write access mode methods for a
VarHandle
to a final field. -
Numeric-based access mode methods (
getAndAdd
andaddAndGet
) for a reference variable type or a non-numeric type (such asboolean
). -
Bitwise-based access mode methods for a reference variable type or the
float
anddouble
types (the latter restriction may be removed in a future revision)
A field need not be marked as volatile
for an associated VarHandle
to perform volatile access. In effect, the volatile
modifier, if present, is ignored. This is different to the behaviour of java.util.concurrent.atomic.Atomic{Int, Long, Reference}FieldUpdater
where corresponding fields have to be marked as volatile. This can be too restrictive in certain cases where it is known certain volatile accesses are not always required.
Methods to create VarHandle
instances for array-based variable types are located in java.lang.invoke.MethodHandles
(see the arrayElement{Getter, Setter}
methods in the MethodHandles
class). For example, a VarHandle
to an array of int
may be created as follows:
VarHandle intArrayHandle = MethodHandles.arrayElementVarHandle(int[].class);
Access mode methods will throw UnsupportedOperationException
when invoked under the following conditions:
-
Numeric-based access mode methods (
getAndAdd
andaddAndGet
) for an array component reference variable type or a non-numeric type (such asboolean
) -
Bitwise-based access mode methods for a reference variable type or the
float
anddouble
types (the latter restriction may be removed in a future revision)
All primitive types and references types are supported for the variable type of variable kinds that are instance fields, static fields and array elements. Other variable kinds may support all or a subset of those types.
Methods to create VarHandle
instances for array-view-based variable types are also located in java.lang.invoke.MethodHandles
. For example, a VarHandle
to view an array of byte
as an unaligned array of long
may be created as follows:
VarHandle longArrayViewHandle = MethodHandles.byteArrayViewVarHandle(
long[].class, java.nio.ByteOrder.BIG_ENDIAN);
Although similar mechanisms can be achieved using java.nio.ByteBuffer
, it requires that a ByteBuffer
instance be created wrapping a byte
array. This does not always guarantee reliable performance due to the fragility of escape analysis and that accesses have to go through the ByteBuffer
instance. In the case of unaligned access all but the plain access mode methods will throw IllegalStateException
. For aligned access certain volatile operations, depending on the variable type are possible. Such VarHandle
instances may be utilized to vectorize array access.
The number of arguments, the argument types, and return type of access mode methods are governed by variable kind, the variable type and the characteristics of the access mode. VarHandle
creation methods (such as those previously described) will document the requirements. For example, a compareAndSet
on the previously-looked up VH_FOO_FIELD_I
handle requires 3 arguments, an instance of receiver Foo
and two int
s for the expected and actual values:
Foo f = ...
boolean r = VH_FOO_FIELD_I.compareAndSet(f, 0, 1);
In contrast, a getAndSet
requires 2 arguments, an instance of receiver Foo
and one int
that is the value to be set:
int o = (int) VH_FOO_FIELD_I.getAndSet(f, 2);
Access to array elements will require an additional argument, of type int
, between the receiver and value arguments (if any), that corresponds to the array index of the element to be operated upon.
For predictable behaviour and performance at runtime VarHandle
instances should be held in static final fields (as required for instances of Atomic{Int, Long, Reference}FieldUpdater)
. This ensures that constant folding will occur for access mode method invocations, such as folding away method signature checks and/or argument cast checks.
Note: Future HotSpot enhancements might support constant folding for
VarHandle
, orMethodHandle
, instances held in non-static final fields, method arguments, or local variables.
A MethodHandle
may be produced for a VarHandle
access mode method by using MethodHandles.Lookup.findVirtual
. For example, to produce a MethodHandle
to the "compareAndSet" access mode for a particular variable kind and type:
Foo f = ...
MethodHandle mhToVhCompareAndSet = MethodHandles.publicLookup().findVirtual(
VarHandle.class,
"compareAndSet",
MethodType.methodType(boolean.class, Foo.class, int.class, int.class));
The MethodHandle
can then be invoked with a variable kind and type compatible VarHandle
instance as the first parameter:
boolean r = (boolean) mhToVhCompareAndSet.invokeExact(VH_FOO_FIELD_I, f, 0, 1);
Or mhToVhCompareAndSet
can be bound to the VarHandle
instance and then invoked:
MethodHandle mhToBoundVhCompareAndSet = mhToVhCompareAndSet
.bindTo(VH_FOO_FIELD_I);
boolean r = (boolean) mhToBoundVhCompareAndSet.invokeExact(f, 0, 1);
Such a MethodHandle
lookup using findVirtual
will perform an asType
transformation to adjust arguments and return values. The behaviour is equivalent to a MethodHandle
produced using MethodHandles.varHandleInvoker
, the analog of MethodHandles.invoker`:
MethodHandle mhToVhCompareAndSet = MethodHandles.varHandleExactInvoker(
VarHandle.AccessMode.COMPARE_AND_SET,
MethodType.methodType(boolean.class, Foo.class, int.class, int.class));
boolean r = (boolean) mhToVhCompareAndSet.invokeExact(VH_FOO_FIELD_I, f, 0, 1);
Thus a VarHandle
may be used in erased or reflective scenarios by a wrapping class, for example replacing the Unsafe
usages within the java.util.concurrent.Atomic*FieldUpdater/Atomic*Array
classes. (Although further work is required such that the updaters are granted access to the look up fields in the declaring class.)
The source compilation of an access mode method invocation will follow the same rules as for signature-polymorphic method invocation to MethodHandle.invokeExact
and MethodHandle.invoke
. The following additions will be required to the Java Language Specification:
- Make reference to the signature-polymorphic access mode methods in the
VarHandle
class. - Allow signature-polymorphic methods to return types other than Object, indicating that the return type is not polymorphic (and would otherwise be declared via a cast at the call site). This makes it easier invoke write-based access methods that return void and invoke
compareAndSet
that returns aboolean
value.
It would be desirable, but not a requirement, that source compilation of a signature-polymorphic method invocation be enhanced to perform target typing of the polymorphic return type such that an explicit cast is not required.
Note: a syntax and runtime support for looking up a
MethodHandle
or aVarHandle
leveraging the syntax of method references, such asVarHandle VH_FOO_FIELD_I = Foo::i
is desirable but not in scope for this JEP.
The runtime invocation of an access mode method invocation will follow similar rules as for signature-polymorphic method invocation to MethodHandle.invokeExact
and MethodHandle.invoke
. The following additions will be required to the Java Virtual Machine Specification:
- Make reference to the signature-polymorphic access mode methods in the
VarHandle
class. - Specify
invokevirtual
byte code behaviour of invocation to access mode signature-polymorphic methods. It is anticipated that such behaviour can be specified by defining a transformation from the access mode method invocation to aMethodHandle
which is then invoked usinginvokeExact
with the same parameters (see previous use ofMethodHandles.Lookup.findVirtual
).
It is important that the VarHandle
implementations for the supported variable kinds, types and access modes are reliably efficient and meet the performance goals. Leveraging signature-polymorphic methods helps in terms of avoiding boxing and array packing. Implementations will:
-
Reside in the
java.lang.invoke
package where HotSpot treats final fields of classes in that package as really final, which enables constant folding when theVarHandle
itself is referenced in a static final field; -
Leverage the JDK internal annotations
@Stable
for constant folding of values that change only once, and@ForceInline
to ensure methods get inlined even if normal inlining thresholds are reached; and -
Use
sun.misc.Unsafe
for underlying enhanced volatile access.
A couple of HotSpot intrinsics are necessary, some of which are enumerated as follows:
-
An intrinsic for
Class.cast
, which has already been added (see JDK-8054492). Before this intrinsic was added a constant foldedClass.cast
would leave behind redundant checks that may cause unnecessary de-optimizations. -
An intrinsic for an
acquire-get
access mode that can synchronize with an intrinsic for aset-release
access mode (seesun.misc.Unsafe.putOrdered{Int, Long, Object}
) when concurrently accessing variables. -
Intrinsics for array bounds checks JDK-8042997. Static methods can be added
java.util.Arrays
that perform such checks and accept a function that is invoked to return an exception to be thrown or string message, to be included in an exception to be thrown, if the check fails. Such intrinsics enable better comparisons using unsigned values (since an array length is always positive) and better hoisting of range checks outside of unrolled loops over the array elements.
In addition further improvements to range checks by HotSpot have been implemented (JDK-8073480) or are needed (JDK-8003585 to strength reduce range checks in say the fork/join framework or in say HashMap
or ConcurrentHashMap
).
The VarHandle
implementations should have minimal dependencies on other classes within the java.lang.invoke
package to avoid increasing startup time and to avoid cyclic dependencies occurring during static initialization. For example, ConcurrentHashMap
is used by such classes and if ConcurrentHashMap
is modified to use VarHandles
it needs to be ensured no cyclic dependencies are introduced. Other more subtle cycles are possible with the use of ThreadLocalRandom
and its use of AtomicInteger
. It is also is desirable that the C2 HotSpot compilation time is not unduly increased for methods containing VarHandle
method invocations.
Memory fences
Fenced operations are defined as static methods on the VarHandle
class and represents a minimal viable set for fine grained control of memory ordering.
/**
* Ensures that loads and stores before the fence will not be
* reordered with loads and stores after the fence.
*
* @apiNote Ignoring the many semantic differences from C and
* C++, this method has memory ordering effects compatible with
* atomic_thread_fence(memory_order_seq_cst)
*/
public static void fullFence() {}
/**
* Ensures that loads before the fence will not be reordered with
* loads and stores after the fence.
*
* @apiNote Ignoring the many semantic differences from C and
* C++, this method has memory ordering effects compatible with
* atomic_thread_fence(memory_order_acquire)
*/
public static void acquireFence() {}
/**
* Ensures that loads and stores before the fence will not be
* reordered with stores after the fence.
*
* @apiNote Ignoring the many semantic differences from C and
* C++, this method has memory ordering effects compatible with
* atomic_thread_fence(memory_order_release)
*/
public static void releaseFence() {}
/**
* Ensures that loads before the fence will not be reordered with
* loads after the fence.
*/
public static void loadLoadFence() {}
/**
* Ensures that stores before the fence will not be reordered with
* stores after the fence.
*/
public static void storeStoreFence() {}
A full fence is stronger (in terms of ordering guarantees) than an acquire fence which is stronger than a load load fence. Likewise a full fence is stronger than a release fence which is stronger than a store store fence.
Reachability fence
The reachability fence is defined as a static method on java.lang.ref.Reference
:
class java.lang.ref.Reference {
// add:
/**
* Ensures that the object referenced by the given reference
* remains <em>strongly reachable</em> (as defined in the {@link
* java.lang.ref} package documentation), regardless of any prior
* actions of the program that might otherwise cause the object to
* become unreachable; thus, the referenced object is not
* reclaimable by garbage collection at least until after the
* invocation of this method. Invocation of this method does not
* itself initiate garbage collection or finalization.
*
* @param ref the reference. If null, this method has no effect.
*/
public static void reachabilityFence(Object ref) {}
}
See JDK-8133348.
It is currently out of scope to provide an annotation, @Finalized
say, to be declared on a method, which at either compile or runtime results in as if the method body was wrapped as follows:
try {
<method body>
} finally {
Reference.reachabilityFence(this);
}
It is anticipated that such functionality could be supported by a compile-time annotation processor.
Alternatives
Introducing new forms of "value type" were considered that support volatile operations. However, this would be inconsistent with properties of other types, and would also require more effort for programmers to use. Reliance upon java.util.concurrent.atomic
FieldUpdater
s was also considered, but their dynamic overhead and usage limitations make them unsuitable.
Several other alternatives, including those based on field references, have been raised and dismissed as unworkable on syntactic, efficiency, and/or usability grounds over the many years that these issues have been discussed.
Syntax enhancements were considered in a previous version of this JEP but were deemed too "magical", with the overloaded use of the volatile
keyword scoping to floating interfaces, one for references and one for each supported primitive type.
Generic types extending from VarHandle
were considered in a previous version of this JEP but such an addition, with enhanced polymorphic signatures for generic types and special treatment of boxed type variables, was considered immature given a future Java release with value types and generics over primitives with JEP 218, and improved arrays with Arrays 2.0.
An implementation-specific invokedynamic
approach was also considered in a previous version of this JEP. This required that compiled method calls with and without invokedynamic
were carefully aligned to be the same in terms of semantics. In addition the use of invokedynamic
in core classes such as say ConcurrentHashMap
will result in cyclic dependencies.
Testing
Stress tests will be developed using the jcstress harness.
Risks and Assumptions
A prototype implementation of VarHandle
has been performance-tested with nano-benchmarks and fork/join benchmarks, where the fork/join library's use of sun.misc.Unsafe
was replaced with VarHandle
. No major performance issues have been observed so far, and the HotSpot compiler issues identified do not seem onerous (folding cast checks and improving array bounds checks). We are therefore confident of the feasibility of this approach. However, we expect that it will require more experimentation to ensure the compilation techniques are reliable in the performance-critical contexts where these constructs are most often needed.
Dependences
The classes in java.util.concurrent
(and other areas identified in the JDK) will be migrated from sun.misc.Unsafe
to VarHandle
.
This JEP does not depend on JEP 188: Java Memory Model Update.