Interoperar con C: cinterop, punteros y memoria manual

Todo lo que Kotlin promete —nulabilidad en el tipo, inmutabilidad por defecto, memoria administrada— deja de aplicarse en cuanto una llamada cruza hacia C. No porque el diseño sea descuidado, sino porque no hay forma de saber si un puntero devuelto por una biblioteca ajena es válido, si el llamante debe liberarlo o si apunta a memoria de la pila que dejará de existir al retornar. Kotlin resuelve esa asimetría de la única manera honesta posible: modela la frontera con un sistema de tipos deliberadamente incómodo, marca toda la API como experimental para que nadie la use por accidente, y deja el resto en tus manos. Esta lección va sobre esa incomodidad, que es información y no burocracia.

De un encabezado C a un klib

La unidad de trabajo es un fichero de definición que describe qué encabezados leer, contra qué enlazar y bajo qué paquete colocar el resultado. La herramienta cinterop lo procesa, analiza los encabezados con un frontend de C real y emite un klib con declaraciones de Kotlin que se corresponden una a una con las de C.

// zstd.def no es C, pero describe C. Se muestra su contenido tipico.
// headers = zstd.h
// package = zstd
// compilerOpts = -I/usr/local/include
// linkerOpts = -L/usr/local/lib -lzstd
// headerFilter = zstd*.h

kotlin {
    linuxX64 {
        compilations.getByName("main").cinterops {
            val zstd by creating {
                defFile(project.file("src/nativeInterop/cinterop/zstd.def"))
                packageName("zstd")
            }
        }
    }
}

Dos parámetros deciden la calidad del resultado. El filtro de encabezados delimita qué declaraciones se consideran parte de la biblioteca y cuáles son arrastre de las cabeceras del sistema; sin él acabas exponiendo media biblioteca estándar de C en tu paquete y multiplicando el tiempo de compilación. Y las opciones del enlazador son lo que decide si el símbolo existirá en el binario final: cinterop genera declaraciones aunque la biblioteca no esté instalada, y el error aparecerá mucho después, al enlazar.

Toda la API generada exige una activación explícita. En Kotlin moderno, cualquier uso de tipos de interoperabilidad requiere aceptar @OptIn(ExperimentalForeignApi::class), y esa fricción es intencionada: marca en el código exactamente qué funciones renuncian a las garantías del lenguaje.

flowchart TD
A[Encabezados C] --> B[Fichero def]
B --> C[Herramienta cinterop]
C --> D[klib de enlaces]
D --> E[Compilador de Kotlin Native]
F[Codigo Kotlin] --> E
E --> G[Ficheros objeto]
G --> H[Enlazador]
I[Biblioteca estatica o dinamica] --> H
H --> J[Binario final]

Punteros y su tipado

El punto que más resistencia genera es que Kotlin distingue dos conceptos que en C se escriben igual. CPointed representa lo que hay en esa dirección; CPointer representa la dirección misma. Los tipos terminados en Var —IntVar, ByteVar, CPointerVar— son variables de C vistas como celdas de memoria escribibles: tienen una propiedad value que lee y escribe la posición apuntada.

De ahí salen las tres operaciones que se usan todo el tiempo. La propiedad ptr sobre algo apuntado devuelve su dirección; la propiedad pointed sobre una dirección devuelve la celda; y el operador de índice sobre un puntero accede a un elemento con aritmética de punteros implícita. La nulabilidad se modela con el tipo: un puntero que puede ser nulo es CPointer<T>? y el puntero nulo de C es exactamente null en Kotlin, de modo que el operador de aserción y las comprobaciones habituales funcionan sin conversiones.

@OptIn(ExperimentalForeignApi::class)
fun ejemploPunteros() = memScoped {
    val n = alloc<IntVar>()            // reserva un int en memoria nativa
    n.value = 42
    val p: CPointer<IntVar> = n.ptr
    println(p.pointed.value)           // 42

    val buffer = allocArray<ByteVar>(256)
    buffer[0] = 'K'.code.toByte()
    val opaco: COpaquePointer = buffer  // se pierde el tipo, no la direccion
    val recuperado = opaco.reinterpret<ByteVar>()
    println(recuperado[0])
}

La reinterpretación merece una advertencia explícita. reinterpret no comprueba nada: es la contrapartida de un molde de puntero en C y su corrección depende enteramente de que sepas qué hay realmente en esa dirección. Un puntero opaco reinterpretado al tipo equivocado no produce una excepción, produce lecturas de basura o una violación de segmento en un punto arbitrario del programa.

memScoped y el ciclo de vida

Ninguna memoria reservada para C la administra el recolector. memScoped establece un ámbito que actúa como colocador: todo lo que se reserva dentro se libera de golpe al salir del bloque, también si sale por una excepción. Es un arena, no un recolector, y por eso es barato y predecible.

Su límite es el que cabe esperar de un arena: los punteros obtenidos dentro dejan de ser válidos al salir. Devolver un puntero desde dentro de un memScoped es el error más frecuente de esta parte del lenguaje y el compilador no lo detecta, porque el tipo del puntero no dice nada sobre cuánto vive lo que apunta.

@OptIn(ExperimentalForeignApi::class)
fun leerLinea(ruta: String): String? = memScoped {
    val f = fopen(ruta, "r") ?: return null
    try {
        val buf = allocArray<ByteVar>(4096)
        if (fgets(buf, 4096, f) == null) null else buf.toKString()
    } finally {
        fclose(f)                       // el arena no sabe nada de descriptores
    }
}

// Cuando el dato debe sobrevivir al bloque, la reserva es manual y el
// emparejamiento con la liberacion pasa a ser responsabilidad tuya.
@OptIn(ExperimentalForeignApi::class)
class Buffer(tam: Int) {
    private val datos = nativeHeap.allocArray<ByteVar>(tam)
    fun cerrar() = nativeHeap.free(datos)
}

Obsérvese la doble contabilidad del primer ejemplo: el arena libera el búfer, pero el descriptor de fichero abierto con fopen no es memoria y debe cerrarse a mano. memScoped administra reservas, no recursos; confundir ambas cosas produce programas que no fugan memoria y sí agotan descriptores.

Cruzar valores: cadenas, estructuras y retrollamadas

Las cadenas son el caso más frecuente y el que más copias silenciosas esconde. Kotlin guarda cadenas en su propio montículo con su propia codificación, así que pasar una a C exige materializar una copia terminada en cero, y recibir una de C exige copiarla al montículo de Kotlin. La propiedad cstr produce esa copia dentro del ámbito actual; el método toKString hace el viaje inverso y asume codificación UTF-8.

Las estructuras se modelan con dos tipos según dónde vivan. Un valor de estructura por copia es CValue, que es inmutable y se pasa por valor; una estructura reservada en memoria y accesible por referencia se manipula a través de su CPointer y sus campos son propiedades normales. La función cValue construye la primera y useContents permite leerla sin colocarla en ningún sitio.

Las retrollamadas imponen la restricción más severa. Un puntero a función de C no puede llevar estado asociado, de modo que staticCFunction solo acepta lambdas que no capturen nada. El contexto se transporta por el propio protocolo de C, normalmente con un puntero opaco de usuario que la biblioteca devuelve intacto a la retrollamada.

@OptIn(ExperimentalForeignApi::class)
fun registrar(cb: CPointer<CFunction<(Int, COpaquePointer?) -> Unit>>) { /* ... */ }

@OptIn(ExperimentalForeignApi::class)
fun instalar(estado: Estado) {
    val ref = StableRef.create(estado)          // ancla el objeto Kotlin
    registrar(staticCFunction { codigo, datos ->
        val e = datos!!.asStableRef<Estado>().get()
        e.recibir(codigo)
    })
    // ref.dispose() cuando la biblioteca garantice que no habra mas llamadas
}

StableRef es la pieza que faltaba: fija un objeto Kotlin para que el recolector no lo mueva ni lo libere mientras C conserve su dirección, y devuelve un puntero opaco transportable. Es una fuga deliberada hasta que alguien la deshaga, y ese alguien eres tú.