Class MemoryHandles

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 = MemoryLayouts.JAVA_SHORT.varHandle(short.class);
    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.

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).

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.

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.

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.

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.

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.

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.

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.

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.