Document UrWasm #253
Document UrWasm #253
Conversation
|
Ready for review @quodss |
|
|
||
| Since Lia's `+run-once` returns a pair of \[yield accumulator], we grab the yield with [`=<`](../../../hoon/rune/tis.md#tisgal) to get the head (`-`) of the result. `+yield-need` is a Lia function that asserts that a yield is successful and returns the unwrapped result. | ||
|
|
||
| Below, we build Lia's `+run-once` core and run it on our imported `.wasm-bin` module, which we give the empty argument `[~ ~]`. (That is, a pair of the initial accumulator state and a map of imports.) The `%$` is where we'd specify a runtime hint like `%bout`, but we stub it out here as we don't need it. |
There was a problem hiding this comment.
Not quite: we initialize a +run-once gate by passing it the molds of the yield and the accumulator, and then we pass it several arguments:
wasm-binbinary;- pair of the initial value of the accumulator and the map of imports
[~ ~]; - hint value, which is ignored in
+run-oncecase, so we default to%$. It is NOT a "runtime hint like%bout", it is a jet hint.+run-oncejet only recognizes%none, which makes the jet punt and it is used for testing/debugging. - The script itself, defined below
The text makes it look like we are in some imperative environment: we run +run-once with wasm-bin and the empty argument, and then we write some regular Hoon. No, the script below is one of the arguments for (run-once yil-mold acc-mold) gate
| :: | ||
| :: build Lia's +run-once core with our .yil-mold | ||
| :: and .acc-mold and run it with our .wasm-bin, which | ||
| :: will be given the empty state [~ ~] |
There was a problem hiding this comment.
Here and elsewhere the comments should follow the convention layed out here https://docs.urbit.org/hoon/style#comment-conventions:
:: comment is separated from code below
::
(add 2 2)| =, arr | ||
| ``` | ||
|
|
||
| We'll measure the input list and concatonate all of its elements into a single atom with [`+rep`](../../../hoon/stdlib/2c.md#rep). |
| ;< vec-out=octs try:m (memread &1.ptr-len (mul 8 &2.ptr-len)) | ||
| ``` | ||
|
|
||
| Now we split the resulting octets atom (`$octs`, a cell of byte length and data) into a list of 64-bit atoms with [`+rip`](../../../hoon/stdlib/2c.md) and add missing trailing zeroes if necessary. (Note that UrWasm's [`+rope`](../../../urbit-os/base/wasm/lib-wasm-runner-op-def.md#rope) "BROKEN_LINK" would preserve the zeroes.) |
There was a problem hiding this comment.
(Note that UrWasm's [
+rope] ... would preserve the zeroes.
This is a reference to a gate internal to Urwasm development. No need to have a link to it here
| ~ | ||
| ``` | ||
|
|
||
| This is a ~10x speedup compared to the pure Hoon implementation. |
There was a problem hiding this comment.
This ratio might be a bit less in light of urbit/vere#836 merged, which sped up comparison jets.
There was a problem hiding this comment.
if you don't mind, you could bench that again
| - [Wasm parser](./lib-wasm-parser.md) | ||
| - [Wasm validator](./lib-wasm-validator.md) | ||
| - [Wasm operator definitions](./lib-wasm-runner-op-def.md) | ||
| - [Wasm interpreter](./wasm-interpreter-data-types.md) |
There was a problem hiding this comment.
this was probably meant to be a link to lib-wasm-runner-engine.md
| (each (script-raw-form (list lia-value) *) (list lia-value)) | ||
| ``` | ||
|
|
||
| Input type for [`+run`](#run). Either a new script to execute or cached values from previous execution. |
There was a problem hiding this comment.
the second option is not cached values but a resolved external call
|
|
||
| Returns the script yield and final accumulator state. | ||
|
|
||
| ### `+init:run-once` {#init-run-once} |
There was a problem hiding this comment.
this is internal to jetted +run-once and would not be called from outside
|
|
||
| Stateful execution of a Wasm module. Can be used to run a new script or resume computation with the provided `$seed` state. | ||
|
|
||
| ### `+init` {#init-run} |
| ^- form:m | ||
| ``` | ||
|
|
||
| Calls an external (import) function. If no cached result is available, yields the function call request to the host environment. Otherwise returns the cached result. |
There was a problem hiding this comment.
First usage of "cached result" confused me but now I see a point, I guess it's fine
2 participants
MVP documentation for UrWasm; doesn't include
threads-js.Adds an overview and tutorial to "Build on Urbit", to which
threads-jsand hooks tutorials can be added later. Also adds data types and library reference to the%basedocs, to which the rest the%basedesk can be added later.