From 9ba09ef20f37a1c5461c2dd6ce6ae389fed3cf11 Mon Sep 17 00:00:00 2001
From: Cheng Shao <terrorjack@type.dance>
Date: Sun, 16 Mar 2025 13:38:20 +0000
Subject: [PATCH] docs: document the wasm backend promise.throwTo() feature

(cherry picked from commit afdd3fe7fff60e046f6a3ee4795c58abe81f03a2)
(cherry picked from commit f4d2149089cffaa1d8309271013bc686584d7789)
---
 docs/users_guide/wasm.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/users_guide/wasm.rst b/docs/users_guide/wasm.rst
index 40335bb322e..a4619261c28 100644
--- a/docs/users_guide/wasm.rst
+++ b/docs/users_guide/wasm.rst
@@ -715,3 +715,14 @@ JavaScript.
 Finally, in JavaScript, you can use ``await __exports.my_func()`` to
 call your exported ``my_func`` function and get its result, pass
 arguments, do error handling, etc etc.
+
+For each async export, the returned ``Promise`` value contains a
+``promise.throwTo()`` callback. The value passed to
+``promise.throwTo()`` will be wrapped as a ``JSException`` and raised
+as an async exception in that thread. This can be useful for
+interrupting Haskell computation in JavaScript. ``promise.throwTo()``
+doesn't block the JavaScript caller like Haskell ``throwTo``. It
+doesn't necessarily result in ``promise`` being rejected since the
+Haskell thread can handle the async exception, and it can be called
+multiple time. It has no effect when the respective Haskell thread has
+already run to completion.
-- 
GitLab