1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
.. _exceptions:
======================
C++ Exceptions Support
======================
By default, exception catching is disabled in Emscripten. For example, if you
compile the following program:
.. code-block:: cpp
#include <stdio.h>
int main() {
try {
puts("throw...");
throw 1;
puts("(never reached)");
} catch(...) {
puts("catch!");
}
return 0;
}
The first ``throw`` will abort the program and you'll see something like this in
the output:
.. code-block:: text
throw...
Aborted(Assertion failed: Exception thrown, but exception catching is not enabled. Compile with -sNO_DISABLE_EXCEPTION_CATCHING or -sEXCEPTION_CATCHING_ALLOWED=[..] to catch.)
If you want to opt-in, you have two following options.
.. _javascript-based-exception-support:
Emscripten (JavaScript-based) Exception Support
===============================================
First, you can enable exceptions via Emscripten's JavaScript-based support. To
enable it, pass ``-fexceptions`` at both compile time and link time.
When you rebuild the example above with this flag, the output will change to:
.. code-block:: text
throw...
catch!
Note that this option has relatively high overhead, but it will work on all
JavaScript engines with WebAssembly support. You can reduce the overhead by
specifying a list of allowed functions in which exceptions are enabled, see the
``EXCEPTION_CATCHING_ALLOWED`` setting.
.. _webassembly-exception-handling-based-support:
WebAssembly Exception Handling-based Support
============================================
Alternatively, you can opt-in to the `native WebAssembly exception handling
<https://github.com/WebAssembly/exception-handling/blob/master/proposals/exception-handling/Exceptions.md>`_
proposal. To enable it, pass ``-fwasm-exceptions`` at both compile time and link
time.
Rebuilding the example with this flag will result in the same output as with
``-fexceptions`` above:
.. code-block:: text
throw...
catch!
This option leverages a new feature that brings built-in instructions for
throwing and catching exceptions to WebAssembly. As a result, it can reduce code
size and performance overhead compared to the JavaScript-based implementation.
This option is currently supported in several major web browsers, but `may not
be supported in all WebAssembly engines yet
<https://webassembly.org/roadmap/>`_.
Debugging Exceptions
====================
Stack Traces
------------
For :ref:`native Wasm exceptions
<webassembly-exception-handling-based-support>`, when :ref:`ASSERTIONS
<debugging-ASSERTIONS>` is enabled, uncaught exceptions will print stack traces
for debugging. :ref:`ASSERTIONS <debugging-ASSERTIONS>` is enabled by default
in :ref:`-O0 <emcc-O0>` and disabled in optimized builds (:ref:`-O1 <emcc-O1>`
and above). You can enable it by passing ``-sASSERTIONS`` to the ``emcc``
command line in optimized builds as well. To display Wasm function names in
stack traces, you also need :ref:`--profiling-funcs <emcc-profiling-funcs>`
(or :ref:`-g <emcc-g>` or :ref:`-gsource-map<emcc-gsource-map>`).
In JavaScript, you can also examine the stack traces using
`WebAssembly.Exception.prototype.stack
<https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Exception/stack>`_
property. For example:
.. code-block:: javascript
try {
... // some code that calls WebAssembly
} catch (e) {
// Do something with e.stack
console.log(e.stack);
}
Stack traces within Wasm code are not supported in :ref:`JavaScript-based
exceptions <javascript-based-exception-support>`.
.. _handling-c-exceptions-from-javascript:
Handling C++ Exceptions from JavaScript
---------------------------------------
You can also catch and examine the type and the message of C++ exceptions from
JavaScript, in case they inherit from ``std::exception`` and thus have ``what``
method.
``getExceptionMessage`` returns a list of two strings: ``[type, message]``. the
``message`` is the result of calling ``what`` method in case the exception is a
subclass of ``std::exception``. Otherwise it will be just an empty string.
.. code-block:: javascript
var sp = stackSave();
try {
... // some code that calls WebAssembly
} catch (e) {
stackRestore(sp);
console.log(getExceptionMessage(e).toString());
} finally {
...
}
In case the thrown value is an integer 3, this will print ``int,``, because the
message part is empty. If the thrown value is an instance of ``MyException``
that is a subclass of ``std::exception`` and its ``what`` message is ``My
exception thrown``, this code will print ``MyException,My exception thrown``.
To use this function, you need to pass ``-sEXPORT_EXCEPTION_HANDLING_HELPERS``
to the options. You need to enable either of Emscripten EH or Wasm EH to use
this option.
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.
.. 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
``decrementExceptionRefcount`` method because the exception
catching code in Wasm does not have a chance to free it. But currently due to
an implementation issue that Wasm EH and Emscripten (JS-based) EH, you need
to call incrementExceptionRefcount additionally in case of Emscripten EH. See
https://github.com/emscripten-core/emscripten/issues/17115 for details and a
code example.
.. todo:: Fix the above-mentinoed `inconsistency
<https://github.com/emscripten-core/emscripten/issues/17115>`_ between Wasm
EH and Emscripten EH, on the reference counting.
Using Exceptions and setjmp-longjmp Together
============================================
See :ref:`using-exceptions-and-setjmp-longjmp-together`.
|
