# jhunt/research architecture

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

- Interactive diagram: https://gitdiagram.com/jhunt/research
- Repository: https://github.com/jhunt/research

## Overview

This is a collection of independent systems-programming research experiments, not one integrated application. The README highlights two workflows: use smaps experiments to inspect process memory through `/proc/$PID/smaps`, and stress software with a custom allocator. Other directories contain standalone data-structure, concurrency, parsing, cryptography, and runtime experiments. The smaps helper pauses for manual inspection; the README describes its monitoring and troubleshooting purpose. Several subsystems are represented by directory-level nodes because their source was not sampled; their internal connections are therefore omitted.

Main entry points: [`regm/asm.c`](https://github.com/jhunt/research/blob/master/regm/asm.c) (Assembler), [`smaps`](https://github.com/jhunt/research/tree/master/smaps) (Smaps experiments), [`smaps/lib.c`](https://github.com/jhunt/research/blob/master/smaps/lib.c) (Smaps helper), [`rcu/lock/main.c`](https://github.com/jhunt/research/blob/master/rcu/lock/main.c) (Locked RCU comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_memory["Memory research"]
  node_smaps_harness["Smaps experiments"]
  node_smaps_helper["Smaps helper<br/>[lib.c]"]
  node_proc_smaps["Process smaps"]
  node_malloc_stress["Allocator stress"]
end

subgraph group_systems["Systems experiments"]
  node_fuse_nullfs["Null filesystem<br/>[nullfs.c]"]
  node_rcu_lock["Locked RCU comparison<br/>[main.c]"]
  node_rcu_qs["Quiescent-state RCU<br/>[main.c]"]
  node_rcu_api["Thread and lock helpers<br/>[api.h]"]
end

subgraph group_language["Language tools"]
  node_lexer["BQL lexer<br/>[bql.ll.c]"]
  node_lexer_demo["Lexer driver<br/>[main.c]"]
  node_assembler["Assembler<br/>[asm.c]"]
  node_vm_runtime["Register VM runtime<br/>[regm.c]"]
  node_opcodes["Opcode definitions<br/>[opcodes.h]"]
end

subgraph group_libraries["Runtime libraries"]
  node_btree["B-tree<br/>[btree.c]"]
  node_btree_api["B-tree interface<br/>[btree.h]"]
  node_chash["Consistent hashing"]
  node_ring["String ring<br/>[ring.c]"]
  node_ring_api["Ring interface<br/>[ring.h]"]
  node_insist["Assertion macro<br/>[insist.h]"]
  node_insist_demo["Assertion example<br/>[main.c]"]
  node_nacl["NaCl crypto<br/>[tweetnacl.c]"]
  node_nacl_api["Crypto interface<br/>[tweetnacl.h]"]
end

node_user(("Researcher"))

node_user -->|"runs experiment"| node_smaps_harness
node_smaps_harness -.->|"uses helper"| node_smaps_helper
node_smaps_helper -->|"prompts inspection"| node_proc_smaps
node_user -->|"runs stress test"| node_malloc_stress
node_user -.->|"runs experiment"| node_fuse_nullfs
node_user -.->|"runs comparison"| node_rcu_lock
node_user -.->|"runs comparison"| node_rcu_qs
node_rcu_lock -->|"uses helpers"| node_rcu_api
node_rcu_qs -->|"uses helpers"| node_rcu_api
node_user -.->|"runs experiment"| node_btree
node_btree -->|"includes interface"| node_btree_api
node_user -.->|"runs experiment"| node_chash
node_user -.->|"runs experiment"| node_ring
node_ring -->|"implements interface"| node_ring_api
node_user -.->|"runs example"| node_insist_demo
node_insist_demo -->|"uses macro"| node_insist
node_user -.->|"runs lexer"| node_lexer_demo
node_lexer_demo -->|"calls lexer API"| node_lexer
node_user -.->|"assembles input"| node_assembler
node_assembler -->|"uses definitions"| node_opcodes
node_assembler -->|"shares VM definitions"| node_vm_runtime
node_user -.->|"uses crypto"| node_nacl
node_nacl -->|"implements API"| node_nacl_api

click node_smaps_harness "https://github.com/jhunt/research/tree/master/smaps"
click node_smaps_helper "https://github.com/jhunt/research/blob/master/smaps/lib.c"
click node_malloc_stress "https://github.com/jhunt/research/tree/master/malloc"
click node_fuse_nullfs "https://github.com/jhunt/research/blob/master/fuse/nullfs/nullfs.c"
click node_rcu_lock "https://github.com/jhunt/research/blob/master/rcu/lock/main.c"
click node_rcu_qs "https://github.com/jhunt/research/blob/master/rcu/qs/main.c"
click node_rcu_api "https://github.com/jhunt/research/blob/master/rcu/api.h"
click node_btree "https://github.com/jhunt/research/blob/master/btree/btree.c"
click node_btree_api "https://github.com/jhunt/research/blob/master/btree/btree.h"
click node_chash "https://github.com/jhunt/research/tree/master/chash"
click node_ring "https://github.com/jhunt/research/blob/master/ringer/ring.c"
click node_ring_api "https://github.com/jhunt/research/blob/master/ringer/ring.h"
click node_insist "https://github.com/jhunt/research/blob/master/insist/insist.h"
click node_insist_demo "https://github.com/jhunt/research/blob/master/insist/main.c"
click node_lexer "https://github.com/jhunt/research/blob/master/lexer-ll/bql.ll.c"
click node_lexer_demo "https://github.com/jhunt/research/blob/master/lexer-ll/main.c"
click node_assembler "https://github.com/jhunt/research/blob/master/regm/asm.c"
click node_vm_runtime "https://github.com/jhunt/research/blob/master/regm/regm.c"
click node_opcodes "https://github.com/jhunt/research/blob/master/regm/opcodes.h"
click node_nacl "https://github.com/jhunt/research/blob/master/nacl/tweetnacl.c"
click node_nacl_api "https://github.com/jhunt/research/blob/master/nacl/tweetnacl.h"

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_smaps_harness,node_smaps_helper,node_proc_smaps,node_malloc_stress toneBlue
class node_fuse_nullfs,node_rcu_lock,node_rcu_qs,node_rcu_api toneAmber
class node_lexer,node_lexer_demo,node_assembler,node_vm_runtime,node_opcodes toneMint
class node_btree,node_btree_api,node_chash,node_ring,node_ring_api,node_insist,node_insist_demo,node_nacl,node_nacl_api toneRose
class node_user toneIndigo
```

## Components

### Memory research

- [Smaps experiments](https://github.com/jhunt/research/tree/master/smaps): `smaps`
- [Smaps helper](https://github.com/jhunt/research/blob/master/smaps/lib.c): `smaps/lib.c`
- **Process smaps**
- [Allocator stress](https://github.com/jhunt/research/tree/master/malloc): `malloc`

### Systems experiments

- [Null filesystem](https://github.com/jhunt/research/blob/master/fuse/nullfs/nullfs.c): `fuse/nullfs/nullfs.c`
- [Locked RCU comparison](https://github.com/jhunt/research/blob/master/rcu/lock/main.c): `rcu/lock/main.c`
- [Quiescent-state RCU](https://github.com/jhunt/research/blob/master/rcu/qs/main.c): `rcu/qs/main.c`
- [Thread and lock helpers](https://github.com/jhunt/research/blob/master/rcu/api.h): `rcu/api.h`

### Language tools

- [BQL lexer](https://github.com/jhunt/research/blob/master/lexer-ll/bql.ll.c): `lexer-ll/bql.ll.c`
- [Lexer driver](https://github.com/jhunt/research/blob/master/lexer-ll/main.c): `lexer-ll/main.c`
- [Assembler](https://github.com/jhunt/research/blob/master/regm/asm.c): `regm/asm.c`
- [Register VM runtime](https://github.com/jhunt/research/blob/master/regm/regm.c): `regm/regm.c`
- [Opcode definitions](https://github.com/jhunt/research/blob/master/regm/opcodes.h): `regm/opcodes.h`

### Runtime libraries

- [B-tree](https://github.com/jhunt/research/blob/master/btree/btree.c): `btree/btree.c`
- [B-tree interface](https://github.com/jhunt/research/blob/master/btree/btree.h): `btree/btree.h`
- [Consistent hashing](https://github.com/jhunt/research/tree/master/chash): `chash`
- [String ring](https://github.com/jhunt/research/blob/master/ringer/ring.c): `ringer/ring.c`
- [Ring interface](https://github.com/jhunt/research/blob/master/ringer/ring.h): `ringer/ring.h`
- [Assertion macro](https://github.com/jhunt/research/blob/master/insist/insist.h): `insist/insist.h`
- [Assertion example](https://github.com/jhunt/research/blob/master/insist/main.c): `insist/main.c`
- [NaCl crypto](https://github.com/jhunt/research/blob/master/nacl/tweetnacl.c): `nacl/tweetnacl.c`
- [Crypto interface](https://github.com/jhunt/research/blob/master/nacl/tweetnacl.h): `nacl/tweetnacl.h`

### Other components

- **Researcher**

## Connections

- Researcher → Smaps experiments: runs experiment
- Smaps experiments → Smaps helper: uses helper (evidence: `smaps/mmap.c`)
- Smaps helper → Process smaps: prompts inspection (evidence: `smaps/lib.c`)
- Researcher → Allocator stress: runs stress test
- Researcher → Null filesystem: runs experiment
- Researcher → Locked RCU comparison: runs comparison
- Researcher → Quiescent-state RCU: runs comparison
- Locked RCU comparison → Thread and lock helpers: uses helpers (evidence: `rcu/lock/main.c`)
- Quiescent-state RCU → Thread and lock helpers: uses helpers (evidence: `rcu/qs/main.c`)
- Researcher → B-tree: runs experiment
- B-tree → B-tree interface: includes interface (evidence: `btree/btree.c`)
- Researcher → Consistent hashing: runs experiment
- Researcher → String ring: runs experiment
- String ring → Ring interface: implements interface (evidence: `ringer/ring.c`)
- Researcher → Assertion example: runs example
- Assertion example → Assertion macro: uses macro (evidence: `insist/main.c`)
- Researcher → Lexer driver: runs lexer
- Lexer driver → BQL lexer: calls lexer API (evidence: `lexer-ll/main.c`)
- Researcher → Assembler: assembles input
- Assembler → Opcode definitions: uses definitions (evidence: `regm/asm.c`)
- Assembler → Register VM runtime: shares VM definitions (evidence: `regm/asm.c`)
- Researcher → NaCl crypto: uses crypto
- NaCl crypto → Crypto interface: implements API (evidence: `nacl/tweetnacl.c`)
