Module jdk.incubator.foreign
Package jdk.incubator.foreign

Class MemoryHandles

java.lang.Object
jdk.incubator.foreign.MemoryHandles
public final class MemoryHandles extends Object
This class defines several factory methods for constructing and combining memory access var handles. Memory access var handles can be obtained using varHandle(ValueLayout). The provided value layout determines the type, as well as the alignment constraint and the byte order associated with the memory access var handle.

The resulting memory access var handle can then be combined in various ways to emulate different addressing modes. The var handles created by this class feature a mandatory coordinate type (of type MemorySegment), and one long coordinate type, which represents the offset, in bytes, relative to the segment, at which dereference should occur.

As an example, consider the memory layout expressed by a GroupLayout instance constructed as follows: 

GroupLayout seq = MemoryLayout.structLayout(
        MemoryLayout.paddingLayout(32),
        ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN).withName("value")
);
To access the member layout named value, we can construct a memory access var handle as follows: 
VarHandle handle = MemoryHandles.varHandle(ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN)); //(MemorySegment, long) -> int
handle = MemoryHandles.insertCoordinates(handle, 1, 4); //(MemorySegment) -> int

Unless otherwise specified, passing a null argument, or an array argument containing one or more null elements to a method in this class causes a NullPointerException to be thrown.

Alignment and access modes

A memory access var handle is associated with an access size S and an alignment constraint B (both expressed in bytes). We say that a memory access operation is fully aligned if it occurs at a memory address A which is compatible with both alignment constraints S and B. If access is fully aligned then following access modes are supported and are guaranteed to support atomic access:
  • read write access modes for all T, with the exception of access modes get and set for long and double on 32-bit platforms.
  • atomic update access modes for int, long, float, double or MemoryAddress. (Future major platform releases of the JDK may support additional types for certain currently unsupported access modes.)
  • numeric atomic update access modes for int, long and MemoryAddress. (Future major platform releases of the JDK may support additional numeric types for certain currently unsupported access modes.)
  • bitwise atomic update access modes for int, long and MemoryAddress. (Future major platform releases of the JDK may support additional numeric types for certain currently unsupported access modes.)
If T is float, double or MemoryAddress then atomic update access modes compare values using their bitwise representation (see Float.floatToRawIntBits(float), Double.doubleToRawLongBits(double) and MemoryAddress.toRawLongValue(), respectively).

Alternatively, a memory access operation is partially aligned if it occurs at a memory address A which is only compatible with the alignment constraint B; in such cases, access for anything other than the get and set access modes will result in an IllegalStateException. If access is partially aligned, atomic access is only guaranteed with respect to the largest power of two that divides the GCD of A and S.

Finally, in all other cases, we say that a memory access operation is misaligned; in such cases an IllegalStateException is thrown, irrespective of the access mode being used.

  • Method Details

    • varHandle

      public static VarHandle varHandle(ValueLayout layout)
      Creates a memory access var handle from given value layout. The provided layout will specify the carrier type, the the byte size, the byte alignment and the byte order associated to the returned var handle. The returned var handle's type is carrier and the list of coordinate types is (MemorySegment, long), where the long coordinate type corresponds to byte offset into a given memory segment. The returned var handle accesses bytes at an offset in a given memory segment, composing bytes to or from a value of the type carrier according to the given endianness; the alignment constraint (in bytes) for the resulting memory access var handle is given by alignmentBytes.
      API Note:
      the resulting var handle features certain access mode restrictions, which are common to all memory access var handles.
      Parameters:
      layout - the value layout for which a memory access handle is to be obtained.
      Returns:
      the new memory access var handle.
      Throws:
      IllegalArgumentException - if an illegal carrier type is used, or if alignmentBytes is not a power of two.

    • asUnsigned

      public static VarHandle asUnsigned(VarHandle target, Class<?> adaptedType)
      Adapts a target var handle by narrowing incoming values and widening outgoing values, to and from the given type, respectively.

      The returned var handle can be used to conveniently treat unsigned primitive data types as if they were a wider signed primitive type. For example, it is often convenient to model an unsigned short as a Java int to avoid dealing with negative values, which would be the case if modeled as a Java short. This is illustrated in the following example: 

      MemorySegment segment = MemorySegment.allocateNative(2, ResourceScope.newImplicitScope());
VarHandle SHORT_VH = ValueLayout.JAVA_SHORT.varHandle();
VarHandle INT_VH = MemoryHandles.asUnsigned(SHORT_VH, int.class);
SHORT_VH.set(segment, (short)-1);
INT_VH.get(segment); // returns 65535

      When calling e.g. VarHandle.set(Object...) on the resulting var handle, the incoming value (of type adaptedType) is converted by a narrowing primitive conversion and then passed to the target var handle. A narrowing primitive conversion may lose information about the overall magnitude of a numeric value. Conversely, when calling e.g. VarHandle.get(Object...) on the resulting var handle, the returned value obtained from the target var handle is converted by a unsigned widening conversion before being returned to the caller. In an unsigned widening conversion the high-order bits greater than that of the target carrier type are zero, and the low-order bits (equal to the width of the target carrier type) are equal to the bits of the value obtained from the target var handle.

      The returned var handle will feature the variable type adaptedType, and the same access coordinates, the same access modes (see VarHandle.AccessMode), and the same atomic access guarantees, as those featured by the target var handle.

      Parameters:
      target - the memory access var handle to be adapted
      adaptedType - the adapted type
      Returns:
      the adapted var handle.
      Throws:
      IllegalArgumentException - if the carrier type of target is not one of byte, short, or int; if adaptedType is not one of int, or long; if the bit width of the adaptedType is not greater than that of the target carrier type.
      See Java Language Specification:
      5.1.3 Narrowing Primitive Conversion

    • filterValue

      public static VarHandle filterValue(VarHandle target, MethodHandle filterToTarget, MethodHandle filterFromTarget)
      Adapts a target var handle by pre-processing incoming and outgoing values using a pair of filter functions.

      When calling e.g. VarHandle.set(Object...) on the resulting var handle, the incoming value (of type T, where T is the last parameter type of the first filter function) is processed using the first filter and then passed to the target var handle. Conversely, when calling e.g. VarHandle.get(Object...) on the resulting var handle, the return value obtained from the target var handle (of type T, where T is the last parameter type of the second filter function) is processed using the second filter and returned to the caller. More advanced access mode types, such as VarHandle.AccessMode.COMPARE_AND_EXCHANGE might apply both filters at the same time.

      For the boxing and unboxing filters to be well-formed, their types must be of the form (A... , S) -> T and (A... , T) -> S, respectively, where T is the type of the target var handle. If this is the case, the resulting var handle will have type S and will feature the additional coordinates A... (which will be appended to the coordinates of the target var handle).

      If the boxing and unboxing filters throw any checked exceptions when invoked, the resulting var handle will throw an IllegalStateException.

      The resulting var handle will feature the same access modes (see VarHandle.AccessMode) and atomic access guarantees as those featured by the target var handle.

      Parameters:
      target - the target var handle
      filterToTarget - a filter to convert some type S into the type of target
      filterFromTarget - a filter to convert the type of target to some type S
      Returns:
      an adapter var handle which accepts a new type, performing the provided boxing/unboxing conversions.
      Throws:
      IllegalArgumentException - if filterFromTarget and filterToTarget are not well-formed, that is, they have types other than (A... , S) -> T and (A... , T) -> S, respectively, where T is the type of the target var handle, or if it's determined that either filterFromTarget or filterToTarget throws any checked exceptions.

    • filterCoordinates

      public static VarHandle filterCoordinates(VarHandle target, int pos, MethodHandle... filters)
      Adapts a target var handle by pre-processing incoming coordinate values using unary filter functions.

      When calling e.g. VarHandle.get(Object...) on the resulting var handle, the incoming coordinate values starting at position pos (of type C1, C2 ... Cn, where C1, C2 ... Cn are the return type of the unary filter functions) are transformed into new values (of type S1, S2 ... Sn, where S1, S2 ... Sn are the parameter types of the unary filter functions), and then passed (along with any coordinate that was left unaltered by the adaptation) to the target var handle.

      For the coordinate filters to be well-formed, their types must be of the form S1 -> T1, S2 -> T1 ... Sn -> Tn, where T1, T2 ... Tn are the coordinate types starting at position pos of the target var handle.

      If any of the filters throws a checked exception when invoked, the resulting var handle will throw an IllegalStateException.

      The resulting var handle will feature the same access modes (see VarHandle.AccessMode) and atomic access guarantees as those featured by the target var handle.

      Parameters:
      target - the target var handle
      pos - the position of the first coordinate to be transformed
      filters - the unary functions which are used to transform coordinates starting at position pos
      Returns:
      an adapter var handle which accepts new coordinate types, applying the provided transformation to the new coordinate values.
      Throws:
      IllegalArgumentException - if the handles in filters are not well-formed, that is, they have types other than S1 -> T1, S2 -> T2, ... Sn -> Tn where T1, T2 ... Tn are the coordinate types starting at position pos of the target var handle, if pos is not between 0 and the target var handle coordinate arity, inclusive, or if more filters are provided than the actual number of coordinate types available starting at pos, or if it's determined that any of the filters throws any checked exceptions.

    • insertCoordinates

      public static VarHandle insertCoordinates(VarHandle target, int pos, Object... values)
      Provides a target var handle with one or more bound coordinates in advance of the var handle's invocation. As a consequence, the resulting var handle will feature less coordinate types than the target var handle.

      When calling e.g. VarHandle.get(Object...) on the resulting var handle, incoming coordinate values are joined with bound coordinate values, and then passed to the target var handle.

      For the bound coordinates to be well-formed, their types must be T1, T2 ... Tn , where T1, T2 ... Tn are the coordinate types starting at position pos of the target var handle.

      The resulting var handle will feature the same access modes (see VarHandle.AccessMode) and atomic access guarantees as those featured by the target var handle.

      Parameters:
      target - the var handle to invoke after the bound coordinates are inserted
      pos - the position of the first coordinate to be inserted
      values - the series of bound coordinates to insert
      Returns:
      an adapter var handle which inserts an additional coordinates, before calling the target var handle
      Throws:
      IllegalArgumentException - if pos is not between 0 and the target var handle coordinate arity, inclusive, or if more values are provided than the actual number of coordinate types available starting at pos.
      ClassCastException - if the bound coordinates in values are not well-formed, that is, they have types other than T1, T2 ... Tn , where T1, T2 ... Tn are the coordinate types starting at position pos of the target var handle.

    • permuteCoordinates

      public static VarHandle permuteCoordinates(VarHandle target, List<Class<?>> newCoordinates, int... reorder)
      Provides a var handle which adapts the coordinate values of the target var handle, by re-arranging them so that the new coordinates match the provided ones.

      The given array controls the reordering. Call #I the number of incoming coordinates (the value newCoordinates.size()), and call #O the number of outgoing coordinates (the number of coordinates associated with the target var handle). Then the length of the reordering array must be #O, and each element must be a non-negative number less than #I. For every N less than #O, the N-th outgoing coordinate will be taken from the I-th incoming coordinate, where I is reorder[N].

      No coordinate value conversions are applied. The type of each incoming coordinate, as determined by newCoordinates, must be identical to the type of the corresponding outgoing coordinate in the target var handle.

      The reordering array need not specify an actual permutation. An incoming coordinate will be duplicated if its index appears more than once in the array, and an incoming coordinate will be dropped if its index does not appear in the array.

      The resulting var handle will feature the same access modes (see VarHandle.AccessMode) and atomic access guarantees as those featured by the target var handle.

      Parameters:
      target - the var handle to invoke after the coordinates have been reordered
      newCoordinates - the new coordinate types
      reorder - an index array which controls the reordering
      Returns:
      an adapter var handle which re-arranges the incoming coordinate values, before calling the target var handle
      Throws:
      IllegalArgumentException - if the index array length is not equal to the number of coordinates of the target var handle, or if any index array element is not a valid index for a coordinate of newCoordinates, or if two corresponding coordinate types in the target var handle and in newCoordinates are not identical.

    • collectCoordinates

      public static VarHandle collectCoordinates(VarHandle target, int pos, MethodHandle filter)
      Adapts a target var handle by pre-processing a sub-sequence of its coordinate values with a filter (a method handle). The pre-processed coordinates are replaced by the result (if any) of the filter function and the target var handle is then called on the modified (usually shortened) coordinate list.

      If R is the return type of the filter (which cannot be void), the target var handle must accept a value of type R as its coordinate in position pos, preceded and/or followed by any coordinate not passed to the filter. No coordinates are reordered, and the result returned from the filter replaces (in order) the whole subsequence of coordinates originally passed to the adapter.

      The argument types (if any) of the filter replace zero or one coordinate types of the target var handle, at position pos, in the resulting adapted var handle. The return type of the filter must be identical to the coordinate type of the target var handle at position pos, and that target var handle coordinate is supplied by the return value of the filter.

      If any of the filters throws a checked exception when invoked, the resulting var handle will throw an IllegalStateException.

      The resulting var handle will feature the same access modes (see VarHandle.AccessMode) and atomic access guarantees as those featured by the target var handle.

      Parameters:
      target - the var handle to invoke after the coordinates have been filtered
      pos - the position of the coordinate to be filtered
      filter - the filter method handle
      Returns:
      an adapter var handle which filters the incoming coordinate values, before calling the target var handle
      Throws:
      IllegalArgumentException - if the return type of filter is void, or it is not the same as the pos coordinate of the target var handle, if pos is not between 0 and the target var handle coordinate arity, inclusive, if the resulting var handle's type would have too many coordinates, or if it's determined that filter throws any checked exceptions.

    • dropCoordinates

      public static VarHandle dropCoordinates(VarHandle target, int pos, Class<?>... valueTypes)
      Returns a var handle which will discard some dummy coordinates before delegating to the target var handle. As a consequence, the resulting var handle will feature more coordinate types than the target var handle.

      The pos argument may range between zero and N, where N is the arity of the target var handle's coordinate types. If pos is zero, the dummy coordinates will precede the target's real arguments; if pos is N they will come after.

      The resulting var handle will feature the same access modes (see VarHandle.AccessMode) and atomic access guarantees as those featured by the target var handle.

      Parameters:
      target - the var handle to invoke after the dummy coordinates are dropped
      pos - position of first coordinate to drop (zero for the leftmost)
      valueTypes - the type(s) of the coordinate(s) to drop
      Returns:
      an adapter var handle which drops some dummy coordinates, before calling the target var handle
      Throws:
      IllegalArgumentException - if pos is not between 0 and the target var handle coordinate arity, inclusive.