AssemblyScript's exports

[sunfishcode]

I'm working on documenting the assumptions that runtimes make when running wasm modules, and I'm not very familiar with AssemblyScript and would like to learn more.

Here are the exports in a simple AssemblyScript wasm module being used in non-Web wasm runtimes:

  (export "__setArgumentsLength" (func 45))
  (export "memory" (memory 0))
  (export "__alloc" (func 4))
  (export "__retain" (func 5))
  (export "__release" (func 6))
  (export "__collect" (func 7))
  (export "__reset" (func 8))
  (export "__rtti_base" (global 4))
  (export "_start" (func 47))
  (export "wasiabort" (func 49))

The _start export is recognized as the entrypoint of the program, meaning a call to "_start" starts the program and ends it. "memory" is also currently recognized and used by APIs to allow pointers to memory to be passed around. The rest appear to be specific to AssemblyScript.

Does AssemblyScript assume that something outside of the module will call these other functions?

If so, I'd like to understand how this should work. If the environment recognizes these exports, importing them and calling them from within functions called by _start would imply a cyclic dependency, and while some environments have ways to do that, isn't something wasm supports in general.

If not, would there be any obstacles to removing these exports?

[dcodeIO]

Most of these exports can be omitted by selecting the half runtime instead of the full runtime. These two runtime variants are essentially the same, but the one named full exports a set of runtime helpers (see also: Anatomy of an AssemblyScript module) to deal with managed objects externally (typically using a helper library we provide for JS hosts). Where these are not needed, using half or otherwise stripping them is just fine. In the case of the above module, --runtime half --noExportMemory and expecting _start to be present would leave us with

  (export "__setArgumentsLength" (func 45))
  (export "wasiabort" (func 49))

where __setArgumentsLength is only present if a function is exported that has optional arguments (this is our replacement to set what's know as arguments.length in JS, before calling into Wasm). I guess there is no good way to assume that no such function export exists per-se because it's user-defined, but without calling __setArgumentsLength first, calling an export of a function with optional arguments will most likely have UB.

Now I don't know where wasiabort comes from here, at least it's not something the compiler typically exports. I assume it comes from a custom layer being implemented for WASI functionality, where the recommended way nowadays is to import "wasi" within the entry file to set everything up automatically (does not yield any additional exports but utilizes WASI implementations then).

Let me know if you have further questions :)

[dcodeIO]

Regarding

Does AssemblyScript assume that something outside of the module will call these other functions?

yes, and it might be the case that an import called within _start (in user code, after the runtime has been initialized) again calls them. For example __retain is a helper to increment the reference count of a managed object, so if an import uses a managed object and wants to do that, the call tree can be

- wasm._start
 - host.myImport
  - wasm.__alloc
  - wasm.__retain
 - host.myOtherImport
  - wasm.__release

but an import like that will technically only be called as soon as everything has been set up for a __retain etc. call to succeed, and it is guaranteed that a __retain etc. call does not itself call any imports, so the call tree does not become any deeper than that.

Do you see any problems with this approach in current non-Web engines? If so, considering that __retain etc. are somewhat essential for the time being, that is while there is no Wasm GC we can use, do you see alternatives?

[sunfishcode]

Ah, wasiabort is indeed specific to the particular application I was looking at.

Thanks for the info about --runtime half! For context, the specific export which started me on this path was __rtti_base, which appears to be missing in the documentation.

Concerning variadic functions or optional arguments, would it be feasible to change to passing an extra parameter which holds the number of arguments being passed? WASI runtimes don't currently recognize __setArgumentsLength, so if there are situations where it needs to be called to avoid UB, there may be bugs.

As a heads up, a callgraph like the one you describe:

- wasm._start
 - host.myImport
  - wasm.__alloc
   [...]

implies that wasm is importing myImport from host and host is importing __alloc from wasm, which is a cyclic dependency, which doesn't work reliably in non-JS runtimes. It's probably not an urgent issue right now, because it only affects programs built from multiple AssemblyScript programs that share reference-counted objects.

[dcodeIO]

For context, the specific export which started me on this path was __rtti_base, which appears to be missing in the documentation.

Ah, right, that's currently documented in internals. It's also not present when --runtime half is being used. Essentially it is an immutable global pointing at the address of the module's RTTI blob, that the JS helper library we provide can use to determine the value alignment of an array for example when a user creates a view on or reads it.

would it be feasible to change to passing an extra parameter which holds the number of arguments being passed

We have been thinking about doing this, but ultimately came to the conclusion that by not changing the signature we can make this feel more natural to a user, at least scenarios where the host is JS and our helper library is used. For example, the JS helper lib wraps each exported function in a way that __setArgumentsLength will be called implicitly before calling the actual function, so a user can just call any function without worrying about it. Perhaps an opportunity to change this behavior will arise eventually, if we decide to switch to a mechanism like wasm-bindgen, which we so far avoided to keep the size of helper code minimal. There are considerations, though.

implies that wasm is importing myImport from host and host is importing __alloc from wasm, which is a cyclic dependency, which doesn't work reliably in non-JS runtimes

I see, thanks. The typical scenario here currently is that these are called by the embedding directly, for example when passing a host-provided string as a managed object to a module or upon returning a managed object to the host. As far as I'm aware most users utilize either an embedding of wasmtime or Lucet to do this, and we are considering to run further WASI tests with wasmtime eventually. What would standalone wasmtime do in this scenario? Will it refuse to load the module right away?

[sunfishcode]

I see, thanks. The typical scenario here currently is that these are called by the embedding directly, for example when passing a host-provided string as a managed object to a module or upon returning a managed object to the host. As far as I'm aware most users utilize either an embedding of wasmtime or Lucet to do this, and we are considering to run further WASI tests with wasmtime eventually. What would standalone wasmtime do in this scenario? Will it refuse to load the module right away?

The specific concern here is multiple wasm modules with a cyclic import dependency between them:

red._start
 - blue.myImport
   - red.__alloc

It won't be possible to instantiate that with expected standard standalone wasm linking semantics. I expect this will be the case for Lucet and other wasm runtimes as well.

One possible solution to this would be to move the AssemblyScript runtime into its own module which the main module and any other modules it uses link from:

red._start
 - runtime.__alloc
 - blue.myImport
   - runtime.__alloc

Of course, that'd only be needed when you have multiple modules; a single-module program could of course include the runtime.

In any case, you've answered my questions for now, so I'll go ahead and close this issue. If you want to follow-up here, feel free to re-open this :-). Thanks!