More non-trivial examples

[james-lawrence]

most of the examples currently are either) specific to the compiler (tinygo, rust, zig) and don't work with golang 1.21 or are so trivial to be essentially useless (add).

add examples that show the following:

• returning dynamically sized bytes/strings from a host function.
• sending/returning arrays of strings and bytes.
• returning multiple of the above.
• reading/writing files (file created by guest, written to from host and the reverse)

currently its hard to mplement dynamic data from the host and none of it is well documented. only successful method I'd managed so far is to pre-allocate a buffer in the guest and use that which sucks since it needs to be sized large enough to hold any possible return data.

reading/writing files are not documented and don't work via the FD.

having working examples of these would ensure that at least normal usage of wazero is documented and working.

[ncruces]

only successful method I'd managed so far is to pre-allocate a buffer in the guest and use that which sucks since it needs to be sized large enough to hold any possible return data.

This really depends on your guest environment, which is why good samples are hard to come by.

But generally, guests manage linear memory, so you need to export a function that allocates memory on demand, and have the host call it. If your guest can't export a function (like Go wasip1) that's really a guest limitation; there's no getting around that.

[james-lawrence]

@ncruces has wazero brought this to the attention of golang's implementation of wasip1? (note: golang potential limitation here isn't really relevant to the overall lack of good example code it doesn't exist for tinygo/rust/zig etc)

[ncruces]

The Go team is aware of this limitation; the semantics are complicated.

W.r.t. samples in other languages, this is precisely what the allocation examples want to convey.

The WASM ABI forces you to design a C like API, where you have to decide things like who allocs memory (the caller/callee). A well designed C API is “easy” to wrap. If you want a more streamlined experience, something like go-plugin may be what you're after.

Having said that, we can always improve documentation and examples; I'd argue that this is precisely the kind of area where new contributors can help the most.

[james-lawrence]

@ncruces add an example for golang proper. I have no issues with exposing an allocation function. im asserting that the examples in this repo are very trivial or make assumptions based on the compiler. the allocations are just one tiny bit and hand waves everthing else is based on that. so have good examples for intended usage that isn't trivial is important.

feel free to ignore the issue i'm just asserting the pain points of getting started and having to reverse engineer the expectations. even when looking at the examples.

edit: the big issue is when using golang's compiler is i'm unsure if what I'm thinking of exposing is safe to do or if it'll interfere with assumptions by the gc. this means people have to spend a ton of time investigating whats say or take less than ideal approaches.

and the allocation doesn't resolve the FD issues I ran into due to lack of examples etc.