llvm.org GIT mirror llvm / 95e9730
Exception handling docs: Describe landingpad clauses' meanings in more detail The original text is very terse, so I've expanded on it. Specifically, in the original text: * "The selector value is a positive number if the exception matched a type info" -- It wasn't clear that this meant "if the exception matched a 'catch' clause". * "If nothing is matched, the behavior of the program is `undefined`_." -- It's actually implementation-defined in C++ rather than undefined, as the new text explains. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@202209 91177308-0d34-0410-b5e6-96231b3b80d8 Mark Seaborn 5 years ago
1 changed file(s) with 55 addition(s) and 6 deletion(s). Raw diff Collapse all Expand all
156156 The ``landingpad`` instruction takes a reference to the personality function to
157157 be used for this ``try``/``catch`` sequence. The remainder of the instruction is
158158 a list of *cleanup*, *catch*, and *filter* clauses. The exception is tested
159 against the clauses sequentially from first to last. The selector value is a
160 positive number if the exception matched a type info, a negative number if it
161 matched a filter, and zero if it matched a cleanup. If nothing is matched, the
162 behavior of the program is `undefined`_. If a type info matched, then the
163 selector value is the index of the type info in the exception table, which can
164 be obtained using the `llvm.eh.typeid.for`_ intrinsic.
159 against the clauses sequentially from first to last. The clauses have the
160 following meanings:
161
162 - ``catch @ExcType``
163
164 - This clause means that the landingpad block should be entered if the
165 exception being thrown is of type ``@ExcType`` or a subtype of
166 ``@ExcType``. For C++, ``@ExcType`` is a pointer to the ``std::type_info``
167 object (an RTTI object) representing the C++ exception type.
168
169 - If ``@ExcType`` is ``null``, any exception matches, so the landingpad
170 should always be entered. This is used for C++ catch-all blocks ("``catch
171 (...)``").
172
173 - When this clause is matched, the selector value will be equal to the value
174 returned by "``@llvm.eh.typeid.for(i8* @ExcType)``". This will always be a
175 positive value.
176
177 - ``filter [ @ExcType1, ..., @ExcTypeN]``
178
179 - This clause means that the landingpad should be entered if the exception
180 being thrown does *not* match any of the types in the list (which, for C++,
181 are again specified as ``std::type_info`` pointers).
182
183 - C++ front-ends use this to implement C++ exception specifications, such as
184 "``void foo() throw (ExcType1, ..., ExcTypeN) { ... }``".
185
186 - When this clause is matched, the selector value will be negative.
187
188 - The array argument to ``filter`` may be empty; for example, "``[0 x i8**]
189 undef``". This means that the landingpad should always be entered. (Note
190 that such a ``filter`` would not be equivalent to "``catch i8* null``",
191 because ``filter`` and ``catch`` produce negative and positive selector
192 values respectively.)
193
194 - ``cleanup``
195
196 - This clause means that the landingpad should always be entered.
197
198 - C++ front-ends use this for calling objects' destructors.
199
200 - When this clause is matched, the selector value will be zero.
201
202 - The runtime may treat "``cleanup``" differently from "``catch
203 null``".
204
205 In C++, if an unhandled exception occurs, the language runtime will call
206 ``std::terminate()``, but it is implementation-defined whether the runtime
207 unwinds the stack and calls object destructors first. For example, the GNU
208 C++ unwinder does not call object destructors when an unhandled exception
209 occurs. The reason for this is to improve debuggability: it ensures that
210 ``std::terminate()`` is called from the context of the ``throw``, so that
211 this context is not lost by unwinding the stack. A runtime will typically
212 implement this by searching for a matching non-``cleanup`` clause, and
213 aborting if it does not find one, before entering any landingpad blocks.
165214
166215 Once the landing pad has the type info selector, the code branches to the code
167216 for the first catch. The catch then checks the value of the type info selector