Davide Grilli
9a0a170799
add local Codex skill for Python->C performance-focused translation define modular C architecture and benchmark/correctness gates add references for patterns, profiling, and module design add scaffold_c_module.py to generate include/src/tests/bench skeleton update agent default prompt for benchmark-backed optimizations
62 lines
1.6 KiB
Markdown
62 lines
1.6 KiB
Markdown
# Architettura Modulare C per Performance
|
|
|
|
## Obiettivo
|
|
|
|
Definire moduli C che siano allo stesso tempo veloci, testabili e sostituibili.
|
|
|
|
## Struttura raccomandata
|
|
|
|
```text
|
|
feature/
|
|
include/feature.h
|
|
src/feature.c
|
|
src/feature_internal.h
|
|
tests/test_feature.c
|
|
bench/bench_feature.c
|
|
```
|
|
|
|
## Regole API
|
|
|
|
1. Esporre API piccole e stabili in `include/feature.h`.
|
|
2. Esporre tipi opachi quando lo stato interno non deve trapelare.
|
|
3. Passare sempre buffer e lunghezze esplicite.
|
|
4. Evitare allocazioni implicite nascoste nelle funzioni hot-path.
|
|
5. Restituire codici errore prevedibili.
|
|
|
|
Esempio di firma:
|
|
|
|
```c
|
|
feature_status_t feature_process(
|
|
const uint8_t *restrict in,
|
|
size_t n,
|
|
uint8_t *restrict out,
|
|
size_t out_n);
|
|
```
|
|
|
|
## Separazione responsabilità
|
|
|
|
- `feature.c`: implementazione pubblica + validazioni input
|
|
- `feature_internal.h`: helper statici e dettagli non pubblici
|
|
- `test_feature.c`: correttezza funzionale e edge case
|
|
- `bench_feature.c`: metriche throughput/latenza isolate
|
|
|
|
## Policy di memoria
|
|
|
|
1. Definire ownership nel contratto API.
|
|
2. Prediligere buffer chiamante-alloca per hot-path.
|
|
3. Usare allocator personalizzato solo se il profiler mostra contesa o overhead.
|
|
|
|
## Policy di concorrenza
|
|
|
|
1. Preferire moduli reentrant e senza stato globale.
|
|
2. Separare stato per thread quando serve parallelismo.
|
|
3. Evitare lock nel percorso caldo; usare partizionamento dati.
|
|
|
|
## Checklist revisione modulo
|
|
|
|
1. API minima e coerente.
|
|
2. Nessun dettaglio interno esportato inutilmente.
|
|
3. Test e benchmark presenti.
|
|
4. Input validation chiara e costo minimo.
|
|
5. Dipendenze inter-modulo ridotte.
|