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