Mention missing multi-threading/processing in faq and new-packages docs (pyodide#5287)

Author: alarmfox

docs/development/new-packages.md

@@ -17,6 +17,22 @@ Most pure Python packages can be installed directly from PyPI with
 {func}`micropip.install` if they have a pure Python wheel. Check if this is the
 case by trying `micropip.install("package-name")`.
 
+Because Pyodide [does not support threading or multiprocessing](https://pyodide.org/en/stable/usage/wasm-constraints.html),
+packages that use threading or multiprocessing will not work without a patch to disable it. For example,
+the following snippet will determine if the platform supports creating new threads.
+
+```py
+def _can_start_thread() -> bool:
+    if sys.platform == "emscripten":
+        return sys._emscripten_info.pthreads
+    return platform.machine() not in ("wasm32", "wasm64")
+
+can_start_thread = _can_start_thread()
+
+if not can_start_thread:
+  n_threads = 1
+```
+
 If there is no wheel on PyPI, but you believe there is nothing preventing it (it
 is a Python package without C extensions):
 

docs/usage/faq.md

@@ -469,3 +469,47 @@ pyodide.runPython(`
     print(js_lambda, js_lambda_, js_lambda__) # 7, 7, 8
 `);
 ```
+
+## Can I use threading/multiprocessing/subprocess?
+
+No, fork and pthreads do not work in Pyodide (see more [here](https://pyodide.org/en/stable/usage/wasm-constraints.html)).
+Attempts to use `threading`, `multiprocessing`, or `subprocess` will raise a `RuntimeError`.
+You may be able to work around this by setting the number of threads to 1:
+
+```py
+def _can_start_thread() -> bool:
+    if sys.platform == "emscripten":
+        return sys._emscripten_info.pthreads
+    return platform.machine() not in ("wasm32", "wasm64")
+
+can_start_thread = _can_start_thread()
+
+if not can_start_thread:
+  n_threads = 1
+```
+
+You can still import the packages and use the general info API, but you cannot
+start any asynchronous work without receiving a `RuntimeError`.
+
+```pycon
+>>> import threading
+>>> current = threading.current_thread()
+>>> current.name
+'MainThread'
+>>> current.daemon
+False
+>>> current.is_alive()
+True
+>>> def target(nums):
+...     print(sum(nums))
+...
+>>> t = threading.Thread(target=target, args=([1, 2, 3], ))
+>>> t.run()
+6
+>>> t.start()
+Traceback (most recent call last):
+  File "<console>", line 1, in <module>
+  File "/lib/python312.zip/threading.py", line 994, in start
+    _start_new_thread(self._bootstrap, ())
+RuntimeError: can't start new thread
+```