Como Closures Funcionam por Dentro:
Quando a Stack Não Basta

No artigo “Como uma chamada de função funciona por dentro”, compilamos funções nomeadas para LLVM IR. A Pulso agora suporta:

• declaração de funções com parâmetros
• retorno de valores via retorne
• chamadas encadeadas como expressões
• duas passadas de compilação (declaração + implementação)

Mas há uma limitação sutil: as variáveis que uma função enxerga são apenas seus parâmetros e suas próprias variáveis locais. Ela não consegue "ver" variáveis declaradas fora dela. Em outras palavras, ainda não temos escopo léxico de verdade — ou melhor, temos, mas não conseguimos transportar esse escopo para fora da função.

Considere este programa Pulso:

fn cria_somador(n) {
    fn somador(x) {
        retorne x + n;
    }
    retorne somador;
}

fn main() {
    var s = cria_somador(10);
    mostre(s(5));   // deveria imprimir 15
}

A função somador referencia n — um parâmetro de cria_somador. Quando cria_somador retorna, seu frame na stack é destruído. Onde n viveu? Na stack. E depois que o frame morre? A memória é reutilizada.

Mas somador foi retornada e atribuída a s. Se chamarmos s(5) mais tarde, ela ainda precisa acessar n. A stack não serve mais.

Stack durante cria_somador(10):
┌─────────────────────────────┐
│  Frame: cria_somador        │
│  n = 10                     │ ← somador precisa disso depois
│  somador = fn(x) { x + n }  │
└─────────────────────────────┘
              ↓ retorna

Stack após retorno:
┌─────────────────────────────┐
│  (frame reutilizado)        │ ← n foi sobrescrito!
└─────────────────────────────┘

Mas 's' ainda aponta para somador...

Uma closure é composta de duas partes:

1. Código: o corpo da função, que o LLVM já sabe compilar.
2. Ambiente: as variáveis do escopo externo que a função referencia — os upvalues.

Em linguagens de alto nível, isso é invisível. Embaixo do capô, a closure é um struct com dois campos:

// Conceitualmente, uma closure é:
struct Closure {
    // ponteiro para a função real
    func: fn(env: *mut u8, args: ...) -> f64,
    // ponteiro para o ambiente capturado (heap)
    env: *mut u8,
}

Quando chamamos uma closure, não chamamos a função diretamente. Chamamos um trampoline — uma pequena rotina que recebe os argumentos, recupera o ambiente do struct e então invoca a função real passando tanto os argumentos quanto o ambiente.

Para a Pulso, vamos simplificar: em vez de um trampoline separado, a closure será representada como um struct de dois ponteiros que o LLVM entende nativamente. Quando chamamos uma closure, passamos o ambiente como primeiro argumento implícito.

Na mini-vm do artigo “Construindo um compilador e uma máquina virtual do zero em Rust”, cada frame tinha acesso às variáveis do frame pai? Não. Cada frame era isolado. Para suportar closures, uma VM precisa de upvalues: referências a variáveis de frames superiores.

Em uma VM com closures (como Lua), o mecanismo funciona assim:

1. Quando uma função interna referencia uma variável externa, a VM não copia o valor. Ela cria um ponteiro (upvalue) para a célula de memória onde a variável vive.
2. Se a variável vive na stack e a função externa retorna, a VM move essa célula para o heap. Todos os upvalues que apontavam para a stack agora apontam para o heap.
3. A closure carrega um array de upvalues. Quando é chamada, esses upvalues são resolvidos para os valores atuais.

Esse mecanismo é elegante, mas complexo. Para a Pulso compilada via LLVM, vamos usar uma abordagem mais direta: alocar as variáveis capturadas no heap desde o início.

Em C, alocar no heap é malloc. Em Rust, é Box::new. Em LLVM IR, usamos a função malloc da libc (ou GC_malloc se tivermos um garbage collector — que ainda não temos).

A estratégia para a Pulso:

1. Análise: durante a compilação, identificamos quais variáveis de uma função são referenciadas por funções aninhadas.
2. Alocação no heap: em vez de alloca (stack), usamos malloc para criar um bloco de memória no heap.
3. Struct de captura: criamos um struct LLVM com um campo para cada variável capturada.
4. Passagem implícita: toda closure recebe um ponteiro para seu ambiente como primeiro parâmetro (depois do ponteiro para a própria closure, se necessário).

Para simplificar, vamos implementar um modelo onde:

• Funções que não capturam nada continuam como antes (funções estáticas).
• Funções que capturam variáveis se tornam closures: recebem um ponteiro env como primeiro argumento.
• O ambiente é um struct alocado no heap com malloc.
• Quando criamos uma closure, alocamos o ambiente, preenchemos os campos e retornamos um par (ponteiro para função, ponteiro para ambiente).

Vamos ver como o programa exemplo se parece em LLVM IR. A closure somador captura n. O ambiente é um struct com um campo n:

; Struct do ambiente: { double }
%Env_somador = type { double }

; A função somador recebe env como primeiro parâmetro
define double @somador(ptr %env, double %x) {
entry:
  ; Carrega n do ambiente
  %n_ptr = getelementptr %Env_somador, ptr %env, i32 0, i32 0
  %n = load double, ptr %n_ptr

  ; x + n
  %result = fadd double %x, %n
  ret double %result
}

; cria_somador aloca o ambiente no heap e retorna a closure
define { ptr, ptr } @cria_somador(double %n) {
entry:
  ; Aloca env no heap: malloc(sizeof(Env_somador))
  %env = call ptr @malloc(i64 8)   ; sizeof(double) = 8

  ; Armazena n no env
  %n_ptr = getelementptr %Env_somador, ptr %env, i32 0, i32 0
  store double %n, ptr %n_ptr

  ; Retorna a closure como par { func_ptr, env_ptr }
  %closure = insertvalue { ptr, ptr } undef, ptr @somador, 0
  %closure2 = insertvalue { ptr, ptr } %closure, ptr %env, 1
  ret { ptr, ptr } %closure2
}

Note as mudanças fundamentais em relação às funções estáticas:

Agora vamos ao código Rust. A mudança principal no CodeGen é que precisamos rastrear, para cada função, quais variáveis do escopo externo ela referencia. Para simplificar, vamos assumir que toda função aninhada é uma closure (mesmo que não capture nada — o overhead é mínimo).

A AST estendida

pub enum Expr {
    // ... Number, Variable, Binary, Call como antes ...
    // NOVO: criação de closure (função anônima ou nomeada aninhada)
    Lambda {
        params: Vec<String>,
        body: Vec<Stmt>,
        // variáveis do escopo externo que esta função referencia
        captures: Vec<String>,
    },
}

pub enum Stmt {
    // ... Var, Print, If, Function, Return como antes ...
}

Na prática, o parser já sabe quais variáveis uma função aninhada referencia. Vamos assumir que essa análise foi feita e o vetor captures vem preenchido.

Gerando o tipo do ambiente

// Para uma closure que captura ["n"], criamos:
// %Env = type { double }
fn build_env_type(&self, captures: &[String])
    -> Result<(StructType<'ctx>, Vec<usize>), String>
{
    let f64_type = self.context.f64_type();
    let field_types: Vec<BasicTypeEnum> =
        captures.iter().map(|_| f64_type.into()).collect();

    let env_type = self.context.struct_type(&field_types, false);

    // Mapeia nome da variável capturada para índice no struct
    let mut indices = Vec::new();
    for (i, name) in captures.iter().enumerate() {
        self.capture_indices.insert(name.clone(), i);
    }

    Ok((env_type, indices))
}

Compilando uma closure

fn compile_lambda(&mut self,
    params: &[String],
    body: &[Stmt],
    captures: &[String],
) -> Result<StructValue<'ctx>, String>
{
    // 1. Cria o tipo do ambiente no heap
    let (env_type, _) = self.build_env_type(captures)?;
    let env_ptr_type = env_type.ptr_type(inkwell::AddressSpace::default());

    // 2. Declara o tipo da closure: { ptr (função), ptr (env) }
    let closure_type = self.context.struct_type(&[
        env_ptr_type.into(),  // ponteiro para função (simplificado: usamos ptr genérico)
        env_ptr_type.into(),  // ponteiro para ambiente
    ], false);

    // 3. Cria a função interna com assinatura: (ptr env, double, double, ...) -> double
    let mut param_types: Vec<BasicMetadataTypeEnum> = vec![env_ptr_type.into()];
    for _ in params {
        param_types.push(self.context.f64_type().into());
    }

    let fn_type = self.context.f64_type().fn_type(&param_types, false);
    let fn_val = self.module.add_function("lambda", fn_type, None);

    // 4. Compila o corpo da função (similar ao artigo anterior,
    //    mas variáveis capturadas são lidas de %env em vez de alloca)
    let entry = self.context.append_basic_block(fn_val, "entry");
    self.builder.position_at_end(entry);

    // Mapeia parâmetros (incluindo env)
    let env_param = fn_val.get_nth_param(0).unwrap().into_pointer_value();
    self.variables.clear();
    self.env_ptr = Some(env_param);
    self.env_type = Some(env_type);

    for (i, param_name) in params.iter().enumerate() {
        let p = fn_val.get_nth_param((i + 1) as u32).unwrap().into_float_value();
        let alloca = self.builder.build_alloca(
            self.context.f64_type(), param_name
        ).map_err(|e| e.to_string())?;
        self.builder.build_store(alloca, p).map_err(|e| e.to_string())?;
        self.variables.insert(param_name.clone(), alloca);
    }

    // Compila o corpo
    for stmt in body {
        self.compile_stmt(stmt)?;
    }

    // Garante retorno
    if self.builder.get_insert_block().unwrap().get_terminator().is_none() {
        self.builder.build_return(
            Some(&self.context.f64_type().const_float(0.0))
        ).map_err(|e| e.to_string())?;
    }

    // 5. Aloca o ambiente no heap com malloc
    let malloc = self.module.get_function("malloc").unwrap();
    let size = env_type.size_of().unwrap();
    let env_ptr = self.builder.build_call(
        malloc, &[size.into()], "env_alloc"
    ).map_err(|e| e.to_string())?
    .try_as_basic_value().left().unwrap()
    .into_pointer_value();

    // 6. Preenche o ambiente com os valores capturados
    for (i, name) in captures.iter().enumerate() {
        let src_ptr = self.variables.get(name)
            .or_else(|| self.parent_vars.get(name))
            .ok_or_else(|| format!("captura '{}' não encontrada", name))?;
        let val = self.builder.build_load(
            self.context.f64_type(), *src_ptr, name
        ).map_err(|e| e.to_string())?;

        let field_ptr = self.builder.build_struct_gep(
            env_type, env_ptr, i as u32, &format!("env.{}", name)
        ).map_err(|e| e.to_string())?;

        self.builder.build_store(field_ptr, val).map_err(|e| e.to_string())?;
    }

    // 7. Monta e retorna a closure { fn_ptr, env_ptr }
    let mut closure = closure_type.get_undef();
    closure = self.builder.build_insert_value(
        closure, fn_val.as_global_value().as_pointer_value(), 0, "closure.fn"
    ).unwrap().into_struct_value();
    closure = self.builder.build_insert_value(
        closure, env_ptr, 1, "closure.env"
    ).unwrap().into_struct_value();

    Ok(closure)
}

Chamando uma closure

fn compile_call(&self,
    closure_val: StructValue<'ctx>,
    args: &[FloatValue<'ctx>],
) -> Result<FloatValue<'ctx>, String>
{
    // Extrai fn_ptr e env_ptr da closure
    let fn_ptr = self.builder.build_extract_value(
        closure_val, 0, "fn_ptr"
    ).unwrap().into_pointer_value();

    let env_ptr = self.builder.build_extract_value(
        closure_val, 1, "env_ptr"
    ).unwrap().into_pointer_value();

    // Monta argumentos: [env, arg1, arg2, ...]
    let mut call_args: Vec<BasicMetadataValueEnum> = vec![env_ptr.into()];
    for arg in args {
        call_args.push(arg.into());
    }

    // Converte o ptr genérico para function pointer
    let fn_type = self.context.f64_type().fn_type(
        &[self.context.ptr_type(inkwell::AddressSpace::default()).into()],
        true  // vararg simplificado — na prática usamos assinatura exata
    );

    let result = self.builder.build_indirect_call(
        fn_type, fn_ptr, &call_args, "call_closure"
    ).map_err(|e| e.to_string())?;

    Ok(result.try_as_basic_value().left().unwrap().into_float_value())
}

Vamos ver o fluxo completo. A estrutura do projeto:

pulso-closures/
├── Cargo.toml
└── src/
    ├── main.rs
    └── codegen.rs

use inkwell::context::Context;
use std::process::Command;

mod codegen;
use codegen::{CodeGen, Expr, Stmt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Programa Pulso:
    // fn cria_somador(n) {
    //     retorne fn(x) { retorne x + n; };
    // }
    // fn main() {
    //     var s = cria_somador(10);
    //     mostre(s(5));
    // }

    let cria_somador_body = vec![
        Stmt::Return(Some(Box::new(Expr::Lambda {
            params: vec!["x".to_string()],
            captures: vec!["n".to_string()],
            body: vec![
                Stmt::Return(Some(Box::new(Expr::Binary {
                    op: "+".to_string(),
                    left: Box::new(Expr::Variable("x".to_string())),
                    right: Box::new(Expr::Variable("n".to_string())),
                }))),
            ],
        }))),
    ];

    let main_body = vec![
        Stmt::Var(
            "s".to_string(),
            Box::new(Expr::Call {
                name: "cria_somador".to_string(),
                args: vec![Expr::Number(10.0)],
            }),
        ),
        Stmt::Print(Box::new(Expr::CallClosure {
                closure: Box::new(Expr::Variable("s".to_string())),
                args: vec![Expr::Number(5.0)],
        })),
    ];

    let program = vec![
        Stmt::Function {
            name: "cria_somador".to_string(),
            params: vec!["n".to_string()],
            body: cria_somador_body,
        },
        Stmt::Function {
            name: "main".to_string(),
            params: vec![],
            body: main_body,
        },
    ];

    let context = Context::create();
    let mut codegen = CodeGen::new(&context, "pulso_closures");

    // Declara malloc e funções
    codegen.declare_externals();
    codegen.declare_functions(&program);

    // Compila
    for stmt in &program {
        if let Stmt::Function { name, params, body } = stmt {
            codegen.compile_function(name, params, body)?;
        }
    }

    println!("=== LLVM IR gerado ===");
    codegen.print_ir();

    codegen.emit_object("programa.o")?;
    let status = Command::new("clang")
        .args(&["programa.o", "-o", "programa", "-lm"])
        .status()?;

    if status.success() {
        println!("\n=== Executável gerado. Rodando... ===");
        Command::new("./programa").status()?;
    }

    Ok(())
}

Compilando e executando

$ cargo run
=== LLVM IR gerado ===
; (trecho simplificado do IR real)
define { ptr, ptr } @cria_somador(double %n) {
entry:
  %env = call ptr @malloc(i64 8)
  %n_ptr = getelementptr { double }, ptr %env, i32 0, i32 0
  store double %n, ptr %n_ptr
  %closure = insertvalue { ptr, ptr } undef, ptr @lambda_0, 0
  %closure1 = insertvalue { ptr, ptr } %closure, ptr %env, 1
  ret { ptr, ptr } %closure1
}

define double @lambda_0(ptr %env, double %x) {
entry:
  %n_ptr = getelementptr { double }, ptr %env, i32 0, i32 0
  %n = load double, ptr %n_ptr
  %add = fadd double %x, %n
  ret double %add
}

define i32 @main() {
entry:
  %s = call { ptr, ptr } @cria_somador(double 1.000000e+01)
  ; ... extrai fn e env, chama lambda_0(env, 5.0) ...
  %call = call double @lambda_0(ptr %env, double 5.000000e+00)
  %printf_call = call i32 (ptr, ...) @printf(ptr @fmt, double %call)
  ret i32 0
}

=== Executável gerado. Rodando...
15

O número 15 veio de uma closure. O valor n = 10 sobreviveu ao retorno de cria_somador porque foi alocado no heap. Quando s(5) foi chamado, a função lambda_0 recuperou n do ambiente e somou com x. Tudo em código de máquina nativo.

Nossa primeira implementação usa malloc e mantém o ambiente vivo até o processo terminar. Isso deixa a representação visível, porém não é uma política de memória aceitável para uma linguagem usada em programas longos. Depois de aprender como a closure nasce, precisamos decidir quando ela morre.

Por que uma closure pode criar ciclos?

Imagine um ambiente que guarda outra closure, e essa segunda closure aponta de volta para o primeiro ambiente. Cada objeto mantém a contagem do outro acima de zero. Um coletor traçador percebe que nenhum deles é alcançável a partir do programa; a contagem de referências pura não percebe.

A partir daqui a Pulso deixou de ser apenas uma sintaxe sobre números: ela possui valores com identidade, tempo de vida e comportamento. Essa é a fronteira onde compilador, runtime e sistema de tipos começam a se encontrar.