feat(skills): add local python-to-c-efficiency skill with modular C scaffold
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
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user