Pular para o conteúdo
Flecha

3. FFI e interoperabilidade nativa

Comece pela declaração nativa, não por um tipo Flecha adivinhado. Registre ABI, convenção de chamada, larguras, constness, layout, representação de strings, tempo de vida, threads e erros. Rejeite a plataforma no build quando esses fatos não corresponderem.

Mantenha declarações extern privadas em um módulo. Ele valida entradas seguras, faz a menor conversão bruta, chama o código nativo, copia ou adota resultados conforme o proprietário documentado e converte falha em erro Flecha. Chamadores não devem precisar de unsafe só porque a implementação usa FFI.

Fontes nativas embutidas fazem parte do contrato. Fixe flags, qualifique cada alvo e teste nulos, buffers vazios, comprimentos máximos, callbacks, repetição e limpeza após falha.

Exemplo testado

Embuta uma unidade C, declare sua ABI escalar exata e retorne imediatamente a Flecha segura.

Arquivo: curriculum/main-evidence/single/foreign_add.fl

curriculum/main-evidence/single/foreign_add.fl
foreign c {
    #include <stdint.h>


    int32_t native_add(int32_t left, int32_t right) {
        return left + right;
    }
}


extern i32 native_add(i32 left, i32 right);


i32 main() {
    stdoutln(native_add(20, 22));
    return 0;
}

O bloco acima é o arquivo completo executado pelos comandos abaixo.

A declaração externa corresponde a uma função C escalar e retorna imediatamente para Flecha tipada. O exemplo não cobre estruturas, callbacks, transferência de propriedade nem diferenças de ABI entre alvos.

Comandos

Comandos
flecha check curriculum/main-evidence/single/foreign_add.fl
flecha build curriculum/main-evidence/single/foreign_add.fl -o build/foreign_add
build/foreign_add

Saída esperada

Saída esperada
42
status de saída: 0

Referência relacionada: /docs/reference/extern/.

O que aprender a seguir

Seção intitulada “O que aprender a seguir”