[clang] [llvm] [mlir] [ErrorHandling] Add reportFatalInternalError + reportFatalUsageError (NFC) (PR #138251)

[Mehdi Amini via cfe-commits]

================
@@ -59,22 +59,42 @@ namespace llvm {
     ~ScopedFatalErrorHandler() { remove_fatal_error_handler(); }
   };
 
-/// Reports a serious error, calling any installed error handler. These
-/// functions are intended to be used for error conditions which are outside
-/// the control of the compiler (I/O errors, invalid user input, etc.)
-///
-/// If no error handler is installed the default is to print the message to
-/// standard error, followed by a newline.
-/// After the error handler is called this function will call abort(), it
-/// does not return.
-/// NOTE: The std::string variant was removed to avoid a <string> dependency.
+/// @deprecated Use reportFatalInternalError() or reportFatalUsageError()
+/// instead.
 [[noreturn]] void report_fatal_error(const char *reason,
                                      bool gen_crash_diag = true);
 [[noreturn]] void report_fatal_error(StringRef reason,
                                      bool gen_crash_diag = true);
 [[noreturn]] void report_fatal_error(const Twine &reason,
                                      bool gen_crash_diag = true);
 
+/// Report a fatal error that likely indicates a bug in LLVM. It serves a
+/// similar purpose as an assertion, but is always enabled, regardless of the
+/// value of NDEBUG.
+///
+/// This will call installed error handlers (or print the message by default)
+/// and then abort. This will produce a crash trace and *will* ask users to
+/// report an LLVM bug.
+[[noreturn]] void reportFatalInternalError(const char *reason);
+[[noreturn]] void reportFatalInternalError(StringRef reason);
+[[noreturn]] void reportFatalInternalError(const Twine &reason);
+
+/// Report a fatal error that does not indicate a bug in LLVM, in contexts
+/// where a more sophisticated error reporting mechanism (such as Error/Expected
+/// or DiagnosticInfo) is not supported.
+///
+/// Examples where this function should be used instead of
+/// reportFatalInternalError() include invalid inputs or options, but also
+/// environment error conditions outside LLVM's control. It should also be used
+/// for known unsupported/unimplemented functionality.
----------------
joker-eph wrote:

Important aspect of this edit:

- Using error reporting APIs is the normal flow, not the exotic one. So the current language saying "more sophisticated error reporting mechanism" can be misleading. It is the "a proper error reporting mechanism".
-  The "with an existing API" acknowledges the difference between introducing a new API and implementing something within an existing one. For example implementing a subclass and specializing virtual method: updating the base class can be very involved if it wasn't originally designed to be able to fail.
- Use "may" instead of "should": none of these examples are "should": an API that can return an error is always preferred. 

https://github.com/llvm/llvm-project/pull/138251