From 036a8865c5f16ff5762aca339c0dc2f20310bc4b Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Fri, 18 Sep 2026 14:43:07 -0700 Subject: [PATCH] [docs] Clarify stack restoration when catching exceptions from JS Clarify that Emscripten does not automatically restore the shadow stack pointer during exception unwinding when an exception escapes into JavaScript, and that callers catching exceptions in JS must use `stackSave()` and `stackRestore()` to avoid leaking stack memory. See: #27610 --- site/source/docs/porting/exceptions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/site/source/docs/porting/exceptions.rst b/site/source/docs/porting/exceptions.rst index cfd96b506d7fc..6e0c6bcca385b 100644 --- a/site/source/docs/porting/exceptions.rst +++ b/site/source/docs/porting/exceptions.rst @@ -149,10 +149,10 @@ exception thrown``, this code will print ``MyException,My exception thrown``. true at ``-O0``. At ``-O1`` or above, you can export it separately by ``-sEXPORTED_RUNTIME_METHODS=getExceptionMessage,decrementExceptionRefcount``. -If the stack pointer has been moved due to stack allocations within the Wasm -function before an exception is thrown, you can use ``stackSave()`` and -``stackRestore()`` to restore the stack pointer so that no stack memory is -leaked. +Emscripten does not automatically restore the shadow stack pointer during +exception unwinding. Therefore, whenever you catch an exception in JavaScript +and intend to continue using the module, you should use ``stackSave()`` and +``stackRestore()`` around the call to prevent stack memory from leaking. .. note:: If you catch a Wasm exception and do not rethrow it, you need to free the storage associated with the exception in JS using