Reachability Graph Visualization¶
Diagnostic visualization — instantiates Reachability-Guided Resource Reclamation
Renders the reference graph and its retention paths so a human can see what is keeping a resource alive and why it will not be reclaimed.
Reachability Graph Visualization turns the reference graph into something a person can look at. When resources are not being reclaimed, the question is never "is this reachable?" — the collector already knows the answer is yes — but "why, and by what path?" This mechanism answers that question visually: it draws the resources, the references between them, and the chains that tie a suspected-dead resource back to a live root, so an engineer can see the one edge that is keeping a whole subgraph alive. It decides nothing and frees nothing. It is a diagnostic instrument, and its entire purpose is to make an invisible retention structure legible so a human can find the edge to cut.
Example¶
A Java service's memory climbs steadily over days until it approaches its heap limit — a classic leak, but the code offers no clue where. An engineer captures a heap dump and opens it in the Eclipse Memory Analyzer (MAT). The dominator tree immediately ranks what is holding the most memory: one HashMap is retaining 400 MB. Selecting it and asking for the path to GC roots draws the retention chain — the map is held by a static field on a cache class, which is held directly by the class loader, an unbreakable root. Now the leak is obvious in a way it never was in the source: entries are being put into a static cache and never evicted, so nothing they transitively hold can ever be reclaimed. The picture did not free a single byte; it showed the engineer exactly which reference to sever. The dominator relationship is what makes the retained-size ranking meaningful.[n1]
How it works¶
From a snapshot of the reference graph it constructs a navigable view. It computes each resource's retained set — everything that would become unreachable if that resource were removed — and organizes resources into a dominator tree so the biggest retainers surface first. For any chosen resource it renders the shortest path to the roots, the concrete chain that explains why it is still live. It flags accumulation points where retained size is disproportionate. Every operation is read-only: it reports reachability and retention; it never alters the graph or reclaims anything.
Tuning parameters¶
- Aggregation level — group resources by type, by module, or by dominator. Coarser grouping tames a huge graph; finer grouping pinpoints the individual retainer.
- Retained vs. shallow size — rank by the memory a resource holds exclusively or only by its own footprint. Retained size finds true leaks; shallow size can mislead toward large-but-shared objects.
- Path filtering — whether to hide non-owning (weak/soft) edges when tracing retention, so the paths shown are the ones that actually pin the resource.
- Snapshot vs. live view — a single dump is cheap and stable but static; sampling over time reveals growth dynamics at higher cost.
When it helps, and when it misleads¶
Its strength is comprehension: it converts an abstract "we have a leak" into a specific retention path a human can act on, and it ranks suspects by how much they actually hold. It misleads in three ways. A snapshot is one instant — it can miss transient spikes or the rate of growth that a single frame cannot show. Large graphs degrade into an unreadable hairball unless aggressively aggregated. And most importantly, it explains retention but never decides or performs reclamation — mistaking the diagram for the remedy leaves the leak in place. The classic misuse is admiring the picture, identifying the retaining edge, and never shipping the code change that cuts it. The guarding discipline is to treat the visualization as a pointer to a fix, close the loop by removing the retaining reference, and confirm with a later snapshot.
How it implements the components¶
reference_and_dependency_graph— the graph of resources and their references is its subject matter, rendered legible rather than left implicit.reachable_closure_record— it visualizes reachability directly: which resources are live and, crucially, by what path back to the roots.leak_and_retention_monitor— it highlights accumulation points and outsized retained sizes, the visual signature of a leak.
It maintains no candidate_reclamation_set and enacts no reclamation_policy — it never selects or frees resources; producing an approvable delete-list is dry_run_reclamation_report's, and actually freeing is reference_counting's.
Against its nearest twin dry_run_reclamation_report: this mechanism is for open-ended exploration of retention structure and emits no delete-list; that one emits a concrete, approvable manifest of what would be reclaimed and a rollback record.
Related¶
- Instantiates: Reachability-Guided Resource Reclamation — supplies the human-facing diagnostic that explains why resources are retained.
- Consumes: tracing_mark_sweep_cycle — it renders the reachability and retention that mechanism's trace computes.
- Sibling mechanisms: reference_counting · generational_collection · concurrent_collection_barrier · cycle_detection_pass · dry_run_reclamation_report · lease_expiry_sweep · tombstone_then_delete · weak_reference_registry
Editorial Notes¶
Form Classification¶
Form family: Analysis, Modeling & Optimization
Rationale: Reachability Graph Visualization operates by computes retained sets, dominators, and shortest paths from a graph snapshot. That concrete deployed or enacted form is Analysis, Modeling & Optimization under the frozen taxonomy.
Nearest alternative: Interface, Display & Cue — Although Interface, Display & Cue can support this mechanism, the frozen evidence makes its operative form the act that computes retained sets, dominators, and shortest paths from a graph snapshot; the alternative is therefore secondary rather than defining.
Review outcome: Adjudicated after independent review; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Reference graphs and garbage-collector reachability are native software-systems concepts.
Review outcome: Independent reviewer agreement; high confidence.
Notes¶
[n1] A dominator tree — resource A dominates B when every path from a root to B passes through A, so A's retained size is everything it exclusively keeps alive. Ranking by dominator retained size is what lets a heap analyzer point straight at the object whose removal would free the most. ↩