Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Concept map

How the pieces fit together.

The three axes

hylic is built on three orthogonal axes. Each can be chosen independently:

%3cluster_opsWHAT to computecluster_domainHOW closures are boxedcluster_execHOW to traversefoldopsFoldOpsinit / accumulate / finalizesharedSharedArc<dyn Fn + Send + Sync>treeopsTreeOpsvisit (children)localLocalRc<dyn Fn>fusedFusedzero-overhead callbackownedOwnedBox<dyn Fn>funnel_eFunnelCPS work-stealing(Shared)

Operations define the computation. Domain determines boxing overhead. Executor determines traversal strategy. Any combination works (subject to domain compatibility).

Type landscape

%3cluster_traitsOperations traits (ops::)cluster_concreteDomain types (one per domain)cluster_executorsExecutors (exec::)cluster_liftsLifts (prelude::)FoldOpsFoldOps<N, H, R>init / accumulate / finalizeSharedFoldshared::Fold<N,H,R>Arc closuresFoldOps->SharedFoldimplLocalFoldlocal::Fold<N,H,R>Rc closuresFoldOps->LocalFoldOwnedFoldowned::Fold<N,H,R>Box closuresFoldOps->OwnedFoldUserStructYourStructimpl FoldOps(zero boxing)FoldOps->UserStructTreeOpsTreeOps<N>visit / applySharedTreegraph::Treeish<N>Arc closuresTreeOps->SharedTreeLiftLift<N, N2>lift_fold / lift_treeish / lift_rootExplainerExplainercomputation traceLift->ExplainerimplExecDSExec<D, S>sole user-facing typeExecDS->FoldOps&impl FoldOpsExecDS->TreeOps&impl TreeOpsFusedSpecfused::Specall domainsExecDS->FusedSpecS =FunnelSpecfunnel::Spec<P>Shared domainwork-stealingExecDS->FunnelSpecS =

How a user navigates

%3pick1. Bring the prelude inuse hylic::prelude::*;build2. Build fold + graphfold(...)treeish(...)pick->buildrun3. RunFUSED.run(&fold, &graph, &root)build->runpar3b. Or parallelexec(funnel::Spec::default(8))  .run(...)build->parif parallel

The prelude defaults to the Shared domain — fold(…) / treeish(…) / FUSED resolve to the Shared constructors. For Local or Owned, take the per-domain path; see Import patterns.

Domain compatibility matrix

SharedLocalOwned
Fusedyesyesyes
Funnelyes——
Explaineryesyes—
Pipeline (Stage 1 + 2)yesyes—
OwnedPipeline——yes

Fused supports all domains (borrows, never clones). Funnel requires N: Clone + Send, R: Send, G: Send + Sync — the Shared domain provides these. The Stage-1/Stage-2 pipeline surface is mirrored across Shared and Local (SeedSugarsShared / SeedSugarsLocal, Stage2SugarsShared / Stage2SugarsLocal, …); the Owned domain gets the dedicated one-shot OwnedPipeline instead, since its closures consume on first use and cannot back a Clone-able chain.

Zero-boxing path

For maximum performance, skip the domain system entirely. Implement FoldOps and TreeOps on concrete structs — the compiler monomorphises every call, eliminating the dyn Fn indirections. See Zero-cost performance for the worked walkthrough.