# 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`) ```c /* 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`) ```c #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`) ```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`) ```c 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`) ```c #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`) ```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: ```c /* 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: ```c /* 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: ```c /* 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: ```c 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: ```c 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: ```c 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