diff options
| author | Alex Bradbury <asb@lowrisc.org> | 2017-08-18 05:29:21 +0000 |
|---|---|---|
| committer | Alex Bradbury <asb@lowrisc.org> | 2017-08-18 05:29:21 +0000 |
| commit | 7182440fbd11ce1c3602bafd8aaba2da765dc94b (patch) | |
| tree | 60c4df26200dea340b126bd2d29cf8883073daee /llvm/docs | |
| parent | 7eaaa0f0f2e88e6dcf6b1e92629ae0106a1fbce0 (diff) | |
| download | bcm5719-llvm-7182440fbd11ce1c3602bafd8aaba2da765dc94b.tar.gz bcm5719-llvm-7182440fbd11ce1c3602bafd8aaba2da765dc94b.zip | |
Give guidance on report_fatal_error in CodingStandards.rst and ProgrammersManual.rst
The current ProgrammersManual.rst document has a lot of well-written
documentation on error handling thanks to @lhames. It suggests errors can be
split cleanly into "programmatic" and "recoverable" errors. However, the
reality in current LLVM seems to be there are a number of cases where a
non-programmatic error is not easily recoverable. Therefore, add a note to
indicate the existence of report_fatal_error for these cases. I've also added
a reminder to CodingStandards.rst in the section on assertions, to indicate
that llvm_unreachable and assertions should not be relied upon to report
errors triggered by user input.
The ProgrammersManual is also silent on the use of LLVMContext::diagnose,
which is used in BPF+WebAssembly+AMDGPU to report some errors during
instruction selection. I don't address that in this patch, as it's not quite
clear how to fit in to the current error handling story
Differential Revision: https://reviews.llvm.org/D36826
llvm-svn: 311146
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/CodingStandards.rst | 5 | ||||
| -rw-r--r-- | llvm/docs/ProgrammersManual.rst | 8 |
2 files changed, 13 insertions, 0 deletions
diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst index fa41198755f..5ca22799191 100644 --- a/llvm/docs/CodingStandards.rst +++ b/llvm/docs/CodingStandards.rst @@ -1232,6 +1232,11 @@ builds), ``llvm_unreachable`` becomes a hint to compilers to skip generating code for this branch. If the compiler does not support this, it will fall back to the "abort" implementation. +Neither assertions or ``llvm_unreachable`` will abort the program on a release +build. If the error condition can be triggered by user input, then the +recoverable error mechanism described in :doc:`ProgrammersManual` or +``report_fatal_error`` should be used instead. + Another issue is that values used only by assertions will produce an "unused value" warning when assertions are disabled. For example, this code will warn: diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst index 7541f2eba8d..6ae72be426c 100644 --- a/llvm/docs/ProgrammersManual.rst +++ b/llvm/docs/ProgrammersManual.rst @@ -441,6 +441,14 @@ the program where they can be handled appropriately. Handling the error may be as simple as reporting the issue to the user, or it may involve attempts at recovery. +.. note:: + + Ideally, the error handling approach described in this section would be + used throughout LLVM. However, this is not yet the case. For + non-programmatic errors where the ``Error`` scheme cannot easily be + applied, ``report_fatal_error`` should be used to call any installed error + handler and then terminate the program. + Recoverable errors are modeled using LLVM's ``Error`` scheme. This scheme represents errors using function return values, similar to classic C integer error codes, or C++'s ``std::error_code``. However, the ``Error`` class is |
