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/ADT/SmallString.h"
75#include "llvm/Support/Error.h"
76#include "llvm/Support/FileOutputBuffer.h"
77#include "llvm/Support/raw_ostream.h"
78#include <mutex>
79
80namespace llvm {
81class DiagnosticInfo;
82}
83
84namespace lld {
85
86llvm::raw_ostream &outs();
87
88enum class ErrorTag { LibNotFound, SymbolNotFound };
89
90class ErrorHandler {
91public:
92 ~ErrorHandler();
93
94 void initialize(llvm::raw_ostream &stdoutOS, llvm::raw_ostream &stderrOS,
95 bool exitEarly, bool disableOutput);
96
97 uint64_t errorCount = 0;
98 uint64_t errorLimit = 20;
99 StringRef errorLimitExceededMsg = "too many errors emitted, stopping now";
100 StringRef errorHandlingScript;
101 StringRef logName = "lld";
102 bool exitEarly = true;
103 bool fatalWarnings = false;
104 bool suppressWarnings = false;
105 bool verbose = false;
106 bool vsDiagnostics = false;
107 bool disableOutput = false;
108 std::function<void()> cleanupCallback;
109
110 void error(const Twine &msg);
111 void error(const Twine &msg, ErrorTag tag, ArrayRef<StringRef> args);
112 [[noreturn]] void fatal(const Twine &msg);
113 void log(const Twine &msg);
114 void message(const Twine &msg, llvm::raw_ostream &s);
115 void warn(const Twine &msg);
116
117 raw_ostream &outs();
118 raw_ostream &errs();
119 void flushStreams();
120
121 std::unique_ptr<llvm::FileOutputBuffer> outputBuffer;
122
123private:
124 using Colors = raw_ostream::Colors;
125
126 std::string getLocation(const Twine &msg);
127 void reportDiagnostic(StringRef location, Colors c, StringRef diagKind,
128 const Twine &msg);
129
130 // We want to separate multi-line messages with a newline. `sep` is "\n"
131 // if the last messages was multi-line. Otherwise "".
132 llvm::StringRef sep;
133
134 // We wrap stdout and stderr so that you can pass alternative stdout/stderr as
135 // arguments to lld::*::link() functions. Since lld::outs() or lld::errs() can
136 // be indirectly called from multiple threads, we protect them using a mutex.
137 // In the future, we plan on supporting several concurrent linker contexts,
138 // which explains why the mutex is not a global but part of this context.
139 std::mutex mu;
140 llvm::raw_ostream *stdoutOS{};
141 llvm::raw_ostream *stderrOS{};
142};
143
144/// Returns the default error handler.
145ErrorHandler &errorHandler();
146
147void error(const Twine &msg);
148void error(const Twine &msg, ErrorTag tag, ArrayRef<StringRef> args);
149[[noreturn]] void fatal(const Twine &msg);
150void log(const Twine &msg);
151void message(const Twine &msg, llvm::raw_ostream &s = outs());
152void warn(const Twine &msg);
153uint64_t errorCount();
154
155enum class DiagLevel { None, Log, Msg, Warn, Err, Fatal };
156
157// A class that synchronizes thread writing to the same stream similar
158// std::osyncstream.
159class SyncStream {
160 ErrorHandler &e;
161 DiagLevel level;
162 llvm::SmallString<0> buf;
163
164public:
165 mutable llvm::raw_svector_ostream os{buf};
166 SyncStream(ErrorHandler &e, DiagLevel level) : e(e), level(level) {}
167 SyncStream(SyncStream &&o) : e(o.e), level(o.level), buf(std::move(o.buf)) {}
168 ~SyncStream();
169 StringRef str() { return os.str(); }
170 uint64_t tell() { return os.tell(); }
171};
172
173[[noreturn]] void exitLld(int val);
174
175void diagnosticHandler(const llvm::DiagnosticInfo &di);
176void checkError(Error e);
177void checkError(ErrorHandler &eh, Error e);
178
179// check functions are convenient functions to strip errors
180// from error-or-value objects.
181template <class T> T check(ErrorOr<T> e) {
182 if (auto ec = e.getError())
183 fatal(ec.message());
184 return std::move(*e);
185}
186
187template <class T> T check(Expected<T> e) {
188 if (!e)
189 fatal(llvm::toString(E: e.takeError()));
190 return std::move(*e);
191}
192
193// Don't move from Expected wrappers around references.
194template <class T> T &check(Expected<T &> e) {
195 if (!e)
196 fatal(llvm::toString(E: e.takeError()));
197 return *e;
198}
199
200template <class T>
201T check2(ErrorOr<T> e, llvm::function_ref<std::string()> prefix) {
202 if (auto ec = e.getError())
203 fatal(prefix() + ": " + ec.message());
204 return std::move(*e);
205}
206
207template <class T>
208T check2(Expected<T> e, llvm::function_ref<std::string()> prefix) {
209 if (!e)
210 fatal(prefix() + ": " + toString(e.takeError()));
211 return std::move(*e);
212}
213
214inline std::string toString(const Twine &s) { return s.str(); }
215
216// To evaluate the second argument lazily, we use C macro.
217#define CHECK(E, S) check2((E), [&] { return toString(S); })
218
219} // namespace lld
220
221#endif
222