Skip to main content

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 imm array cloned to imm is the array itself.
  • An imm object rebuilt from its own fields at the same type is the object. So once Conduit has inlined it, to_imm of a Vec that's imm already costs nothing.
  • A clone to imm of an array that nothing else can reach becomes an array_freeze in place, shown by a region analysis. The region of a value v is the mut objects it reaches, following the arrays and structs it holds but not what closures captured, and imm v copies exactly those. When the program has the region's objects only inside v, and no object outside the region holds one, making the region imm where it is can't be told apart from copying it: the Lean proof shows this (region_freeze_step in Unique.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 E

    is monomorphized on A and B but keeps E, so there's one map for 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, like T = 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 match is in: what its arms can do, and what resuming its continuations does, which is the row the checker gives a Cont (#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 perform without 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's host: an externref in Wasm, which Conduit counts and keeps in a table. Each such declaration is a type of its own to the checker, so a JsString can't be given where an Element is expected, though both are host in Conduit. Like a struct, it can have functions in its namespace, like JsString.from.

  • An Option of a type of the host, like Option[Element], is Conduit's nullable host, not a data type: None is host_null(), Some(x) is x, a match tests host_is_null, and the x it binds is host_unwrap. So a function the host provides that may give null, like getElementById, is declared to give an Option[Element], and a JavaScript null arrives as None. Where an operation has an Option[T] of its own type parameter, which is the data type of Option[any], the conversion makes None of a null and Some of a host value, boxed, and the other way back.

  • An operation's own type parameters are any. The T of fn fail[T](error: E) -> T is Conduit's boxed any in the operation's signature, so every use of fail is the same operation, and its handlers' arms see any for T. A perform boxes the arguments of type T and unboxes the result, at the types of that use. It isn't monomorphized, as a function of which the performance matters would be. A T inside another type, like -> Option[T], is converted by rebuilding the value: Option[i32] becomes Option[any] by matching it and boxing what it holds, with a function for each pair of types, so that one for List[T] calls itself. An array is copied, and a closure is wrapped in one that converts its arguments and result. A mut value with T in it isn't converted, since the handler would get a copy. Data that holds an any is mut in Conduit, since only a mut object can hold a readonly any.

  • handle is 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]; }.