Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

notice __cxa_init_primary_exception in suggested implementation section #176

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

notice __cxa_init_primary_exception in suggested implementation section #176

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
18b4de4
notice __cxa_init_primary_exception in suggested implementation section
itrofimow Jan 17, 2024
6afbba3
wording
itrofimow Jan 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions abi-eh.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the guidance, I'll try to rearrange things, and do so with more mandating wording.


<p>
Vaguely, the process of throwing an exception consists of
three independent parts:
<ol>
<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>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


<p>
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>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

<code><pre>
void* __cxa_init_primary_exception (void *thrown_exception, std::type_info *tinfo, void (*dest) (void *) );
</pre></code>

The arguments are:
<ul>
<p>
<li> The address of the thrown exception object
(which points to the throw value, after the header,
as specified above).
<p>
<li> A <code>std::type_info</code> pointer,
giving the static type of the throw argument
as a <code>std::type_info</code> pointer,
used for matching potential catch sites to the thrown exception.
<p>
<li> A destructor pointer to be used eventually to destroy the object.
</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>.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't seem appropriate for the ABI document. The runtime can be implemented however it sees fit.


<p>
<i>
Collaboration between <code>__cxa_init_primary_exception()</code> and
whichever way <code>std::rethrow_exception</code> is implemented is necessary to handle the p.3 (deferred unwinding).
</i>


<p>
<a name=imp-catch></a>
Expand Down