GBR: ADR-001 Adoção do ETS (Erlang Term Storage) para Roteamento de Alta Frequência (gbr_monitor)

• *Status:* Aceito
• *Data:* 2026-05-01

*Contexto:*

A FVideen está desenvolvendo o gbr_monitor, o componente central para processamento de eventos do sistema operacional distribuído. Inicialmente, o componente gerenciava o estado dos processos monitorados utilizando um Dicionário (Dict) mantido na memória de um único Ator Gerenciador (Registry). Com o aumento da frequência de ingestão esperada (milhões de eventos por segundo) e a necessidade de escalabilidade massiva, o Dicionário local formava um gargalo de contenção, pois todas as leituras e escritas exigiam passagem sequencial pela caixa de mensagens (Mailbox) do Ator Gerenciador, bloqueando o despacho paralelo.

*Decisão:*

1. *Roteamento Baseado em ETS (Erlang Term Storage):* Substituir o Dicionário local por uma tabela ETS pública. O ETS opera como um banco de dados em memória nativo do Erlang, escrito em C.
2. *Leituras Lock-free e Escritas Serializadas:* - *Roteador (Router):* Implementar o roteamento de métricas como funções puras que realizam a leitura direta no ETS sem bloqueios. Se o Ator alvo (PID) estiver registrado, o roteador despacha o evento instantaneamente de forma paralela. - *Criador (Spawner/Manager):* Implementar um Ator central responsável apenas por instanciar novos Atores quando a busca no ETS falhar, garantindo a prevenção de condições de corrida (Race Conditions) durante a criação simultânea de recursos.
3. *Criação do Wrapper gbr_ets:* Isolar a complexidade da API nativa do ETS (ets:new, ets:lookup) em um projeto separado (shared/gbr_ets). Utilizar FFI em Erlang puro (.erl) para instanciar as tabelas, abstraindo tipos nativos (set, read_concurrency) por trás de uma API de Tipos Customizados (Custom Types) tipicamente segura em Gleam.
4. *Cast Opaco (FFI Identity):* Devido à remoção intencional da função dynamic.from na versão 0.70+ do gleam_stdlib para reforçar a segurança de tipos, implementou-se a função FFI identity em Erlang. Esta função permite a injeção forçada de tipos complexos (como o Subject do Ator) na tabela ETS sem incorrer na sobrecarga computacional de dynamic.decode no momento da extração. A extração é operada utilizando o pacote interno do compilador Gleam com unsafe_coerce, otimizando a latência da execução.

*Consequências:*

• *Positivas:* Redução significativa do estrangulamento por contenção de Mensagens no Registry; throughput superior suportando a taxa exigida pelo GKE; estrutura adaptada a sistemas críticos de telecomunicações; isolamento robusto entre tipos complexos e primitivas C.
• *Negativas/Riscos:* A utilização de unsafe_coerce viola as garantias matemáticas do compilador Gleam. Esse risco foi mitigado através de validação estrita no momento da inserção (somente o Manager insere os tipos corretos na tabela ETS). Se pacotes não autorizados adulterarem o ETS, ocorrerá um erro catastrófico em runtime.