Skip to content

Commit 9a7230f

Browse files
authored
[EH] Rename EH library functions in JS (#17183)
Terms like 'object' and 'value' were used interchangeably and inconsistently, causing confusion. This tries to make it more consistent. - Thrown object: A user-thrown value in C++, which is a C++ pointer. When you do `throw 3;`, libc++abi allocates a storage to store an exception and store that value '3' within that storage. This is the pointer to that location. This is consistent with the term used by libc++abi; which also calls the pointer 'thrown object'. Emscripten EH throws this directly, so you get this value right away when you catch an exception with JS `catch`. In Wasm EH, which uses libc++abi, this is not the value libc++abi actually throws. See below. - Unwind header: The pointer that actually gets thrown in libc++abi. This pointer preceeds the thrown object: https://github.com/emscripten-core/emscripten/blob/24f765dc3545e89f232c9f8503f6426055271628/system/lib/libcxxabi/src/cxa_exception.cpp#L26-L28 This is an internal detail of libc++abi so we don't want to expose this to users. Emscripten EH doesn't use this concept. - WebAssembly exception: A native Wasm exception, represented by `WebAssembly.Exception` JS object. This is what is actually gets thrown from Wasm `throw` instruction. libunwind receives the unwind header pointer (see above) from libc++abi, and create an `WebAssembly.Exception` object and package the received value with the C++ exception tag, and throws it. So this is what you get when you catch a Wasm exception with JS `catch`. Relevant previous discussion: #17157 (review)
1 parent 47ca906 commit 9a7230f

File tree

1 file changed

+18
-13
lines changed

1 file changed

+18
-13
lines changed

src/library_exceptions.js

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -398,31 +398,36 @@ var LibraryExceptions = {
398398
return Module['asm']['__cpp_exception'];
399399
},
400400

401-
$getCppExceptionThrownValue__deps: ['$getCppExceptionTag', '__thrown_object_from_unwind_exception'],
402-
$getCppExceptionThrownValue: function(ex) {
401+
// Given an WebAssembly.Exception object, returns the actual user-thrown
402+
// C++ object address in the Wasm memory.
403+
// WebAssembly.Exception is a JS object representing a Wasm exception,
404+
// provided by Wasm JS API:
405+
// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Exception
406+
$getCppExceptionThrownObjectFromWebAssemblyException__deps: ['$getCppExceptionTag', '__thrown_object_from_unwind_exception'],
407+
$getCppExceptionThrownObjectFromWebAssemblyException: function(ex) {
403408
// In Wasm EH, the value extracted from WebAssembly.Exception is a pointer
404409
// to the unwind header. Convert it to the actual thrown value.
405-
var unwind_ex = ex.getArg(getCppExceptionTag(), 0);
406-
return ___thrown_object_from_unwind_exception(unwind_ex);
410+
var unwind_header = ex.getArg(getCppExceptionTag(), 0);
411+
return ___thrown_object_from_unwind_exception(unwind_header);
407412
},
408413

409-
$incrementExceptionRefcount__deps: ['__cxa_increment_exception_refcount', '$getCppExceptionThrownValue'],
410-
$incrementExceptionRefcount: function(obj) {
411-
var ptr = getCppExceptionThrownValue(obj);
414+
$incrementExceptionRefcount__deps: ['__cxa_increment_exception_refcount', '$getCppExceptionThrownObjectFromWebAssemblyException'],
415+
$incrementExceptionRefcount: function(ex) {
416+
var ptr = getCppExceptionThrownObjectFromWebAssemblyException(ex);
412417
___cxa_increment_exception_refcount(ptr);
413418
},
414419

415-
$decrementExceptionRefcount__deps: ['__cxa_decrement_exception_refcount', '$getCppExceptionThrownValue'],
416-
$decrementExceptionRefcount: function(obj) {
417-
var ptr = getCppExceptionThrownValue(obj);
420+
$decrementExceptionRefcount__deps: ['__cxa_decrement_exception_refcount', '$getCppExceptionThrownObjectFromWebAssemblyException'],
421+
$decrementExceptionRefcount: function(ex) {
422+
var ptr = getCppExceptionThrownObjectFromWebAssemblyException(ex);
418423
___cxa_decrement_exception_refcount(ptr);
419424
},
420425

421-
$getExceptionMessage__deps: ['__get_exception_message', 'free', '$getCppExceptionThrownValue'],
422-
$getExceptionMessage: function(obj) {
426+
$getExceptionMessage__deps: ['__get_exception_message', 'free', '$getCppExceptionThrownObjectFromWebAssemblyException'],
427+
$getExceptionMessage: function(ex) {
423428
// In Wasm EH, the thrown object is a WebAssembly.Exception. Extract the
424429
// thrown value from it.
425-
var ptr = getCppExceptionThrownValue(obj);
430+
var ptr = getCppExceptionThrownObjectFromWebAssemblyException(ex);
426431
var utf8_addr = ___get_exception_message(ptr);
427432
var result = UTF8ToString(utf8_addr);
428433
_free(utf8_addr);

0 commit comments

Comments
 (0)