cpu-miner/.codex/skills/python-to-c-efficiency/references/patterns-python-c.md

Patterns Python -> C (efficienza)

1) Mapping dati: scegliere strutture contigue

• list[int/float] -> buffer contiguo (int32_t*, float*, double*) + size_t n
• tuple a campi fissi -> struct con tipi espliciti
• dict con chiavi piccole/note -> array indicizzato o enum + switch
• set su dominio ridotto -> bitmap; su dominio ampio -> hash table dedicata

Pattern consigliato per API:

int kernel_run(const float *restrict in, float *restrict out, size_t n);

2) Mapping controllo di flusso

• List comprehension numerica -> loop for con output preallocato
• sum(...) -> accumulatore locale tipizzato
• Generator pipeline -> passaggi espliciti su buffer intermedi preallocati
• Evitare callback in hot-path quando una chiamata diretta è possibile

3) Mapping semantica numerica

• Definire policy per float vs double prima della traduzione
• Riprodurre comportamento su NaN/Inf, divisione, modulo e rounding
• Isolare conversioni int/float fuori dal loop caldo

4) Gestione memoria e ownership

• Definire ownership in firma funzione e commento API
• Evitare malloc/free per elemento o per iterazione
• Riusare arena/buffer quando il workload è batch
• Validare dimensioni e puntatori in ingresso all'inizio della funzione

5) Branch e cache locality

• Ordinare il branch con caso frequente nel percorso lineare
• Ridurre dipendenze dati tra iterazioni in loop lunghi
• Ordinare campi struct per ridurre padding e cache miss

6) Error model coerente

Pattern consigliato:

typedef enum {
  KERNEL_OK = 0,
  KERNEL_ERR_NULL = 1,
  KERNEL_ERR_SIZE = 2
} kernel_status_t;

Restituire errori prevedibili e senza side effect parziali non documentati.

7) Sequenza pratica di traduzione

1. Portare codice 1:1 in C per equivalenza funzionale.
2. Inserire test di parità output.
3. Profilare la versione C.
4. Ottimizzare solo le funzioni che dominano runtime.