# hamzahat/c_garbage_collector architecture

> Architecture diagram of the GitHub repository hamzahat/c_garbage_collector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamzahat/c_garbage_collector
- Repository: https://github.com/hamzahat/c_garbage_collector

## Overview

##### Project Type and Purpose
- Type: A C library providing a “safe” malloc/free wrapper–style garbage collector.
- Purpose:
– Track all memory allocations at runtime
– Offer three operations: ALLOCATE, FREE_ONE, FREE_ALL
– Automatically free leaked or untracked memory on failure or on demand

##### File Structure
- Top-level:
– ft_safe_malloc.c → contains implementation of:
· Internal tracker (likely a linked list or array of pointers)
· The `ft_safe_malloc()` API handling three keys
– README.md → describes usage, macro keys, and behavior
- No external configs, no frontend/backend split—this is purely a library component.

##### Core Components
1) Client Code
– Any C application that calls `ft_safe_malloc()` or `malloc()` directly.
2) ft_safe_malloc API Layer
– Exposed function: `void *ft_safe_malloc(size_t size, int key, int exit_status, void *to_delete);`
– Macro keys: ALLOCATE, FREE_ONE, FREE_ALL
3) Internal Tracker (Data Structure)
– Stores every successfully allocated pointer
– Supports insertion, lookup, deletion
4) Underlying Memory Allocator
– Standard `malloc()` and `free()` from `<stdlib.h>`
5) Exit Handler
– Invoked when allocation fails or when FREE_ALL is called with exit status

##### Relationships & Data Flow
- Client → ft_safe_malloc (API)
– Calls with key=ALLOCATE: API forwards to Underlying Allocator, then records pointer in Tracker
– Calls with key=FREE_ONE: API looks up pointer (if tracked), calls free(), removes from Tracker; if untracked, still calls free()
– Calls with key=FREE_ALL: API iterates Tracker, free() each pointer, optionally calls `exit(exit_status)`
- ft_safe_malloc (API) → Internal Tracker
– Insert/Delete/Iterate operations
- ft_safe_malloc (API) → Underlying Memory Allocator
– malloc(size) and free(ptr)

##### Architectural Patterns & Principles
- Wrapper Pattern: Encapsulates raw `malloc`/`free` calls in a safe API
- RAII-inspired Resource Tracking (though in C)
- Single Responsibility:
– API function orchestrates operations
– Tracker manages data structure
- Fail-Fast Strategy: On allocation failure, free all and exit

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (C Application)"]:::client

    subgraph "ft_safe_malloc Library"
        API["API Layer: ft_safe_malloc()"]:::api
        Tracker["Tracker (Data Store)"]:::data
        ExitHandler["Exit Handler"]:::external
    end

    Stdlib["stdlib malloc()/free()"]:::stdlib

    %% Flow for ALLOCATE
    Client -->|"ft_safe_malloc(key=ALLOCATE)"| API
    API -->|"malloc(size)→ptr"| Stdlib
    Stdlib -->|"ptr returned"| API
    API -->|"insert(ptr)"| Tracker
    API -->|"return ptr"| Client

    %% Flow for FREE_ONE
    Client -->|"ft_safe_malloc(key=FREE_ONE, to_delete)"| API
    API -->|"lookup(ptr)"| Tracker
    API -->|"free(ptr)"| Stdlib
    API -->|"delete(ptr)"| Tracker

    %% Flow for FREE_ALL
    Client -->|"ft_safe_malloc(key=FREE_ALL, exit_status)"| API
    API -->|"iterate & free all"| Tracker
    Tracker -->|"free(ptr)"| Stdlib
    API -->|"exit(status)"| ExitHandler

    %% Legend
    subgraph "Legend"
        L1["Macro Keys: ALLOCATE, FREE_ONE, FREE_ALL"]
        L2["Fail-Fast: FREE_ALL triggers exit(status)"]
    end

    %% Click Events
    click API "https://github.com/hamzahat/c_garbage_collector/blob/main/ft_safe_malloc.c"
    click Tracker "https://github.com/hamzahat/c_garbage_collector/blob/main/ft_safe_malloc.c"
    click ExitHandler "https://github.com/hamzahat/c_garbage_collector/blob/main/ft_safe_malloc.c"
    click L1 "https://github.com/hamzahat/c_garbage_collector/blob/main/README.md"

    %% Styles
    classDef client fill:#FFA500,stroke:#333,color:#000
    classDef api fill:#ADD8E6,stroke:#333,color:#000
    classDef data fill:#90EE90,stroke:#333,color:#000
    classDef stdlib fill:#D3D3D3,stroke:#333,color:#000
    classDef external fill:#D3D3D3,stroke:#333,color:#000
    class Client client
    class API api
    class Tracker data
    class Stdlib stdlib
    class ExitHandler external
    class L1,L2 external
```
