Взаимодействие с C

Основные типы взаимодействия

Все поддерживаемые типы C имеют соответствующие представления в Kotlin:

• Знаковые, беззнаковые целочисленные и числовые типы с плавающей точкой отображаются на их аналоги в Kotlin с той же шириной.

• Указатели и массивы отображаются на CPointer<T>?.

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

• Структуры и объединения отображаются на типы, члены которых доступны через обозначение точкой, т. е. someStructInstance.field1.

• typedef представлены как typealias.

Также любой тип C имеет тип Kotlin, представляющий lvalue этого типа, т. е. значение, расположенное в памяти, а не просто неизменяемое самодостаточное значение. Подумайте о ссылках C++, как о похожей концепции. Для структур (и typedef к структурам) это представление является основным и имеет то же имя, что и сама структура, для перечислений Kotlin оно называется ${type}Var, для CPointer<T> это CPointerVar<T>, а для большинства других типов это ${type}Var.

Для типов, которые имеют оба представления, представление с «lvalue» имеет изменяемое свойство .value для доступа к значению.

val path = getenv("PATH")?.toKString() ?: ""

fun shift(ptr: CPointer<BytePtr>, length: Int) {
    for (index in 0 .. length - 2) {
        ptr[index] = ptr[index + 1]
    }
}

val intPtr = bytePtr.reinterpret<IntVar>()

val intPtr: CPointer<IntVar> = bytePtr.reinterpret()

val longValue = ptr.toLong()
val originalPtr = longValue.toCPointer<T>()

Выделение памяти

Нативная память может быть выделена с помощью интерфейса NativePlacement , например:

val byteVar = placement.alloc<ByteVar>()

или

val bytePtr = placement.allocArray<ByteVar>(5)

Наиболее «естественное» размещение — в объекте nativeHeap. Оно соответствует выделению нативной памяти с помощью malloc и предоставляет дополнительную операцию .free() для освобождения выделенной памяти:

val buffer = nativeHeap.allocArray<ByteVar>(size)
<use buffer>
nativeHeap.free(buffer)

Однако срок действия выделенной памяти часто привязан к лексическому объёму. Можно определить такой объем с помощью memScoped { ... }. В фигурных скобках временное размещение доступно в качестве неявного получателя, поэтому можно выделить нативную память с помощью alloc и allocArray, и выделенная память будет автоматически освобождена после выхода из области видимости.

Например, функция C, возвращающая значения через параметры указателей, может быть использована следующим образом:

val fileSize = memScoped {
    val statBuf = alloc<stat>()
    val error = stat("/", statBuf.ptr)
    statBuf.st_size
}

Передача указателей в связывания

Хотя указатели C отображаются на тип CPointer<T> , параметры типа указателя функции C отображаются на CValuesRef<T>. При передаче CPointer<T> в качестве значения такого параметра, он передаётся функции C как есть. Однако вместо указателя можно передать последовательность значений. В этом случае последовательность передаётся «по значению», т. е. функция C получает указатель на временную копию этой последовательности, которая действительна только до возврата функции.

Представление CValuesRef<T> параметров указателей разработано для поддержки литералов массивов C без явного выделения нативной памяти. Для создания неизменяемой самодостаточной последовательности значений C предоставляются следующие методы:

• ${type}Array.toCValues(), где type — тип Kotlin-примитива

• Array<CPointer<T>?>.toCValues(), List<CPointer<T>?>.toCValues()

• cValuesOf(vararg elements: ${type}), где type — примитив или указатель

Например:

C:

void foo(int* elements, int count);
...
int elements[] = {1, 2, 3};
foo(elements, 3);

Kotlin:

foo(cValuesOf(1, 2, 3), 3)

Строки

В отличие от других указателей, параметры типа const char* представляются как строка Kotlin String. Поэтому можно передавать любую Kotlin-строку в связывание, ожидающее строку C.

Также доступны некоторые инструменты для ручного преобразования между Kotlin и C-строками:

• fun CPointer<ByteVar>.toKString(): String

• val String.cstr: CValuesRef<ByteVar>.

Для получения указателя нужно выделить .cstr в нативной памяти, например:

val cString = kotlinString.cstr.getPointer(nativeHeap)

Во всех случаях предполагается, что C-строка закодирована в UTF-8.

Для пропуска автоматического преобразования и обеспечения использования сырых указателей в связываниях можно использовать инструкцию noStringConversion в файле .def , например:

noStringConversion = LoadCursorA LoadCursorW

Таким образом, любое значение типа CPointer<ByteVar> может передаваться в качестве аргумента типа const char*. Если нужно передать Kotlin-строку, можно использовать код такого вида:

memScoped {
    LoadCursorA(null, "cursor.bmp".cstr.ptr)   // for ASCII version
    LoadCursorW(null, "cursor.bmp".wcstr.ptr)  // for Unicode version
}

Указатели с областью видимости

Можно создать указатель, устойчивый к области видимости, представления C экземпляра CValues<T> , используя свойство расширения CValues<T>.ptr , доступное в memScoped { ... }. Это позволяет использовать API, которые требуют указателей C с ограниченным сроком действия в определённой области видимости. Например:

memScoped {
    items = arrayOfNulls<CPointer<ITEM>?>(6)
    arrayOf("one", "two").forEachIndexed { index, value -> items[index] = value.cstr.ptr }
    menu = new_menu("Menu".cstr.ptr, items.toCValues().ptr)
    ...
}

В этом примере все значения, передаваемые в API C new_menu() , имеют срок действия самой внутренней области memScope , к которой они относятся. Как только поток управления выходит из области видимости memScoped , указатели C становятся недоступными.

Передача и получение структур по значению

Когда функция C принимает или возвращает структуру/объединение T по значению, соответствующий тип аргумента или возвращаемого значения представляется как CValue<T>.

CValue<T> — это непрозрачный тип, поэтому к полям структуры нельзя обратиться с помощью соответствующих свойств Kotlin. Возможно, если API использует структуры как дескрипторы, но если необходим доступ к полям, доступны следующие методы преобразования:

• fun T.readValue(): CValue<T>. Преобразует (lvalue) T в CValue<T>. Таким образом, чтобы создать CValue<T>, можно выделить T, заполнить его и затем преобразовать в CValue<T>.

• CValue<T>.useContents(block: T.() -> R): R. Временно помещает CValue<T> в память и затем выполняет переданный лямбда-выражение со значением T в качестве получателя. Таким образом, для чтения одного поля можно использовать следующий код:

  val fieldValue = structValue.useContents { field }
  

Обратные вызовы

Для преобразования функции Kotlin в указатель на функцию C можно использовать staticCFunction(::kotlinFunction). Также она может предоставить лямбду вместо ссылки на функцию. Функция или лямбда не должны захватывать какие-либо значения.

val stableRef = StableRef.create(kotlinReference)
val voidPtr = stableRef.asCPointer()

val stableRef = voidPtr.asStableRef<KotlinClass>()
val kotlinReference = stableRef.get()

stableRef.dispose()

Макросы

Каждый C-макрос, который расширяется до константы, представлен как свойство Kotlin. Другие макросы не поддерживаются. Однако их можно вручную экспонировать, обернув их поддерживаемыми объявлениями. Например, макрос-функция FOO может быть экспонирована как функция foo путем добавления пользовательского объявления в библиотеку:

headers = library/base.h

---

static inline int foo(int arg) {
    return FOO(arg);
}

Подсказки файла определения

Файл .def поддерживает несколько вариантов для настройки сгенерированных библиотек.

• Значение свойства excludedFunctions задает список функций, разделенный пробелами, которые должны быть проигнорированы. Это может потребоваться, потому что функция, объявленная в заголовке C, не гарантируется, что она действительно вызываема, и часто определить это автоматически сложно или невозможно. Этот параметр также может использоваться для обхода ошибки в самом механизме взаимодействия.

• Значения свойств strictEnums и nonStrictEnums являются списками перечислений, разделенными пробелами, которые должны быть сгенерированы как перечисление Kotlin или как целочисленные значения соответственно. Если перечисление не включено ни в один из этих списков, то оно генерируется на основе эвристики.

• Значение свойства noStringConversion является списком функций, разделенным пробелами, параметры const char* которых не должны автоматически преобразовываться в строку Kotlin.

Переносимость

Иногда в C-библиотеках есть параметры функций или поля структур платформозависимого типа, например, long или size_t. Сам Kotlin не предоставляет ни неявных целочисленных преобразований, ни преобразований целочисленных типов в стиле C (например, (size_t) intValue). Поэтому, чтобы упростить написание переносимого кода в таких случаях, предоставляется метод convert:

fun ${type1}.convert<${type2}>(): ${type2}

где каждое из type1 и type2 должно быть целочисленного типа, со знаком или без знака.

.convert<${type}> имеет тот же смысл, что и один из методов .toByte, .toShort, .toInt, .toLong, .toUByte, .toUShort, .toUInt или .toULong, в зависимости от type.

Пример использования convert:

fun zeroMemory(buffer: COpaquePointer, size: Int) {
    memset(buffer, 0, size.convert<size_t>())
}

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

Фиксация объектов

Объекты Kotlin могут быть закреплены, т. е. их положение в памяти гарантировано остается неизменным до момента открепления, и указатели на внутренние данные таких объектов могут передаваться в функции C. Например:

fun readData(fd: Int): String {
    val buffer = ByteArray(1024)
    buffer.usePinned { pinned ->
        while (true) {
            val length = recv(fd, pinned.addressOf(0), buffer.size.convert(), 0).toInt()

            if (length <= 0) {
               break
            }
            // Now `buffer` has raw data obtained from the `recv()` call.
        }
    }
}

Здесь мы используем вспомогательную функцию usePinned, которая закрепляет объект, выполняет блок и открепляет его при нормальном и исключительном завершении.