C_projet/CLAUDE.md
2026-11-04 18:00:08 +01:00

11 KiB

C Object-Oriented Architecture

This project uses an object-oriented design pattern in C based on opaque pointers and vtables for method dispatch and polymorphism.

Project Structure

.
├── src/                    # Implementation files (.c)
├── src/include/            # Protected headers (protected_*.h)
├── include/                # Public API headers (*.h)
├── CMakeLists.txt          # Minimalist CMake configuration
└── CLAUDE.md               # This file

Type Definition Pattern

Each class follows an opaque pointer pattern to hide implementation details:

Public Header (include/class.h)

/* Opaque type definition - structure details hidden from users */
typedef struct _class_t class_t;

/* Vtable definition with function pointers - made public for polymorphism */
typedef struct {
    void (*method_a)(const class_t *const self);
    int (*method_b)(const class_t *const self, int arg);
} vtable_class_t;

/* Dispatcher functions - the ONLY way to access methods */
void class_method_a(const class_t *const self);
int class_method_b(const class_t *const self, int arg);

/* Constructors */
class_t* class_build_default(void);
class_t* class_build_logic(/* constructor arguments */);

/* Destructor */
void class_destroy(class_t *self);

Protected Header (src/include/protected_class.h)

#ifndef PROTECTED_CLASS_H
#define PROTECTED_CLASS_H

#include "class.h"

/* Real structure definition - only visible to implementation and children */
struct _class_t {
    vtable_class_t vtable;  /* Virtual table as first field */
    /* ... other members ... */
};

/* Protected constructors for use by child classes */
class_t* class_init_default(void);
class_t* class_init_logic(/* constructor arguments */);

#endif

IMPORTANT: protected_class.h must NEVER be included in class.h or any other public .h file.

Implementation (src/class.c)

#include "class.h"              /* For function prototypes and public typedefs */
#include "protected_class.h"    /* For structure definition */

/* Private (static) implementation */
static void _class_method_a_impl(const class_t *const self) {
    /* Implementation */
}

static int _class_method_b_impl(const class_t *const self, int arg) {
    /* Implementation */
}

/* Default vtable with standard implementations */
static const vtable_class_t class_default_vtable = {
    .method_a = _class_method_a_impl,
    .method_b = _class_method_b_impl,
};

/* Constructors */
class_t* class_build_default(void) {
    return class_init_default();
}

class_t* class_build_logic(/* args */) {
    /* Validation and setup if needed */
    return class_init_logic(/* args */);
}

/* Protected constructor with actual initialization logic */
class_t* class_init_default(void) {
    class_t *self = malloc(sizeof(class_t));
    if (!self) return NULL;
    
    /* Initialize vtable with default implementation */
    self->vtable = class_default_vtable;
    
    /* Initialize other members */
    
    return self;
}

class_t* class_init_logic(/* args */) {
    /* Similar to init_default but with custom initialization */
}

/* Destructor */
class_t* class_destroy(class_t *self) {
    if (!self) return NULL;
    /* Clean up resources */
    free(self);
    return NULL;
}

/* Dispatcher functions - delegate to vtable */
void class_method_a(const class_t *const self) {
    return self->vtable.method_a(self);
}

int class_method_b(const class_t *const self, int arg) {
    return self->vtable.method_b(self, arg);
}

Inheritance Pattern

Single Inheritance via Vtable Extension

Child classes extend a parent's vtable by embedding the parent vtable as the first field (named super):

Child Public Header (include/child.h)

typedef struct _child_t child_t;

/* Child vtable includes parent vtable and new methods */
typedef struct {
    vtable_class_t super;           /* Parent vtable as first field */
    void (*method_c)(const child_t *const self);
} vtable_child_t;

/* Only dispatch NEW methods - parent methods are accessed via parent dispatcher */
void child_method_c(const child_t *const self);

/* Constructors */
child_t* child_build_default(void);
child_t* child_build_logic(/* args */);

/* Destructor */
child_t* child_destroy(child_t *self);

Child Protected Header (src/include/protected_child.h)

#ifndef PROTECTED_CHILD_H
#define PROTECTED_CHILD_H

#include "child.h"
#include "protected_class.h"  /* Include parent's protected header */

struct _child_t {
    vtable_child_t vtable;
    /* ... child-specific members ... */
};

child_t* child_init_default(void);
child_t* child_init_logic(/* args */);

#endif

Child Implementation (src/child.c)

#include "child.h"
#include "protected_child.h"

static void _child_method_c_impl(const child_t *const self) {
    /* Implementation */
}

static const vtable_child_t child_default_vtable = {
    .super = class_default_vtable,      /* Use parent's default vtable */
    .method_c = _child_method_c_impl,
};

child_t* child_init_default(void) {
    child_t *self = malloc(sizeof(child_t));
    if (!self) return NULL;
    
    /* Assign child vtable (which includes parent vtable) */
    self->vtable = child_default_vtable;
    
    /* Initialize child-specific members */
    
    return self;
}

child_t* child_destroy(child_t *self) {
    if (!self) return NULL;
    /* Clean up child resources */
    free(self);
    return NULL;
}

void child_method_c(const child_t *const self) {
    return self->vtable.method_c(self);
}

Using Parent Methods from Child Code

When child code needs to call parent methods, cast and use the parent dispatcher:

/* In child implementation or user code */
child_t *obj = child_build_default();

/* Call parent method through explicit cast */
class_method_a((const class_t *const) obj);

/* Call child method */
child_method_c(obj);

obj = child_destroy(obj);

Note: Each class only provides dispatchers for its own methods. There are NO child dispatchers that call parent dispatchers—the programmer is responsible for explicit parent method calls via casting.

Method Visibility

Private Methods (Static)

  • Declared and defined in .c files only
  • Prefixed with _ (e.g., _class_method_impl)
  • Not visible outside the implementation file
  • Used as vtable function implementations

Protected Methods

  • Declared in src/include/protected_class.h
  • Prefixed with class name, no underscore (e.g., class_init_default)
  • Used by child classes and implementations
  • Constructors and initialization helpers typically protected

Public Methods

  • Declared in include/class.h
  • Dispatcher functions for vtable methods
  • User-facing constructors and destructors
  • The primary API of the class

Virtual Table Access

Virtual table members are NEVER accessed directly. Access is always through dispatcher functions:

/* WRONG - don't do this */
self->vtable.method_a(self);

/* RIGHT - always use dispatchers */
class_method_a(self);

This ensures:

  • Proper abstraction and encapsulation
  • Consistent method resolution
  • Easy to maintain and debug

Default Vtable Pattern

Each implementation file defines a static const vtable with default function pointers, avoiding manual vtable initialization in each constructor:

/* In src/class.c */
static const vtable_class_t class_default_vtable = {
    .method_a = _class_method_a_error,
    .method_b = _class_method_b_default,
};

Protected constructors then simply assign this default vtable to newly allocated instances:

class_t* class_init_default(void) {
    class_t *self = malloc(sizeof(class_t));
    if (!self) return NULL;
    
    self->vtable = class_default_vtable;  /* Assign default vtable */
    
    /* Initialize other members */
    
    return self;
}

This pattern:

  • Reduces code duplication across multiple constructors
  • Ensures vtable consistency across object instances
  • Simplifies maintenance of method implementations

Method Naming Conventions for Base Classes

Base classes should use specific naming conventions for default method implementations to indicate whether a method is abstract or has a default implementation:

Abstract Methods (No Implementation)

Abstract methods that must be overridden by child classes are named with _error suffix:

static void _class_method_a_error(const class_t *const self) {
    fprintf(stderr, "ERROR: method_a() must be specialized in a child class\n");
    assert(0);
}

static const vtable_class_t class_default_vtable = {
    .method_a = _class_method_a_error,
    .method_b = _class_method_b_default,
};

When an abstract method is called without being overridden, the error function prints a descriptive message and fails with assert(0).

Methods with Default Behavior

Methods that have a default implementation are named with _default suffix:

static void _class_method_b_default(const class_t *const self) {
    /* Default implementation */
}

static const vtable_class_t class_default_vtable = {
    .method_a = _class_method_a_error,
    .method_b = _class_method_b_default,
};

Child classes can override _class_method_b_default if they need specialized behavior, or inherit the default by reusing the parent's vtable entry.

Naming Summary:

  • class_method_error — Abstract method requiring specialization
  • class_method_default — Method with default implementation

Constructor/Destructor Conventions

Constructors

  • class_t* class_build_default(void) — Public default constructor

    • Typically a thin wrapper calling protected class_init_default()
    • May include validation before calling the protected method
  • class_t* class_build_logic(/* args */) — Public specialized constructor

    • For constructors with specific arguments
    • Typically wraps class_init_logic(/* args */)
  • class_t* class_init_default(void) — Protected default constructor

    • Contains actual construction logic
    • Allocation, vtable initialization, member setup
    • Called by public constructor or child classes
  • class_t* class_init_logic(/* args */) — Protected specialized constructor

    • Protected variant for child classes to reuse construction logic

Destructors

  • void class_destroy(class_t *self) — Public and protected
    • Returns void.
    • Cleans up resources and frees memory

Summary Checklist

  • Structure struct _class_t declared in protected_class.h
  • Typedef typedef struct _class_t class_t; in public class.h
  • Vtable typedef in public class.h
  • Vtable as first field of real structure
  • Dispatcher functions in public header and implementation
  • Private implementations as static functions with _ prefix
  • Protected methods (constructors) declared in protected header
  • Public API (dispatchers, public constructors/destructors) in public header
  • Child classes embed parent vtable as super field
  • No #include "protected_*.h" in any public header
  • Implementation files include both public and protected headers