[llvm-commits] Fwd: [Patch] Exception Handling Documentation

[Chris Lattner]

On Jul 29, 2011, at 11:36 PM, Bill Wendling wrote:
>> From: Bill Wendling <bwendling at apple.com>
>> Subject: [Patch] Exception Handling Documentation
>> Date: July 29, 2011 11:23:08 PM PDT
>> To: llvm-commits at cs.uiuc.edu
>> 
>> This is the documentation for the new exception handling rewrite. It describes the new 'landingpad' and 'resume' instructions. The 'landingpad' instruction defines the values returned by the personality function. It specifies the personality function, what types the landing pad can catch, whether the landing pad is a "cleanup", and/or what types the landing pad is allowed to throw.
>> 
>> The 'resume' instruction is used to resume propagation of an existing (in-flight) exception.


+/pre>

Invalid tag.

+  <a name="i_resume">'<tt>resume</tt>' Instruction</a>

Is "resume" the final name for this instruction?


+<h5>Semantics:</h5>
+<p>The '<tt>resume</tt>' instruction resumes propagation of an existing
+   (in-flight) exception.</p>


+<h5>Overview:</h5>
+<p>The '<tt>resume</tt>' instruction is a terminator instruction that has no
+   successors. Its operand must have the same type as the result of any
+   '<tt>landingpad</tt>' instruction in the same function.</p>

Please split this up into overview/arguments sections like the other instructions.

-> "...an existing in-flight exception whose unwinding was interrupted with a <a href="#i_landingpad">landing pad</a> instruction."


+  clause := catch <ty> {, <ty>}*
+  clause := filter <ty> {, <ty>}*

"ty" and "somety" imply an LLVM type, not a global variable.  Also, don't you require a type on the global variable?  Something like "catch i32* @G" is what you're going for, right?



"is used to specify a basic block"
-> "is used to specify that a basic block"


"is a landing pad." -> This is self referential.  You need to explain what a landing pad is, otherwise the only people that can understand this are people who already know what it does.

I would suggest adding a few paragraphs describing how EH in LLVM works to the "High Level Structure" section, probably right before "Pointer Aliasing Rules".  You can then link to it from resume/landingpad/invoke.  Here's a start:


When an exception is thrown by a runtime system, it walks up the stack looking for frames that may potentially handle it.  These frames are indicated by having call sites formed with '<a>invoke' instructions.  When the runtime system finds a frame that has an invoke in it, it transfers control flow into the function, at the point of a landingpad instruction....

This also gives you a place to put a (SIMPLE!) example or two, which is essential.


<p>There are several restrictions:</p>

This should be in the semantics section.


+</div>
+
+</div>
+
+</div>

Not sure what is going on here.


You need to improve the i_invoke section to describe its relation to landingpad.

-Chris