Взаимодействие с 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.

Для типов, имеющих оба представления, у того, что имеет «левостороннее значение», есть свойство mutable .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 с жизненным циклом, привязанным к определенной MemScope. Например:

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

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

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

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

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

• fun T.readValue(): CValue<T>. Преобразует (левостороннее значение) 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, которая закрепляет объект, выполняет блок и открепляет его при нормальном завершении и при возникновении исключения.