Haskell Inspector

HEQL standard library

Generated from commit e8a491d6e1e2.

The HEQL standard library, rendered from the one table the typechecker and evaluator are built from — so this reference cannot drift from the language it describes.

Grade legend — C0 constant · Cr roots · Cn node pass · Ce edge pass · Cp pass × bounded path search · C? super-linear. The {caps} are the engine capabilities a name needs; entries marked (not yet supported) typecheck but fail at evaluation on this backend.

#Sources & constants

Name Type Grade Description
heap Bag Node Cn Every live closure in the snapshot.
allocated Bag Node Ce {blocks} Every closure a linear block scan finds: the reachable heap plus floating garbage (dead-but-not-yet-collected). A node's rooted field separates them; [c | c <- allocated, not c.rooted] is the garbage. Needs a connector that ships block frontiers.
edges Bag Edge Ce {reverse-graph} Every pointer field of every closure, as src -> tgt edges.
roots Bag Root Cr {roots} The GC roots, each with its node and kind.
rootNodes Set Node Cr {roots} The GC root set as a node set: the roots' closures, ready to seed reachable (the prelude's aliveVia/rootsOf are built on it).
snapshots Seq Snapshot C0 {snapshots} (not yet supported) All loaded snapshots, for multi-snapshot queries (heap @ s).
blocks Bag Block Cn {blocks} Every heap block (4 KiB; a large object's block group is one row): live bytes, object count, occupancy, pinnedness — the fragmentation census.
totalHeapBytes Q B C0 Total shallow bytes in the snapshot (the sum of all .self).
maxEra Era C0 {eras} The newest allocation era in the snapshot.
eraBack Q 1 -> Era C0 {eras} The era n steps before maxEra (clamped to the snapshot's range).

#Path steps

Name Type Grade Description
ptr RPQ C0 {reverse-graph} One pointer edge, source to target.
strong RPQ C0 {reverse-graph} ptr minus weak-reference fields: what the GC actually retains.
dom RPQ C0 {dominators} One dominator-tree child edge.

#Node predicates

Name Type Grade Description
ratio Node -> Q 1 C0 reads {Node.retained, Node.self} Amplification factor: retained / self.

#Dominator structure

Name Type Grade Description
children Node -> Bag Node C0 {dominators} Immediate dominator-tree children: what this node alone keeps alive, one level down.
domParent Node -> Maybe Node C0 {dominators} The immediate dominator, if any.
dominated Node -> Set Node C0 {dominators} Everything this node exclusively keeps alive (its dominator subtree).

#Pointer structure

Name Type Grade Description
outEdges Node -> Bag Edge C0 {reverse-graph} This node's outgoing pointer edges (works on garbage nodes too).

#Reachability & paths

Name Type Grade Description
reachable RPQ -> Set Node -> Set Node Cp {paths, reverse-graph} Everything reachable from the start set along a path matching the RPQ.
witness RPQ -> Node -> Node -> Maybe Path Cp {paths, reverse-graph} One shortest path between two nodes matching the RPQ, as evidence.
dist RPQ -> Set Node -> Node -> Maybe (Q 1) Cp {paths, reverse-graph} Shortest r-path length (edge count) from the seed set to the node; Nothing when unreachable.
cyclic RPQ -> Set Node Cp {paths, reverse-graph} The nodes on some cycle matching the step (linear Tarjan; the kernel behind the self-arrow guard c -[r]-> c).
scc RPQ -> Bag (Set Node) Cp {paths, reverse-graph} The nontrivial strongly connected components of the step graph — a partition, ordered by each component's smallest node.
chains RPQ -> (Node -> Bool) -> Bag Path Cp {dominators, paths} Maximal deterministic runs of matching nodes: thunk chains, list spines.
paths RPQ -> Set Node -> Set Node -> Q 1 -> Q 1 -> Seq Path Cp {paths, reverse-graph} Up to maxPaths shortest witness paths from the seed set along the RPQ to any node of the dst set, each at most maxDepth nodes, seed first (paths /rpq/ seeds dsts maxPaths maxDepth). A display sample, not a search: quantifying over it can miss paths — use reachable/aliveVia for exact path-containment. The prelude's retainerPaths/retainerPathsWith are paths /(~ptr)*/ target rootNodes.
reachWorlds RPQ -> Bag a -> Bag (Node, Mask a) -> (Node -> Mask a) -> Bag (a, Set Node) Cp {paths, reverse-graph, roots} Multi-world reachability (reachWorlds /rpq/ cands seeds pass): one row per DISTINCT candidate key with that world's ALIVE set — the least fixpoint of alive[v] = seed[v] ∪ (alive[u] ∩ pass v) over per-node k-bit masks, k counterfactuals in about one sweep. Seeds are (node, mask) pairs; pass maps each node to the worlds that may step INTO it. Masks come from the four-constructor vocabulary only (allWorlds/noWorlds/world/allBut); v1 lowers single-star steps, field-projection keys, and at most 256 candidates. See deletionWorlds/retainedByEach in the prelude.
freedWorlds RPQ -> Bag a -> Bag (Node, Mask a) -> (Node -> Mask a) -> Bag (a, Set Node) Cp {paths, reverse-graph, roots} The freed polarity of reachWorlds: one row per distinct candidate key with the COMPLEMENT of its alive set over the live population — what the GC would reclaim in that world. The complement stays inside the kernel (one extraction flag), so no per-row whole-heap scan is ever needed.
allWorlds Mask a C0 The mask selecting every world (a mask constructor; see reachWorlds).
noWorlds Mask a C0 The empty world mask (a mask constructor; see reachWorlds).
world a -> Mask a C0 The mask selecting one candidate key's world (a mask constructor; see reachWorlds).
allBut a -> Mask a C0 The mask selecting every world except one key's (a mask constructor; see reachWorlds).
nodes Path -> Seq Node C0 A path's nodes, in order.
pathLength Path -> Q 1 C0 The number of edges in a path.

#Signatures & content

Name Type Grade Description
objectHash Node -> Hash C0 {object-hash} Structural value hash: equal hashes mean structurally equal values (dedup key).
objectKey Node -> { hash : Hash, label : Text, type : CType } C0 {object-hash} Group key for duplicates: objectHash plus the label and type it determines, read off the key instead of asserted with 'the'.
retainerSig Node -> Hash Cp {paths, reverse-graph} How-is-it-retained signature: equal means the same retention shape.
contentHash Node -> Hash C0 Shallow value hash: info table + non-pointer payload (no recursion). Equal hashes mean the same closure type and flat content — exact for byte arrays / flat constructors, a proxy otherwise. Precomputed for every node, so it works on allocated garbage too; the dedup key.
payload Node -> Bytes C0 {content} (not yet supported) Bounded prefix of the non-pointer payload bytes.
utf8Prefix Node -> Text C0 {content} (not yet supported) Best-effort UTF-8 decode of the payload (empty if binary).

#Kinds

Name Type Grade Description
showKind Node -> Text C0 reads {Node.type} The node's kind atom, by name (Con, Thunk, MVar, ...).
isJust Maybe a -> Bool C0 True when the Maybe carries a value.
isNothing Maybe a -> Bool C0 True when the Maybe is empty.

#Set conversions

Name Type Grade Description
toBag Set Node -> Bag Node C0 A node set as a bag, for the bag-shaped combinators. Representation-free on the engine (both are node vectors), so it erases at lowering.
toSet Bag Node -> Set Node C0 Deduplicate a bag of nodes into a set.

#Aggregates

Name Type Grade Description
count Coll a -> Q 1 C0 The number of elements in any collection.
sum Coll (Q u) -> Q u C0 Sum of a collection of quantities.
domRetained Coll Node -> Q B C0 {dominators} Retained bytes of a group as a whole: the dominator-deduplicated total the dominators view shows. Unlike sum g.retained, members nested under another member of the same group are not double counted.
avg Coll (Q u) -> Maybe (Q u) C0 Mean of a collection of quantities (Nothing on empty).
max Coll (Q u) -> Maybe (Q u) C0 Largest quantity (Nothing on empty).
min Coll (Q u) -> Maybe (Q u) C0 Smallest quantity (Nothing on empty).
avgOr Q u -> Coll (Q u) -> Q u C0 Mean of the quantities, or the default on empty.
maxOr Q u -> Coll (Q u) -> Q u C0 Largest quantity, or the default on empty.
minOr Q u -> Coll (Q u) -> Q u C0 Smallest quantity, or the default on empty.
frac (a -> Bool) -> Coll a -> Q 1 C0 The fraction of elements satisfying the predicate (0 on empty).
grams Q 1 -> Seq a -> Seq (Seq a) C0 Sliding n-grams (full windows) over a sequence, in order. The window is capped at 5 (the engines render sequence keys verbatim up to that length).
any (a -> Bool) -> Coll a -> Bool C0 Does any element satisfy the predicate?
all (a -> Bool) -> Coll a -> Bool C0 Does every element satisfy the predicate?
argmax (a -> b) -> Coll a -> a C0 The element with the largest key value (numeric key; ties keep the first element).
argmin (a -> b) -> Coll a -> a C0 The element with the smallest key value (numeric key; ties keep the first element).
rep Coll Node -> Node C0 A group's representative: its member with the largest retained size.
top Q 1 -> (a -> b) -> Coll a -> Seq a C0 The k elements with the largest key value, descending. The key must be numeric (a quantity, era or index); order a text column with order by instead.
distinct Coll Node -> Set Node C0 Exact node deduplication, into a set.
distinctValues Coll a -> Bag a C0 Scalar deduplication (bounded; marks itself partial on overflow).
collect Coll a -> Bag a C0 A bounded bag of members, kept as drillable evidence (cap 50).
sample Q 1 -> Coll a -> Bag a C0 A uniform sample of n elements, deterministic per snapshot.
quantile Q 1 -> Coll (Q u) -> Q u C0 Approximate q-quantile of a collection of quantities (exact up to 1024 elements, then a log-bucket sketch; exact quantile sorts instead).
quantileExact Q 1 -> Coll (Q u) -> Q u C0 Exact q-quantile (sorts the collection; the elaboration of exact quantile).
histogram Coll (Q u) -> Histogram u C0 Log2-bucket distribution; renders as a sparkline.

#Collections

Name Type Grade Description
take Q 1 -> Seq a -> Seq a C0 The first n elements of a sequence; the composition form of the limit qualifier.
drop Q 1 -> Seq a -> Seq a C0 All but the first n elements of a sequence.
first Coll a -> a C0 The first element of a sequence or path.
last Coll a -> a C0 The last element of a sequence or path.
filter (a -> Bool) -> Coll a -> Coll a C0 Keep the elements satisfying the predicate.
groupBy (a -> b) -> Bag a -> Bag (b, Bag a) C0 Composition form of the group by qualifier: bucket by key, yielding (key, bucket) pairs. For |> chains and function arguments; inside a comprehension, prefer group by.
orderBy (a -> b) -> Coll a -> Seq a C0 Composition form of the order by qualifier: sort ascending by a key function. Inside a comprehension, prefer order by.
orderByDesc (a -> b) -> Coll a -> Seq a C0 Composition form of order by ... desc: sort descending by a key function.
census Coll Node -> Bag { label : Text, count : Q 1, self : Q B } C0 Label census of a node collection: one {label, count, self} row per label.

#Findings

Name Type Grade Description
card Node -> Finding C0 A card for a head node; an optional record overrides title, summary, bytes, count, evidence, chips.
finding Node -> Finding C0 Alias of card.
chip Text -> ChipVal -> Tone -> Chip C0 A header chip: a label, a value (text/number/percent/bytes), and an optional tone (defaults neutral).
tiers Coll (Bool, Tone) -> Tone C0 The first matching (condition ~> tone) pair decides the tone; neutral otherwise.
text Text -> ChipVal C0 Chip value: a text string.
number Q 1 -> ChipVal C0 Chip value: a plain number.
percent Q 1 -> ChipVal C0 Chip value: a fraction in [0,1], shown as a percentage bar.
pct Q 1 -> ChipVal C0 Alias of percent.
bytes Q B -> ChipVal C0 Chip value: a byte size, humanised.
neutral Tone C0 Tone: neutral (grey).
info Tone C0 Tone: info (blue).
good Tone C0 Tone: good (green).
warn Tone C0 Tone: warning (amber).
bad Tone C0 Tone: bad (red).
high Tone C0 Tone alias: bad (red).
medium Tone C0 Tone alias: warn (amber).
low Tone C0 Tone alias: neutral (grey).

#Node fields

Field Type Grade Description
c.addr Addr C0 Heap address: the node's identity.
c.type CType C0 Closure-type tag, a CType (THUNK, SELECTOR, MUT_VAR, ...).
c.label Text C0 Constructor / closure label.
c.module Text C0 {ipe} Defining module, from IPE info (empty if unknown).
c.name Text C0 {ipe} IPE symbol name.
c.ident Text C0 {ipe} Unqualified name: a constructor's bare name ("Bin", ":"), else the enclosing source binding from IPE (empty if unknown).
c.package Text C0 {ipe} Owning unit-id, e.g. "containers-0.7.0-" (empty if unknown; filter with startsWith).
c.pos SrcPos C0 {ipe} Source position; renders as a clickable link.
c.self Q B C0 Shallow size: the bytes of this closure alone.
c.retained Q B C0 Retained size: bytes freed if this node died (dominator tree).
c.era Era C0 {eras} Allocation era (needs era profiling).
c.block Addr C0 {blocks} Start address of the heap block containing this closure; joins to Block.addr. Empty when no block data is loaded.
c.rooted Bool C0 True if the closure is reachable from a GC root. Always true for heap nodes; on allocated, false marks floating garbage.

#Edge fields

Field Type Grade Description
e.src Node C0 The pointing closure.
e.tgt Node C0 The pointed-at closure.
e.field Ix C0 Which pointer field of the source.
e.fieldName Maybe Text C0 {ipe} The source field's name, when metadata carries it.

#Root fields

Field Type Grade Description
r.node Node C0 The rooted closure.
r.kind RootKind C0 Root kind, a RootKind (STACK, CAF, STABLE_PTR, ...).

#Frame fields

Field Type Grade Description
f.label Text C0 The frame's rendered name: its info-table symbol when IPE data is present, else the frame type keyed by info-table address.
f.type Text C0 The frame's closure type (RET_SMALL, UPDATE_FRAME, ...).
f.pos SrcPos C0 {ipe} The frame's source position (IPE, keyed on its info table); renders as a clickable link.
f.size Q B C0 The frame's size (header + payload).
f.ptrs Seq Node C0 The closures the frame pins: its pointer slots' live targets, in slot order (an UNDERFLOW frame pins the continuation Stack). A member list, not a column.

#Block fields

Field Type Grade Description
b.addr Addr C0 The block's start address.
b.pinned Bool C0 Pinned blocks cannot be compacted or freed while any object in them lives.
b.objects Q 1 C0 Live closures residing in this block.
b.live Q B C0 Their summed shallow bytes.
b.dead Q 1 C0 Floating-garbage closures residing in this block (unreachable, from the linear scan). 0 unless the connector ships block frontiers.
b.deadBytes Q B C0 Their summed shallow bytes — reclaimable space the block still occupies.
b.size Q B C0 The block's (or block group's) data capacity.
b.occupancy Q 1 C0 live / size: near 0 means the block is mostly dead space the OS cannot reclaim.
b.garbageFrac Q 1 C0 deadBytes / (live + deadBytes): the share of the block's occupied space that is floating garbage. Near 1 = a block kept mapped mostly by trash.

#Enums

Tag sets a query compares .type / .kind / .threadStatus against.

#CType

Closure-type tag, exactly as the node's .type field reports it.

CONSTR · CONSTR_1_0 · CONSTR_0_1 · CONSTR_2_0 · CONSTR_1_1 · CONSTR_0_2 · CONSTR_NOCAF · FUN · THUNK · SELECTOR · BCO · AP · PAP · AP_STACK · IND · RET_BCO · RET_SMALL · RET_BIG · RET_FUN · UPDATE_FRAME · CATCH_FRAME · UNDERFLOW_FRAME · STOP_FRAME · BLOCKING_QUEUE · BLACKHOLE · MVAR · TVAR · ARR_WORDS · MUT_ARR_PTRS · MUT_VAR · WEAK · PRIM · MUT_PRIM · TSO · STACK · TREC_CHUNK · ATOMICALLY_FRAME · CATCH_RETRY_FRAME · CATCH_STM_FRAME · WHITEHOLE · SMALL_MUT_ARR_PTRS · COMPACT_NFDATA · CONTINUATION · ANN_FRAME

#ThreadStatus

A TSO's RTS status / why it is blocked (.threadStatus).

RUNNING · BLOCKED_MVAR · BLOCKED_MVAR_READ · BLOCKED_BLACKHOLE · BLOCKED_READ · BLOCKED_WRITE · BLOCKED_DELAY · BLOCKED_STM · BLOCKED_DOPROC · BLOCKED_CCALL · BLOCKED_CCALL_INTERRUPTIBLE · BLOCKED_THROWTO · MIGRATING · FINISHED · KILLED

#RootKind

What kind of GC root keeps a closure alive (Root.kind).

STACK · CAF · STATIC · STABLE_PTR · STABLE_NAME · THREAD · WEAK

#Units

Dimension Description Suffixes
B Bytes, with binary multiples. B KiB MiB GiB TiB
dimensionless core scaling k (×1000) M (×1000000)
Haskell Inspector