Skip to content

[ProgrammersManual] Update report_fatal_error docs #138502

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

Merged
merged 1 commit into from
May 6, 2025
Merged

[ProgrammersManual] Update report_fatal_error docs #138502

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
15 changes: 12 additions & 3 deletions llvm/docs/ProgrammersManual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -437,6 +437,15 @@ that should never be entered if the program invariants hold:
llvm_unreachable("X should be Foo or Bar here");
}

Additionally, ``reportFatalInternalError`` can be used to report invariant
violations even in builds that do not enable assertions:

.. code-block:: c++

if (VerifyFooAnalysis && !Foo.verify()) {
reportFatalInternalError("Analysis 'foo' not preserved");
}

Copy link
Contributor

Choose a reason for hiding this comment

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

I think it would be helpful to additionally say "This will produce a crash trace and will ask users to report an LLVM bug." as you do in the doc comment in the header. But this is a non-blocking suggestion.

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 in a section about assertions, if you want to include this I don't think it should single out this API but be explicit around line 419.

Copy link
Contributor

Choose a reason for hiding this comment

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

Ack, good point about the surrounding context. I think more detail on exactly what reportFatalInternalError does would be helpful, but I agree the section in general could be made more explicit. Probably makes more sense as a separate PR then.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think this section in general needs some more information on what these APIs do under different build options. E.g. for llvm_unreachable() we have three different behaviors based on the value of LLVM_ENABLE_ASSERTIONS and LLVM_UNREACHABLE_OPTIMIZE. It will either abort with a crash trace, aggressively optimize away the unreachable path or produce a trap. (Which means that llvm_unreachable can be both weaker and stronger than plain assert...)

Recoverable Errors
^^^^^^^^^^^^^^^^^^

Expand All @@ -452,9 +461,9 @@ recovery.
While it would be ideal to use this error handling scheme throughout
LLVM, there are places where this hasn't been practical to apply. In
situations where you absolutely must emit a non-programmatic error and
the ``Error`` model isn't workable you can call ``report_fatal_error``,
which will call installed error handlers, print a message, and abort the
program. The use of `report_fatal_error` in this case is discouraged.
the ``Error`` model isn't workable you can call ``reportFatalUsageError``,
which will call installed error handlers, print a message, and exit the
program. The use of `reportFatalUsageError` in this case is discouraged.

Recoverable errors are modeled using LLVM's ``Error`` scheme. This scheme
represents errors using function return values, similar to classic C integer
Expand Down
Loading