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

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@311146 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst
index fa41198755fd74df7ca6b49aafc589eaf7a5ca33..5ca22799191a5ea4be5121c38af8fdf15472f8ed 100644 (file)
--- a/docs/CodingStandards.rst
+++ b/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/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst
index 7541f2eba8d2904fa9965e13917d0ec3b4adcedb..6ae72be426c24b0cbf790d1ac531bba2f1f6f16e 100644 (file)
--- a/docs/ProgrammersManual.rst
+++ b/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