---
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)