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) |