Re-land "[PDB] Merge types in parallel when using ghashing"
[lldb.git] / 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 lld::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 class raw_ostream;
80 }
81
82 namespace lld {
83
84 // We wrap stdout and stderr so that you can pass alternative stdout/stderr as
85 // arguments to lld::*::link() functions.
86 extern llvm::raw_ostream *stdoutOS;
87 extern llvm::raw_ostream *stderrOS;
88
89 llvm::raw_ostream &outs();
90 llvm::raw_ostream &errs();
91
92 class ErrorHandler {
93 public:
94   uint64_t errorCount = 0;
95   uint64_t errorLimit = 20;
96   StringRef errorLimitExceededMsg = "too many errors emitted, stopping now";
97   StringRef logName = "lld";
98   bool exitEarly = true;
99   bool fatalWarnings = false;
100   bool verbose = false;
101   bool vsDiagnostics = false;
102   bool disableOutput = false;
103   std::function<void()> cleanupCallback;
104
105   void error(const Twine &msg);
106   LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg);
107   void log(const Twine &msg);
108   void message(const Twine &msg);
109   void warn(const Twine &msg);
110
111   void reset() {
112     if (cleanupCallback)
113       cleanupCallback();
114     *this = ErrorHandler();
115   }
116
117   std::unique_ptr<llvm::FileOutputBuffer> outputBuffer;
118
119 private:
120   using Colors = raw_ostream::Colors;
121
122   std::string getLocation(const Twine &msg);
123 };
124
125 /// Returns the default error handler.
126 ErrorHandler &errorHandler();
127
128 inline void error(const Twine &msg) { errorHandler().error(msg); }
129 inline LLVM_ATTRIBUTE_NORETURN void fatal(const Twine &msg) {
130   errorHandler().fatal(msg);
131 }
132 inline void log(const Twine &msg) { errorHandler().log(msg); }
133 inline void message(const Twine &msg) { errorHandler().message(msg); }
134 inline void warn(const Twine &msg) { errorHandler().warn(msg); }
135 inline uint64_t errorCount() { return errorHandler().errorCount; }
136
137 LLVM_ATTRIBUTE_NORETURN void exitLld(int val);
138
139 void diagnosticHandler(const llvm::DiagnosticInfo &di);
140 void checkError(Error e);
141
142 // check functions are convenient functions to strip errors
143 // from error-or-value objects.
144 template <class T> T check(ErrorOr<T> e) {
145   if (auto ec = e.getError())
146     fatal(ec.message());
147   return std::move(*e);
148 }
149
150 template <class T> T check(Expected<T> e) {
151   if (!e)
152     fatal(llvm::toString(e.takeError()));
153   return std::move(*e);
154 }
155
156 // Don't move from Expected wrappers around references.
157 template <class T> T &check(Expected<T &> e) {
158   if (!e)
159     fatal(llvm::toString(e.takeError()));
160   return *e;
161 }
162
163 template <class T>
164 T check2(ErrorOr<T> e, llvm::function_ref<std::string()> prefix) {
165   if (auto ec = e.getError())
166     fatal(prefix() + ": " + ec.message());
167   return std::move(*e);
168 }
169
170 template <class T>
171 T check2(Expected<T> e, llvm::function_ref<std::string()> prefix) {
172   if (!e)
173     fatal(prefix() + ": " + toString(e.takeError()));
174   return std::move(*e);
175 }
176
177 inline std::string toString(const Twine &s) { return s.str(); }
178
179 // To evaluate the second argument lazily, we use C macro.
180 #define CHECK(E, S) check2((E), [&] { return toString(S); })
181
182 } // namespace lld
183
184 #endif