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
diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst
index 7541f2e..6ae72be 100644
--- a/llvm/docs/ProgrammersManual.rst
+++ b/llvm/docs/ProgrammersManual.rst
@@ -441,6 +441,14 @@
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