# ggaisenn/ggalloc architecture

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

- Interactive diagram: https://gitdiagram.com/ggaisenn/ggalloc
- Repository: https://github.com/ggaisenn/ggalloc

## Overview

ggalloc is a C/C++-compatible custom heap allocator with manual freeing and stack-scanning mark-and-sweep collection. Its user workflow requests a payload, reuses or grows the linked heap, then releases memory manually or through a GC cycle. The README documents first-fit allocation, splitting, coalescing, corruption checks and POSIX sbrk integration. Edges reflect explicit README statements or sampled allocator calls; the GC’s internal sweep details are partly unsampled.

Main entry points: [`allocator.h`](https://github.com/ggaisenn/ggalloc/blob/main/allocator.h) (Metadata Blocks), [`allocator.cpp`](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp) (ggalloc), [`main_demo.cpp`](https://github.com/ggaisenn/ggalloc/blob/main/main_demo.cpp) (Allocator Demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_allocation["Heap Allocation"]
  node_api["Allocator API<br/>[allocator.h]"]
  node_allocator["ggalloc<br/>[allocator.cpp]"]
  node_freeapi["ggfree<br/>[allocator.cpp]"]
end

subgraph group_memory["Heap Management"]
  node_firstfit["First-Fit Search<br/>[allocator.cpp]"]
  node_split["Block Splitting<br/>[allocator.cpp]"]
  node_request["Heap Growth<br/>[allocator.cpp]"]
  node_blocks[("Metadata Blocks<br/>[allocator.h]")]
  node_coalesce["Coalescing<br/>[allocator.cpp]"]
  node_valid["Heap Bounds Check<br/>[allocator.cpp]"]
end

subgraph group_gc["Garbage Collection"]
  node_gcapi["gggc<br/>[allocator.cpp]"]
  node_mark["Mark Phase<br/>[allocator.cpp]"]
  node_sweep["Sweep Phase<br/>[allocator.cpp]"]
end

node_caller(("C/C++ Caller"))
node_os["POSIX sbrk"]
node_stack[("Thread Stack")]
node_demo["Allocator Demo<br/>[main_demo.cpp]"]

node_caller -->|"calls"| node_api
node_api -->|"exposes"| node_allocator
node_allocator -->|"searches"| node_firstfit
node_firstfit -->|"scans"| node_blocks
node_firstfit -->|"splits"| node_split
node_allocator -->|"requests"| node_request
node_request -->|"grows break"| node_os
node_request -->|"links block"| node_blocks
node_allocator -->|"returns payload"| node_blocks
node_caller -->|"calls"| node_freeapi
node_freeapi -->|"validates"| node_valid
node_freeapi -->|"coalesces"| node_coalesce
node_coalesce -->|"merges neighbors"| node_blocks
node_caller -->|"runs cycle"| node_gcapi
node_gcapi -->|"runs mark"| node_mark
node_mark -->|"scans roots"| node_stack
node_mark -->|"checks pointers"| node_valid
node_mark -->|"marks reachable"| node_blocks
node_gcapi -->|"runs sweep"| node_sweep
node_sweep -->|"reclaims blocks"| node_blocks
node_sweep -->|"coalesces"| node_coalesce
node_demo -->|"uses"| node_api

click node_api "https://github.com/ggaisenn/ggalloc/blob/main/allocator.h"
click node_allocator "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_firstfit "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_split "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_request "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_blocks "https://github.com/ggaisenn/ggalloc/blob/main/allocator.h"
click node_freeapi "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_coalesce "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_valid "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_gcapi "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_mark "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_sweep "https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp"
click node_demo "https://github.com/ggaisenn/ggalloc/blob/main/main_demo.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_allocator,node_freeapi toneBlue
class node_firstfit,node_split,node_request,node_blocks,node_coalesce,node_valid,node_stack toneAmber
class node_gcapi,node_mark,node_sweep toneMint
class node_caller,node_os toneIndigo
class node_demo toneTeal
```

## Components

### Heap Allocation

- [Allocator API](https://github.com/ggaisenn/ggalloc/blob/main/allocator.h): `allocator.h`
- [ggalloc](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`
- [ggfree](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`

### Heap Management

- [First-Fit Search](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`
- [Block Splitting](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`
- [Heap Growth](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`
- [Metadata Blocks](https://github.com/ggaisenn/ggalloc/blob/main/allocator.h): `allocator.h`
- [Coalescing](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`
- [Heap Bounds Check](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`

### Garbage Collection

- [gggc](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`
- [Mark Phase](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`
- [Sweep Phase](https://github.com/ggaisenn/ggalloc/blob/main/allocator.cpp): `allocator.cpp`

### Other components

- **C/C++ Caller**
- **POSIX sbrk**
- **Thread Stack**
- [Allocator Demo](https://github.com/ggaisenn/ggalloc/blob/main/main_demo.cpp): `main_demo.cpp`

## Connections

- C/C++ Caller → Allocator API: calls (evidence: `allocator.h`)
- Allocator API → ggalloc: exposes (evidence: `allocator.h`)
- ggalloc → First-Fit Search: searches (evidence: `allocator.cpp`)
- First-Fit Search → Metadata Blocks: scans (evidence: `allocator.cpp`)
- First-Fit Search → Block Splitting: splits (evidence: `allocator.cpp`)
- ggalloc → Heap Growth: requests (evidence: `allocator.cpp`)
- Heap Growth → POSIX sbrk: grows break (evidence: `allocator.cpp`)
- Heap Growth → Metadata Blocks: links block (evidence: `allocator.cpp`)
- ggalloc → Metadata Blocks: returns payload (evidence: `allocator.cpp`)
- C/C++ Caller → ggfree: calls
- ggfree → Heap Bounds Check: validates (evidence: `allocator.cpp`)
- ggfree → Coalescing: coalesces (evidence: `allocator.cpp`)
- Coalescing → Metadata Blocks: merges neighbors (evidence: `allocator.cpp`)
- C/C++ Caller → gggc: runs cycle
- gggc → Mark Phase: runs mark (evidence: `allocator.cpp`)
- Mark Phase → Thread Stack: scans roots (evidence: `allocator.cpp`)
- Mark Phase → Heap Bounds Check: checks pointers (evidence: `allocator.cpp`)
- Mark Phase → Metadata Blocks: marks reachable (evidence: `allocator.cpp`)
- gggc → Sweep Phase: runs sweep (evidence: `allocator.cpp`)
- Sweep Phase → Metadata Blocks: reclaims blocks (evidence: `allocator.cpp`)
- Sweep Phase → Coalescing: coalesces (evidence: `allocator.cpp`)
- Allocator Demo → Allocator API: uses (evidence: `main_demo.cpp`)
