Interoperabilidad con C: ABI, Handles Opacos y Excepciones

La interoperabilidad con C es el arte de construir puentes entre el modelo de objetos de C++ y el modelo procedural de C. Esto se logra principalmente mediante la directiva extern "C", que desactiva el name mangling (la codificación de nombres que hace el compilador para soportar sobrecarga y namespaces), permitiendo que el linker encuentre las funciones bajo sus nombres originales. Debes usar este mecanismo cuando tu librería necesite ser llamada desde lenguajes como C, Python o Rust, o cuando debas interactuar con APIs de bajo nivel del sistema operativo. Si fallas al implementar este puente —por ejemplo, dejando que una excepción escape hacia el entorno de C o mezclando la gestión de memoria de new con free— el programa sufrirá un crash inmediato o un comportamiento indefinido. Para lograr una interfaz limpia, utilizamos handles opacos: punteros a estructuras cuya definición real se mantiene oculta en el archivo de implementación, protegiendo la encapsulación de tus objetos de C++.

#include <iostream>
#include <string>
#include <stdexcept>
#include <cstdio>
#include <memory>

// --- INTERFAZ ESTILO C (Lo que vería un usuario de C en un .h) ---
// Usamos extern "C" para que el nombre de la función sea predecible para el linker.
extern "C" {
    // Handle opaco: el usuario de C no sabe qué hay dentro de esta struct.
    typedef struct Motor_s* MotorHandle;

    typedef enum {
        MOTOR_SUCCESS = 0,
        MOTOR_ERROR_INVALID_ARG = 1,
        MOTOR_ERROR_RUNTIME = 2
    } MotorStatus;

    MotorHandle motor_create();
    MotorStatus motor_process(MotorHandle handle, const char* data);
    void motor_destroy(MotorHandle handle);
}

// --- IMPLEMENTACIÓN EN C++ (Lo que compila el desarrollador de C++) ---

// Clase interna con lógica compleja que no quiere ser expuesta directamente.
class Motor {
public:
    explicit Motor(std::string name) : nombre_(std::move(name)) {}

    void process(const std::string& data) {
        if (data.empty()) {
            throw std::invalid_argument("Datos vacíos");
        }
        if (data == "crash") {
            throw std::runtime_error("Error crítico interno");
        }
        std::printf("[Motor %s] Procesando: %s\n", nombre_.c_str(), data.c_str());
    }

private:
    std::string nombre_;
};

// Implementación de la API para C
extern "C" {
    MotorHandle motor_create() {
        // Usamos new para inicializar el objeto en el heap.
        // El puntero se trata como un handle opaco (void* o struct*) para C.
        return reinterpret_cast<MotorHandle>(new Motor("V8-Turbo"));
    }

    MotorStatus motor_process(MotorHandle handle, const char* data) {
        if (!handle || !data) {
            return MOTOR_ERROR_INVALID_ARG;
        }

        // Reinterpretamos el handle al tipo original de C++.
        Motor* motor = reinterpret_cast<Motor*>(handle);

        try {
            // La lógica de C++ puede lanzar excepciones, pero no deben 
            // cruzar la frontera hacia C.
            motor->process(std::string(data));
            return MOTOR_SUCCESS;
        } catch (const std::invalid_argument&) {
            return MOTOR_ERROR_INVALID_ARG;
        } catch (...) {
            // Capturamos cualquier otra excepción para evitar un abort()
            // que el entorno de C no sabría cómo manejar.
            return MOTOR_ERROR_RUNTIME;
        }
    }

    void motor_destroy(MotorHandle handle) {
        if (handle) {
            // El destructor debe ser llamado mediante delete para 
            // asegurar que el objeto de C++ se limpie correctamente.
            delete reinterpret_cast<Motor*>(handle);
        }
    }
}

// --- CLIENTE (Simulando un programa en C puro) ---
int main() {
    // El usuario de C solo ve handles y funciones procedurales.
    MotorHandle mi_motor = motor_create();

    // Caso 1: Operación exitosa
    MotorStatus status = motor_process(mi_motor, "Cargando combustible...");
    if (status != MOTOR_SUCCESS) {
        std::printf("Error en operación 1: %d\n", status);
    }

    // Caso 2: Error de argumentos (C-style string vacío)
    status = motor_process(mi_motor, "");
    if (status == MOTOR_ERROR_INVALID_ARG) {
        std::printf("Error detectado: Argumento inválido\n");
    }

    // Caso 3: Error de ejecución (Excepción de C++ capturada)
    status = motor_process(mi_motor, "crash");
    if (status == MOTOR_ERROR_RUNTIME) {
        std::printf("Error detectado: Error de runtime (excepción de C++)\n");
    }

    // Liberación de recursos mediante la API.
    motor_destroy(mi_motor);

    return 0;
}

Análisis del código

En la implementación, la directiva extern "C" es crucial. Si la hubiéramos omitido en las funciones de la API, el compilador habría generado símbolos como _Z11motor_createv, haciendo imposible que un programa escrito en C puro encontrara la función motor_create.

El uso de reinterpret_cast es el mecanismo que nos permite tratar un puntero a una clase compleja (Motor*) como un tipo opaco (MotorHandle). Para el usuario de la API, el contenido de Motor_s es una caja negra; esto garantiza el encapsulamiento, impidiendo que un programador de C intente acceder a miembros privados o manipular el puntero de forma indebida.

Un punto crítico es la gestión de la memoria. En motor_create usamos new, por lo que motor_destroy debe usar obligatoriamente delete. Si utilizáramos malloc en C para crear el objeto, el constructor de la clase Motor nunca se llamaría, dejando el objeto en un estado indefinido (especialmente peligroso con std::string).

Finalmente, observa la función motor_process. He implementado un bloque try-catch que actúa como una barrera de seguridad. En C++, una excepción no capturada que atraviesa una función con enlace de C provoca un std::terminate. Al transformar la excepción en un MotorStatus (un simple enum compatible con C), permitimos que el llamador maneje el error mediante lógica procedural estándar.

El error frecuente

Un error muy común al mezclar lenguajes es la confusión en la responsabilidad de la memoria. Si un usuario de C decide que, como él llamó a una función de creación, él debe liberar la memoria, intentará hacer esto:

// ERROR CRÍTICO
MotorHandle h = motor_create(); // Internamente usa 'new'
free(h);                        // ¡ERROR! Mezclar malloc/free con new/delete

Este error provoca un comportamiento indefinido (Undefined Behavior). Aunque en algunos implementadores de sistemas de memoria esto parezca “funcionar” sin inmediato crash, en la práctica corrompe el estado del heap, ya que new puede haber reservado memoria mediante una ruta distinta a la de malloc (especialmente si hay herencia o tipos complejos). Siempre define claramente en la documentación de tu API quién es el dueño del objeto y qué función de liberación debe usarse.

N° 126