Wrapped exports should return Promises

[fgmccabe]

The current spec of JSPI returns a Promise if the underlying wasm suspended (due to a call to a suspending import) and returns a regular value if the export 'returned normally'.
This is not a recommended approach to designing API for the web: return types of the form JSPromise | AnythingNotAPromise are not recommended.
The fix is to always return a Promise, and to have the final return value be the equivalent of
Promise.resolve(innerExport())

[dschuff]

Does this mean that it will always be impossible to avoid a trip through the microtask queue every time a wrapped export is called?

[fgmccabe]

Essentially, yes. Calling a wrapped export will inevitably result in that trip.
On the flip side, at least it will be uniform: when you call a wrapped export, you will get a promise. Which means that you will not need to bifurcate your business logic.

[thibaudmichaud]

Suspending imports can also return a JSPromise | AnythingNotAPromise. Should it also wrap non-Promise results in a Promise.resolve()?

[fgmccabe]

Is this forced on us?

[tlively]

Atomics.waitAsync bends over backwards to avoid the extra trip through the microtask queue. It returns an object that contains a bool signifying whether the other member is a promise or raw value: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Atomics/waitAsync#return_value. If we want to avoid the trip through the microtask queue, I assume we would need to do something similar. It may not be worth it.

[RossTate]

Cool example! My sense is that their design to avoid the microtask queue is more heavy-handed than what people would want here, so my inclination at the moment would be that "consistently require and produce promises" is the right default here, but I'm definitely open to the alternative if people would prefer it.

[rektide]

I agree fully that this is accepted dogmatism for the web. It felt like something that emerged very sharp & very hard right as promises were being standardized, & it doesn't feel like there's been a lot of discussion or updates now that promises are here. I wish there were a way to reopen this discussion better, because it feels like there is so much performance we leave on the table for something that rarely has been a problem for developers.

With tools like await there is now far less impact to returning either a value or a promise, where-as historically handling value-or-promise required considerable care. The hazard here has been largely ameliorated.

Personally I'd love to see the spec embrace the faster route. Let higher-level tools wrap & alter their wasm exports as they'd like to take the hit in the name of (now not so relevant) convenience, but leave the low level capability to be fast possible!

[tlively]

AFAIU, await doesn't solve the problem because awaiting a non-promise value implicitly creates a promise and returns to the microtask queue anyway. We would need something like fast_await that continues directly if the awaited object is not a promise.

[fgmccabe]

IMO, the performance argument does not hold against the destruction of code integrity.
If an export has been marked as promising, that means that the application has to be constructed in such a way as to anticipate that it did return a promise. Allowing the export to not actually return a promise complicates the logic of the application.
OTOH, for unpromising (sic) exports, there is no such expectation; and they can continue to be as fast as ever.

[tlively]

I don't think we should rule out the possibility that the performance problems might be bad enough that we will need to do something about them.

For instance, in the wasm-split use case, nearly all the exports will need to be wrapped and JS will have to be prepared for them to return a promise in case they trigger the loading of a secondary module and suspend. However, on each thread, there will only ever be a single suspension per secondary module, and after the secondary modules have been loaded, the program will never suspend again (all assuming the program does not otherwise use JSPI).

For that use case, forcing the JS to return to the event loop on every call to an export is pure overhead in the limit. An alternative solution would be to have both a wrapped and unwrapped version of each export and have a macro to choose between them based on whether the secondary module has been loaded, and perhaps that's enough, but is that what we really want producers to have to do?

[fgmccabe]

This does not address the code question. If you call a function that might return a Promise, you have to code it in such a way that it will. Instead of two exports, you force the applications programmer to have two call paths to the code.

[tlively]

Right, to avoid wait overhead there would always have to be two code paths: one that awaits a promise and one that does not. Note that these code paths could be encapsulated in a macro or similar. This is true whether the two code paths call different versions of the export or whether they call the wrapped export and inspect its result. The difference is that the former solution requires being able to tell in advance whether an export may suspend, which is possible in limited wasm-split use cases but not in general.

Would it be possible to have the program configure the wrapper to either always return a promise or to return an object like the one returned by Atomics.waitAsync? (The default could be to always return a promise) That way programs could opt in to handling this additional complexity where the performance benefit is worth it.

[fgmccabe]

That is an interesting suggestion. Worth considering.
I do however, pushback on the performance question. If a wasm module is big enough to warrant code splitting, I find it unlikely that it will be so sensitive to the performance of an individual export like this.

[ajklein]

Waiting on an eagerly-resolved Promise does not return to the event loop, only the microtask queue (which runs, effectively, when the JS stack unwinds but before returning control to the event loop). So the performance should be strictly better than returning to the event loop, at least.

@tlively, what would this "macro" look like from the JS point of view? It's hard for me to imagine JS code that transparently switches between sync and async.

[tlively]

Yeah, I admit that there might not actually be a performance problem here and that ideally we would get some data to inform this choice. I'm just worried about this becoming one of those "peanut butter" performance problems where it's spread all over the system making everything just a little slower.

I don't know about any kind of macro system in use in normal Web dev, but in Emscripten we literally run (a reimplementation of) the C preprocessor over our JS and also have some AST-rewriting passes to expand macros that look like normal function calls, so it would be totally trivial to implement such a macro.

Specifically, with the more limited, duplicated-exports solution for wasm-split, the macro would expand to this:

if (secondaryModuleLoaded) {
  x = unwrappedExport();
} else {
  x = await wrappedExport();
}

And with the solution where the wrapped function may or may not return a promise:

x = wrappedExport();
if (looksLikePromise(x)) {
  x = await x;
}

Of course then you run into the issue where the unwrapped, raw return value x also looks like a promise, and that's where the return scheme of Atomics.waitAsync can help disambiguate.

[ajklein]

I'm fairly sure CPP is not common in the JS community, and the assumption here that you're inside an async function may not always hold either. I'll also point out that the W3C TAG guidelines on using Promise in web specs suggests unconditionally returning promises.

[fgmccabe]

This is good to know, especially since I agree with this :)

[fgmccabe]

After some off-line discussions, this is how we should proceed:

1. The MAP version of the API will always return a promise. This simplifies the caller logic as well as simplifying internal handling of exceptions. Essentially, a wrapped export returns a promise: the promise will eventually be resolved with the value returned by the export; or, in the case that the export raises and exception or traps, the promise's reject function will be called.
2. In a future version of the API, depending on feedback from the user community, we will extend the API to allow an application developer to specify wether the wrapped export should always return a Promise or only do so when suspending (at least once).