Writergate em Zig: Migrar getStdOut para std.Io.Writer

Se o seu programa parou de compilar com um erro em std.io.getStdOut, std.io.getStdIn ou bufferedWriter, você encontrou o Writergate: a reescrita do subsistema de I/O da biblioteca padrão do Zig na série 0.15/0.16. Não é um bug do seu código, e não há flag para voltar atrás. A saída padrão agora vem de um handle de arquivo, o buffer é seu, e o flush é obrigatório.

Este guia mostra o que mudou, por que mudou, como converter os padrões mais comuns (stdout, stderr, arquivo, leitura linha a linha, escrita em socket) e quais armadilhas aparecem depois da migração — principalmente saída que “some” por falta de flush e buffers com tempo de vida curto demais.

Como a biblioteca padrão continua evoluindo antes do 1.0, trate os nomes exatos como algo a confirmar contra a versão fixada no seu build.zig.zon e no CI. O que este artigo garante é o modelo mental correto, que não muda entre patches.

Resposta rápida

O que foi o Writergate

Até a série 0.14, Reader e Writer eram tipos genéricos: cada combinação de contexto e conjunto de erros gerava um novo tipo. Isso tinha três custos práticos.

O primeiro é code bloat. Uma função declarada como fn imprime(writer: anytype) é instanciada de novo para cada writer concreto que você passa. Em projetos grandes, o compilador acaba gerando dezenas de variantes de código idêntico em espírito.

O segundo é composição. Encadear buffer, contador, compressor e writer final produzia tipos aninhados longos, difíceis de nomear e de guardar em structs. Armazenar “um writer qualquer” exigia apagamento de tipo manual.

O terceiro é performance escondida. O buffer ficava dentro de um wrapper, e a implementação não tinha como saber que o destino era um arquivo capaz de receber uma escrita vetorizada, ou que os dados já estavam prontos em outro buffer e poderiam ser enviados sem cópia.

A reescrita ataca os três pontos: a interface passou a ser um tipo concreto com um buffer visível e uma função de despacho. Isso significa menos instanciações genéricas, tipos que cabem em campos de struct, e espaço para o kernel receber operações melhores. O preço é ergonômico e recai sobre quem migra: agora você declara o buffer e você chama o flush.

O novo formato mínimo para stdout

O padrão essencial tem quatro passos, na ordem: obtenha o handle, declare o buffer, crie o writer, garanta o flush.

const std = @import("std");

pub fn main() !void {
    // 1. Handle do arquivo de saída padrão
    var stdout_file = std.fs.File.stdout();

    // 2. Buffer explícito — tempo de vida controlado por você
    var buffer: [4096]u8 = undefined;

    // 3. Writer sobre o handle usando esse buffer
    var stdout_writer = stdout_file.writer(&buffer);
    const out = &stdout_writer.interface;

    // 4. Flush garantido em qualquer caminho de saída
    defer out.flush() catch {};

    try out.print("Olá, {s}!\n", .{"mundo"});
    try out.writeAll("Segunda linha\n");
}

Três detalhes merecem atenção.

O buffer é uma variável comum da função. Se você criá-lo dentro de um bloco menor e devolver o writer para fora, o writer aponta para memória inválida. Esse é o erro número um depois da migração.

O defer ... catch {} é conveniente, mas engole o erro. Em ferramentas onde a saída importa — geradores de arquivo, exportadores, pipelines — prefira um flush explícito no fim do caminho feliz, com try, e mantenha o defer apenas como rede de segurança.

A escrita agora falha em dois momentos diferentes: quando o buffer enche e precisa ir para o kernel, e no flush final. Um try out.print(...) que passa não significa que os bytes saíram.

stderr, arquivos e sockets seguem o mesmo padrão

O mesmo trio handle + buffer + writer vale para os outros destinos.

const std = @import("std");

pub fn main() !void {
    // stderr: normalmente sem buffer grande, para diagnóstico imediato
    var err_buf: [512]u8 = undefined;
    var err_file = std.fs.File.stderr();
    var err_writer = err_file.writer(&err_buf);
    const err = &err_writer.interface;
    defer err.flush() catch {};

    // arquivo em disco: buffer maior reduz syscalls
    var file = try std.fs.cwd().createFile("relatorio.txt", .{});
    defer file.close();

    var file_buf: [16 * 1024]u8 = undefined;
    var file_writer = file.writer(&file_buf);
    const out = &file_writer.interface;

    for (0..1000) |i| {
        try out.print("linha {d}\n", .{i});
    }

    // Flush explícito com try: aqui o erro de disco realmente importa
    try out.flush();
    try err.print("relatorio.txt escrito\n", .{});
}

Para sockets, a lógica não muda: o writer envolve o handle da conexão e o buffer determina quantas chamadas de rede você faz. Isso interage diretamente com o algoritmo de Nagle e com TCP_NODELAY — vale ler o guia sobre TCP_NODELAY e opções de socket em Zig antes de escolher tamanhos. Um buffer de aplicação bem dimensionado costuma resolver o problema que muita gente tenta resolver desligando Nagle.

Leitura: o mesmo contrato, do outro lado

Ler stdin ou um arquivo segue a mesma estrutura. O buffer deixa de ser um detalhe interno e passa a ser parte da sua declaração.

const std = @import("std");

pub fn main() !void {
    var stdin_file = std.fs.File.stdin();
    var in_buf: [4096]u8 = undefined;
    var stdin_reader = stdin_file.reader(&in_buf);
    const in = &stdin_reader.interface;

    var out_buf: [4096]u8 = undefined;
    var stdout_file = std.fs.File.stdout();
    var stdout_writer = stdout_file.writer(&out_buf);
    const out = &stdout_writer.interface;
    defer out.flush() catch {};

    // Lê linha a linha até o fim da entrada
    while (in.takeDelimiterExclusive('\n')) |linha| {
        try out.print("[{d}] {s}\n", .{ linha.len, linha });
    } else |err| switch (err) {
        error.EndOfStream => {},
        else => return err,
    }
}

Duas consequências práticas dessa forma de ler:

A linha devolvida aponta para dentro do seu buffer. Ela é válida até a próxima leitura. Se você precisa guardá-la, copie com o allocator — allocator.dupe(u8, linha) — exatamente como no cuidado descrito no guia de array de strings em Zig.

Uma linha maior que o buffer é um erro, não um crescimento silencioso. Isso é uma proteção: entrada não confiável não consegue forçar alocação ilimitada. Para arquivos de log e CSV com linhas longas, dimensione o buffer conscientemente e trate o caso de excesso, como no guia de ETL de CSV e JSONL em Zig.

Funções que recebem “um writer qualquer”

O padrão antigo era anytype. O novo padrão é receber um ponteiro para a interface concreta.

const std = @import("std");

// Antes: uma instanciação por tipo de writer
// fn escreveRelatorio(writer: anytype, total: usize) !void

// Agora: um único código, qualquer destino
fn escreveRelatorio(out: *std.Io.Writer, total: usize) !void {
    try out.writeAll("== relatório ==\n");
    try out.print("itens: {d}\n", .{total});
}

Isso muda o design do seu código para melhor. A função agora tem um tipo estável, pode ser guardada em struct, passada por lista, e testada facilmente: basta criar um writer sobre um buffer em memória e comparar os bytes produzidos.

test "relatório formata como esperado" {
    var buf: [256]u8 = undefined;
    var w = std.Io.Writer.fixed(&buf);

    try escreveRelatorio(&w, 3);

    try std.testing.expectEqualStrings(
        "== relatório ==\nitens: 3\n",
        w.buffered(),
    );
}

Testar formatação sem tocar em disco era possível antes, mas verboso. Com a interface concreta vira o caminho natural, e combina bem com as práticas do guia de testes em Zig.

Roteiro de migração para um projeto existente

Migrar um projeto médio é mecânico se você seguir uma ordem.

1. Fixe a versão. Escolha a versão do compilador e registre-a no README, no CI e no container. Migrar mirando um alvo móvel é a forma mais rápida de perder um dia. O guia de instalação do Zig mostra como manter versões paralelas.

2. Localize os pontos de I/O. Procure por getStdOut, getStdIn, getStdErr, bufferedWriter, bufferedReader e anytype em assinaturas de função. Normalmente são poucos arquivos: um módulo de CLI, um de log e um de serialização.

3. Converta de fora para dentro. Comece no main, onde os buffers de verdade nascem, e desça. As funções internas mudam apenas a assinatura de anytype para *std.Io.Writer.

4. Coloque os flushes. Todo caminho de saída — retorno normal, erro, sinal — precisa passar por um flush. Se o programa trata SIGTERM, o flush entra no encerramento ordenado descrito em graceful shutdown em Zig.

5. Rode os testes e olhe a saída de verdade. Compilar não é suficiente. Um programa migrado pela metade compila perfeitamente e imprime nada.

6. Meça se o I/O for quente. Buffer maior nem sempre é melhor. Compare com perf stat e flamegraphs como no guia de profiling em Zig.

Se a base for grande, os adaptadores de compatibilidade oferecidos durante a transição permitem migrar por módulo, mantendo o resto funcionando. Use-os como andaime temporário e remova-os na mesma release: adaptador esquecido vira dívida invisível quando a próxima versão sair.

Armadilhas comuns depois da migração

Saída vazia. Faltou flush, ou o catch {} do defer engoliu o erro. Verifique primeiro isso, sempre.

Ponteiro para buffer morto. O buffer foi declarado dentro de um if ou de uma função auxiliar e o writer sobreviveu a ele. O sintoma é lixo na saída ou crash em modos com verificação desligada. Compile em Debug ou ReleaseSafe ao investigar, conforme o tutorial de debugging em Zig.

Erro de disco descoberto tarde demais. Como o erro real aparece no flush, try no flush final é obrigatório em ferramentas que geram artefatos.

Buffer de progresso em CLI. Barras de progresso e logs de andamento precisam de flush em cada atualização, senão aparecem todos de uma vez no fim.

Mistura de destinos com buffers independentes. Se stdout e stderr têm buffers separados, a ordem relativa das mensagens no terminal pode surpreender. Para diagnóstico ordenado, escreva tudo em um único destino ou faça flush antes de trocar.

Ler e guardar sem copiar. A fatia devolvida pelo reader vive no seu buffer e é invalidada na leitura seguinte.

Vale a pena, apesar do incômodo

A reescrita foi impopular no curto prazo por um motivo justo: quebrou código funcionando de milhares de projetos, incluindo exemplos publicados em livros, cursos e — como neste site — artigos e cheatsheets antigos. Mas ela é coerente com a proposta do Zig, que aparece no panorama do Zig em 2026: custos explícitos, sem mágica escondida, sem alocação implícita.

Um buffer visível é um buffer que você pode dimensionar, reutilizar e medir. Uma interface concreta é uma interface que você pode guardar, injetar e testar. E um flush obrigatório é uma falha de escrita que aparece no lugar certo, em vez de sumir silenciosamente no encerramento do processo.

Se você mantém um projeto Zig em produção, trate esta migração como uma tarefa agendada e não como uma emergência: fixe a versão, converta os pontos de I/O, coloque os flushes, rode os testes e siga em frente. Depois, aproveite para revisar as camadas vizinhas — error handling e observabilidade ficam mais simples quando o I/O tem um único formato explícito em todo o código.

Perguntas frequentes

Por que std.io.getStdOut não existe mais?

Porque o subsistema de I/O foi reescrito na série 0.15/0.16. O acesso a stdout, stdin e stderr passou a ser feito por handles de arquivo com buffer explícito e pela nova interface de escrita e leitura.

Preciso mesmo chamar flush?

Sim, sempre que houver buffer. Sem flush, os bytes pendentes nunca chegam ao destino. Use defer como rede de segurança e try no flush final quando a saída for um artefato importante.

Qual tamanho de buffer devo usar?

Alguns kilobytes para terminal, dezenas de kilobytes para arquivos grandes. Meça antes de aumentar: o ganho satura rápido e buffers enormes atrasam a visibilidade da saída.

Como escrever uma função que aceita qualquer writer?

Receba *std.Io.Writer em vez de anytype. Você ganha um tipo estável, menos código gerado e testes triviais com um writer sobre buffer em memória.

Dá para suportar Zig 0.14 e 0.16 no mesmo código?

Na prática não compensa. Fixe uma versão, migre de forma controlada e trate a atualização do compilador como tarefa com testes.

Onde ficam os erros de escrita agora?

Podem aparecer em qualquer operação que force o esvaziamento do buffer e, no caso mais comum, no flush. Nunca descarte o erro do flush em ferramentas que produzem arquivos.

Conclusão

O Writergate não foi uma mudança cosmética: foi a troca de uma abstração genérica e implícita por uma interface concreta com custos visíveis. Para quem migra, o resumo cabe em uma frase — o buffer é seu e o flush é seu.

O caminho seguro é sempre o mesmo: fixe a versão do compilador, converta o I/O de fora para dentro começando pelo main, declare buffers com tempo de vida claro, troque anytype por *std.Io.Writer nas assinaturas, garanta flush em todos os caminhos de saída e valide olhando a saída real, não apenas o build passando.

Feito isso, o resultado é um código com menos instanciações genéricas, tipos que cabem em structs, testes de formatação sem tocar em disco e falhas de escrita que aparecem no lugar certo. Continue pelo guia de ETL e arquivos grandes e pela referência de std.fs.File para consolidar a camada de I/O do seu projeto.