Класс MemoryHandles

Возвращаемый обработчик varHandle может удобно использоваться для представления беззнаковых примитивных типов данных как более широких знаковых примитивных типов. Например, часто удобно моделировать беззнаковый short как Java int, чтобы избежать работы с отрицательными значениями, которые были бы в случае моделирования как Java short. Это иллюстрируется в следующем примере:

    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
 

При вызове, например, VarHandle.set(Object...) на результирующем обработчике varHandle, входящее значение (типа adaptedType) преобразуется с помощью сужающего примитивного преобразования и затем передаётся в обработчик varHandle target. Сужающее примитивное преобразование может потерять информацию о полном значении числовой величины. И наоборот, при вызове, например, VarHandle.get(Object...) на результирующем обработчике varHandle, возвращённое значение, полученное от обработчика varHandle target, преобразуется с помощью расширяющего беззнакового преобразования перед возвращением вызывающей стороне. При расширяющем беззнаковом преобразовании старшие биты, большие, чем у типа носителя target, обнуляются, и младшие биты (равные ширине типа носителя target) равны битам значения, полученного от обработчика varHandle target.

Возвращаемый обработчик varHandle будет иметь тип adaptedType, и те же координаты доступа, те же режимы доступа (см. VarHandle.AccessMode), и те же гарантии атомарного доступа, что и у обработчика varHandle target.

При вызове, например, VarHandle.set(Object...) на результирующем обработчике varHandle, входящее значение (типа T, где T — тип последнего параметра первой функции фильтра) обрабатывается с помощью первой функции фильтра и затем передаётся целевому обработчику varHandle. И наоборот, при вызове, например, VarHandle.get(Object...) на результирующем обработчике varHandle, возвращаемое значение, полученное от целевого обработчика varHandle (типа T, где T — тип последнего параметра второй функции фильтра) обрабатывается с помощью второй функции фильтра и возвращается вызывающей стороне. Более продвинутые типы режимов доступа, такие как VarHandle.AccessMode.COMPARE_AND_EXCHANGE, могут применять оба фильтра одновременно.

Для корректной работы функций фильтра для преобразования в/из упакованных типов, их типы должны быть вида (A... , S) -> T и (A... , T) -> S, соответственно, где T — тип целевого обработчика varHandle. Если это так, результирующий обработчик varHandle будет иметь тип S и будет иметь дополнительные координаты A... (которые будут добавлены к координатам целевого обработчика varHandle).

Результирующий обработчик varHandle будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик varHandle.

При вызове, например, VarHandle.get(Object...) на результирующем обработчике переменной, входящие координатные значения, начиная с позиции pos (типа C1, C2 ... Cn, где C1, C2 ... Cn — возвращаемый тип унарных функций фильтрации), преобразуются в новые значения (типа S1, S2 ... Sn, где S1, S2 ... Sn — типы параметров унарных функций фильтрации), а затем передаются (вместе с любой координатой, которая не была изменена адаптацией) целевому обработчику переменной.

Для корректной работы координатных фильтров их типы должны соответствовать форме S1 -> T1, S2 -> T1 ... Sn -> Tn, где T1, T2 ... Tn — типы координат, начиная с позиции pos целевого обработчика переменной.

Результирующий обработчик переменной будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик переменной.

При вызове, например, VarHandle.get(Object...) на результирующем обработчике переменной, входящие координатные значения объединяются со связанными координатными значениями и затем передаются целевому обработчику переменной.

Для корректности связанных координат их типы должны соответствовать T1, T2 ... Tn , где T1, T2 ... Tn — типы координат, начиная с позиции pos целевого обработчика переменной.

Результирующий обработчик переменной будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик переменной.

Данный массив управляет перестановкой. Обозначим количество входящих координат через #I, (значение newCoordinates.size()) и количество исходящих координат (количество координат, связанных с целевым обработчиком переменной) через #O. Тогда длина массива переупорядочения должна быть #O, а каждый элемент должен быть неотрицательным числом, меньшим #I. Для каждого N меньше #O, N-я исходящая координата будет взята из I-й входящей координаты, где I равно reorder[N].

Преобразования значений координат не применяются. Тип каждой входящей координаты, как определено в newCoordinates, должен быть идентичен типу соответствующей исходящей координаты в целевом обработчике переменной.

Массив переупорядочения необязательно должен задавать фактическую перестановку. Входящая координата будет дублироваться, если ее индекс встречается в массиве более одного раза, и входящая координата будет пропущена, если ее индекс не встречается в массиве.

Результирующий обработчик переменной будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик переменной.

Если R — возвращаемый тип фильтра (который не может быть void), целевой обработчик переменной должен принимать значение типа R в качестве координаты на позиции pos, перед и/или после любой координаты, не переданной в фильтр. Координаты не переупорядочиваются, а возвращаемый результат фильтра заменяет (по порядку) всю подпоследовательность координат, изначально переданную адаптеру.

Типы аргументов (если таковые имеются) фильтра заменяют ноль или одну координаты типа целевого обработчика переменной на позиции pos в результирующем адаптаторном обработчике переменной. Возвращаемый тип фильтра должен быть идентичен типу координаты целевого обработчика переменной на позиции pos, и эта координата целевого обработчика переменной предоставляется значением, возвращенным фильтром.

Результирующий обработчик переменной будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик переменной.

Аргумент pos может принимать значения от нуля до N, где N — арность типов координат целевого обработчика переменной. Если pos равно нулю, фиктивные координаты будут предшествовать реальным аргументам целевого обработчика; если pos равно N, они будут следовать за ними.

Результирующий обработчик переменной будет иметь те же режимы доступа (см. VarHandle.AccessMode) и гарантии атомарного доступа, что и целевой обработчик переменной.