# dcompiler/loca architecture

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

- Interactive diagram: https://gitdiagram.com/dcompiler/loca
- Repository: https://github.com/dcompiler/loca

## Overview

loca is a collection of program-locality profiling and cache-policy analysis tools, with a Ruby web interface for browsing and plotting results. A likely workflow is to profile a program, analyze reference traces or simulate replacement policies, then inspect generated data; only parts of that wiring are visible in the sampled source, so uncertain handoffs are omitted.

Main entry points: [`gem/lib/src/Footprint/dual_fp_all.cpp`](https://github.com/dcompiler/loca/blob/master/gem/lib/src/Footprint/dual_fp_all.cpp) (Footprint profiler), [`policies/ForwardOPTStackDistanceAnalyzer/OPTStackDistanceAnalyzer.c`](https://github.com/dcompiler/loca/blob/master/policies/ForwardOPTStackDistanceAnalyzer/OPTStackDistanceAnalyzer.c) (OPT distance analyzer), [`policies/lru/lru.py`](https://github.com/dcompiler/loca/blob/master/policies/lru/lru.py) (LRU simulator), [`policies/2q/2q.py`](https://github.com/dcompiler/loca/blob/master/policies/2q/2q.py) (2Q simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_profiling["Profiling"]
  node_footprint["Footprint profiler<br/>[dual_fp_all.cpp]"]
  node_histogram["Footprint histogram<br/>[histo.H]"]
  node_footprint_variants["Footprint variants"]
end

subgraph group_analysis["Trace Analysis"]
  node_opt["OPT distance analyzer"]
  node_opt_tools["OPT trace tools"]
end

subgraph group_simulation["Cache Simulation"]
  node_lru["LRU simulator<br/>[lru.py]"]
  node_twoq["2Q simulator<br/>[2q.py]"]
  node_lfu["LFU simulator<br/>[lfu.py]"]
  node_arc["ARC simulator<br/>[arc.py]"]
  node_lirs["LIRS simulator<br/>[lirs.c]"]
  node_lease["Lease policy<br/>[lease_lru.c]"]
end

subgraph group_presentation["Results Interface"]
  node_server["Result browser<br/>[server.rb]"]
  node_plot["Plot generation<br/>[plot.rb]"]
  node_plot_p["Plot generation<br/>[plot_p.rb]"]
end

node_program(("Target program"))
node_pin{{"Pin runtime"}}
node_trace["Reference trace"]
node_results["Analysis results"]
node_user(("Analyst"))

node_program -.->|"executes under"| node_pin
node_pin -->|"instruments"| node_footprint
node_footprint -->|"updates counts"| node_histogram
node_footprint -->|"writes profile"| node_results
node_trace -->|"reads trace"| node_opt
node_opt_tools -.->|"prepares inputs"| node_opt
node_opt -->|"writes distances"| node_results
node_trace -->|"reads trace"| node_lru
node_trace -->|"reads trace"| node_twoq
node_trace -->|"reads trace"| node_lfu
node_trace -->|"reads trace"| node_arc
node_trace -->|"reads trace"| node_lirs
node_lru -->|"writes MRC"| node_results
node_twoq -->|"writes MRC"| node_results
node_lfu -->|"writes MRC"| node_results
node_server -->|"browses files"| node_results
node_user -->|"requests results"| node_server
node_plot -.->|"plots data"| node_results
node_plot_p -.->|"plots data"| node_results

click node_footprint "https://github.com/dcompiler/loca/blob/master/gem/lib/src/Footprint/dual_fp_all.cpp"
click node_histogram "https://github.com/dcompiler/loca/blob/master/gem/lib/src/Footprint/histo.H"
click node_footprint_variants "https://github.com/dcompiler/loca/tree/master/gem/lib/src/Footprint"
click node_opt "https://github.com/dcompiler/loca/blob/master/policies/ForwardOPTStackDistanceAnalyzer/OPTStackDistanceAnalyzer.c"
click node_opt_tools "https://github.com/dcompiler/loca/tree/master/policies/ForwardOPTStackDistanceAnalyzer"
click node_lru "https://github.com/dcompiler/loca/blob/master/policies/lru/lru.py"
click node_twoq "https://github.com/dcompiler/loca/blob/master/policies/2q/2q.py"
click node_lfu "https://github.com/dcompiler/loca/blob/master/policies/lfu/lfu.py"
click node_arc "https://github.com/dcompiler/loca/blob/master/policies/arc/arc.py"
click node_lirs "https://github.com/dcompiler/loca/blob/master/policies/lirs/lirs/lirs.c"
click node_lease "https://github.com/dcompiler/loca/blob/master/policies/lc/lc_with_item_size/lease_lru.c"
click node_server "https://github.com/dcompiler/loca/blob/master/server/server.rb"
click node_plot "https://github.com/dcompiler/loca/blob/master/server/plot.rb"
click node_plot_p "https://github.com/dcompiler/loca/blob/master/server/plot_p.rb"

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_footprint,node_histogram,node_footprint_variants toneBlue
class node_opt,node_opt_tools toneAmber
class node_lru,node_twoq,node_lfu,node_arc,node_lirs,node_lease toneMint
class node_server,node_plot,node_plot_p toneRose
class node_program,node_pin,node_trace,node_results,node_user toneIndigo
```

## Components

### Profiling

- [Footprint profiler](https://github.com/dcompiler/loca/blob/master/gem/lib/src/Footprint/dual_fp_all.cpp): `gem/lib/src/Footprint/dual_fp_all.cpp`
- [Footprint histogram](https://github.com/dcompiler/loca/blob/master/gem/lib/src/Footprint/histo.H): `gem/lib/src/Footprint/histo.H`
- [Footprint variants](https://github.com/dcompiler/loca/tree/master/gem/lib/src/Footprint): `gem/lib/src/Footprint`

### Trace Analysis

- [OPT distance analyzer](https://github.com/dcompiler/loca/blob/master/policies/ForwardOPTStackDistanceAnalyzer/OPTStackDistanceAnalyzer.c): `policies/ForwardOPTStackDistanceAnalyzer/OPTStackDistanceAnalyzer.c`
- [OPT trace tools](https://github.com/dcompiler/loca/tree/master/policies/ForwardOPTStackDistanceAnalyzer): `policies/ForwardOPTStackDistanceAnalyzer`

### Cache Simulation

- [LRU simulator](https://github.com/dcompiler/loca/blob/master/policies/lru/lru.py): `policies/lru/lru.py`
- [2Q simulator](https://github.com/dcompiler/loca/blob/master/policies/2q/2q.py): `policies/2q/2q.py`
- [LFU simulator](https://github.com/dcompiler/loca/blob/master/policies/lfu/lfu.py): `policies/lfu/lfu.py`
- [ARC simulator](https://github.com/dcompiler/loca/blob/master/policies/arc/arc.py): `policies/arc/arc.py`
- [LIRS simulator](https://github.com/dcompiler/loca/blob/master/policies/lirs/lirs/lirs.c): `policies/lirs/lirs/lirs.c`
- [Lease policy](https://github.com/dcompiler/loca/blob/master/policies/lc/lc_with_item_size/lease_lru.c): `policies/lc/lc_with_item_size/lease_lru.c`

### Results Interface

- [Result browser](https://github.com/dcompiler/loca/blob/master/server/server.rb): `server/server.rb`
- [Plot generation](https://github.com/dcompiler/loca/blob/master/server/plot.rb): `server/plot.rb`
- [Plot generation](https://github.com/dcompiler/loca/blob/master/server/plot_p.rb): `server/plot_p.rb`

### Other components

- **Target program**
- **Pin runtime**
- **Reference trace**
- **Analysis results**
- **Analyst**

## Connections

- Target program → Pin runtime: executes under
- Pin runtime → Footprint profiler: instruments
- Footprint profiler → Footprint histogram: updates counts
- Footprint profiler → Analysis results: writes profile
- Reference trace → OPT distance analyzer: reads trace
- OPT trace tools → OPT distance analyzer: prepares inputs
- OPT distance analyzer → Analysis results: writes distances
- Reference trace → LRU simulator: reads trace
- Reference trace → 2Q simulator: reads trace
- Reference trace → LFU simulator: reads trace
- Reference trace → ARC simulator: reads trace
- Reference trace → LIRS simulator: reads trace
- LRU simulator → Analysis results: writes MRC
- 2Q simulator → Analysis results: writes MRC
- LFU simulator → Analysis results: writes MRC
- Result browser → Analysis results: browses files
- Analyst → Result browser: requests results
- Plot generation → Analysis results: plots data
- Plot generation → Analysis results: plots data