contrib/llvm-project/lld/include/lld/Common/ErrorHandler.h

   1 //===- ErrorHandler.h -------------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // We designed lld's error handlers with the following goals in mind:
  10 //
  11 //  - Errors can occur at any place where we handle user input, but we don't
  12 //    want them to affect the normal execution path too much. Ideally,
  13 //    handling errors should be as simple as reporting them and exit (but
  14 //    without actually doing exit).
  15 //
  16 //    In particular, the design to wrap all functions that could fail with
  17 //    ErrorOr<T> is rejected because otherwise we would have to wrap a large
  18 //    number of functions in lld with ErrorOr. With that approach, if some
  19 //    function F can fail, not only F but all functions that transitively call
  20 //    F have to be wrapped with ErrorOr. That seemed too much.
  21 //
  22 //  - Finding only one error at a time is not sufficient. We want to find as
  23 //    many errors as possible with one execution of the linker. That means the
  24 //    linker needs to keep running after a first error and give up at some
  25 //    checkpoint (beyond which it would find cascading, false errors caused by
  26 //    the previous errors).
  27 //
  28 //  - We want a simple interface to report errors. Unlike Clang, the data we
  29 //    handle is compiled binary, so we don't need an error reporting mechanism
  30 //    that's as sophisticated as the one that Clang has.
  31 //
  32 // The current lld's error handling mechanism is simple:
  33 //
  34 //  - When you find an error, report it using error() and continue as far as
  35 //    you can. An internal error counter is incremented by one every time you
  36 //    call error().
  37 //
  38 //    A common idiom to handle an error is calling error() and then returning
  39 //    a reasonable default value. For example, if your function handles a
  40 //    user-supplied alignment value, and if you find an invalid alignment
  41 //    (e.g. 17 which is not 2^n), you may report it using error() and continue
  42 //    as if it were alignment 1 (which is the simplest reasonable value).
  43 //
  44 //    Note that you should not continue with an invalid value; that breaks the
  45 //    internal consistency. You need to maintain all variables have some sane
  46 //    value even after an error occurred. So, when you have to continue with
  47 //    some value, always use a dummy value.
  48 //
  49 //  - Find a reasonable checkpoint at where you want to stop the linker, and
  50 //    add code to return from the function if errorCount() > 0. In most cases,
  51 //    a checkpoint already exists, so you don't need to do anything for this.
  52 //
  53 // This interface satisfies all the goals that we mentioned above.
  54 //
  55 // You should never call fatal() except for reporting a corrupted input file.
  56 // fatal() immediately terminates the linker, so the function is not desirable
  57 // if you are using lld as a subroutine in other program, and with that you
  58 // can find only one error at a time.
  59 //
  60 // warn() doesn't do anything but printing out a given message.
  61 //
  62 // It is not recommended to use llvm::outs() or llvm::errs() directly in lld
  63 // because they are not thread-safe. The functions declared in this file are
  64 // thread-safe.
  65 //
  66 //===----------------------------------------------------------------------===//
  67
  68 #ifndef LLD_COMMON_ERRORHANDLER_H
  69 #define LLD_COMMON_ERRORHANDLER_H
  70
  71 #include "lld/Common/LLVM.h"
  72
  73 #include "llvm/ADT/STLExtras.h"
  74 #include "llvm/Support/Error.h"
  75 #include "llvm/Support/FileOutputBuffer.h"
  76
  77 namespace llvm {
  78 class DiagnosticInfo;
  79 }
  80
  81 namespace lld {
  82
  83 class ErrorHandler {
  84 public:
  85   uint64_t errorCount = 0;
  86   uint64_t errorLimit = 20;
  87   StringRef errorLimitExceededMsg = "too many errors emitted, stopping now";
  88   StringRef logName = "lld";
  89   llvm::raw_ostream *errorOS = &llvm::errs();
  90   bool colorDiagnostics = llvm::errs().has_colors();
  91   bool exitEarly = true;
  92   bool fatalWarnings = false;
  93   bool verbose = false;
  94   bool vsDiagnostics = false;
  95
  96   void error(const Twine &msg);
  97   LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg);
  98   void log(const Twine &msg);
  99   void message(const Twine &msg);
 100   void warn(const Twine &msg);
 101
 102   std::unique_ptr<llvm::FileOutputBuffer> outputBuffer;
 103
 104 private:
 105   void printHeader(StringRef s, raw_ostream::Colors c, const Twine &msg);
 106 };
 107
 108 /// Returns the default error handler.
 109 ErrorHandler &errorHandler();
 110
 111 inline void error(const Twine &msg) { errorHandler().error(msg); }
 112 inline LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg) {
 113   errorHandler().fatal(msg);
 114 }
 115 inline void log(const Twine &msg) { errorHandler().log(msg); }
 116 inline void message(const Twine &msg) { errorHandler().message(msg); }
 117 inline void warn(const Twine &msg) { errorHandler().warn(msg); }
 118 inline uint64_t errorCount() { return errorHandler().errorCount; }
 119
 120 LLVM_ATTRIBUTE_NORETURN void exitLld(int val);
 121
 122 void diagnosticHandler(const llvm::DiagnosticInfo &di);
 123 void checkError(Error e);
 124
 125 // check functions are convenient functions to strip errors
 126 // from error-or-value objects.
 127 template <class T> T check(ErrorOr<T> e) {
 128   if (auto ec = e.getError())
 129     fatal(ec.message());
 130   return std::move(*e);
 131 }
 132
 133 template <class T> T check(Expected<T> e) {
 134   if (!e)
 135     fatal(llvm::toString(e.takeError()));
 136   return std::move(*e);
 137 }
 138
 139 template <class T>
 140 T check2(ErrorOr<T> e, llvm::function_ref<std::string()> prefix) {
 141   if (auto ec = e.getError())
 142     fatal(prefix() + ": " + ec.message());
 143   return std::move(*e);
 144 }
 145
 146 template <class T>
 147 T check2(Expected<T> e, llvm::function_ref<std::string()> prefix) {
 148   if (!e)
 149     fatal(prefix() + ": " + toString(e.takeError()));
 150   return std::move(*e);
 151 }
 152
 153 inline std::string toString(const Twine &s) { return s.str(); }
 154
 155 // To evaluate the second argument lazily, we use C macro.
 156 #define CHECK(E, S) check2((E), [&] { return toString(S); })
 157
 158 } // namespace lld
 159
 160 #endif