# sdogruyol/gcry architecture

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

- Interactive diagram: https://gitdiagram.com/sdogruyol/gcry
- Repository: https://github.com/sdogruyol/gcry

## Overview

gcry is a Crystal-native, shard-delivered conservative mark–sweep garbage collector that replaces Boehm when an application is built with `-Dgc_none`. The documented runtime workflow routes Crystal allocation through gcry’s GC interface, tracks heap objects and roots, marks reachable objects during stop-the-world collection, then sweeps and releases unused memory. The README also documents platform support, optional precise-layout research mode, and built-in metrics. The supplied source excerpts mainly identify override, raw-output, scan, and stop-the-world modules; internal call wiring beyond the documented workflow is therefore kept intentionally broad.

Main entry points: [`src/gcry/stw_slots.cr`](https://github.com/sdogruyol/gcry/blob/master/src/gcry/stw_slots.cr) (Stop World), [`src/gcry/gc_override.cr`](https://github.com/sdogruyol/gcry/blob/master/src/gcry/gc_override.cr) (GC Override), [`src/gcry`](https://github.com/sdogruyol/gcry/tree/master/src/gcry) (Root Scanning), [`src/gcry/collect_scan.cr`](https://github.com/sdogruyol/gcry/blob/master/src/gcry/collect_scan.cr) (Collection Scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["GC Runtime"]
  node_gc_api["GC Override<br/>[gc_override.cr]"]
  node_heap["Heap Allocator"]
  node_layout["Object Layout"]
end

subgraph group_collection["Collection"]
  node_root_scan["Root Scanning"]
  node_stw["Stop World<br/>[stw_slots.cr]"]
  node_mark["Mark Phase"]
  node_sweep["Sweep Phase"]
  node_scan_impl["Collection Scan<br/>[collect_scan.cr]"]
  node_stack_maps["Precise Stack Maps"]
end

subgraph group_platforms["Platform Support"]
  node_linux["Linux Support<br/>[linux_stw.cr]"]
  node_darwin["Darwin Support<br/>[darwin_stw.cr]"]
  node_windows["Windows Support<br/>[windows_stw.cr]"]
end

subgraph group_observability["Metrics"]
  node_metrics["GC Metrics"]
  node_prometheus["Prometheus Export"]
end

node_app(("Crystal Application"))

node_app -->|"allocates through"| node_gc_api
node_gc_api -->|"routes allocation"| node_heap
node_heap -->|"uses layout"| node_layout
node_gc_api -->|"triggers collection"| node_stw
node_stw -->|"coordinates scanning"| node_root_scan
node_root_scan -->|"scans roots"| node_scan_impl
node_scan_impl -->|"marks reachable"| node_mark
node_mark -->|"hands off marks"| node_sweep
node_sweep -->|"reclaims blocks"| node_heap
node_stw -->|"platform control"| node_linux
node_stw -->|"platform control"| node_darwin
node_stw -->|"platform control"| node_windows
node_gc_api -->|"records activity"| node_metrics
node_metrics -->|"exports metrics"| node_prometheus
node_root_scan -.->|"optional precision"| node_stack_maps

click node_gc_api "https://github.com/sdogruyol/gcry/blob/master/src/gcry/gc_override.cr"
click node_heap "https://github.com/sdogruyol/gcry/tree/master/src/gcry"
click node_layout "https://github.com/sdogruyol/gcry/tree/master/src/gcry"
click node_root_scan "https://github.com/sdogruyol/gcry/tree/master/src/gcry"
click node_stw "https://github.com/sdogruyol/gcry/blob/master/src/gcry/stw_slots.cr"
click node_mark "https://github.com/sdogruyol/gcry/tree/master/src/gcry"
click node_sweep "https://github.com/sdogruyol/gcry/tree/master/src/gcry"
click node_scan_impl "https://github.com/sdogruyol/gcry/blob/master/src/gcry/collect_scan.cr"
click node_linux "https://github.com/sdogruyol/gcry/blob/master/src/gcry/platform/linux_stw.cr"
click node_darwin "https://github.com/sdogruyol/gcry/blob/master/src/gcry/platform/darwin_stw.cr"
click node_windows "https://github.com/sdogruyol/gcry/blob/master/src/gcry/platform/windows_stw.cr"
click node_metrics "https://github.com/sdogruyol/gcry/tree/master/src/gcry"
click node_prometheus "https://github.com/sdogruyol/gcry/tree/master/src/gcry"
click node_stack_maps "https://github.com/sdogruyol/gcry/tree/master/src/gcry"

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_gc_api,node_heap,node_layout toneBlue
class node_root_scan,node_stw,node_mark,node_sweep,node_scan_impl,node_stack_maps toneAmber
class node_linux,node_darwin,node_windows toneMint
class node_metrics,node_prometheus toneRose
class node_app toneIndigo
```

## Components

### GC Runtime

- [GC Override](https://github.com/sdogruyol/gcry/blob/master/src/gcry/gc_override.cr): `src/gcry/gc_override.cr`
- [Heap Allocator](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`
- [Object Layout](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`

### Collection

- [Root Scanning](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`
- [Stop World](https://github.com/sdogruyol/gcry/blob/master/src/gcry/stw_slots.cr): `src/gcry/stw_slots.cr`
- [Mark Phase](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`
- [Sweep Phase](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`
- [Collection Scan](https://github.com/sdogruyol/gcry/blob/master/src/gcry/collect_scan.cr): `src/gcry/collect_scan.cr`
- [Precise Stack Maps](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`

### Platform Support

- [Linux Support](https://github.com/sdogruyol/gcry/blob/master/src/gcry/platform/linux_stw.cr): `src/gcry/platform/linux_stw.cr`
- [Darwin Support](https://github.com/sdogruyol/gcry/blob/master/src/gcry/platform/darwin_stw.cr): `src/gcry/platform/darwin_stw.cr`
- [Windows Support](https://github.com/sdogruyol/gcry/blob/master/src/gcry/platform/windows_stw.cr): `src/gcry/platform/windows_stw.cr`

### Metrics

- [GC Metrics](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`
- [Prometheus Export](https://github.com/sdogruyol/gcry/tree/master/src/gcry): `src/gcry`

### Other components

- **Crystal Application**

## Connections

- Crystal Application → GC Override: allocates through
- GC Override → Heap Allocator: routes allocation
- Heap Allocator → Object Layout: uses layout
- GC Override → Stop World: triggers collection
- Stop World → Root Scanning: coordinates scanning
- Root Scanning → Collection Scan: scans roots
- Collection Scan → Mark Phase: marks reachable
- Mark Phase → Sweep Phase: hands off marks
- Sweep Phase → Heap Allocator: reclaims blocks
- Stop World → Linux Support: platform control
- Stop World → Darwin Support: platform control
- Stop World → Windows Support: platform control
- GC Override → GC Metrics: records activity
- GC Metrics → Prometheus Export: exports metrics
- Root Scanning → Precise Stack Maps: optional precision