Usar C++ desde Rust: cómo un envoltorio seguro convierte un use-after-free en un error de compilaciónUsing C++ from Rust: how a safe wrapper turns a use-after-free into a compile error

El mismo bug, escrito dos veces#

Esta entrada gira alrededor de una librería pequeña y real: un almacén clave-valor escrito en C++ sobre std::unordered_map, con una API en C, que se usa desde Rust a través de un envoltorio seguro. Todo el código compila y lo he ejecutado en mi equipo. Empecemos por un programa en C++ de veintiuna líneas:

// cl /std:c++20 /EHsc /W4 /Zi /fsanitize=address dangling.cpp kv.cpp
// El bug: guardar el puntero de kv_get y usarlo después de un kv_set.
#include "kv.h"
#include <cstdio>

int main() {
    kv* db = kv_new();
    // 27 caracteres: más de lo que std::string guarda dentro del propio
    // objeto (15 o 22, según la biblioteca), así que va al heap.
    kv_set(db, "email", "ana.garcia.tome@example.com");

    // Apunta dentro del std::string que guarda el valor.
    const char* email = kv_get(db, "email");

    // Un valor más largo no cabe en el búfer actual: std::string reserva
    // uno nuevo y libera el viejo, al que sigue apuntando `email`.
    kv_set(db, "email", "ana.garcia.fernandez.tome@example-company.com");

    std::printf("%s\n", email);  // lectura de memoria ya liberada
    kv_free(db);
}

Compila con cl /W4 sin un solo aviso, y también con g++ -Wall -Wextra -pedantic. Pero al ejecutarlo con AddressSanitizer, que vigila cada acceso a memoria mientras el programa se ejecuta, aparece esto.

Esta es la salida real en mi equipo, un Intel Core i9-14900KF con Windows 11, con MSVC y AddressSanitizer (un extracto: […] marca las líneas quitadas):

==17532==ERROR: AddressSanitizer: heap-use-after-free on address 0x126bd17a0760 […]
READ of size 2 at 0x126bd17a0760 thread T0
    […]
    #12 0x7ff78e401094 in main dangling.cpp:19
    […]
0x126bd17a0760 is located 0 bytes inside of 32-byte region [0x126bd17a0760,0x126bd17a0780)
freed by thread T0 here:
    […]
    #8 0x7ff78e401926 in `anonymous namespace'::Store::set kv.cpp:22
    #9 0x7ff78e4012b6 in kv_set kv.cpp:53
    #10 0x7ff78e401083 in main dangling.cpp:17
    […]
previously allocated by thread T0 here:
    […]
    #10 0x7ff78e401926 in `anonymous namespace'::Store::set kv.cpp:22
    #11 0x7ff78e4012b6 in kv_set kv.cpp:53
    #12 0x7ff78e401055 in main dangling.cpp:10
    […]
SUMMARY: AddressSanitizer: heap-use-after-free […]

La traza se lee de abajo arriba. La memoria se reservó en la línea 10, con el primer kv_set. Se liberó en la línea 17, con el segundo kv_set, dentro de std::string::operator= (kv.cpp:22). Y se leyó en la línea 19, en el printf: un uso después de liberar (use-after-free). La región de 32 bytes es el búfer donde vivía el primer valor en la biblioteca de MSVC.

El culpable no es la tabla hash. std::unordered_map no invalida los punteros ni las referencias a sus elementos cuando se reorganiza (el rehash); lo dice el estándar en [unord.req.general]. El culpable es el std::string: sus funciones miembro que no son const, como la asignación, pueden invalidar los punteros a su contenido ([string.require]). Si el valor nuevo no cabe en el búfer actual, la asignación reserva uno nuevo y libera el viejo, y email sigue apuntando al viejo.

Por eso el primer valor tiene 27 caracteres. Una cadena corta cabe dentro del propio objeto std::string, sin ir al heap: hasta 15 caracteres en MSVC y en libstdc++, hasta 22 en libc++. Con un valor corto no habría memoria liberada y AddressSanitizer no vería nada.

Ahora, el mismo bug escrito en Rust, con el envoltorio que veremos en esta entrada:

// cargo build --example dangling --features show-bug
// No compila, a propósito.
// El mismo bug que dangling.cpp, escrito en Rust con el envoltorio.
use kvdemo::Kv;

fn main() {
    let mut db = Kv::new().unwrap();
    db.set("email", "ana.garcia.tome@example.com").unwrap();

    // email es un &str prestado de db
    let email = db.get("email").unwrap();

    db.set("email", "ana.garcia.fernandez.tome@example-company.com")
        .unwrap();

    println!("{email}");
}

Esta es la salida real en mi equipo, con cargo build:

error[E0502]: cannot borrow `db` as mutable because it is also borrowed as immutable
  --> examples\dangling.rs:13:5
   |
11 |     let email = db.get("email").unwrap();
   |                 -- immutable borrow occurs here
12 |
13 |     db.set("email", "ana.garcia.fernandez.tome@example-company.com")
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ mutable borrow occurs here
...
16 |     println!("{email}");
   |                ----- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `kvdemo` (example "dangling") due to 1 previous error

No compila. El borrow checker ve que email es un préstamo de db que sigue vivo en la línea 16, y no deja que set lo modifique mientras tanto.

Pero conviene ser precisos, porque es la idea de toda la entrada: Rust no sabe nada de std::string. El compilador no conoce las reglas de invalidación de C++. Lo que hace cumplir es el contrato que escribí en el envoltorio: «el puntero de kv_get vale hasta el siguiente kv_set o kv_free», expresado como un &str cuyo lifetime depende de &self, más un set que pide &mut self. Si el envoltorio estuviera mal escrito, por ejemplo si get devolviera un &'static str, compilaría y el bug volvería.

En Un secreto que ejecutaba código conté que Rust elimina clases enteras de fallos de memoria, pero no los fallos de significado. Aquí se ve la otra cara: un fallo de memoria de C++ que Rust sí impide, porque el envoltorio lo expresa en tipos. El borrow checker está haciendo cumplir una regla de C++ porque alguien la escribió en los tipos de Rust.

Qué es unsafe de verdad#

Para escribir ese envoltorio hace falta unsafe, y es fácil entenderlo mal. unsafe no desactiva el borrow checker ni ninguna otra comprobación del compilador. Según el libro de Rust, desbloquea exactamente cinco superpoderes:

1. desreferenciar un puntero crudo;
2. llamar a una función unsafe, incluida cualquiera declarada a través de FFI;
3. acceder a una variable static mut o modificarla;
4. implementar un trait unsafe;
5. acceder a los campos de una union.

Todo lo demás se sigue comprobando igual, dentro y fuera del bloque. Es lo que hace a Rust tan seguro, como contamos en Por qué Rust sigue siendo el lenguaje más seguro en 2026: esas garantías siguen activas, y unsafe solo abre esas cinco puertas.

En mi guía de Rust de sistemas lo resumo así: unsafe no es una forma de callar al compilador, sino una promesa tuya. Le dices al compilador que has comprobado a mano lo que él no puede comprobar. Si la promesa es falsa, el resultado es el mismo comportamiento indefinido que en C++.

En el código de esta entrada aparecen tres de los cinco:

Y una convención que sigue todo el código: cada bloque unsafe lleva encima un comentario // SAFETY: que justifica por qué la promesa se cumple. Es la práctica habitual en Rust, y hace que cada promesa se pueda revisar.

La frontera en C#

Rust y C++ no se hablan directamente. Se hablan a través de C, que es el idioma común de casi todos los lenguajes: la convención de llamada de C y tipos que los dos lados entienden igual.

Esta es toda la API, el archivo kv.h:

// kv.h: API en C de un almacén clave-valor escrito en C++.
// Todo lo que cruza esta frontera es C: punteros, enteros y structs
// planos.
#pragma once
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
#define KV_NOEXCEPT noexcept
extern "C" {
#else
#define KV_NOEXCEPT
#endif

// Opaco: quien use la API solo maneja punteros, nunca ve el interior.
typedef struct kv kv;

// Códigos de error: las excepciones de C++ no cruzan la frontera.
enum { KV_OK = 0, KV_EINVAL = 1, KV_ENOMEM = 2, KV_EINTERNAL = 3 };

// Struct compartido por valor: el diseño en memoria tiene que coincidir
// byte a byte en los dos lados.
typedef struct kv_stats {
    uint8_t  version;  // versión del struct
    uint64_t entries;  // número de entradas
    uint32_t buckets;  // cubetas de la tabla hash
} kv_stats;

// Devuelve 0 para seguir recorriendo, cualquier otro valor para parar.
typedef int (*kv_visit_fn)(const char* key, const char* value, void* ctx);

// NULL si no hay memoria. kv_free acepta NULL.
kv*         kv_new(void) KV_NOEXCEPT;
void        kv_free(kv* self) KV_NOEXCEPT;
int         kv_set(kv* self, const char* key,
                   const char* value) KV_NOEXCEPT;
// El puntero devuelto es válido hasta el siguiente kv_set o kv_free.
const char* kv_get(const kv* self, const char* key) KV_NOEXCEPT;
void        kv_stats_get(const kv* self, kv_stats* out) KV_NOEXCEPT;
void        kv_for_each(const kv* self, kv_visit_fn visit,
                        void* ctx) KV_NOEXCEPT;

#ifdef __cplusplus
}
#endif

Cuatro decisiones que merece la pena mirar:

• Tipo opaco. typedef struct kv kv; declara el tipo sin mostrar su contenido. Quien usa la API solo maneja punteros a kv y nunca ve lo que hay dentro, así que el interior puede cambiar sin romper a nadie.
• Códigos de error en vez de excepciones. C no tiene excepciones, y Rust tampoco sabe qué hacer con ellas. Cada error se convierte en un número.
• extern "C". Pide a C++ que use la convención de llamada de C y que no decore los nombres, así que desde fuera se ven como kv_new, kv_set…
• La macro KV_NOEXCEPT. En C++17, noexcept forma parte del tipo de la función, así que la declaración del header tiene que coincidir con la definición. En C la macro no pone nada.

Por debajo de la frontera, la librería es C++ normal. Este fragmento de kv.cpp es la clase que guarda los datos, que lanza std::invalid_argument si la clave está vacía, y la función kv_set, que traduce cada excepción a un código de error:

// C++ normal: lanza excepciones y usa la biblioteca estándar.
class Store {
public:
    void set(const char* key, const char* value) {
        if (key == nullptr || *key == '\0')
            throw std::invalid_argument("empty key");
        map_[key] = value;
    }
    const std::string* get(const char* key) const {
        auto it = map_.find(key);
        return it == map_.end() ? nullptr : &it->second;
    }
    const auto& items() const { return map_; }

private:
    std::unordered_map<std::string, std::string> map_;
};

// Ninguna excepción sale de aquí: cada una se traduce a un código de
// error.
int kv_set(kv* self, const char* key, const char* value) noexcept {
    try {
        self->set(key, value);
        return KV_OK;
    } catch (const std::invalid_argument&) {
        return KV_EINVAL;
    } catch (const std::bad_alloc&) {
        return KV_ENOMEM;
    } catch (...) {
        return KV_EINTERNAL;
    }
}

kv_set está marcada noexcept, y eso no hace magia. Si una excepción intentara salir de una función noexcept, C++ llamaría a std::terminate ([except.handle]): el programa abortaría igual, aunque de forma definida, en vez de desenrollar la pila hacia Rust. Por eso kv_set las captura todas y las convierte en códigos. Lo mismo vale para kv_for_each, que llama a un callback que no controla:

// noexcept: si el callback lanzara, std::terminate en vez de desenrollar
// la pila hacia quien nos llamó.
void kv_for_each(const kv* self, kv_visit_fn visit, void* ctx) noexcept {
    for (const auto& [key, value] : self->items())
        if (visit(key.c_str(), value.c_str(), ctx) != 0)
            break;
}

Y hay una línea del header que es la más importante de todas, aunque parezca un comentario más: «El puntero devuelto es válido hasta el siguiente kv_set o kv_free». Es el contrato de kv_get, y es la regla que el envoltorio va a convertir en un lifetime.

Así se usa la librería desde Rust, con el envoltorio seguro:

// cargo run
// Usa la librería C++ desde Rust a través del envoltorio seguro.
use kvdemo::{Kv, KvError, ffi::KvStats};

// Los mismos campos que KvStats, con el diseño por defecto de Rust.
#[allow(dead_code)]
struct StatsRustLayout {
    version: u8,
    entries: u64,
    buckets: u32,
}

fn main() -> Result<(), KvError> {
    println!("size_of KvStats (repr C) = {}", size_of::<KvStats>());
    println!(
        "size_of same fields (repr Rust) = {}",
        size_of::<StatsRustLayout>()
    );

    let mut db = Kv::new()?;
    db.set("lang", "rust")?;
    db.set("ffi", "c++")?;
    println!("get(lang) = {:?}", db.get("lang"));
    println!("get(nope) = {:?}", db.get("nope"));

    // Errores de C++ (una excepción) y de Rust (un NUL dentro de la
    // cadena)
    println!("set(\"\") = {:?}", db.set("", "x"));
    println!("set(\"a\\0b\") = {:?}", db.set("a\0b", "x"));

    let s = db.stats();
    println!(
        "stats: version={} entries={} buckets={}",
        s.version, s.entries, s.buckets
    );

    let mut keys = Vec::new();
    db.for_each(|k, _| {
        keys.push(k.to_owned());
        true
    });
    keys.sort();
    println!("keys = {keys:?}");
    Ok(())
}

Esta es la salida real en mi equipo, con cargo run:

size_of KvStats (repr C) = 24
size_of same fields (repr Rust) = 16
get(lang) = Some("rust")
get(nope) = None
set("") = Err(InvalidKey)
set("a\0b") = Err(InteriorNul)
stats: version=1 entries=2 buckets=8
keys = ["ffi", "lang"]

Los errores llegan desde los dos lados de la frontera. set("") devuelve Err(InvalidKey): es una excepción de C++, std::invalid_argument, convertida en código de error por kv_set. set("a\0b") devuelve Err(InteriorNul) sin llegar a C++: una cadena de C termina en el primer NUL, así que no puede contener uno dentro, y CString::new la rechaza antes de cruzar.

Un detalle de la salida: buckets=8 es lo que hace la biblioteca estándar de MSVC. Otra biblioteca estándar da otro número de cubetas.

#[repr(C)] y el relleno#

Además de punteros y enteros, por la frontera cruza un struct por valor: kv_stats. Para eso, los dos lados tienen que estar de acuerdo en su diseño en memoria, byte a byte. Con tres campos, uint8_t version, uint64_t entries y uint32_t buckets, las reglas de alineación de C dan:

Los dos lados lo comprueban al compilar. En C++, en kv.cpp:

// El diseño de kv_stats es parte de la API: si cambia, el build falla
// aquí. 1 + 7 (relleno) + 8 + 4 + 4 (relleno) = 24 bytes.
static_assert(sizeof(kv_stats) == 24);
static_assert(alignof(kv_stats) == 8);

Y en Rust, en lib.rs, con el mismo struct marcado #[repr(C)] y una aserción que se evalúa en tiempo de compilación:

    /// El mismo diseño en memoria que `kv_stats` en C.
    #[repr(C)]
    #[derive(Debug, Default, Clone, Copy)]
    pub struct KvStats {
        pub version: u8,
        pub entries: u64,
        pub buckets: u32,
    }

// Si el diseño en memoria no coincide con el de C, no compila.
const _: () = assert!(size_of::<ffi::KvStats>() == 24);
const _: () = assert!(align_of::<ffi::KvStats>() == 8);

Si algún lado cambia, no compila. Las dos primeras líneas de la salida de cargo run muestran por qué hace falta #[repr(C)]: 24 bytes con él, y 16 con los mismos campos y el diseño por defecto de Rust (el struct StatsRustLayout de main.rs).

Esos 16 bytes merecen un matiz: no están garantizados. La Referencia de Rust dice que, con el diseño por defecto, el orden de los campos no está especificado. 16 es lo que hace este compilador, rustc 1.98.1, que coloca los campos de otra forma para ahorrar relleno. Lo único garantizado es #[repr(C)].

En mi guía de C++ de sistemas enseño lo mismo desde el otro lado. struct Bad { char a; int x; char b; } ocupa unos 12 bytes, y struct Good { int x; char a; char b; }, con los mismos campos en otro orden, unos 8. En C++ reordenas tú a mano. Rust reordena solo cuando no le pides repr(C), y precisamente por eso un struct que cruza la frontera tiene que llevarlo. En mi guía de Rust lo dejé escrito así: sin #[repr(C)], un struct compartido con C no tiene ninguna garantía de diseño.

El envoltorio seguro#

Todo el unsafe del crate vive en un solo archivo, lib.rs. Vamos por partes.

Primero, la declaración de las funciones de C:

    unsafe extern "C" {
        // No recibe punteros: llamarla no puede romper nada.
        pub safe fn kv_new() -> *mut Kv;
        pub fn kv_free(this: *mut Kv);
        pub fn kv_set(
            this: *mut Kv,
            key: *const c_char,
            value: *const c_char,
        ) -> c_int;
        pub fn kv_get(
            this: *const Kv,
            key: *const c_char,
        ) -> *const c_char;
        pub fn kv_stats_get(this: *const Kv, out: *mut KvStats);
        pub fn kv_for_each(
            this: *const Kv,
            visit: KvVisitFn,
            ctx: *mut c_void,
        );
    }

Desde la edición 2024, los bloques extern tienen que llevar unsafe: declarar una función externa ya es una promesa sobre su firma, que el compilador no puede comprobar. Dentro del bloque, cada función se puede marcar safe, estable desde Rust 1.82. Aquí kv_new es safe fn porque no recibe punteros: llamarla no puede romper nada. Las demás siguen siendo unsafe de llamar.

Después, el tipo opaco del lado de Rust:

    /// Tipo opaco: no tiene campos accesibles ni tamaño conocido, y el
    /// marcador lo deja sin Send, Sync ni Unpin automáticos.
    #[repr(C)]
    pub struct Kv {
        _data: (),
        _marker: PhantomData<(*mut u8, PhantomPinned)>,
    }

Es la forma que recomienda el Nomicon: un struct sin campos útiles, con un marcador PhantomData<(*mut u8, PhantomPinned)> que lo deja sin Send, Sync ni Unpin automáticos. Un puntero crudo no es ni Send ni Sync, y PhantomPinned quita Unpin, así que Rust no supone nada que no sepamos. Mi guía usaba _private: [u8; 0]; el Nomicon añade el marcador.

Luego, el tipo público: un puntero no nulo al objeto de C++, y un Drop que lo libera.

/// El almacén, visto desde Rust: dueño único del objeto C++.
pub struct Kv {
    ptr: NonNull<ffi::Kv>,
}

impl Drop for Kv {
    fn drop(&mut self) {
        // SAFETY: el puntero salió de kv_new y se libera una sola vez.
        unsafe { ffi::kv_free(self.ptr.as_ptr()) };
    }
}

Esto es RAII, lo mismo que en C++. En mi guía de Rust lo describo así: Drop es el destructor de Rust, se llama automáticamente, exactamente una vez. En la de C++ lo explico con una clase File que abre el archivo con fopen en el constructor y lo cierra con fclose en el destructor. Aquí, el objeto de C++ se libera con kv_free cuando el Kv sale de ámbito, pase lo que pase.

Y ahora, el corazón de la entrada, set y get:

    pub fn set(&mut self, key: &str, value: &str) -> Result<(), KvError> {
        let key = CString::new(key).map_err(|_| KvError::InteriorNul)?;
        let value =
            CString::new(value).map_err(|_| KvError::InteriorNul)?;
        // SAFETY: el puntero es válido mientras exista self, y &mut self
        // garantiza que nadie más lo usa. Las dos cadenas acaban en NUL y
        // viven hasta el final de la llamada.
        let code = unsafe {
            ffi::kv_set(self.ptr.as_ptr(), key.as_ptr(), value.as_ptr())
        };
        match code {
            ffi::KV_OK => Ok(()),
            ffi::KV_EINVAL => Err(KvError::InvalidKey),
            ffi::KV_ENOMEM => Err(KvError::OutOfMemory),
            _ => Err(KvError::Internal),
        }
    }

    /// El &str devuelto apunta a memoria de C++, y su lifetime está
    /// atado a &self: mientras exista, nadie puede llamar a set, que pide
    /// &mut self.
    ///
    /// ```compile_fail,E0502
    /// let mut db = kvdemo::Kv::new().unwrap();
    /// db.set("k", "ana.garcia.tome@example.com").unwrap();
    /// let v = db.get("k").unwrap();
    /// db.set("k", "ana.garcia.fernandez.tome@example-company.com")
    ///     .unwrap();
    /// println!("{v}");
    /// ```
    pub fn get(&self, key: &str) -> Option<&str> {
        let key = CString::new(key).ok()?;
        // SAFETY: puntero válido y clave acabada en NUL.
        let value =
            unsafe { ffi::kv_get(self.ptr.as_ptr(), key.as_ptr()) };
        if value.is_null() {
            return None;
        }
        // SAFETY: kv_get devuelve una cadena acabada en NUL que vive
        // hasta el siguiente kv_set o kv_free, y ninguno de los dos puede
        // ocurrir mientras viva el préstamo de self del que sale este
        // &str.
        unsafe { CStr::from_ptr(value) }.to_str().ok()
    }

Aquí está el contrato del header, traducido a tipos. set pide &mut self: un préstamo exclusivo. get pide &self y devuelve un Option<&str> cuyo lifetime está atado a ese &self. Mientras el &str exista, el préstamo de db sigue vivo, y nadie puede conseguir el &mut self que pide set. El último comentario SAFETY de get es la clave del bug del principio: el &str puede apuntar a memoria de C++ porque el contrato de kv_get y las reglas de préstamos de Rust dicen lo mismo.

Encima de get hay un doctest marcado compile_fail,E0502, con el mismo bug. cargo test lo compila en cada ejecución y el test pasa solo si no compila, y con ese error. Si alguien cambiara el envoltorio y el bug volviera a compilar, el test fallaría.

Esta es la salida real en mi equipo, con cargo test:

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test a_panic_in_the_callback_comes_back_to_rust ... ok
test errors_from_both_sides_of_the_boundary ... ok
test for_each_visits_every_entry_and_can_stop ... ok
test set_get_and_overwrite ... ok
test stats_cross_the_boundary_by_value ... ok
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test src\lib.rs - Kv::get (line 119) - compile fail ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.04s

La última línea con ok es ese doctest: compile fail ... ok.

El envoltorio impide otro bug más. Este programa intenta modificar el almacén mientras lo recorre:

// cargo build --example reentrant --features show-bug
// No compila, a propósito: modificar el almacén mientras se recorre.
// En C++, un kv_set dentro del callback de kv_for_each podría provocar
// un rehash e invalidar el iterador.
use kvdemo::Kv;

fn main() {
    let mut db = Kv::new().unwrap();
    db.set("a", "1").unwrap();
    db.for_each(|k, _| {
        db.set(&format!("{k}-copy"), "x").unwrap();
        true
    });
}

Esta es la salida real en mi equipo, con cargo build:

error[E0502]: cannot borrow `db` as mutable because it is also borrowed as immutable
  --> examples\reentrant.rs:10:17
   |
10 |     db.for_each(|k, _| {
   |     -- -------- ^^^^^^ mutable borrow occurs here
   |     |  |
   |     |  immutable borrow later used by call
   |     immutable borrow occurs here
11 |         db.set(&format!("{k}-copy"), "x").unwrap();
   |         -- second borrow occurs due to use of `db` in closure

For more information about this error, try `rustc --explain E0502`.
error: could not compile `kvdemo` (example "reentrant") due to 1 previous error

for_each pide &self y el closure necesita &mut db para llamar a set: los dos préstamos chocan. En C++ el equivalente, llamar a kv_set dentro del callback de kv_for_each, compila sin problema. Y si la inserción provoca un rehash, invalida el iterador que está usando el recorrido ([unord.req.general]).

unsafe impl Send y Sync: el cuarto superpoder#

El tipo opaco no es ni Send ni Sync, así que Kv tampoco lo sería, y no se podría usar desde varios hilos. Para permitirlo hacen falta dos promesas explícitas:

// SAFETY: Kv es el único dueño del objeto C++, y el objeto no depende del
// hilo que lo creó: puede pasar de un hilo a otro.
unsafe impl Send for Kv {}

// SAFETY: con &Kv solo se llega a kv_get, kv_stats_get y kv_for_each, que
// solo llaman a funciones miembro const de std::unordered_map. La
// biblioteca estándar de C++ garantiza que esas llamadas, hechas a la vez
// desde varios hilos, no provocan carreras de datos ([res.on.data.races]).
unsafe impl Sync for Kv {}

Send es fácil: Kv es el único dueño del objeto de C++, y el objeto no depende del hilo que lo creó. Sync es más delicado, porque significa que varios hilos pueden usar &Kv a la vez. La justificación está en el estándar de C++, en [res.on.data.races]: una función de la biblioteca estándar solo modifica los objetos a los que accede a través de argumentos que no son const, incluido this. Por eso varias llamadas a funciones const del mismo unordered_map, desde varios hilos a la vez, no provocan carreras de datos. Y con un &Kv solo se llega a kv_get, kv_stats_get y kv_for_each, que solo llaman a funciones miembro const.

Ojo, porque esa promesa depende del código de hoy. Si mañana alguien añade a kv_get una caché que se modifica en cada lectura, la promesa se rompe y el compilador no lo notará. Es exactamente lo que significa unsafe: el compilador te cree.

Con la promesa hecha, cuatro hilos pueden leer a la vez:

// cargo run --example threads
// Cuatro hilos leen a la vez del mismo almacén C++. Compila porque Kv es
// Sync: la promesa de `unsafe impl Sync` en lib.rs.
use kvdemo::Kv;
use std::thread;

fn main() {
    let mut db = Kv::new().unwrap();
    for i in 0..1000 {
        db.set(&format!("key{i}"), &format!("value{i}")).unwrap();
    }

    let db = &db; // a partir de aquí, solo lectura
    let found: usize = thread::scope(|s| {
        let workers: Vec<_> = (0..4)
            .map(|t| {
                s.spawn(move || {
                    (0..1000)
                        .filter(|i| i % 4 == t)
                        .filter(|i| db.get(&format!("key{i}")).is_some())
                        .count()
                })
            })
            .collect();
        workers.into_iter().map(|w| w.join().unwrap()).sum()
    });

    println!("found {found} of 1000 keys from 4 threads");
}

Esta es la salida real en mi equipo, con cargo run:

found 1000 of 1000 keys from 4 threads

Y para ver que la promesa es necesaria, comenté temporalmente unsafe impl Sync for Kv {}. Esta es la salida real en mi equipo, con cargo build (las primeras 15 líneas):

error[E0277]: `NonNull<kvdemo::ffi::Kv>` cannot be shared between threads safely
   --> examples\threads.rs:17:25
    |
 17 |                   s.spawn(move || {
    |  ___________________-----_^
    | |                   |
    | |                   required by a bound introduced by this call
 18 | |                     (0..1000)
 19 | |                         .filter(|i| i % 4 == t)
 20 | |                         .filter(|i| db.get(&format!("key{i}")).is_some())
 21 | |                         .count()
 22 | |                 })
    | |_________________^ `NonNull<kvdemo::ffi::Kv>` cannot be shared between threads safely
    |
    = help: within `kvdemo::Kv`, the trait `Sync` is not implemented for `NonNull<kvdemo::ffi::Kv>`
[…]

Rust no deja compartir un puntero crudo entre hilos hasta que alguien se hace responsable.

Pánicos y callbacks#

kv_for_each llama a una función de Rust desde C++. ¿Qué pasa si esa función hace panic!? Este programa lo prueba sin el envoltorio, llamando directamente a la API en C:

// cargo run --example panic_abort
// Un callback extern "C" que hace panic, sin el envoltorio: el pánico
// intenta salir de una función extern "C" y el proceso aborta.
use kvdemo::ffi;
use std::ffi::{c_char, c_int, c_void};

extern "C" fn visit(
    _key: *const c_char,
    _value: *const c_char,
    _ctx: *mut c_void,
) -> c_int {
    panic!("something went wrong in the callback");
}

fn main() {
    let db = ffi::kv_new();
    // SAFETY: db sale de kv_new; los literales c"..." acaban en NUL.
    unsafe {
        ffi::kv_set(db, c"lang".as_ptr(), c"rust".as_ptr());
        ffi::kv_for_each(db, visit, std::ptr::null_mut());
        ffi::kv_free(db);
    }
    println!("never printed");
}

(Los literales c"lang" son cadenas de C con su NUL final, escritas directamente en Rust; son estables desde Rust 1.77.)

Esta es la salida real en mi equipo, con cargo run (un extracto, sin la traza):

thread 'main' (14964) panicked at examples\panic_abort.rs:12:5:
something went wrong in the callback
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

thread 'main' (14964) panicked at /rustc/48a229ceaefd4985c50990b14116b6d856af0985/library\core\src\panicking.rs:225:5:
panic in a function that cannot unwind
stack backtrace:
   […]
thread caused non-unwinding panic. aborting.

El pánico intenta salir de una función extern "C", que no puede desenrollar la pila, y el proceso aborta. En la traza completa aparece kv_for_each (kv.cpp:83): el pánico ocurrió dentro de una llamada desde C++. Abortar es lo que hace Rust desde la versión 1.81; antes, un pánico que salía de una función extern "C" era comportamiento indefinido. El caso contrario no ha cambiado: una excepción de C++ que cruza una frontera extern "C" hacia Rust sigue siendo comportamiento indefinido, según el Nomicon.

La solución está en Kv::for_each: un trampolín, una función extern "C" genérica que hace de puente entre C++ y el closure:

    /// Recorre las entradas hasta que `visit` devuelve false. Si `visit`
    /// hace panic, el pánico no atraviesa el código C++: se captura en el
    /// trampolín y se relanza aquí, ya de vuelta en Rust.
    pub fn for_each<F: FnMut(&str, &str) -> bool>(&self, visit: F) {
        struct Ctx<F> {
            visit: F,
            panic: Option<Box<dyn Any + Send>>,
        }

        extern "C" fn trampoline<F: FnMut(&str, &str) -> bool>(
            key: *const c_char,
            value: *const c_char,
            ctx: *mut c_void,
        ) -> c_int {
            // SAFETY: ctx es el &mut Ctx<F> que pasamos a kv_for_each
            // abajo, y sigue vivo mientras dura la llamada.
            let ctx = unsafe { &mut *ctx.cast::<Ctx<F>>() };
            // SAFETY: kv_for_each pasa cadenas acabadas en NUL que viven
            // durante la llamada al callback.
            let (key, value) =
                unsafe { (CStr::from_ptr(key), CStr::from_ptr(value)) };
            let (Ok(key), Ok(value)) = (key.to_str(), value.to_str())
            else {
                return 0; // no es UTF-8: se salta
            };
            // AssertUnwindSafe: si hay pánico, se relanza sin volver a
            // usar ctx.visit.
            match panic::catch_unwind(AssertUnwindSafe(|| {
                (ctx.visit)(key, value)
            })) {
                Ok(true) => 0,
                Ok(false) => 1,
                Err(payload) => {
                    ctx.panic = Some(payload);
                    1 // que C++ pare de recorrer
                }
            }
        }

        let mut ctx = Ctx { visit, panic: None };
        // SAFETY: puntero válido; ctx vive hasta que kv_for_each vuelve.
        unsafe {
            ffi::kv_for_each(
                self.ptr.as_ptr(),
                trampoline::<F>,
                (&raw mut ctx).cast::<c_void>(),
            )
        };
        if let Some(payload) = ctx.panic {
            panic::resume_unwind(payload);
        }
    }

El trampolín llama al closure dentro de panic::catch_unwind. Si hay un pánico, guarda el payload, devuelve 1 para que C++ pare de recorrer y, ya de vuelta en Rust, lo relanza con panic::resume_unwind. El pánico rodea el código C++ en vez de atravesarlo. Dos detalles más:

• &raw mut ctx crea un puntero crudo sin pasar por una referencia; es sintaxis estable desde Rust 1.82.
• El AssertUnwindSafe está justificado porque, si hay pánico, se relanza sin volver a usar ctx.visit.

El mismo pánico, a través del envoltorio:

// cargo run --example panic_safe
// El mismo pánico, a través del envoltorio: vuelve a Rust como un pánico
// normal, que se puede capturar, y el almacén sigue funcionando.
use kvdemo::Kv;
use std::panic;

fn main() {
    let mut db = Kv::new().unwrap();
    db.set("lang", "rust").unwrap();

    let result = panic::catch_unwind(|| {
        db.for_each(|_, _| panic!("something went wrong in the callback"));
    });

    println!("panic caught back in Rust: {}", result.is_err());
    println!("get(lang) = {:?}", db.get("lang"));
}

Esta es la salida real en mi equipo, con cargo run:

thread 'main' (81384) panicked at examples\panic_safe.rs:12:28:
something went wrong in the callback
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
panic caught back in Rust: true
get(lang) = Some("rust")

El pánico vuelve a Rust, se captura como cualquier otro y el almacén sigue funcionando.

Hay otra opción cuando sí quieres que el desenrollado cruce la frontera: la ABI "C-unwind", estable desde Rust 1.71. En esta entrada no se usa, porque la frontera está diseñada para que no la cruce nada.

Sin sistema operativo debajo: #![no_std]#

Todo lo anterior usa std, la biblioteca estándar de Rust. Y std asume que hay un sistema operativo debajo: heap, hilos, archivos. Como explico en mi guía, un driver o un kernel es lo que ese sistema necesita, así que no puede apoyarse en std.

Con #![no_std] solo queda core, la parte de la biblioteca que no depende de nada:

• no hay heap por defecto: hace falta el crate alloc y un #[global_allocator] propio;
• no hay manejo de pánicos: hay que definir un #[panic_handler].

Rust for Linux se apoya en esa base. El soporte para Rust entró en el kernel con Linux 6.1, publicado el 11 de diciembre de 2022. Si quieres ver qué hay «debajo», la serie de los anillos empieza en De Ring 3 a Ring 0.

Lo que me llevo#

• unsafe es una promesa, no un interruptor. Desbloquea cinco operaciones; todo lo demás se sigue comprobando.
• Diseña la frontera en C para que no cruce nada que se desenrolle: ni excepciones ni pánicos.
• Convierte los contratos de la documentación en tipos y lifetimes. Un comentario no lo comprueba nadie; un lifetime, el compilador.
• Cada unsafe con su SAFETY, y todos en un solo archivo. Así se pueden revisar.
• Comprueba el diseño en memoria en los dos lados, con aserciones en tiempo de compilación.
• Los tests compile_fail convierten «esto no debería compilar» en algo que se verifica.