|
7 | 7 | // |
8 | 8 | //===----------------------------------------------------------------------===// |
9 | 9 | // |
10 | | -// In LLD, we have three levels of errors: fatal, error or warn. |
| 10 | +// We designed lld's error handlers with the following goals in mind: |
11 | 11 | // |
12 | | -// Fatal makes the program exit immediately with an error message. |
13 | | -// You shouldn't use it except for reporting a corrupted input file. |
| 12 | +// - Errors can occur at any place where we handle user input, but we don't |
| 13 | +// want them to affect the normal execution path too much. Ideally, |
| 14 | +// handling errors should be as simple as reporting them and exit (but |
| 15 | +// without actually doing exit). |
14 | 16 | // |
15 | | -// Error prints out an error message and increment a global variable |
16 | | -// ErrorCount to record the fact that we met an error condition. It does |
17 | | -// not exit, so it is safe for a lld-as-a-library use case. It is generally |
18 | | -// useful because it can report more than one error in a single run. |
| 17 | +// In particular, the design to wrap all functions that could fail with |
| 18 | +// ErrorOr<T> is rejected because otherwise we would have to wrap a large |
| 19 | +// number of functions in lld with ErrorOr. With that approach, if some |
| 20 | +// function F can fail, not only F but all functions that transitively call |
| 21 | +// F have to be wrapped with ErrorOr. That seemed too much. |
19 | 22 | // |
20 | | -// Warn doesn't do anything but printing out a given message. |
| 23 | +// - Finding only one error at a time is not sufficient. We want to find as |
| 24 | +// many errors as possible with one execution of the linker. That means the |
| 25 | +// linker needs to keep running after a first error and give up at some |
| 26 | +// checkpoint (beyond which it would find cascading, false errors caused by |
| 27 | +// the previous errors). |
21 | 28 | // |
22 | | -// It is not recommended to use llvm::outs() or llvm::errs() directly |
23 | | -// in LLD because they are not thread-safe. The functions declared in |
24 | | -// this file are mutually excluded, so you want to use them instead. |
| 29 | +// - We want a simple interface to report errors. Unlike Clang, the data we |
| 30 | +// handle is compiled binary, so we don't need an error reporting mechanism |
| 31 | +// that's as sophisticated as the one that Clang has. |
| 32 | +// |
| 33 | +// The current lld's error handling mechanism is simple: |
| 34 | +// |
| 35 | +// - When you find an error, report it using error() and continue as far as |
| 36 | +// you can. An internal error counter is incremented by one every time you |
| 37 | +// call error(). |
| 38 | +// |
| 39 | +// A common idiom to handle an error is calling error() and then returning |
| 40 | +// a reasonable default value. For example, if your function handles a |
| 41 | +// user-supplied alignment value, and if you find an invalid alignment |
| 42 | +// (e.g. 17 which is not 2^n), you may report it using error() and continue |
| 43 | +// as if it were alignment 1 (which is the simplest reasonable value). |
| 44 | +// |
| 45 | +// Note that you should not continue with an invalid value; that breaks the |
| 46 | +// internal consistency. You need to maintain all variables have some sane |
| 47 | +// value even after an error occurred. So, when you have to continue with |
| 48 | +// some value, always use a dummy value. |
| 49 | +// |
| 50 | +// - Find a reasonable checkpoint at where you want to stop the linker, and |
| 51 | +// add code to return from the function if errorCount() > 0. In most cases, |
| 52 | +// a checkpoint already exists, so you don't need to do anything for this. |
| 53 | +// |
| 54 | +// This interface satisfies all the goals that we mentioned above. |
| 55 | +// |
| 56 | +// You should never call fatal() except for reporting a corrupted input file. |
| 57 | +// fatal() immediately terminates the linker, so the function is not desirable |
| 58 | +// if you are using lld as a subroutine in other program, and with that you |
| 59 | +// can find only one error at a time. |
| 60 | +// |
| 61 | +// warn() doesn't do anything but printing out a given message. |
| 62 | +// |
| 63 | +// It is not recommended to use llvm::outs() or llvm::errs() directly in lld |
| 64 | +// because they are not thread-safe. The functions declared in this file are |
| 65 | +// thread-safe. |
25 | 66 | // |
26 | 67 | //===----------------------------------------------------------------------===// |
27 | 68 |
|
|
0 commit comments