# 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.