Интерфейс MemoryAddress

Все суперинтерфейсы:: Addressable

public sealed interface MemoryAddress extends Addressable

Адрес в памяти моделирует ссылку на расположение в памяти. Адреса в памяти обычно получают с помощью метода MemorySegment.address(), и могут ссылаться как на память вне кучи, так и на память внутри кучи. Адреса памяти вне кучи называются нативными адресами памяти (см. isNative()). Нативные адреса памяти позволяют клиентам получить сырой адрес памяти (выраженный как значение типа long), который затем можно использовать, например, при взаимодействии с нативным кодом.

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

Адрес в памяти ассоциируется со объёмом ресурсов; объём ресурсов определяет жизненный цикл адреса в памяти и возможность использования адреса из нескольких потоков. Адреса памяти, полученные из численных значений или из нативного кода, ассоциируются с глобальным объёмом ресурсов. Адреса памяти, полученные из сегментов, ассоциируются с тем же объёмом ресурсов, что и сегмент, из которого они были получены.

Все реализации этого интерфейса должны быть базирующимися на значениях; программисты должны рассматривать экземпляры, которые равны, как взаимозаменяемые и не должны использовать экземпляры для синхронизации, иначе может произойти непредсказуемое поведение. Например, в будущей версии синхронизация может завершиться сбоем. Для сравнения следует использовать метод equals .

Классы, не относящиеся к платформе, не должны реализовывать MemoryAddress напрямую.

Если не указано иное, передача null аргумента или аргумента массива, содержащего один или несколько элементов null , методу в этом классе приводит к тому, что выбрасывается исключение NullPointerException.

Требования к реализации:: Реализации этого интерфейса неизменяемы, потокобезопасны и базируются на значениях.

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final MemoryAddress`	`NULL`	Экземпляр нативного адреса в памяти, моделирующий адрес `NULL`, ассоциированный с глобальным объёмом ресурсов.

Краткое описание методов

Модификатор и тип	Метод	Описание
`MemoryAddress`	`addOffset(long offset)`	Создаёт новый адрес в памяти с заданным смещением (в байтах), которое может быть отрицательным, от текущего.
`default MemoryAddress`	`address()`	Преобразует этот объект в экземпляр `MemoryAddress`.
`MemorySegment`	`asSegment(long bytesSize, Runnable cleanupAction, ResourceScope scope)`	Возвращает новый нативный сегмент памяти заданного размера и объёма ресурсов (заменяя объём ресурсов, уже связанный с этим адресом), базовый адрес которого — этот адрес.
`MemorySegment`	`asSegment(long bytesSize, ResourceScope scope)`	Возвращает новый нативный сегмент памяти заданного размера и объёма ресурсов (заменяя объём ресурсов, уже связанный с этим адресом), базовый адрес которого — этот адрес.
`boolean`	`equals(Object that)`	Сравнивает указанный объект с этим адресом на равенство.
`int`	`hashCode()`	Возвращает хэш-код для этого адреса.
`boolean`	`isNative()`	Является ли это адресом памяти вне кучи?
`static MemoryAddress`	`ofLong(long value)`	Получает экземпляр нативного адреса памяти из заданного адреса типа long.
`ResourceScope`	`scope()`	Возвращает объём ресурсов, связанный с этим адресом памяти.
`long`	`segmentOffset(MemorySegment segment)`	Возвращает смещение этого адреса памяти в заданном сегменте.
`long`	`toRawLongValue()`	Возвращает сырое значение типа long, связанное с этим нативным адресом памяти.

Подробное описание полей

NULL

static final MemoryAddress NULL

Примером реализации объекта, представляющего собой адрес в памяти, связанный с глобальным объемом ресурсов, является данный.

Подробное описание методов

address

default MemoryAddress address()

Описание скопировано из интерфейса: Addressable

Преобразует этот объект в экземпляр MemoryAddress.

Specified by:: address в интерфейсе Addressable
Возвращает:: экземпляр MemoryAddress, связанный с этим объектом.

addOffset

MemoryAddress addOffset(long offset)

Создает новый адрес памяти с заданным смещением (в байтах), которое может быть отрицательным, относительно текущего.

Параметры:: offset - указанное смещение (в байтах) относительно этого адреса, которое должно использоваться для создания нового адреса.
Возвращает:: новый адрес памяти с заданным смещением относительно текущего.

scope

ResourceScope scope()

Возвращает объем ресурсов, связанный с этим адресом памяти.

Возвращает:: объем ресурсов, связанный с этим адресом памяти.

segmentOffset

long segmentOffset(MemorySegment segment)

Возвращает смещение этого адреса памяти относительно заданного сегмента. Более конкретно, если базовый адрес сегмента и этот адрес являются адресами в физической памяти, результат вычисляется как this.toRawLongValue() - segment.address().toRawLongValue(). В противном случае, если оба адреса представляют собой (B, O1), (B, O2), где B — один и тот же базовый объект кучи, а O1, O2 — смещения в байтах (относительно базового объекта), связанные с этим адресом и базовым адресом сегмента, результат вычисляется как O1 - O2.

Если базовый адрес сегмента и этот адрес являются адресами в куче, но с разными базовыми объектами, результат неопределен, и будет выброшено исключение. Аналогично, если базовый адрес сегмента является адресом в куче (соответственно, вне кучи), а этот адрес — адресом вне кучи (соответственно, в куче), результат неопределен, и будет выброшено исключение. В противном случае результат представляет собой смещение в байтах SO. Если этот адрес находится в пространственных пределах заданного сегмента, то 0 <= SO < segment.byteSize(); в противном случае, SO < 0 || SO > segment.byteSize().

Параметры:: segment - сегмент относительно которого должно быть вычислено смещение адреса
Возвращает:: смещение этого адреса памяти относительно заданного сегмента.
Исключение:: IllegalArgumentException - если segment несовместим с этим адресом; это может произойти, например, когда segment моделирует область памяти в куче, а этот адрес является адресом в физической памяти.

asSegment

MemorySegment asSegment(long bytesSize, ResourceScope scope)

Возвращает новый сегмент памяти с указанным размером и объемом ресурсов (заменяя объем, уже связанный с этим адресом), базовый адрес которого равен этому адресу. Этот метод может быть полезен при взаимодействии с пользовательскими источниками памяти (например, пользовательскими выделениями), где адрес некоторой подлежащей области памяти обычно получается из кода нативного языка (часто как простое значение long). Возвращаемый сегмент не является только для чтения (см. MemorySegment.isReadOnly()), и связан с предоставленным объемом ресурсов.

Клиенты должны убедиться, что адрес и границы относятся к допустимой области памяти, доступной для чтения и, при необходимости, записи; попытка доступа к недопустимому месту памяти из кода Java вернет произвольное значение, не окажет видимого эффекта или вызовет неопределенное исключение.

Этот метод эквивалентен следующему коду:


    asSegment(byteSize, null, scope);

Этот метод ограничен. Ограниченные методы небезопасны, и, если они используются неправильно, их использование может привести к аварийному завершению JVM или, что еще хуже, к неявной порче памяти. Таким образом, клиенты должны избегать зависимости от ограниченных методов и использовать безопасные и поддерживаемые функции, где это возможно.

Параметры:: bytesSize - желаемый размер.; scope - объем сегмента нативного типа.
Возвращает:: новый сегмент памяти с заданным базовым адресом, размером и объемом.
Исключение:: IllegalArgumentException - если bytesSize <= 0.; IllegalStateException - если объем, связанный с этим адресом, или предоставленный объем уже закрыт, или если доступ происходит из потока, отличного от потока, владеющего этими объемами.; UnsupportedOperationException - если этот адрес не является адресом в физической памяти.; IllegalCallerException - если доступ к этому методу происходит из модуля M и опция командной строки --enable-native-access отсутствует или не упоминает имя модуля M, или ALL-UNNAMED в случае, если M является безымянным модулем.

asSegment

MemorySegment asSegment(long bytesSize, Runnable cleanupAction, ResourceScope scope)

Возвращает новый сегмент памяти с указанным размером и объемом ресурсов (заменяя объем, уже связанный с этим адресом), базовый адрес которого равен этому адресу. Этот метод может быть полезен при взаимодействии с пользовательскими источниками памяти (например, пользовательскими выделениями), где адрес некоторой подлежащей области памяти обычно получается из кода нативного языка (часто как простое значение long). Возвращаемый сегмент связан с предоставленным объемом ресурсов.

Вызов ResourceScope.close() на объеме, связанном с возвращенным сегментом, приведет к вызову предоставленного действия очистки (если таковое имеется).

Параметры:: bytesSize - желаемый размер.; cleanupAction - действие очистки; может быть null.; scope - объем сегмента нативного типа.
Возвращает:: новый сегмент памяти с заданным базовым адресом, размером и объемом.
Исключение:: IllegalArgumentException - если bytesSize <= 0.; IllegalStateException - если объем, связанный с этим адресом, или предоставленный объем уже закрыт, или если доступ происходит из потока, отличного от потока, владеющего этими объемами.; UnsupportedOperationException - если этот адрес не является адресом в физической памяти.; IllegalCallerException - если доступ к этому методу происходит из модуля M и опция командной строки --enable-native-access отсутствует или не упоминает имя модуля M, или ALL-UNNAMED в случае, если M является безымянным модулем.

isNative

boolean isNative()

Является ли это адрес памяти вне кучи?

Возвращает:: true, если это адрес памяти вне кучи.

toRawLongValue

long toRawLongValue()

Возвращает значение типа long, связанное с этим адресом памяти в физической памяти.

Возвращает:: Значение типа long, связанное с этим адресом памяти в физической памяти.
Исключение:: UnsupportedOperationException - если этот адрес памяти не является адресом в физической памяти.; IllegalStateException - если объем, связанный с этим сегментом, уже закрыт, или если доступ происходит из потока, отличного от потока, владеющего сегментом.

equals

boolean equals(Object that)

Сравнивает указанный объект с этим адресом на равенство. Возвращает true тогда и только тогда, когда указанный объект также является адресом и ссылается на ту же область памяти, что и этот адрес.

Overrides:

equals в классе Object

Примечание API:

два адреса могут считаться равными, несмотря на то, что их связанные объемы ресурсов отличаются. Это может произойти, например, если один и тот же адрес памяти используется для создания сегментов памяти с разными объемами ресурсов (используя asSegment(long, ResourceScope)), и базовый адрес полученных сегментов затем сравнивается.

Параметры:

that - объект, который необходимо сравнить на равенство с этим адресом.

Возвращает:

true если указанный объект равен этому адресу.

См. также:

hashCode

int hashCode()

Возвращает значение хэш-кода для этого адреса.

Overrides:

hashCode в классе Object

Возвращает:

значение хэш-кода для этого адреса.

См. также:

ofLong

static MemoryAddress ofLong(long value)

Получение экземпляра адреса в памяти из заданного адреса типа long. Возвращаемый адрес связан со глобальным областью ресурсов.

Параметры:: value - адрес типа long.
Возвращает:: новый экземпляр адреса в памяти.

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/jdk.incubator.foreign/jdk/incubator/foreign/MemoryAddress.html