README

Triton

Filho de Poseidon, guardião das profundezas: retém o que não pode se perder.

Pool de recursos genérico e de alto desempenho para Delphi

Semântica de lease, backpressure, LIFO/FIFO, métricas estruturadas e adapters plugáveis.

Playbook • Contribuindo

---

Triton é uma biblioteca Delphi para pooling de recursos orientada à produção. Foi criada para substituir implementações legadas que sofrem de locks globais de escrita no caminho quente, crescimento ilimitado e ausência de observabilidade nativa. Inspirado em HikariCP, Apache Commons Pool 2 e Npgsql, Triton leva essas mesmas ideias a sério no Delphi.

---

Por que o Triton?

Pools Delphi legados tipicamente:

• Adquirem e selecionam itens dentro de um lock global de escrita: todas as threads serializam na criação
• Fazem busca linear O(n) para encontrar um item ocioso
• Não têm MaxSize real: sob carga, o pool simplesmente cresce sem parar
• Não oferecem backpressure: threads se acumulam sem disjuntor
• Misturam infraestrutura de pool com política específica do recurso
• Não têm métricas nativas: não é possível observar o que está acontecendo

O Triton resolve todos esses pontos separando o core do pool da política do adapter, garantindo reserva atômica do slot e oferecendo observabilidade estruturada desde o início.

---

Funcionalidades Principais

Funcionalidade	Descrição
Lease atômico	Um slot é reservado antes de qualquer instância ser entregue ao chamador; dois leases nunca compartilham o mesmo recurso
Backpressure	MaxPendingWaiters rejeita tentativas de acquire quando a fila de espera está cheia, devolvendo uma falha rápida em vez de travar
WarmUp	Pré-aloca um número configurado de recursos antes do servidor começar a aceitar tráfego
LIFO / FIFO	Política de reutilização de idle configurável: LIFO favorece conexões usadas mais recentemente ("quentes"); FIFO garante equidade
Semântica de lease	O chamador recebe um ITritonLease<T>; chamar Release recicla, Discard destrói
ValidateOnAcquire	O adapter executa um health check antes de entregar o recurso; conexões falhas são substituídas de forma transparente
ResetOnRelease	O adapter limpa o estado do recurso (ex.: rollback) antes de devolvê-lo à fila ociosa
Detecção de leak	Leases mantidos por mais tempo que LeakDetectionThresholdMs emitem uma observação estruturada e incrementam um contador
Keep-alive	Manutenção em background sonda conexões ociosas periodicamente para mantê-las saudáveis
Housekeeper	Worker interno leve executa evicção e keep-alive fora do caminho quente
Métricas estruturadas	Snapshot() retorna um TTritonMetricsSnapshot completo com contadores, picos e percentis
Observabilidade plugável	OnObservation emite eventos estruturados em caminhos lentos e de falha, sem acoplamento a nenhum backend de log
Core genérico	TTriton<T> funciona com qualquer tipo de recurso via ITritonAdapter<T> tipado

---

O Ciclo de Vida do Pool em Ação

Cinco fases, um loop de 36 segundos: o warm-up cria as MinSize instâncias de uma vez; o fluxo normal faz as mesmas instâncias girarem entre Acquire/Release; um pico de carga cresce o pool além do MinSize até o MaxSize; o esgotamento mostra o que o caller realmente vê quando todo slot está emprestado e o AcquireTimeoutMs se esgota; a recuperação é onde IdleTimeoutMs e IdleTimeoutJitterMs entram em ação: as extras fecham em onda escalonada em vez de todas de uma vez, enquanto as instâncias de MinSize ficam paradas o tempo todo (só são recicladas de forma preguiçosa pelo MaxLifetimeMs, no próximo Acquire ou Release, nunca evictadas proativamente pelo housekeeper).

---

Performance & Benchmarks

Medido em dois níveis: um microbenchmark isolado da primitiva Acquire/Release (zero syscalls no caminho sem contenção, hot path sem alocação) e um soak de mundo real (mesmo servidor HTTP, mesmo driver de banco, só o pool muda) com 2000 usuários virtuais por 20 minutos, ~40:1 de contenção, PostgreSQL:

Métrica	Pool de referência	Triton
Throughput	912 req/s	967 req/s (+6%)
Latência mediana	270 ms	228 ms (−16%)
p95	2,15 s	1,83 s (−15%)

Sob carga moderada os dois pools empatam; a vantagem do Triton aparece sob alta contenção, na cauda de latência e na taxa de falha. Reprodução em samples/05-benchmark-sqlite e samples/06-benchmark-pool-latency.

---

Documentação

A referência completa está no Playbook, um guia modular cobrindo conceitos, adapters, operação e receitas.

Seção	Conteúdo
Visão geral	O que é o Triton, arquitetura em camadas, quando usar
Inspirações	Bibliotecas que influenciaram o design do Triton e o que foi aproveitado de cada uma
Conceitos core	Lease semantics, slot state machine, adapter contract, opções
Referência de Configuração	Todas as opções de TTritonOptions, tipos, defaults e quando ajustar cada uma
Adapters	FireDAC, THTTPClient, TIdSMTP, criando seu adapter
Operação e runtime	Observabilidade, métricas, backpressure, leak detection, housekeeper
Receitas	Padrões prontos para cenários comuns

---

A Família Olímpica

Poseidon comanda os mares: poder bruto, a engine assíncrona sob as ondas. Hermes percorre todos os reinos: carrega mensagens, mais rápido que qualquer onda. Hefesto forja nas profundezas: invisível, incansável, transformando matéria bruta em obra acabada. Apollo é o deus da luz e da verdade: traz tudo à luz.

Projeto	Mito	Papel
Poseidon	Deus dos mares	Framework HTTP assíncrono nativo + engine de I/O (IOCP/RIO, io_uring/epoll)
Hermes	Mensageiro dos deuses, guia entre os reinos	Cliente Redis (chave-valor, pub/sub, mensageria)
Hefesto	Forjador dos deuses, trabalha nas sombras	Jobs em background (filas, workers, retry, agendamento)
Apollo	Deus da luz e da verdade, traz as coisas à luz	Logging estruturado (sinks assíncronos, OTLP, Seq, Loki, Datadog)

---

Contribuindo

Veja CONTRIBUTING.md com diretrizes sobre adapters, testes, atualização do playbook e fluxo de pull request.

---

🇺🇸 Read this document in English: README_en.md