Add additional documentation to spawn_local

[drewcrawford]

This adds documentation to help troubleshoot why spawn_local might not work as expected.

see #2945 and chemicstry/wasm_thread#6

[daxpedda]

Events, queueMicrotask, setTimeout and Scheduler.postTask() are also affected by this so the issue isn't specific to spawn_local(). I think there needs to be a general understanding that blocking in Wasm is much more often than not a bad idea compared to native.

So its probably better to add documentation to functions that block instead to all possible functions that are affected by blocking. In the case of wasm-bindgen its js_sys::Atomics::wait*. Additionally some top-level documentation somewhere would help make this information be conveyed much more generally.

Thank you for looking into this and going through the effort of a PR!

[drewcrawford]

The issue being addressed here is not caused by blocking, so wider awareness of blocking does not address the concern.

Rather, the issue is caused by not blocking: worker threads that never block never have their tasks executed (or stop executing suddenly).

If this is not appropriate to document then the PR should be closed.

[daxpedda]

Ah, I misunderstood the original issue!

Indeed, the issue that you are talking about has nothing to do with spawn_local() or wasm_bindgen. The issue is that wasm_thread decided to close workers after the main task is finished, to more closely mimic the behavior of std::thread. So this is a documentation issue on wasm_threads side.

I thought that the issue was that blocking a worker prevents tasks spawned with spawn_local & co. to never be run. Which is indeed something related to how JS works and probably could use some documentation in wasm_bindgen. But as you said, this is unrelated to this PR.

With that said: closing this PR then.