Conduit
Conduit is the IR that Bolt compiles
to after type checking. boltlang-mir-build turns each body into MIR, a
tree in which each node has its type and each use what it calls, with
match compiled to a decision graph by boltlang-pattern.
boltlang-mir-mono walks the MIR to find the instances of each function,
and boltlang-codegen-conduit turns the MIR of each instance into a
Conduit module, which Conduit optimizes and compiles to WebAssembly.
This page is about what's particular to Bolt: how its mutability, its copies and its effects map onto Conduit's. Conduit's own docs describe the IR itself.
Mutability parameters
A generic function keeps its 'm parameters and its where clauses in
Conduit, and an instance is specialized on types but not on mutabilities.
So there's one Conduit function for every instance, generic in the
mutabilities it takes:
fn fn1['m1, 'm2](%0: 'm2 [i32]) -> ('m1 data10['m2]) where 'm2: 'm1 { .. }
let %1: mut data10[imm] = call fn1[mut, imm](%0)
A data type gets a mutability parameter for each mutability in its type
arguments, so Option[mut [i32]] and Option[imm [i32]] share one
declaration. A struct's fields without mut or imm are inherit.
At run time nothing changes: a backend has no mutabilities, so a function is compiled once for every mutability it's called with.
Copies to imm
Conduit has no deep copy. Copying a value to imm is the job of the type's
ToImm impl, which is shallow, and builds the new value with Conduit's
new and array_clone:
Vec { items: array_freeze(v.items), len: v.len }
where array_freeze lowers to an array_clone to imm. Conduit's
copies pass then removes what it can:
- An
immarray cloned toimmis the array itself. - An
immobject rebuilt from its own fields at the same type is the object. So once Conduit has inlined it,to_immof aVecthat'simmalready costs nothing. - A clone to
immof an array that nothing else can reach becomes anarray_freezein place, shown by a region analysis. The region of a valuevis themutobjects it reaches, following the arrays and structs it holds but not what closures captured, andimm vcopies exactly those. When the program has the region's objects only insidev, and no object outside the region holds one, making the regionimmwhere it is can't be told apart from copying it: the Lean proof shows this (region_freeze_stepinUnique.lean).
The last doesn't fire on to_imm of a fresh mut Vec yet: the impl
reads v.len after cloning the buffer, so v is still used and the
analysis keeps the copy. Reading an integer field can't reach the array,
so the analysis could see past such reads
(conduit#9).
imm e is a call of the deep copy of its type, a function the compiler
makes for each type it copies, as rustc makes drop glue: a shim, built by
boltlang-mir-transform when monomorphization finds the imm e. It calls
the type's to_imm_deep, from its impl of ToImmDeep. A type without
one, or whose impl's bounds don't hold, is an error, found where the
instance is made: imm of a Vec[Point] needs ToImmDeep[Point], as
to_imm_deep would. So the prelude, and the small one of the tests, have
impls for their own types. What imm doesn't change, like an imm [i32],
is given back as it is, with no call and no impl.
Effects
A call of an operation is a perform, and a match with effect arms (see
the effects design) is a handle: the
scrutinee becomes a closure, the value arms the return clause, and the arms
of each operation its clause, a function that takes the operation's
arguments and the continuation, and matches the arguments as a tuple. The
clauses share the locals of the code around the match that they use, as
the handler's environment, with a local that's assigned as its ref.
An effect with type parameters is one Conduit effect for each of its
arguments, like State_i32 for State[i32], and an operation used as a
function, like say in xs.each(say), is a closure of a shim that
performs it. A match with arms for several effects is one handler of
all of them, with a clause for each of their operations: an arm for
operations of two effects, like effect fail(c) | abort(c), _ => c, is
the clause of each. So an arm's own operations go to the handler around
the match, not to the match itself, as nesting a handle per effect
would.
Effect parameters, like the E of map, are passed through to Conduit as
effect parameters, as mutability parameters are. Instances are only made
for types, so a map that's called with functions of different effects is
still one function in Conduit. Not lowered yet: a handler whose arms hold values of
a mutability that's a parameter, since a clause can't have mutability
parameters in Conduit.
Every function, closure and continuation gets its row from the checker:
Conduit's effect types follow Bolt's: rows after does, joined with +,
with Nothing for the empty row and effect parameters E1, E2, ..
written without a quote, as Bolt writes E. Effects are capitalized, as
Bolt's are: Effect20.
-
Effect parameters are kept, as mutability parameters are. A function like
fn map[A, B, E](xs: [A], f: fn(A) -> B does E) -> [B] does Eis monomorphized on
AandBbut keepsE, so there's onemapfor every callback. An instance's row parameters are its effect parameters, which each call and closure of it gives rows for, and its lambdas and handlers have them too. A row parameter of the caller in a type argument, likeT = fn() does E, becomes one of the callee's instance, as for mutabilities. -
Data types get an effect parameter for each row in their type arguments, like that of the closure in
Option[fn() does Log], as they do for mutabilities. -
A handler's row is that of the function or closure the
matchis in: what its arms can do, and what resuming its continuations does, which is the row the checker gives aCont(#370 would make it smaller). The scrutinee's closure does that and the handled effect. -
Top-level code has no effects, since the checker rejects an operation there that nothing handles. So a
performwithout a handler can't happen at run time. -
An effect with type parameters, like
State[i32], becomes one Conduit effect per instance, as a generic data type does. -
A type of the host, declared as
#[link(wasm)] type JsString;, is Conduit'shost: anexternrefin Wasm, which Conduit counts and keeps in a table. Each such declaration is a type of its own to the checker, so aJsStringcan't be given where anElementis expected, though both arehostin Conduit. Like a struct, it can have functions in its namespace, likeJsString.from. -
An
Optionof a type of the host, likeOption[Element], is Conduit'snullable host, not a data type:Noneishost_null(),Some(x)isx, amatchtestshost_is_null, and thexit binds ishost_unwrap. So a function the host provides that may givenull, likegetElementById, is declared to give anOption[Element], and a JavaScriptnullarrives asNone. Where an operation has anOption[T]of its own type parameter, which is the data type ofOption[any], the conversion makesNoneof a null andSomeof a host value, boxed, and the other way back. -
An operation's own type parameters are
any. TheToffn fail[T](error: E) -> Tis Conduit's boxedanyin the operation's signature, so every use offailis the same operation, and its handlers' arms seeanyforT. Aperformboxes the arguments of typeTand unboxes the result, at the types of that use. It isn't monomorphized, as a function of which the performance matters would be. ATinside another type, like-> Option[T], is converted by rebuilding the value:Option[i32]becomesOption[any]by matching it and boxing what it holds, with a function for each pair of types, so that one forList[T]calls itself. An array is copied, and a closure is wrapped in one that converts its arguments and result. Amutvalue withTin it isn't converted, since the handler would get a copy. Data that holds ananyismutin Conduit, since only amutobject can hold areadonly any. -
handleis typed as Bolt types a handler: it takes its effect out of what the body performs, and puts back what the clauses perform. -
Rows tell Conduit what suspends. A function whose row has no suspending effect, like
Async, never needs its stack captured.
In Conduit, results are always in parentheses, so
fn() -> (imm fn() -> () does E) gives the row to the inner closure and
fn() -> (imm fn() -> ()) does E to the outer one. Bolt's syntax can't
tell these apart yet.
Still to decide, for Conduit:
- Effects whose parameters are rows, like
effect Spawn[E] { fn spawn[T](task: fn() -> T does E) -> Task[T]; }.