Un wrapper seguro sobre una API C: imposible de usar mal

Una API C típica es un campo de minas: te da un manejador opaco con una función crear, te obliga a llamar a liberar exactamente una vez, y castiga con comportamiento indefinido cualquier desliz —liberar dos veces, usar tras liberar, olvidar comprobar el nulo—. En C esas obligaciones viven en la cabeza del programador y en los comentarios. En Rust las trasladamos al sistema de tipos: un Drop que libera una sola vez, un NonNull que descarta el nulo en la frontera, y firmas con &self y &mut self que dejan que el borrow checker prohíba el use-after-free. El resultado es un tipo cuya API pública es, literalmente, imposible de usar mal. Este es el patrón central, completo y en funcionamiento.

La API C cruda

Supongamos una librería en C que ofrece un almacén clave-valor a través de un contexto opaco. Su cabecera declara cuatro funciones y un tipo del que no conocemos el interior. En Rust 2024 los bloques extern son unsafe extern, porque enlazar con símbolos externos es en sí una promesa que el compilador no puede verificar:

use std::ptr::NonNull;

// Tipo opaco: solo lo manejamos por puntero, nunca por valor.
#[repr(C)]
struct Contexto {
    _priv: [u8; 0],
}

unsafe extern "C" {
    fn ctx_new() -> *mut Contexto;
    fn ctx_free(c: *mut Contexto);
    fn ctx_put(c: *mut Contexto, clave: u32, valor: u32) -> i32;
    fn ctx_get(c: *const Contexto, clave: u32, salida: *mut u32) -> i32;
}

Usar estas funciones directamente exige unsafe en cada llamada y recuerda cada contrato de memoria a mano. Nuestro trabajo es envolverlas una sola vez.

El wrapper que posee el recurso

El tipo público guarda el manejador como NonNull<Contexto> —jamás un puntero que pudiera ser nulo— y el campo es privado, la frontera que impide manipularlo desde fuera:

pub struct Almacen {
    ptr: NonNull<Contexto>,
}

impl Almacen {
    pub fn new() -> Option<Almacen> {
        // SAFETY: ctx_new no tiene precondiciones; devuelve null si falla
        let bruto = unsafe { ctx_new() };
        // NonNull::new convierte el nulo en None: el error C se vuelve un Option
        NonNull::new(bruto).map(|ptr| Almacen { ptr })
    }

    pub fn insertar(&mut self, clave: u32, valor: u32) -> bool {
        // SAFETY: ptr viene de ctx_new y sigue vivo (Drop no ha corrido);
        // &mut self da el acceso exclusivo que la API C presupone
        unsafe { ctx_put(self.ptr.as_ptr(), clave, valor) == 0 }
    }

    pub fn obtener(&self, clave: u32) -> Option<u32> {
        let mut salida = 0u32;
        // SAFETY: ptr valido; &raw mut salida apunta a un u32 escribible
        let codigo = unsafe { ctx_get(self.ptr.as_ptr(), clave, &raw mut salida) };
        (codigo == 0).then_some(salida)
    }
}

impl Drop for Almacen {
    fn drop(&mut self) {
        // SAFETY: ptr viene de ctx_new y no se libero antes; se libera una sola vez
        unsafe { ctx_free(self.ptr.as_ptr()); }
    }
}

Fíjate en &raw mut salida: el operador de referencia cruda de Rust 2024, que obtiene un *mut u32 sin pasar por una referencia intermedia. Y observa que ninguna firma pública contiene unsafe: quien use Almacen escribe Rust seguro de principio a fin.

Por qué cada error C se vuelve inexpresable

La clave está en que cada garantía no es una convención ni un comentario: es una propiedad del tipo que el compilador verifica. El usuario no puede escribir el programa incorrecto porque el código sencillamente no compila.

fn ejemplo() {
    let mut a = Almacen::new().expect("sin memoria");
    a.insertar(1, 100);
    let b = a;                 // la propiedad se mueve a b
    // a.insertar(2, 200);     // ERROR de compilacion: a fue movido
    assert_eq!(b.obtener(1), Some(100));
} // aqui corre Drop de b: ctx_free una sola vez, sin fuga

flowchart LR
subgraph C[API C cruda]
  N1[ctx_new devuelve puntero o nulo] --> U1[usar exige recordar cada contrato]
  U1 --> F1[liberar a mano exactamente una vez]
end
subgraph R[Wrapper Rust seguro]
  N2[new devuelve Option NonNull] --> U2[metodos con self y mut self]
  U2 --> F2[Drop libera una sola vez automatico]
end
C -->|se encapsula en| R
style C fill:#f38ba8,color:#11111b
style R fill:#a6e3a1,color:#11111b