performance discussion

This commit is contained in:
bQUARKz 2026-03-10 11:02:06 +00:00
parent 8152269d5b
commit 52aed9d0ea
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
9 changed files with 555 additions and 0 deletions

View File

@ -0,0 +1,66 @@
# Agenda - [PERF] Runtime Telemetry Hot Path
## Problema
O runtime cobra telemetria de asset bank no caminho quente de todo host tick.
Hoje, `tick()` consulta `bank_info()` para `gfx` e `audio` mesmo quando nenhum logical frame foi fechado. O custo de observabilidade acaba sendo pago continuamente pela execucao normal.
## Dor
- CPU e locks sao gastos em todos os ticks, nao apenas quando a metrica muda.
- hardware barato sofre mais com trabalho pequeno e repetitivo do que com picos raros.
- overlay, stats e certifier acabam puxando custo estrutural para o core do runtime.
## Hotspots Atuais
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L167)
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L618)
## Alvo da Discussao
Remover varredura e agregacao lock-heavy do hot path do tick sem perder observabilidade util.
## O Que Precisa Ser Definido
1. Modelo de metrica.
Decidir o que passa a ser contador incremental e o que continua sendo snapshot sob demanda.
2. Frequencia de coleta.
Decidir se atualizacao acontece:
- no fechamento do logical frame;
- apenas com overlay/debug ativo;
- por amostragem periodica;
- por evento de mutacao (`load`, `commit`, `cancel`).
3. Responsabilidade da agregacao.
Delimitar se a verdade dos bytes/slots fica:
- no `AssetManager`;
- no runtime;
- em uma camada propria de telemetry cache.
4. Garantia de consistencia.
Decidir qual grau de defasagem e aceitavel para handheld barato:
- exato em tempo real;
- eventual por frame;
- eventual por tick de debug.
## Open Questions de Arquitetura
1. O certifier realmente precisa de snapshot de bank a cada tick?
2. O overlay pode ler uma versao resumida da telemetria em vez de recalcular tudo?
3. Vale manter caminho "preciso" so para testes/debug e caminho "barato" para runtime normal?
## Dependencias
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/16a-syscall-policies.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- metrica incremental vs snapshot;
- ponto canonico de atualizacao da telemetria;
- custo maximo aceitavel no hot path do tick;
- comportamento de overlay/certifier sobre dados defasados.

View File

@ -0,0 +1,74 @@
# Agenda - [PERF] Async Background Work Lanes for Assets and FS
## Problema
`asset.load()` hoje cria uma thread do SO por requisicao. Ao mesmo tempo, `fs` ainda nao tem uma politica clara para sync assincrono barato em hardware simples.
O projeto precisa de paralelismo para IO/decode/sync, mas o target inclui handheld DIY e hardware barato, onde um pool grande ou explosao de threads pode piorar a latencia em vez de melhorar.
## Dor
- `thread::spawn` por request escala mal e cria jitter.
- assets e `fs` competem por IO sem uma politica unica de fila/prioridade.
- sem lane dedicada, operacoes de background tendem a vazar custo para o main loop.
- sem disciplina, o host desktop vira referencia errada para hardware fraco.
## Hotspots Atuais
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L353)
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L53)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L315)
## Alvo da Discussao
Fechar um modelo de execucao assincrona para `asset` e `fs` que seja previsivel em hardware simples.
## O Que Precisa Ser Definido
1. Topologia de workers.
Escolher entre:
- uma thread dedicada para `asset` e outra para `fs`;
- um worker unico multiplexando filas;
- um pool minimo e fixo;
- proibicao explicita de `spawn` por request.
2. Separacao por dominio.
Decidir se `asset` e `fs` compartilham scheduler/fila ou se cada dominio tem lane propria.
3. Politica de prioridade.
Definir:
- prioridade de loads visuais vs audio;
- prioridade de sync de save/config;
- limite de trabalho por frame para install/commit.
4. Modelo de retorno.
Fechar como o guest observa backlog, cancelamento e saturacao:
- status imediato de fila cheia;
- status de pending;
- metrica de backlog;
- politica de cancelamento.
5. Orçamento para hardware barato.
Definir quantas threads o runtime pode assumir como baseline.
## Open Questions de Arquitetura
1. O v1 precisa de lanes separadas para `asset` e `fs` ou basta uma fila central com classes de prioridade?
2. Decode de asset fica no mesmo worker do IO ou em fase distinta?
3. Commit/install no device continua no main thread por determinismo?
## Dependencias
- `../specs/09-events-and-concurrency.md`
- `../specs/15-asset-management.md`
- `../specs/16a-syscall-policies.md`
- `014-app-home-filesystem-surface-and-semantics.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- numero e tipo de workers aceitos no baseline;
- fila/prioridade de `asset` e `fs`;
- proibicao ou aceitacao limitada de `thread::spawn` por request;
- modelo de status/telemetria para backlog e saturacao.

View File

@ -0,0 +1,68 @@
# Agenda - [PERF] Host Desktop Frame Pacing and Presentation
## Problema
O host desktop ainda roda em modo agressivo de polling e apresentacao continua.
Hoje o loop usa `ControlFlow::Poll`, pede redraw incondicionalmente e converte o framebuffer inteiro de RGB565 para RGBA8 a cada `RedrawRequested`, mesmo quando nao ha novo frame logico.
## Dor
- CPU fica ocupada sem ganho visual.
- port de referencia no desktop mascara problemas de pacing em hardware barato.
- a conta de energia/temperatura piora mesmo quando a VM esta ociosa.
## Hotspots Atuais
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L252)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L270)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L390)
## Alvo da Discussao
Fechar uma politica de pacing/apresentacao host-driven que nao desperdice CPU quando nao existe frame novo.
## O Que Precisa Ser Definido
1. Gatilho de redraw.
Decidir se redraw acontece:
- apenas com logical frame pronto;
- por deadline de vsync;
- por dirty flag do front buffer;
- por evento externo relevante.
2. Politica do event loop.
Decidir entre:
- `Wait`;
- `WaitUntil`;
- `Poll` apenas em modo debug/profiling.
3. Conversao de framebuffer.
Definir se a conversao RGB565 -> RGBA8:
- continua full-frame;
- passa a ser dirty-region;
- sai da CPU e vai para shader/path especifico do host.
4. Modo ocioso.
Delimitar comportamento quando VM esta pausada, em breakpoint ou sem cart.
## Open Questions de Arquitetura
1. O host desktop deve ser referencia conservadora de energia ou apenas shell de desenvolvimento?
2. O runtime precisa expor um sinal explicito de "novo frame disponivel" para o host?
3. Existe necessidade real de redraw continuo quando o overlay esta desligado?
## Dependencias
- `../specs/01-time-model-and-cycles.md`
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- politica de control flow do host;
- criterio canonico de redraw;
- estrategia de conversao/apresentacao de framebuffer;
- comportamento de idle/pause/debug.

View File

@ -0,0 +1,63 @@
# Agenda - [PERF] GFX Render Pipeline and Dirty Regions
## Problema
O renderer `gfx` recompõe a cena inteira a cada frame logico, mesmo quando a mudanca visual e pequena.
Hoje `render_all()` reconstrói buckets de sprites, escaneia os 512 sprites, redesenha layers e aplica dois passes fullscreen de fade sem politica de invalidacao.
## Dor
- custo visual basico cresce demais para hardware simples.
- pequenos updates pagam preco de full redraw.
- fade, HUD e world composition ficam sempre no caminho critico.
## Hotspots Atuais
- [gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs#L563)
- [gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs#L671)
## Alvo da Discussao
Definir ate onde o v1 precisa sair do modelo brute force para um pipeline com invalidacao e custo previsivel.
## O Que Precisa Ser Definido
1. Granularidade de invalidacao.
Escolher entre:
- dirty flag por frame inteiro;
- dirty region por layer;
- dirty list por sprite/HUD;
- combinacao minima viavel.
2. Buckets e traversal de sprites.
Decidir se os buckets continuam sendo reconstruidos por frame ou se viram estrutura incremental.
3. Fades.
Definir se fade neutro precisa bypass total e se fade parcial pode operar por regiao/camada.
4. Cache de composicao.
Delimitar se layers estaticas/HUD podem manter cache intermediario.
5. Meta de custo.
Fechar qual teto de pixels/trabalho por frame e aceitavel no baseline.
## Open Questions de Arquitetura
1. O fantasy console quer simular hardware de full redraw ou quer um renderer pragmatico para handheld barato?
2. Dirty regions quebram alguma expectativa de determinismo visivel?
3. O HUD deve continuar no mesmo pipeline da world scene?
## Dependencias
- `../specs/04-gfx-peripheral.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- nivel minimo de invalidacao no v1;
- politica de rebuild de buckets de sprites;
- bypass/cache de fade e HUD;
- meta de custo para o render pipeline.

View File

@ -0,0 +1,61 @@
# Agenda - [PERF] Runtime Introspection Syscalls
## Problema
As syscalls de introspecao ainda carregam custo de serializacao e agregacao demais para algo que deveria ser observabilidade sob demanda.
Hoje `BankInfo` e `BankSlotInfo` montam JSON por chamada e puxam dados potencialmente caros do asset manager.
## Dor
- tooling de debug pode contaminar custo percebido da runtime surface.
- serializacao de string/JSON vira alocacao no meio do dispatch.
- sem fronteira clara, apps podem abusar de syscalls de introspecao como se fossem baratas.
## Hotspots Atuais
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L481)
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L618)
## Alvo da Discussao
Separar claramente custo de introspecao/debug do custo da superficie operacional normal.
## O Que Precisa Ser Definido
1. Papel dessas syscalls.
Decidir se `BankInfo`/`BankSlotInfo` sao:
- superficie publica normal;
- superficie de debug;
- superficie host/devtools apenas.
2. Shape de retorno.
Definir se JSON continua existindo ou se v1 exige shape mais barato/canonico.
3. Caching.
Delimitar se snapshots de introspecao podem ser cacheados por frame.
4. Limites de uso.
Decidir se o runtime deve impor throttling, budget ou feature gate de debug.
## Open Questions de Arquitetura
1. Vale manter JSON na ABI do guest ou isso deveria ficar restrito ao host/debugger?
2. Existe um subconjunto de dados numericos suficiente para carts sem tooling externo?
3. O certifier deve observar essas chamadas como custo anormal de debug?
## Dependencias
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/15-asset-management.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- papel normativo de `BankInfo`/`BankSlotInfo`;
- permanencia ou remocao de JSON como shape de retorno;
- politica de cache/throttling;
- custo aceitavel de introspecao no dispatch.

View File

@ -0,0 +1,59 @@
# Agenda - [PERF] Host Debug Overlay Isolation
## Problema
O overlay de debug ainda usa o pipeline emulado de `gfx` e injeta custo visual no caminho normal do host.
Hoje o host formata strings por frame, desenha texto via `gfx` e faz `present()` extra para sobrepor telemetria.
## Dor
- debug ligado altera custo do render path que deveria estar sendo medido.
- overlay de desenvolvimento distorce a leitura de performance do console.
- handheld barato nao deveria pagar composicao de HUD tecnico no mesmo pipeline do jogo.
## Hotspots Atuais
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L126)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L381)
## Alvo da Discussao
Isolar o overlay de debug do custo medido do console sem perder utilidade para desenvolvimento.
## O Que Precisa Ser Definido
1. Lugar de composicao.
Decidir se o overlay:
- continua no `gfx` emulado;
- sobe para camada host nativa;
- vira surface separada de debug.
2. Politica de strings/glyphs.
Definir se texto e reconstruido por frame ou cacheado.
3. Custo em modo debug.
Delimitar qual overhead e aceitavel quando overlay estiver ativo.
4. Efeito na telemetria.
Fechar se a telemetria deve incluir ou excluir explicitamente o custo do overlay.
## Open Questions de Arquitetura
1. O overlay precisa ser representativo do hardware final ou apenas ferramenta de desktop?
2. Vale um modo "perf puro" onde overlay nunca toca no framebuffer do console?
3. O host deve oferecer toggles separados para stats, logs e overlay visual?
## Dependencias
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- onde o overlay e composto;
- politica de cache de texto/glyphs;
- como o custo do overlay aparece na telemetria;
- overhead maximo aceitavel em modo debug.

View File

@ -0,0 +1,69 @@
# Agenda - [PERF] VM Allocation and Copy Pressure
## Problema
O core da VM ainda aloca e clona demais em alguns caminhos relevantes, especialmente quando strings entram no fluxo.
Hoje `ADD` com string usa `format!`/`to_string()`, `GET_GLOBAL` clona valores e varios caminhos de erro montam strings dinamicas.
## Dor
- churn de heap reduz o teto de throughput da VM.
- carts que abusam de string e estado global pagam custo cedo demais.
- hardware barato sente alocacao repetitiva de forma desproporcional.
## Hotspots Atuais
- [virtual_machine.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-vm/src/virtual_machine.rs#L635)
- [virtual_machine.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-vm/src/virtual_machine.rs#L870)
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L111)
## Alvo da Discussao
Definir o nivel de disciplina de alocacao/copia exigido do core da VM no baseline do console.
## O Que Precisa Ser Definido
1. Prioridade dos casos.
Fechar quais caminhos sao realmente hot:
- opcodes de string;
- acesso a globals;
- faults;
- logs.
2. Estrategia de ownership.
Decidir onde vale introduzir:
- borrow temporario;
- small-string strategy;
- copy-on-write;
- intern/cache de strings.
3. Meta de alocacao.
Definir se o projeto quer:
- zero alloc no frame loop feliz;
- alloc rara e explicita;
- apenas reducao oportunista.
4. Instrumentacao.
Decidir como medir alocacao sem transformar a VM em microbenchmark artificial.
## Open Questions de Arquitetura
1. Strings sao citizen de primeira classe no fantasy console ou recurso conveniente mas caro?
2. Vale endurecer a linguagem/ABI para reduzir alocacao implicitamente?
3. Caminhos de fault precisam ser maximizados para desempenho ou apenas os caminhos felizes?
## Dependencias
- `../specs/02a-vm-values-and-calling-convention.md`
- `../specs/03-memory-stack-heap-and-allocation.md`
- `../specs/10-debug-inspection-and-profiling.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- caminho quente prioritario para desengordurar;
- meta minima de alocacao/copia da VM;
- estrategia de ownership para strings/values;
- instrumentacao canonica para medir regressao.

View File

@ -0,0 +1,63 @@
# Agenda - [PERF] Cartridge Boot and Program Ownership
## Problema
O bootstrap do cart ainda faz copia desnecessaria de dados grandes e de metadados que poderiam ter ownership mais claro.
Hoje `initialize_vm()` clona `program`, `title`, `app_version` e `entrypoint` ao carregar o cart. Isso nao e o maior gargalo em steady-state, mas sinaliza que ownership de boot ainda esta frouxo.
## Dor
- reload, troca de cart e cenarios de tooling pagam custo desnecessario.
- ownership frouxo no boot tende a reaparecer em hot-reload, debugger e loader.
- em hardware pequeno, boot "barato" tambem importa.
## Hotspots Atuais
- [lifecycle.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/lifecycle.rs#L125)
## Alvo da Discussao
Fechar um modelo de ownership de cart/programa que reduza copias sem comprometer simplicidade ou seguranca do runtime.
## O Que Precisa Ser Definido
1. Ownership do programa.
Decidir se o bytecode:
- e movido para a VM;
- e compartilhado por `Arc`;
- e mantido no cart com view emprestada.
2. Ownership de metadata.
Delimitar o que precisa ser copiado para estado corrente do runtime e o que pode ser referenciado.
3. Ciclo de vida.
Definir como ownership funciona em:
- boot inicial;
- troca de cart;
- debugger/reload;
- run-cart futuro.
4. Meta de boot.
Fechar qual custo de inicializacao e aceitavel para o baseline.
## Open Questions de Arquitetura
1. O projeto quer boot otimizado para trocas frequentes ou apenas para cold start?
2. Existe risco real de aliasing/perigo de lifetime ao evitar copias aqui?
3. Vale aceitar copia de metadata pequena e atacar so `program`?
## Dependencias
- `../specs/13-cartridge.md`
- `../specs/14-boot-profiles.md`
- `009-system-run-cart.md`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- ownership canonico de `program`;
- politica de copia/referencia para metadata de cart;
- comportamento em reload/troca de cart;
- meta de custo para boot e reinicializacao.

View File

@ -16,6 +16,38 @@ As agendas atuais são:
- `010-system-fault-semantics-and-control-surface.md`
- `012-vm-owned-random-service.md`
- `014-app-home-filesystem-surface-and-semantics.md`
- `015-perf-runtime-telemetry-hot-path.md`
- `016-perf-async-background-work-lanes-for-assets-and-fs.md`
- `017-perf-host-desktop-frame-pacing-and-presentation.md`
- `018-perf-gfx-render-pipeline-and-dirty-regions.md`
- `019-perf-runtime-introspection-syscalls.md`
- `020-perf-host-debug-overlay-isolation.md`
- `021-perf-vm-allocation-and-copy-pressure.md`
- `022-perf-cartridge-boot-and-program-ownership.md`
## Sequenciamento Recomendado [PERF]
Ordem sugerida para discussao das agendas de performance:
1. `015-perf-runtime-telemetry-hot-path.md`
2. `016-perf-async-background-work-lanes-for-assets-and-fs.md`
3. `017-perf-host-desktop-frame-pacing-and-presentation.md`
4. `018-perf-gfx-render-pipeline-and-dirty-regions.md`
5. `019-perf-runtime-introspection-syscalls.md`
6. `020-perf-host-debug-overlay-isolation.md`
7. `021-perf-vm-allocation-and-copy-pressure.md`
8. `022-perf-cartridge-boot-and-program-ownership.md`
Justificativa curta:
- `015` e o imposto mais imediato no hot path do runtime.
- `016` fecha a topologia de trabalho assincrono antes de codarmos otimizaoes isoladas.
- `017` impede que o host desktop continue mascarando custo real com busy-poll.
- `018` define o teto de custo do renderer antes de micro-otimizacoes locais.
- `019` separa observabilidade de superficie operacional normal.
- `020` impede que tooling de debug distorca medicao de render e frame pacing.
- `021` entra depois que os gargalos estruturais maiores estiverem delimitados.
- `022` fecha ownership e custo de boot, importante mas menos quente que o frame loop.
## Sequenciamento Recomendado