Интерфейс CLinker

public sealed interface CLinker

Реализация C-линкера обеспечивает соответствие соглашениям вызова C Application Binary Interface (ABI). Экземпляры этого интерфейса могут использоваться для связывания внешних функций в нативных библиотеках, которые следуют ABI C целевой платформы JVM.

Связывание внешней функции — это процесс, требующий двух компонентов: тип метода и дескриптор функции. Тип метода состоит из набора типов носителей, которые вместе задают сигнатуру Java, которой клиенты должны следовать при вызове основной внешней функции. Дескриптор функции содержит набор макетов памяти, которые вместе задают сигнатуру внешней функции и информацию о классификации (через пользовательские атрибуты макета, см. CLinker.TypeKind), чтобы связывание могло произойти.

Клиенты этого API могут создавать дескрипторы функций, используя предопределенные константы макетов памяти (на основе подмножества встроенных типов языка C), которые содержатся в этом интерфейсе; альтернативно, они также могут дополнять существующие макеты значений требуемым атрибутом классификации CLinker.TypeKind (это можно сделать с помощью метода MemoryLayout.withAttribute(String, Constable)). Отсутствие этого может привести к ошибкам связывания, так как связывание требует дополнительной информации о классификации для определения, например, того, как аргументы должны загружаться в регистры во время вызова внешней функции.

Реализации этого интерфейса поддерживают следующие примитивные типы носителей: byte, short, char, int, long, float, и double, а также MemoryAddress для передачи указателей и MemorySegment для передачи структур и объединений. Наконец, тип носителя CLinker.VaList может использоваться для сопоставления с родным типом va_list.

Для успешного процесса связывания должны быть соблюдены некоторые требования; если M и F — тип метода (полученный после удаления префиксных аргументов) и дескриптор функции соответственно, используемые во время процесса связывания, то должны выполняться следующие условия:

Арность M должна быть такой же, как у F;
Если возвращаемый тип M равен void, то F не должно иметь возвращаемого макета (см. FunctionDescriptor.ofVoid(MemoryLayout...));
для каждой пары типа носителя C и макета L в M и F соответственно, где C и L относятся к одному аргументу или возвращаемому значению, должны выполняться следующие условия:
- Если C — примитивный тип, то L должен быть ValueLayout, а размер макета должен соответствовать размеру типа носителя (см. Integer.SIZE и аналогичные поля в других классах обёртки примитивных типов);
- Если C — MemoryAddress.class, то L должен быть ValueLayout, а его размер должен соответствовать размеру адреса платформы (см. MemoryLayouts.ADDRESS). Для этой цели можно использовать константу макета C_POINTER;
- Если C — MemorySegment.class, то L должен быть GroupLayout
- Если C — VaList.class, то L должен быть C_VA_LIST

Функции с переменным числом аргументов, объявленные в C с трейлинг-эллипсами (...) в конце списка формальных параметров или со пустым списком формальных параметров, не поддерживаются напрямую. Невозможно создать обработчик методов, принимающий переменное количество аргументов, а также невозможно создать заглушку upcall, оборачивающую обработчик методов, принимающий переменное количество аргументов. Однако только для downcalls можно связать нативную функцию с переменным числом аргументов, используя специализированный тип метода и дескриптор функции: для каждого аргумента, который должен передаваться как аргумент с переменным числом аргументов, должен присутствовать явный дополнительный тип носителя и макет памяти в типе метода и объектах дескриптора функции, переданных линкеру. Кроме того, поскольку макеты памяти, соответствующие аргументам с переменным числом аргументов в дескрипторе функции, должны содержать дополнительную информацию о классификации, требуется использовать asVarArg(MemoryLayout) для создания макетов памяти для каждого параметра, соответствующего аргументу с переменным числом аргументов в специализированном дескрипторе функции.

На платформах, которые не поддерживаются, этот класс не сможет инициализироваться с ExceptionInInitializerError.

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

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

END_OF_DOCUMENT_MARKER

Краткое описание вложенных классов

Модификатор и тип	Интерфейс	Описание
`static enum`	`CLinker.TypeKind`	Тип C.
`static interface`	`CLinker.VaList`	Интерфейс, моделирующий тип C `va_list`.

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

Модификатор и тип	Поле	Описание
`static final ValueLayout`	`C_CHAR`	Макет типа C `char`.
`static final ValueLayout`	`C_DOUBLE`	Макет типа C `double`.
`static final ValueLayout`	`C_FLOAT`	Макет типа C `float`.
`static final ValueLayout`	`C_INT`	Макет типа C `int`.
`static final ValueLayout`	`C_LONG`	Макет типа C `long`.
`static final ValueLayout`	`C_LONG_LONG`	Макет типа C `long long`.
`static final ValueLayout`	`C_POINTER`	Нативный тип `T*`.
`static final ValueLayout`	`C_SHORT`	Макет типа C `short`.
`static final MemoryLayout`	`C_VA_LIST`	Макет типа C `va_list`.

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

Модификатор и тип	Метод	Описание
`static MemoryAddress`	`allocateMemory(long size)`	Выделяет память заданного размера с помощью malloc.
`static <T extends MemoryLayout> T`	`asVarArg(T layout)`	Возвращает макет памяти, подходящий для использования в качестве макета для аргументов с переменным числом аргументов в специализированном описателе функций.
`MethodHandle`	`downcallHandle(MethodType type, FunctionDescriptor function)`	Получает дескриптор внешнего метода с заданным типом и содержащим указанный описатель функции, который может использоваться для вызова целевой внешней функции по адресу.
`MethodHandle`	`downcallHandle(Addressable symbol, MethodType type, FunctionDescriptor function)`	Получает дескриптор внешнего метода с заданным типом и содержащим указанный описатель функции, который может использоваться для вызова целевой внешней функции по указанному адресу.
`MethodHandle`	`downcallHandle(Addressable symbol, SegmentAllocator allocator, MethodType type, FunctionDescriptor function)`	Получает дескриптор внешнего метода с заданным типом и содержащим указанный описатель функции, который может использоваться для вызова целевой внешней функции по указанному адресу.
`static void`	`freeMemory(MemoryAddress addr)`	Освобождает память, указанную заданным адресом памяти.
`static CLinker`	`getInstance()`	Возвращает компоновщик C для текущей платформы.
`static SymbolLookup`	`systemLookup()`	Получает системный поиск, подходящий для поиска символов в стандартных библиотеках C.
`static MemorySegment`	`toCString(String str, ResourceScope scope)`	Преобразует строку Java в строку C, закодированную в UTF-8 и завершающуюся нулём, сохраняя результат в сегменте памяти, связанном с предоставленным ресурсным копом.
`static MemorySegment`	`toCString(String str, SegmentAllocator allocator)`	Преобразует строку Java в строку C, закодированную в UTF-8 и завершающуюся нулём, сохраняя результат в сегменте памяти, выделенном с помощью предоставленного аллокатора.
`static String`	`toJavaString(MemoryAddress addr)`	Преобразует строку C, закодированную в UTF-8 и завершающуюся нулём, хранящуюся по заданному адресу, в строку Java.
`static String`	`toJavaString(MemorySegment addr)`	Преобразует строку C, закодированную в UTF-8 и завершающуюся нулём, хранящуюся по заданному адресу, в строку Java.
`MemoryAddress`	`upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope)`	Выделяет нативный заглушку с заданным копом, который может передаваться другим внешним функциям (в качестве указателя на функцию); вызов такого указателя на функцию из кода нативно приведет к выполнению предоставленного дескриптора метода.

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

C_CHAR

static final ValueLayout C_CHAR

Макет для типа C char

C_SHORT

static final ValueLayout C_SHORT

Макет для типа C short

C_INT

static final ValueLayout C_INT

Макет для типа C int

C_LONG

static final ValueLayout C_LONG

Макет для типа C long

C_LONG_LONG

static final ValueLayout C_LONG_LONG

Макет для типа C long long.

C_FLOAT

static final ValueLayout C_FLOAT

Макет для типа C float

C_DOUBLE

static final ValueLayout C_DOUBLE

Макет для типа C double

C_POINTER

static final ValueLayout C_POINTER

Родной тип.

C_VA_LIST

static final MemoryLayout C_VA_LIST

Макет для типа C va_list

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

getInstance

static CLinker getInstance()

Возвращает компоновщик C для текущей платформы.

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

Возвращает:: компоновщик для этой системы.
Имеет исключения:: IllegalCallerException - если доступ к этому методу осуществляется из модуля M, и параметр командной строки --enable-native-access отсутствует, или не упоминает имя модуля M, или ALL-UNNAMED в случае, если M является безымянным модулем.

systemLookup

static SymbolLookup systemLookup()

Получает поиск системы, подходящий для поиска символов в стандартных библиотеках C. Набор символов, доступных для поиска, не определён, так как он зависит от платформы и операционной системы.

Возвращает:: поиск библиотеки, специфичный для системы, подходящий для поиска символов в стандартных библиотеках C.
Имеет исключения:: IllegalCallerException - если доступ к этому методу осуществляется из модуля M, и параметр командной строки --enable-native-access отсутствует, или не упоминает имя модуля M, или ALL-UNNAMED в случае, если M является безымянным модулем.

downcallHandle

MethodHandle downcallHandle(Addressable symbol, MethodType type, FunctionDescriptor function)

Получает обработчик внешнего метода с заданным типом и функцией описания, который можно использовать для вызова целевой внешней функции по указанному адресу.

Если тип возвращаемого значения предоставленного типа метода — MemorySegment, то полученный обработчик метода содержит дополнительный параметр префикса типа SegmentAllocator, который будет использоваться runtime компоновщиком для выделения структур, возвращаемых по значению.

Параметры:

symbol - символ обратного вызова.

type - тип метода.

function - описание функции.

Возвращает:

обработчик метода обратного вызова.

Имеет исключения:

IllegalArgumentException - в случае несоответствия типа метода и описания функции, или если символ является MemoryAddress.NULL

См. также:

SymbolLookup

downcallHandle

MethodHandle downcallHandle(Addressable symbol, SegmentAllocator allocator, MethodType type, FunctionDescriptor function)

Если тип возвращаемого значения предоставленного типа метода — MemorySegment, то предоставленный выделенный объект памяти будет использоваться runtime компоновщиком для выделения структур, возвращаемых по значению.

Параметры:

symbol - символ обратного вызова.

allocator - выделенный объект памяти.

type - тип метода.

function - описание функции.

Возвращает:

обработчик метода обратного вызова.

Имеет исключения:

IllegalArgumentException - в случае несоответствия типа метода и описания функции, или если символ является MemoryAddress.NULL

См. также:

SymbolLookup

downcallHandle

MethodHandle downcallHandle(MethodType type, FunctionDescriptor function)

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

Если тип возвращаемого значения предоставленного типа метода — MemorySegment, то результирующий обработчик метода содержит дополнительный параметр префикса (вставленный сразу после параметра адреса), типа SegmentAllocator, который будет использоваться runtime компоновщиком для выделения структур, возвращаемых по значению.

Возвращаемый обработчик метода выбросит IllegalArgumentException, если целевой адрес, переданный ему, равен MemoryAddress.NULL, или NullPointerException, если целевой адрес — null.

Параметры:

type - тип метода.

function - описание функции.

Возвращает:

обработчик метода обратного вызова.

Имеет исключения:

IllegalArgumentException - в случае несоответствия типа метода и описания функции.

См. также:

SymbolLookup

upcallStub

MemoryAddress upcallStub(MethodHandle target, FunctionDescriptor function, ResourceScope scope)

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

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

Целевой обработчик метода не должен генерировать исключения. Если целевой обработчик метода выбросит исключение, VM завершится с ненулевым кодом выхода. Чтобы предотвратить аварийное завершение VM из-за необработанного исключения, клиенты могли бы обернуть весь код в целевом обработчике метода в блок try/catch, который ловит любой Throwable, например, используя MethodHandles.catchException(MethodHandle, Class, MethodHandle) комбинатор обработчика метода, и обработать исключения как нужно в соответствующем блоке catch.

Параметры:: target - целевой обработчик метода.; function - описание функции.; scope - объем заглушки обратного вызова.
Возвращает:: сегмент нативной заглушки.
Имеет исключения:: IllegalArgumentException - если тип метода цели и описание функции не совпадают.; IllegalStateException - если scope уже закрыт, или если доступ происходит из потока, отличного от потока, владеющего scope.

asVarArg

static <T extends MemoryLayout> T asVarArg(T layout)

Возвращает макет памяти, подходящий для использования в качестве макета для аргументов с переменным числом параметров в специализированном описании функции.

Параметры типа:: T - тип макета памяти
Параметры:: layout - макет для адаптации
Возвращает:: возможно, новый макет с нужными атрибутами

toCString

static MemorySegment toCString(String str, SegmentAllocator allocator)

Преобразует строку Java в UTF-8 закодированную, завершающуюся нулём строку C, сохраняя результат в сегменте памяти, выделенном с помощью предоставленного аллокатора.

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

Parameters:: str - строка Java, которая должна быть преобразована в строку C.; allocator - аллокатор, который должен быть использован для выделения сегмента.
Returns:: новый сегмент памяти, содержащий преобразованную строку C.

toCString

static MemorySegment toCString(String str, ResourceScope scope)

Преобразует строку Java в UTF-8 закодированную, завершающуюся нулём строку C, сохраняя результат в сегменте памяти, связанном с предоставленным ресурсным пространством.

Parameters:: str - строка Java, которая должна быть преобразована в строку C.; scope - ресурсное пространство, которое должно быть связано с возвращённым сегментом.
Returns:: новый сегмент памяти, содержащий преобразованную строку C.
Throws:: IllegalStateException - если scope уже закрыто, или если доступ происходит из потока, отличного от потока, владеющего scope.

toJavaString

static String toJavaString(MemoryAddress addr)

Преобразует UTF-8 закодированную, завершающуюся нулём строку C, хранящуюся по указанному адресу, в строку Java.

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

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

Parameters:: addr - адрес, по которому хранится строка.
Returns:: строка Java с содержимым завершающейся нулём строки C по данному адресу.
Throws:: IllegalArgumentException - если размер родной строки больше максимальной поддерживаемой платформой строки, или если addr == MemoryAddress.NULL.; IllegalCallerException - если доступ к этому методу происходит из модуля M и опция командной строки --enable-native-access либо отсутствует, либо не упоминает имя модуля M, или ALL-UNNAMED в случае, если M является безымянным модулем.

toJavaString

static String toJavaString(MemorySegment addr)

Преобразует UTF-8 закодированную, завершающуюся нулём строку C, хранящуюся по указанному адресу, в строку Java.

Parameters:: addr - адрес, по которому хранится строка.
Returns:: строка Java с содержимым завершающейся нулём строки C по данному адресу.
Throws:: IllegalArgumentException - если размер родной строки больше максимальной поддерживаемой платформой строки.; IllegalStateException - если размер родной строки больше размера сегмента, связанного с addr, или если addr связано с сегментом, который не активен.

allocateMemory

static MemoryAddress allocateMemory(long size)

Выделяет память заданного размера с помощью malloc.

Parameters:: size - размер памяти для выделения
Returns:: адрес памяти addr выделенной памяти
Throws:: OutOfMemoryError - если malloc не смог выделить требуемое количество родной памяти.; IllegalCallerException - если доступ к этому методу происходит из модуля M и опция командной строки --enable-native-access либо отсутствует, либо не упоминает имя модуля M, или ALL-UNNAMED в случае, если M является безымянным модулем.

freeMemory

static void freeMemory(MemoryAddress addr)

Освобождает память, указанную данным адресом памяти.

Parameters:: addr - адрес памяти родной памяти, которая должна быть освобождена
Throws:: IllegalCallerException - если доступ к этому методу происходит из модуля M и опция командной строки; IllegalArgumentException - если addr == MemoryAddress.NULL. --enable-native-access либо отсутствует, либо не упоминает имя модуля M, или ALL-UNNAMED в случае, если M является безымянным модулем.

© 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/CLinker.html