-
Notifications
You must be signed in to change notification settings - Fork 17.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
cmd/compile: add go:wasmexport directive #65199
Comments
Thanks for putting this together—this is exciting. Generating a module that can act as a reactor and a command sounds like a great idea. I noticed this might conflict with how Node interprets a module. If a module exports both _start and _initialize, it will throw an exception: https://nodejs.org/api/wasi.html
|
Using // ToDebugString represents the method "wasi:io/error.error#to-debug-string".
//
// Returns a string that is suitable to assist humans in debugging
// this error.
//
// WARNING: The returned string should not be consumed mechanically!
// It may change across platforms, hosts, or other implementation
// details. Parsing this string is a major platform-compatibility
// hazard.
func (self Error) ToDebugString() string {
var ret string
self.to_debug_string(&ret)
return ret
}
//go:wasmimport wasi:io/error@0.2.0-rc-2023-11-10 [method]error.to-debug-string
func (self Error) to_debug_string(ret *string) Subjectively, using methods seems better aligned with the Component Model semantics than the equivalent: //go:wasmimport wasi:io/error@0.2.0-rc-2023-11-10 [method]error.to-debug-string
func error__to_debug_string(self Error, ret *string) Given that resources are opaque |
Thank you for the information about Node's behavior here, I wasn't aware. That is certainly troubling. I will try to see what if any other precedent there is for this behavior in the ecosystem to see whether we or Node are in the wrong. If a host calls both Indeed, if we do need some way to allow users to choose whether to build a command (executing |
This may be true, but I still think this proposal serves as an MVP that we can enhance with method support in a subsequent proposal once the initial hurdles have been overcome. |
Maybe it’s a bigger question about what is defined behavior. Is having both |
Have had previous discussions about |
I created an issue to ask the NodeJS devs for the source of this design decision: nodejs/node#51544 |
Hey. Node developer that implemented that design decision here. 👋 That change was nearly four years ago, and I have since forgotten the exact motivation. However, I was able to dig this up: WebAssembly/WASI@d8b286c. At that point in time, WASI commands had a WASI has changed a good bit since then. I no longer work on WASI, so I don't know if that design decision is still valid or not. I would recommend checking with the folks in the WASI repos. |
WebAssembly/wasi-http#95 contains discussion to use |
Any user created |
Thanks so much for providing your input and this reference. It seems this doc now lives at https://github.com/WebAssembly/WASI/blob/a7be582112b35e281058f1df7d8628bb30a69c3f/legacy/application-abi.md. I wonder, given that this is now under the
If so, this design would need to change to allow the user to choose whether to compile a Command or a Library (Reactor). @sunfishcode perhaps you could provide some guidance here? |
The Preview 2 is based on the Wasm component model.
Edit: I was mistaken about the component-model start function. It's not permitted to call imports, so it's not usable for arbitrary initialization code. There are ongoing discussions about this. |
Thanks for the explanation. This proposal targets our existing wasm implementations, |
What’s an example of tooling that converts a module to a component that supports the component model Wasmtime seems to not support the |
In light of the discussion around |
Thanks for the proposal! Looks good overall.
Is there something similar for js/wasm? Or the library/export mechanism is very different? Also, will the mechanism be similar for later wasip2, or eventual wasi? If so, maybe we can choose a more general name like wasm-library, so we don't need to have a different build mode for each of them? (For start it is okay to only implement on wasip1, just like the c-shared build mode is not implemented on all platforms.)
Is
So, this sounds like that at the end of the exported function, the Go runtime will not try to schedule other goroutines to run but directly return to Wasm? I assume this might be okay. But
I'm not sure we want this debug mode. As you mentioned, it is probably not uncommon to have background goroutines. If one wants to ensure there is no goroutine at the time of exported function exiting, one probably can check it with runtime.NumGoroutine. Thanks. |
Any wasm module can declare exports, but we don't anticipate that exporting methods like this is generally useful to users of For wasip2, as illustrated by Dan's reply above, it's not clear what the export mechanism would look like yet. The name
The expectation within the greater wasip1 ecosystem seems to be that if
Yes, once the exported function returns, we would not schedule other available goroutines but return to the host. The reason for this is that we believe it's what users would expect to happen, since the runtime and various standard libraries maintain their own goroutines that would make it hard to predict the behavior and runtime of exported functions. If you believe that to be an incorrect assumption we're happy to reconsider this. Note that this also includes goroutines started by the exported function itself.
This is a fair point, and we could certainly slim down the proposal by removing this and consider it as a future addition. Thanks! |
Sounds good, thanks. I guess it might be fine to return to the host when the exported function returns. I guess one question is when the "background" goroutines run. If the exported functions get called and return, but none of them explicitly wait for the background goroutines, the background goroutines will probably never run? Would that be a problem for, say, timers? |
The background goroutines could run again if the exported function gets called again. I think ideally users who want concurrent work in exported functions would utilize something like a sync.WaitGroup to ensure work is completed during the execution of the function. A future proposal might be able to tackle this by exposing something like |
The problem of having goroutines blocked after the export call returned isn't much different from what happens when invoking an import. When a WebAssembly module calls a host import, it yields control to the WebAssembly runtime; no goroutines can execute during that time. The issue is amplified with exports because the WebAssembly runtime could keep the module paused for extended periods of time, and the expectation is that imports usually return shortly after they were invoked, but it isn't fundamentally different. Despite the limitations, we can still deliver incremental value to Go developers by allowing them to declare exports. |
@johanbrandhorst when it comes to background goroutines, do you know if the proposed solution different from |
We have a separate PR to TinyGo that prototypes the same model, suspending and resuming goroutines on an export call. |
If the exported function (or another exported function) gets called again, and that function returns without explicitly synchronizing or rescheduling, the background goroutine may still not run? I think blocking for a little while is not a problem, but it might be a problem if it never get to run (while the exported function get called again and again)? As you mentioned, once we have thread supports, it may not be a problem. |
It's true that goroutines may never get to run if there's no point in the exported function to yield to the runtime. I think that's still what I would expect to happen if I wrote my exported function this way. All alternatives would be more confusing I think (waiting before returning or maybe running the scheduler before executing the exported function). As you say, we can hopefully improve this with threads support in the future. |
Okay. This is probably fine. We can change it later if there is any problem. Thanks. |
I've removed the GODEBUG option, we can add that as an enhancement later and suggest users use |
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1, but it is certainly possible to extend it to other targets like GOOS=js, wasm-unknown, or wasip2. It is also currently limited to -buildmode=c-shared, this is a limitation that could easily be lifted in the future.
@aykevl I think it's not necessary for TinyGo to 100% repeat what big Go implements. TinyGo is used widely by community because it's in many ways superior to big Go in Wasm world. And if you were to implement Wasm/WASI plugins TinyGo is the only option. WebAssembly support is still experimental and there in no guarantee that it won't be abandoned at some point, like it happened to go mobile. |
Calling time.Sleep in a wasmexport function is just fine. It doesn't panic. E.g.
prints
It just sleeps a second. And the Go runtime will naturally schedule other goroutines during
prints
In general, blocking syscalls are okay. It just blocks until the operation is done. It cannot return to the host, as the Wasm module itself is single threaded. However, the "syscalls" are provided by the host, so it calls to the host for the syscall implementation, which doesn't necessarily have to block. E.g. if I run the first wasmexport function above with wazero with configuration
(note the
It is only and indeed problematic if the wasmexport function blocks indefinitely, e.g. a deadlock, which will cause a runtime fatal error. |
@akavel I think this is similar to the implementation in this repo. At time.Sleep, the runtime will schedule other runnable goroutines to run. It calls the system sleep when there is no runnable goroutines. And wasmexport should not change that. |
@cherrymui Thank you for explaining! Yes that makes much more sense. I'll update the TinyGo PR to match. |
Change https://go.dev/cl/611315 mentions this issue: |
This commit fixes the automatic extension when building the wasip1_wasm target. Additionally, in future Go versions, support will be added for generating c-shared WASM binaries. golang/go#65199 Therefore, this PR corrects the extension in the build process and removes the .h file from the release when c-shared is enabled and the target is WASM.
The function resultsToWasmFields was originally for only wasmimport. I adopted it for wasmexport as well, but forgot to update a few places that were wasmimport-specific. This leads to compiler panic if an invalid result type is passed, and also unsafe.Pointer not actually supported. This CL fixes it. Updates #65199. Change-Id: I9bbd7154b70422504994840ff541c39ee596ee8f Reviewed-on: https://go-review.googlesource.com/c/go/+/611315 Reviewed-by: Michael Knyszek <mknyszek@google.com> Reviewed-by: Achille Roussel <achille.roussel@gmail.com> LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1, but it is certainly possible to extend it to other targets like GOOS=js, wasm-unknown, or wasip2. It is also currently limited to -buildmode=c-shared, this is a limitation that could easily be lifted in the future.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1, but it is certainly possible to extend it to other targets like GOOS=js, wasm-unknown, or wasip2.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1, but it is certainly possible to extend it to other targets like GOOS=js, wasm-unknown, or wasip2.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1 and wasm-unknown, but it is certainly possible to extend it to other targets like GOOS=js and wasip2.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1 and wasm-unknown, but it is certainly possible to extend it to other targets like GOOS=js and wasip2.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1 and wasm-unknown, but it is certainly possible to extend it to other targets like GOOS=js and wasip2.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1 and wasm-unknown, but it is certainly possible to extend it to other targets like GOOS=js and wasip2.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1 and wasm-unknown, but it is certainly possible to extend it to other targets like GOOS=js and wasip2.
This adds support for the `//go:wasmexport` pragma as proposed here: golang/go#65199 It is currently implemented only for wasip1 and wasm-unknown, but it is certainly possible to extend it to other targets like GOOS=js and wasip2.
This is a change that needs to be mentioned in Go 1.24 release notes; that doesn't seem to be done yet. Reopening as a release blocker to track that. |
Background
#38248 defined a new compiler directive,
go:wasmimport
, for interfacing with host defined functions. This allowed calling from Go code into host functions, but it’s still not possible to call from the WebAssembly (Wasm) host into Go code.Some applications have adopted the practice of allowing them to be extended by calling into Wasm compiled code according to some well defined ABI. Examples include Envoy, Istio, VS Code and others. Go cannot support compiling code to these applications, as the only exported function in the module compiled by Go is
_start
, mapping to the main function in a main package.Despite this, some users are designing custom plugin systems using this interface, utilizing standard in and standard out for communicating with the Wasm binary. This shows a desire for exporting Go functions in the community.
There have been historical discussions on implementing this before (including #42372, #25612 and #41715), but none of them have reached a consensus on a design and implementation. In particular, #42372 had a long discussion (and design doc) that never provided a satisfying answer for how to run executed functions in the Go runtime. Instead of reviving that discussion, this proposal will attempt to build on it and answer the questions posed. This proposal supersedes #42372.
Exporting functions to the wasm host is also a necessity for a hypothetical
GOOS=wasip2
targeting preview 2 of the WASI specification. This could be implemented as a special case in the compiler but since this is a feature requested by users it could reuse that functionality (similar togo:wasmimport
today).Proposal
Repurpose the
-buildmode
build flag valuec-shared
for the wasip1 port. It now signals to the compiler to replace the_start
function with an_initialize
function, which performs runtime and package initialization.Add a new compiler directive,
go:wasmexport
, which is used to signal to the compiler that a function should be exported using a Wasm export in the resulting Wasm binary. Using the compiler directive will result in a compilation failure unless the targetGOOS
iswasip1
.There is a single
optionalrequired parameter to the directive, defining the name of the exported function:(UPDATE: make the parameter required, consistent with the
//export
pragma and easier to implement).The directive is only allowed on functions, not methods.
Discussion
Parallel with -buildmode=c-shared and CGO
The proposed implementation is inspired by the implementation of C references to Go functions. When an exported function is called, a new goroutine (G) is created, which executes on a single thread (M), since Wasm is a single threaded architecture. The runtime will wake up and resume scheduling goroutines as necessary, with the exported function being one of the goroutines available for scheduling. Any other goroutines started during package initialization or left over from previous exported function executions will also be available for scheduling.
Why a "-buildmode" option?
The wasi_snapshot_preview1 documentation states that a
_start
function and an_initialize
function are mutually exclusive. Additionally, at the end of the current_start
functions as compiled by Go,proc_exit
is called. At this point, the module is considered done, and cannot be interacted with. Given these conditions, we need some way for a user to declare that they want to build a binary especially for exporting one or more functions and to include the_initialize
function for package and runtime initialization.We also considered using a
GOWASM
option instead, but this feels wrong since that environment variable is used to specify options relating to the architecture (existing options aresatconv
andsignext
), while this export option is dependent on the behavior of the "OS" (what functions to export, what initialization pattern to expect).What happens to func main when exports are involved?
Go code compiled to a wasip1 Wasm binary can be either a "Command", which includes the
_start
function, or a "Reactor/Library", which includes the_initialize
function.When using
-buildmode=c-shared
, the resulting Wasm binary will not contain a_start
function, and will only contain the_initialize
function and any exported functions. The Gomain
function will not be exported to the host. The user can choose to export it like any other function using the//go:wasmexport
directive. The_initialize
function will not automatically callmain
. Themain
function will not initialize the runtime.When the
-buildmode
flag is unset, the_start
function and any exported functions will be exported to the host. Using//go:wasmexport
on themain
function in this mode will result in a compilation error. In this mode, only_start
will initialize the runtime, and so must be the first export called from the host. Any other exported functions may only be called through calling into host functions that call other exports during the execution of the_start
function. Once the_start
function has returned, no other exports may be called on the same instance.Why not reuse //export?
//export
is used to export Go functions to C when usingbuildmode=c-shared
. Use of//export
puts restrictions on the use of the file, namely that it cannot contain definitions, only declarations. It’s also something of an ugly duckling among compiler directives in that it doesn’t use the now establishedgo:
prefix. A new directive removes the need for users to define functions separately from the declaration, has a nice symmetry withgo:wasmimport,
and uses the well establishedgo:
prefix.Handling Reentrant Calls and Panics
Reentrant calls happen when the Go application calls a host import, and that invocation calls back into an exported function. Reentrant calls are handled by creating a new goroutine. If a panic reaches the top-level of the
go:wasmexport
call, the program crashes because there are no mechanisms allowing the guest application to propagate the panic to the Wasm host.Naming exports
When the name of the Go function matches that of the desired Wasm export, the name parameter can be omitted.
For example:
Is equivalent to
The names
_start
and_initialize
are reserved and not available for user exported functions.Third-party libraries
Third-party libraries will need to be able to define exports, as WASI functionality such as wasi-http requires calling into exported functions, which would be provided by the third party library in a user-friendly wrapper. Any exports defined in third party libraries are compiled to exported Wasm functions.
Module names
The current Wasm architecture doesn’t define a module name of the compiled module, and this proposal does not suggest adding one. Module names are useful to namespace different compiled Wasm binaries, but it can usually be configured by the runtime or using post-processing tools on the binaries. Future proposals may suggest some way to build this into the Go build system, but this proposal suggests not naming it for simplicity.
Conflicting exports
If the compiler detects multiple exports using the same name, a compile error will occur and warn the user that multiple definitions are in conflict. This may have to happen at link time. If this happens in third-party libraries the user has no recourse but to avoid using one of the libraries.
Supported Types
The
go:wasmimport
directive allows the declaration of host imports by naming the module and function that the application depends on. The directive applies restrictions on the types that can be used in the function signatures, limiting to fixed-size integers and floats, andunsafe.Pointer,
which allows simple mapping rules between the Go and Wasm types. Thego:wasmexport
directive will use the same type restrictions. Any future relaxing of this restriction will be subject to a separate proposal.Spawning Goroutines from go:wasmexport functions
The proposal considers scenarios where the
go:wasmexport
call spawns new goroutines. In the absence of threading or stack switching capability in Wasm, the simplest option is to document that all goroutines still running when the invocation of thego:wasmexport
function returns will be paused until the control flow re-enters the Go application.In the future, we anticipate that Wasm will gain the ability to either spawn threads or integrate with the event loop of the host runtime (e.g., via stack-switching) to drive background goroutines to completion after the invocation of a
go:wasmexport
function has returned.Blocking in go:wasmexport functions
When the goroutine running the exported function blocks for any reason, the function will yield to the Go runtime. The Go runtime will schedule other goroutines as necessary. If there are no other goroutines, the application will crash with a deadlock, as there is no way to proceed, and Wasm code cannot block.
Authors
@johanbrandhorst, @achille-roussel, @Pryz, @dgryski, @evanphx, @neelance, @mdlayher
Acknowledgements
Thanks to all participants in the
go:wasmexport
discussion at the Go contributor summit at GopherCon 2023, without which this proposal would not have been possible.CC @golang/wasm @cherrymui
The text was updated successfully, but these errors were encountered: