static/README.wasm.md | 25 +++++++++++++++++++++++++
1 file changed, 25 insertions(+)
New commits:
commit 5b1df7709d75c6dd993da5a272e7e37e55a70174
Author: Stephan Bergmann <stephan.bergm...@allotropia.de>
AuthorDate: Wed Jul 24 17:26:46 2024 +0200
Commit: Stephan Bergmann <stephan.bergm...@allotropia.de>
CommitDate: Wed Jul 24 22:15:08 2024 +0200
Document the Emscripten threads issue
Change-Id: Ia26b48d46283a9528a665eb5028bd5b9bd0dd953
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/170972
Tested-by: Jenkins
Reviewed-by: Stephan Bergmann <stephan.bergm...@allotropia.de>
diff --git a/static/README.wasm.md b/static/README.wasm.md
index 54efd7ac4636..4aa2f592e6ef 100644
--- a/static/README.wasm.md
+++ b/static/README.wasm.md
@@ -337,6 +337,31 @@ Emscripten supports standalone WASI binaries:
-
<https://emscripten.org/docs/introducing_emscripten/about_emscripten.html#about-emscripten-porting-code>
- <https://emscripten.org/docs/compiling/Building-Projects.html>
+### Threads and the event loop
+
+The Emscripten emulation of pthreads requires the JS main thread event loop to
be able to promptly
+respond both when spawning and when exiting a pthread. But the Qt5 event loop
runs on the JS main
+thread, so the JS main thread event loop is blocked while a LO VCL Task is
executed. And our
+pthreads are typically spawned and joined from within such Task executions,
which means that the JS
+main thread event loop is not available to reliably perform those Emscripten
pthread operations.
+
+For pthread spawning, the solution is to set -sPTHREAD_POOL_SIZE to a
sufficiently large value, so
+that each of our pthread spawning requests during an inappropriate time finds
a pre-spawned JS
+Worker available.
+
+There are patterns (like, at the time of writing this, the
configmgr::Components::WriteThread) where
+a pthread can get spawned and joined and then re-spawned (and re-joined)
multiple times during a
+single VCL Task execution (i.e., without the JS main thread event loop having
a chance to get in
+between any of those operations). But as the underlying Emscripten ptherad
exiting operations will
+therefore queue up, the pthread spawning operations will eventually run out of
-sPTHREAD_POOL_SIZE
+pre-spawned JS Workers. The solution here is to change our pthread usage
patterns accordingly, so
+that such pthreads are rather kept running than being joined and re-spawned.
+
+(-sPROXY_TO_PTHREAD would move the Qt5 event loop off the JS main thread,
which should elegantly
+solve all of the above issues. But Qt5 just doesn't appear to be prepared to
run on anything but
+the JS main thread; e.g., it tries to access the global JS `window` object in
various places, which
+is available on the JS main thread but not in a JS Worker.)
+
## Building headless LibreOffice as WASM for use in another product
### Set up Emscripten
