notice __cxa_init_primary_exception in suggested implementation section #176
Conversation
| Sometimes it's desirable to do p.1 and p.2 with leaving p.3 for later: this is what | ||
| <code>std::exception_ptr</code> does.<br> | ||
| To better support such use cases implementors of the ABI are encouraged to provide a | ||
| <code>__cxa_init_primary_exception</code> function, which implements p.2.<br> |
There was a problem hiding this comment.
I don't think we usually "encourage" things. We should say that systems must now provide this function, and we should caution library authors that it might not exist on older systems, and they'll need to deal with that.
| </ul> | ||
|
|
||
| Noticing the similarities of parameters of this function and <code>__cxa_throw</code>,<br> | ||
| <code>__cxa_init_primary_exception</code> is expected to be used as a subroutine of <code>__cxa_throw</code>. |
There was a problem hiding this comment.
This doesn't seem appropriate for the ABI document. The runtime can be implemented however it sees fit.
| @@ -2077,6 +2077,52 @@ <h5> 3.4.1 Allocating the Exception Object </h5> | |||
| its buffers before acquiring one. | |||
| </ul> | |||
|
|
|||
| <p> | |||
| <a name=imp-initialize></a> | |||
| <h5> 3.4.2 Initializing the Exception Object</h5> | |||
There was a problem hiding this comment.
This should go in the previous section. We don't seem to have any documentation for std::exception_ptr; we should probably add that as a new subsection. I would suggest making that section 2.6 (renumbering the existing 2.6 to 2.7), and then this can be section "2.6.1 Creating an exception object without throwing it".
The rest of the section std::exception_ptr section will be a little awkward, though, because we don't have agreement on a stable ABI for any of it. Basically, we need operations to (1) get the current exception object (for std::current_exception(), (2) manage the lifetime of an exception object (for std::exception_ptr's value operations), and (3) throw an exception object (for std::rethrow_exception). And we should also document the basic representation (just a pointer) and the relationship with the result of __cxa_init_primary_exception (it's that pointer, right?).
libc++abi provides these functions, which are collectively probably the right design:
__cxa_current_primary_exception__cxa_rethrow_primary_exception__cxa_decrement_exception_refcount__cxa_increment_exception_refcount
libsupc++'s ABI support for all this isn't really layered, though.
CC'ing @jicama
There was a problem hiding this comment.
Thanks for the guidance, I'll try to rearrange things, and do so with more mandating wording.
| <li> Allocate the memory for the exception and copy user object into that memory | ||
| <li> Set up the internal fields of the exception object | ||
| <li> Start unwinding process | ||
| </ol> |
There was a problem hiding this comment.
This is already documented. I'd just start with a clear statement like this:
<p><code>std::make_exception_ptr</code> requires a valid exception object to be created without throwing it. To do this, the implementation can follow the outline for throwing an exception above, but instead of calling `__cxa_throw` to finish the initialization of the exception, it should call:
<code><pre>
extern "C" void *__cxa_init_primary_exception (void *thrown_exception, std::type_info *tinfo, void (*dest) (void *) );
</pre></code>
You should also document the return value.
Aims to resolve #173