README needs clarification, Limitations / FAQ

[deavid]

While reading the README.md I still have basically two questions:

1. Does this crate really allow for multithreading on WASM targets, despite Bevy does not support this at the moment?

2. What are the limitations of this crate? Can you do anything you want? Can you access ECS inside the thread? Resources?

So, in general, I am asking to update the README in the following way:

1. State more clearly what kind of parallelism this enables in WASM
2. Specify/make it clear what this does in contrast with regular Bevy.
3. Add some Limitations section or FAQ section to explain what is this crate good for and not so good for.

Otherwise anyone interested on anything remotely similar has to guess and try for themselves, spending hours to find out if their use case is supported or not.

[nuzzles]

While reading the README.md I still have basically two questions:

1. Does this crate really allow for multithreading on WASM targets, despite Bevy does not support this at the moment?

2. What are the limitations of this crate? Can you do anything you want? Can you access ECS inside the thread? Resources?

So, in general, I am asking to update the README in the following way:

1. State more clearly what kind of parallelism this enables in WASM

2. Specify/make it clear what this does in contrast with regular Bevy.

3. Add some Limitations section or FAQ section to explain what is this crate good for and not so good for.

Otherwise anyone interested on anything remotely similar has to guess and try for themselves, spending hours to find out if their use case is supported or not.

I'm open to changing the README and I'm open to accepting MRs as well.

This crate primarily provides 2 capabilities - Receiving results from background tasks and handling timeouts the same way for Web and Native.

The crate gives you system parameters, e.g. TaskRunner and TaskPool, which are system parameters like any other (e.g. Local).

The TaskRunner system parameter is generic over whatever you wish to compute in the background, and it uses oneshot channels to send the result back. This is something absolutely missing from bevy - the ability to get a result back from a task sent to the AsyncComputeTaskPool in bevy (all tasks spawned on the bevy task pool must be a future that outputs ()). Something else that is absolutely missing is the ability to handle tasks with timeouts on WASM, which we provide.

Under the hood, we build directly over bevy's AsyncComputeTaskPool, which itself is built over async-executor (the same authors of smol). This crate does not bring in any advanced feature support for experimental wasm-threading or heavy dependencies. bevy_async_task is designed as a small utility library to spawn, poll, and receive results within the same system without blocking the main thread.

I actually have no idea how this is done within the context of smol/async-executor/AsyncComputeTaskPool on WASM - I'm guessing it's a simple promise that is spawned in JavaScript and "ticked" independently when asked, such as the next system run. Either way, it feels like multi-threading and doesn't block.

[nuzzles]

If you want to know the impetus of why I created this crate, it's because I'm building a web game that needed to run networking tasks (e.g. Login and get my account) which meant I needed to wait on a networking call, return the response, and add a timeout to prevent infinite waiting.

[deavid]

Okay, in my case is because I have heavy CPU computations on the game that currently are single thread, and as I have no threads for WASM I have to make all my heavy systems to finish serialized before 1 frame.

My interest here was if this would be able to use more than 1 thread in WASM to send compute heavy operations, and I am okay even if I need to collect the results on the next frame.

But from what you explain, you also depend on WASM support on Bevy, which means that this crate gives concurrency but no parallelism in WASM - that would probably change once Bevy sorts that out. So this isn't useful for my use case.

However, it's nice to know that you are using this for login/auth purposes. I'll remember this if I need to implement something similar in the future.

[nuzzles]

Okay, in my case is because I have heavy CPU computations on the game that currently are single thread, and as I have no threads for WASM I have to make all my heavy systems to finish serialized before 1 frame.

My interest here was if this would be able to use more than 1 thread in WASM to send compute heavy operations, and I am okay even if I need to collect the results on the next frame.

But from what you explain, you also depend on WASM support on Bevy, which means that this crate gives concurrency but no parallelism in WASM - that would probably change once Bevy sorts that out. So this isn't useful for my use case.

However, it's nice to know that you are using this for login/auth purposes. I'll remember this if I need to implement something similar in the future.

Yes, this matches my understanding. I actually don't know if Bevy uses web workers under the hood, so there could be some (crappy) parallelism happening.

It seems wasm-threads are mostly stable? (https://caniuse.com/wasm-threads)
I'd recommend a raising an issue in Bevy to enable wasm threading in their task pooling, but if it's taking too slow or there's a desire to push that work here, I am willing to improve bevy_async_task with wasm-threads.

[deavid]

I already pushed them today in bevyengine/bevy#4078 but I don't have hopes for this happening in any substance in 2025 or 2026.

If you think you can make it work, I would appreciate. I'm sure a lot of people would come to this crate too to get multicore performance for WASM.