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
112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
---
|
|
name: python-to-c-efficiency
|
|
description: Tradurre codice Python in C ad alte prestazioni con focus su modularizzazione, riduzione overhead e benchmarking ripetibile. Usare quando Codex deve convertire `.py` in moduli `.c/.h`, isolare hot-path CPU o memoria, progettare API C stabili e consegnare implementazioni validate con test di equivalenza e misure performance prima/dopo.
|
|
---
|
|
|
|
# Python to C Efficiency
|
|
|
|
## Obiettivo
|
|
|
|
Convertire sezioni critiche Python in C con tre vincoli obbligatori:
|
|
|
|
1. Mantenere comportamento osservabile equivalente.
|
|
2. Consegnare codice modulare e manutenibile.
|
|
3. Dimostrare miglioramento con benchmark ripetibile.
|
|
|
|
## Workflow Decisionale
|
|
|
|
1. Misurare prima di tradurre.
|
|
Profilare Python e identificare i veri hotspot. Evitare conversioni "a tappeto".
|
|
|
|
2. Delimitare il confine C.
|
|
Tradurre kernel computazionali e lasciare in Python orchestrazione, I/O e glue code quando non critici.
|
|
|
|
3. Disegnare il modulo C.
|
|
Definire API, ownership memoria, error handling e formato dati prima dell'implementazione.
|
|
|
|
4. Implementare versione corretta.
|
|
Portare la logica Python in C senza ottimizzazioni premature.
|
|
|
|
5. Ottimizzare solo hotspot confermati.
|
|
Applicare tecniche CPU/cache/memoria su funzioni misurate come dominanti.
|
|
|
|
6. Validare correttezza e performance.
|
|
Confrontare output Python/C e pubblicare metriche prima/dopo con stesso dataset.
|
|
|
|
## Architettura Modulare Obbligatoria
|
|
|
|
Usare struttura per modulo:
|
|
|
|
```text
|
|
<feature>/
|
|
include/<feature>.h
|
|
src/<feature>.c
|
|
src/<feature>_internal.h # opzionale
|
|
tests/test_<feature>.c
|
|
bench/bench_<feature>.c
|
|
```
|
|
|
|
Applicare queste regole:
|
|
|
|
1. Esporre nel `.h` solo API pubbliche, tipi pubblici minimi e codici errore.
|
|
2. Nascondere dettagli interni in `_internal.h` o nel `.c`.
|
|
3. Passare buffer con puntatore + lunghezza (`ptr`, `size_t n`).
|
|
4. Dichiarare `const` e `restrict` quando semanticamente corretti.
|
|
5. Evitare stato globale mutabile nel percorso caldo.
|
|
|
|
Per bootstrap rapido della struttura usare:
|
|
|
|
```bash
|
|
python3 scripts/scaffold_c_module.py --name my_kernel --out-dir /path/progetto
|
|
```
|
|
|
|
## Regole di Implementazione ad Alte Prestazioni
|
|
|
|
1. Rendere i tipi espliciti (`int32_t`, `uint64_t`, `size_t`, `float`, `double`).
|
|
2. Preallocare e riusare memoria nei loop intensivi.
|
|
3. Favorire layout contigui e accesso sequenziale cache-friendly.
|
|
4. Ridurre branch imprevedibili nel hot-path.
|
|
5. Ridurre indirezioni e dispatch dinamico dove non necessario.
|
|
6. Applicare `static inline` solo dove il profiler giustifica il beneficio.
|
|
7. Usare algoritmo migliore prima di micro-ottimizzare il codice.
|
|
|
|
## Contratto di Correttezza
|
|
|
|
Prima di dichiarare completata la traduzione, eseguire sempre:
|
|
|
|
1. Test di regressione su casi nominali e edge case.
|
|
2. Confronto output Python vs C su dataset condiviso.
|
|
3. Build debug con sanitizer e assenza di errori runtime.
|
|
|
|
## Contratto di Performance
|
|
|
|
Misurare e riportare sempre:
|
|
|
|
1. Tempo wall e CPU.
|
|
2. Memoria massima.
|
|
3. Throughput o latenza per input unitario.
|
|
|
|
Accettare il risultato solo se:
|
|
|
|
1. Esiste speedup reale su workload target.
|
|
2. Il miglioramento è ripetibile su più run.
|
|
3. Eventuali regressioni secondarie sono documentate.
|
|
|
|
## Output Richiesto
|
|
|
|
Produrre sempre:
|
|
|
|
1. File `.c/.h` modulari con API chiara.
|
|
2. Nota breve di mapping Python→C per le parti critiche.
|
|
3. Comandi build debug/release usati.
|
|
4. Tabella compatta benchmark prima/dopo.
|
|
5. Rischi residui o tradeoff aperti.
|
|
|
|
## Riferimenti
|
|
|
|
Caricare in base al task:
|
|
|
|
- Mapping costrutti e pattern: [references/patterns-python-c.md](references/patterns-python-c.md)
|
|
- Build, profiler e benchmark: [references/compiler-and-profiling.md](references/compiler-and-profiling.md)
|
|
- Design modulare C: [references/modular-c-architecture.md](references/modular-c-architecture.md)
|