[cxx-abi-dev] Flaws in spec for __cxa_begin_catch

[Cary Coutant]

> That seems like a good strategy.  Would you care to submit a patch to 
> the ABI spec?

All right, I took a stab at it. You may want to do some wordsmithing.

-cary


*** abi-eh.html	Fri Nov 19 09:55:12 2004
--- abi-eh-041119.html	Fri Nov 19 10:49:10 2004
***************
*** 13,23 ****
   C++ ABI for Itanium: Exception Handling
   </b></i></font>

   <font size=-1>
   <p>
! <i>Revised 31 July 2001.
   <a href=#revisions>Revision history</a> at end of document.
   </i>

   </center>

--- 13,23 ----
   C++ ABI for Itanium: Exception Handling
   </b></i></font>

   <font size=-1>
   <p>
! <i>Revised 19 November 2004.
   <a href=#revisions>Revision history</a> at end of document.
   </i>

   </center>

*************** Multithreading behavior.
*** 1236,1250 ****
   <p>
   <a name=cxx-exc-object></a>
   <h5> 2.2.1  C++ Exception Objects </h5>

   <p>
! A <span class="change">complete</span>
   C++ exception object consists of a header,
   which is a wrapper around an unwind object header with additional C++
   specific information,
! followed by the <span class="change">thrown C++</span>
   exception object itself.
   The structure of the header is as follows:
   <code><pre>
         struct __cxa_exception {
   	std::type_info *	exceptionType;
--- 1236,1250 ----
   <p>
   <a name=cxx-exc-object></a>
   <h5> 2.2.1  C++ Exception Objects </h5>

   <p>
! A complete
   C++ exception object consists of a header,
   which is a wrapper around an unwind object header with additional C++
   specific information,
! followed by the thrown C++
   exception object itself.
   The structure of the header is as follows:
   <code><pre>
         struct __cxa_exception {
   	std::type_info *	exceptionType;
*************** several things are considered <i>excepti
*** 1755,1778 ****

   Most of the behavior of a handler is implementation-defined.
   However, in order to allow maintenance of the exception stack,
   all handlers must make the following calls.

   <p>
   Upon entry, a handler must call:
   <code><pre>
! 	void __cxa_begin_catch ( void *exceptionObject );
   </pre></code>
   This routine:
   <ul>
   <li> Increment's the exception's handler count.
   <li> Places the exception on the stack of currently-caught exceptions
       if it is not already there,
       linking the exception to the previous top of the stack.
   <li> Decrements the uncaught_exception count.
   </ul>

   <p>
   When the personality routine encounters a termination condition,
   it will call <code>__cxa_begin_catch()</code> to mark the exception
   as handled and then call <code>terminate()</code>,
   which shall not return to its caller.
--- 1755,1801 ----

   Most of the behavior of a handler is implementation-defined.
   However, in order to allow maintenance of the exception stack,
   all handlers must make the following calls.

+ <div class="change">
   <p>
   Upon entry, a handler must call:
   <code><pre>
! 	void *__cxa_get_exception_ptr ( void *exceptionObject );
! </pre></code>
! This routine returns the adjusted pointer to the exception object.
! (The adjusted pointer is typically computed by the personality routine
! during phase 1 and saved in the exception object.)
! </div>
!
! <p>
! <strike>Upon entry,</strike>
! <span class="change">Following initialization of the catch 
parameter,</span>
! a handler must call:
! <code><pre>
! 	void <span class="change">*</span>__cxa_begin_catch ( void 
*exceptionObject );
   </pre></code>
   This routine:
   <ul>
   <li> Increment's the exception's handler count.
   <li> Places the exception on the stack of currently-caught exceptions
       if it is not already there,
       linking the exception to the previous top of the stack.
   <li> Decrements the uncaught_exception count.
+ <li><span class="change">Returns the adjusted pointer to the 
exception object.</span>
   </ul>

+ <div class="change">
+ <p>
+ If the initialization of the catch parameter is trivial
+ (e,g., there is no formal catch parameter, or the parameter has no 
copy constructor),
+ the calls to <code>__cxa_get_exception_ptr()</code> and
+ <code>__cxa_begin_catch()</code> may be combined into a single call to
+ <code>__cxa_begin_catch()</code>.
+ </div>
+
   <p>
   When the personality routine encounters a termination condition,
   it will call <code>__cxa_begin_catch()</code> to mark the exception
   as handled and then call <code>terminate()</code>,
   which shall not return to its caller.
*************** This might be translated as follows:
*** 2253,2268 ****
--- 2276,2293 ----
   	[Cleanup code corresponding to exit of scope]
   	[enclosing the try block]
   	_Unwind_Resume();

   	H1: // Handler label
+ 	<span class="change">adjusted_exception_ptr = 
__cxa_get_exception_ptr(exception);</span>
   	[Initialize catch parameter]
   	__cxa_begin_catch(exception);
   	[User code]
   	goto R1;

   	H2:
+ 	<span class="change">adjusted_exception_ptr = 
__cxa_get_exception_ptr(exception);</span>
   	[Initialize catch parameter]
   	__cxa_begin_catch(exception);
   	[User code]
   	buz(); // Call attributes: Landing pad L2, action record A2
   	goto R1;
*************** and below.
*** 2304,2313 ****
--- 2329,2342 ----
   </font>


   <p><a name=revisions></a> <hr> <p>
   <h3> Appendix R:  Revisions </h3>
+
+ <p>
+ <font color="blue">[041119]</font>
+ Add __cxa_get_exception_ptr, add return value to __cxa_begin_catch.

   <p>
   <font color="blue">[011126]</font>
   Add __cxa_current_exception_type.