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

В этом примере все значения, передаваемые в 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 и const char* представляют собой разделенные пробелами списки перечислений, которые должны быть сгенерированы как перечисление 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, которая фиксирует объект, выполняет блок и открепляет его по нормальному и исключательному путям.