Skip to content

CSTYLE.md

Latest commit

 

History

History
412 lines (341 loc) · 12 KB

CSTYLE.md

File metadata and controls

412 lines (341 loc) · 12 KB

Linear Genetic Programming - Analisi Stile di Programmazione C

📊 Panoramica del Codebase

Dimensioni: 4101 linee C + 1105 linee header = 5206 linee totali Architettura: Modularità a layer con separazione chiara VM/Genetics/Evolution/Fitness Standard C: Supporto da C99 a C2X con detection automatica

🎨 STILE E CONVENZIONI

1. Naming Conventions

Strutture e Tipi

// Pascal Case per struct names
struct VirtualMachine { ... };
struct LGPInput { ... };
struct FitnessParams { ... };

// Enum values in UPPER_CASE
enum FitnessType {
    MINIMIZE = 0,
    MAXIMIZE = 1
};

// Typedef evitato - preferenza per "struct Name" esplicito

Funzioni e Variabili

// Snake case per funzioni
uint64_t run_vm(struct VirtualMachine *env, const uint64_t clock_limit);
struct Program rand_instruction(const struct LGPInput *const in, const uint64_t prog_size);

// Variabili locali snake_case
uint64_t best_individ = 0;
double immf;
const uint8_t reg1 = bytecode.reg[0];

Costanti e Macro

// UPPER_CASE per costanti e macro
#define INSTR_NUM 97
#define REG_NUM 4
#define HASH_SEED 0x5ab26229f0294a21ULL
#define RANDOM_MAX 0xFFFFFFFF

// Macro complesse multi-line con naming descrittivo
#define INSTR_MACRO \
    INSTRUCTION(EXIT, 0, 0, 0, 1) \
    INSTRUCTION(LOAD_RAM, 1, 1, 2, 0) \
    // ...

2. Type System e Safety

Uso Sistematico di Sized Integers

// Sempre uint64_t/uint32_t/uint8_t invece di int/long
uint64_t size;                    // Non 'size_t' 
uint32_t addr;                    // Non 'unsigned int'
uint8_t reg1, reg2, reg3;        // Non 'int' per register indices

// Enum con backing type esplicito (quando supportato)
enum InstrCode
#if defined(C2X_SUPPORTED)
    : uint8_t    // Explicit backing type
#endif
{
    INSTR_MACRO
};

Const Correctness Rigoroso

// Const pointer parameters ovunque possibile
struct Instruction rand_instruction(const struct LGPInput *const in, const uint64_t prog_size);
uint64_t best_individ(const struct Population *const pop, const enum FitnessType ftype);

// Const per variabili locali quando appropriato
const uint8_t reg1 = bytecode.reg[0];
const uint32_t addr = bytecode.addr;
const struct Operation op = in->instr_set.op[RAND_UPTO(in->instr_set.size - 1)];

Restrict Keyword per Performance

struct LGPInput {
    // ...
    union Memblock *restrict memory;  // Performance hint
};

3. Memory Management Strategy

Aligned Allocation per Performance Critical Data

// Programs usano aligned_alloc per SIMD compatibility
mutated.content = aligned_alloc(VECT_ALIGNMENT, sizeof(struct Instruction) * size);

// Padding automatico per alignment
#if VECT_ALIGNMENT != 0
    uint64_t align = VECT_ALIGNMENT / 8;
    size = (size + align - 1) & ~(align - 1);
    ASSERT(size % align == 0);
#endif

Error Handling con Macro Centralizzate

// Macro per malloc failure handling
if (mutated.content == NULL) {
    MALLOC_FAIL_THREADSAFE(sizeof(struct Instruction) * size);
}

// Definite in logger.h
#define MALLOC_FAIL(byte) LOG_EXIT("malloc failed, tryed to allocate " #byte " bytes")
#define MALLOC_FAIL_THREADSAFE(byte) LOG_EXIT_THREADSAFE("malloc failed...")

Cleanup Functions Sistematiche

void free_individual(struct Individual *ind);
void free_population(struct Population *pop);
void free_lgp_input(struct LGPInput *in);

// Usage pattern:
inline void free_individual(struct Individual *ind) {
    aligned_free(ind->prog.content);  // Consistent with aligned_alloc
}

4. Macro System Avanzato

X-Macro Pattern per Code Generation

// Definizione centralizzata di tutte le istruzioni
#define INSTR_MACRO \
    INSTRUCTION(EXIT, 0, 0, 0, 1) \
    INSTRUCTION(LOAD_RAM, 1, 1, 2, 0) \
    INSTRUCTION(STORE_RAM, 2, 1, 2, 2) \
    // ... 94 more instructions

// Generazione automatica di enum
#define INSTRUCTION(name, code, regs, addr, change) I_##name = code,
enum InstrCode { INSTR_MACRO };
#undef INSTRUCTION

// Generazione automatica di strutture dati
#define INSTRUCTION(name, code, regs, addr, change) [code] = {#name, regs, addr, change, code},
const struct Operation INSTRSET[] = { INSTR_MACRO };
#undef INSTRUCTION

Macro per Threading e Random Number Generation

// Thread-aware RNG con macro eleganti
#ifdef INCLUDE_OMP
    #define RANDOM_ENGINE_INDEX omp_get_thread_num()
#else
    #define RANDOM_ENGINE_INDEX 0
#endif

#define random() get_MT19937(&random_engines[RANDOM_ENGINE_INDEX])

// Macro per range generation
#define RAND_BOUNDS(min, max) ((min) + ((uint64_t) random() % ((max) - (min) + (uint64_t) 1)))
#define RAND_UPTO(max) ((uint64_t) random() % ((max) + (uint64_t) 1))

5. SIMD e Performance Optimization

Conditional SIMD Compilation

#if defined(INCLUDE_AVX512F)
    // AVX-512 implementation
    static inline __m512i avx512_xxh_roll(const __m512i previous, const __m512i input) {
        const __m512i prime2 = _mm512_set1_epi64(PRIME2);
        // ...
    }
#elif defined(INCLUDE_AVX2)
    // AVX2 fallback
    static inline __m256i avx256_xxh_roll(const __m256i previous, const __m256i input) {
        // ...
    }
#elif defined(INCLUDE_SSE2)
    // SSE2 fallback
    static inline __m128i sse2_xxh_roll(const __m128i previous, const __m128i input) {
        // ...
    }
#elif defined(INCLUDE_NEON)
    // ARM NEON implementation
    static inline uint64x2_t neon_xxh_roll(const uint64x2_t previous, const uint64x2_t input) {
        // ...
    }
#endif

Static Inline Functions per Performance

// Preferenza per static inline invece di macro per funzioni complesse
static inline uint64_t roll_left(const uint64_t num, const uint64_t step) {
    return ((num << step) | (num >> (64 - step)));
}

static inline uint64_t xxh_roll(const uint64_t previous, const uint64_t input) {
    return roll_left(previous + input * PRIME2, 31) * PRIME1;
}

6. Error Handling e Debugging

ASSERT Macro per Development

// Custom ASSERT implementation
#define ASSERT(x) \
    do \
        if(!(x)) unreachable(); \
    while(0)

// Usage pattern sistemático
ASSERT(prog_size > 0);
ASSERT(in->rom_size > 0);
ASSERT(mutated.size > 0);
ASSERT(mutated.size <= max_individ_len);

Logging Thread-Safe

// Centralized logging con thread safety
#define LOG_EXIT(message) log_error_exit(message, __FILE__, __LINE__)
#define LOG_EXIT_THREADSAFE(message) log_error_exit_ts(message, __FILE__, __LINE__)

// OpenMP critical sections per shared state
#pragma omp critical
{
    if(progmap.table[index].prog.size == 0) {
        progmap.table[index].prog = prog;
        added = 1;
    }
}

7. Cross-Platform Compatibility

Conditional Compilation per Portabilità

// C Standard detection
#if !defined(__STDC_VERSION__) || __STDC_VERSION__ < 201112L
    // C89/C90/C99 compatibility
    #if defined(_MSC_VER)
        #define alignas(n) __declspec(align(n))
        #define unreachable() (__assume(0))
    #elif defined(__GNUC__) || defined(__clang__)
        #define alignas(n) __attribute__((aligned(n)))
        #define unreachable() (__builtin_unreachable())
    #endif
#elif __STDC_VERSION__ <= 201710L
    // C11/C17
    #include <stdalign.h>
    #define NORETURN_ATTRIBUTE _Noreturn
#else
    // C2X/C23
    #define C2X_SUPPORTED
    #define NORETURN_ATTRIBUTE [[noreturn]]
    #define UNUSED_ATTRIBUTE [[maybe_unused]]
#endif

Platform-Specific Memory Allocation

#if defined(_MSC_VER)
    #include <malloc.h>
    #define aligned_alloc(alignment, size) _aligned_malloc((size), (alignment))
    #define aligned_free(ptr) _aligned_free(ptr)
#elif defined(__GNUC__) || defined(__clang__)
    static inline void *aligned_alloc(size_t alignment, size_t size) {
        void *p;
        return posix_memalign(&p, alignment, size) == 0 ? p : NULL;
    }
    #define aligned_free(ptr) free(ptr)
#endif

8. Structure Layout e Data Organization

POD (Plain Old Data) Structures

// Strutture semplici, no inheritance, no vtables
struct Instruction {
    uint8_t op;           // 1 byte
    uint8_t reg[3];       // 3 bytes
    uint32_t addr;        // 4 bytes
};                        // Total: 8 bytes (packed)

union Memblock {
    uint64_t i64;         // 8 bytes
    double f64;           // 8 bytes
};                        // Size: 8 bytes

Designated Initializers (C99+)

// Inizializzazione esplicita dei campi
const struct InstructionSet COMPLETE_INSTRSET = {
    .size = INSTR_NUM,
    .op = INSTRSET
};

struct Program mutated = { .size = from_parent + mutation_len };
struct LGPResult res = { .generations = 0, .pop = pop, .evaluations = pop.size };

9. Function Design Patterns

Pure Functions con Const Parameters

// Input-only parameters sempre const
uint64_t xxhash_program(const struct Program *const prog);
unsigned int equal_program(const struct Program *const prog1, const struct Program *const prog2);

// Return struct by value per immutabilità
struct Instruction rand_instruction(const struct LGPInput *const in, const uint64_t prog_size);
struct Program mutation(const struct LGPInput *const in, const struct Program *const parent, ...);

Static Functions per Internal API

// Funzioni helper non esposte
static inline struct Program rand_program(const struct LGPInput *const in, ...);
static inline uint64_t best_individ(const struct Population *const pop, ...);
static inline uint64_t next_power_of_two(uint64_t x);

10. OpenMP Integration

Parallel Loops con Proper Scheduling

// Dynamic scheduling per workload balancing
#pragma omp parallel for schedule(dynamic,1) num_threads(NUMBER_OF_OMP_THREADS)
for (uint64_t i = 0; i < pop.size; i++) {
    struct Program prog = rand_program(in, params->minsize, params->maxsize);
    pop.individual[i] = (struct Individual){ .prog = prog, .fitness = fitness->fn(...) };
}

// Static scheduling per work uniformo
#pragma omp parallel for schedule(static,1) num_threads(NUMBER_OF_OMP_THREADS)
for(uint64_t i = 0; i < input_num; i++) {
    // Uniform work per thread
}

Atomic Operations per Thread Safety

// Atomic captures per statistics
#pragma omp atomic capture
evaluations_local = evaluations += pop.size;

#pragma omp atomic capture
generations_local = ++generations;

🏆 PUNTI DI FORZA DELLO STILE

✅ Eccellenti

  1. Const Correctness: Uso sistematico e rigoroso
  2. Type Safety: Sized integers ovunque, no implicit conversions pericolose
  3. Memory Alignment: Gestione expert-level per performance SIMD
  4. Cross-Platform: Supporto compiler e architetture multiple
  5. X-Macro Pattern: Code generation elegante e maintainable
  6. Performance Focus: Static inline, restrict, branch prediction hints
  7. Thread Safety: OpenMP integration ben progettata
  8. Modularità: Separazione chiara responsibilities

⚠️ Aree di Miglioramento Minori

  1. Documentation: Scarsi commenti inline (tipico C systems programming)
  2. Magic Numbers: Alcuni valori hardcoded (97 instructions, 4 registers)
  3. Error Propagation: Sistema di errori principalmente abort-based
  4. Naming: Alcune abbreviazioni (immf, prcount) potrebbero essere più chiare

🎯 VALUTAZIONE COMPLESSIVA

Stile: Professionale C Systems Programming Livello: Expert/Advanced (8.5/10) Paradigma: Performance-First Procedural C

Il codebase dimostra:

  • Deep understanding di C moderno (C99-C2X)
  • Expertise in performance optimization (SIMD, alignment, threading)
  • Solid software engineering practices (modularity, const correctness, error handling)
  • Cross-platform system programming competence

È uno stile production-ready tipico di:

  • Game engines (id Software, Epic)
  • Scientific computing libraries (BLAS, LAPACK)
  • System software (kernels, drivers)
  • High-performance computing frameworks

Raccomandazione: Questo stile è appropriato e ben eseguito per il dominio del progetto. Le scelte architetturali sono giustificate dai requisiti di performance.

Analisi dettagliata del codebase C - 5206 linee analizzate 15 settembre 2025