397 lines
11 KiB
Markdown
397 lines
11 KiB
Markdown
# 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
|