Line data Source code
1 : //===- llvm/Support/Error.h - Recoverable error handling --------*- 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 : // This file defines an API used to report recoverable errors.
10 : //
11 : //===----------------------------------------------------------------------===//
12 :
13 : #ifndef LLVM_SUPPORT_ERROR_H
14 : #define LLVM_SUPPORT_ERROR_H
15 :
16 : #include "llvm-c/Error.h"
17 : #include "llvm/ADT/Twine.h"
18 : #include "llvm/Config/abi-breaking.h"
19 : #include "llvm/Support/AlignOf.h"
20 : #include "llvm/Support/Compiler.h"
21 : #include "llvm/Support/Debug.h"
22 : #include "llvm/Support/ErrorHandling.h"
23 : #include "llvm/Support/ErrorOr.h"
24 : #include "llvm/Support/Format.h"
25 : #include "llvm/Support/raw_ostream.h"
26 : #include <cassert>
27 : #include <cstdint>
28 : #include <cstdlib>
29 : #include <functional>
30 : #include <memory>
31 : #include <new>
32 : #include <optional>
33 : #include <string>
34 : #include <system_error>
35 : #include <type_traits>
36 : #include <utility>
37 : #include <vector>
38 :
39 : namespace llvm {
40 :
41 : class ErrorSuccess;
42 :
43 : /// Base class for error info classes. Do not extend this directly: Extend
44 : /// the ErrorInfo template subclass instead.
45 : class ErrorInfoBase {
46 : public:
47 : virtual ~ErrorInfoBase() = default;
48 :
49 : /// Print an error message to an output stream.
50 : virtual void log(raw_ostream &OS) const = 0;
51 :
52 : /// Return the error message as a string.
53 : virtual std::string message() const {
54 : std::string Msg;
55 : raw_string_ostream OS(Msg);
56 : log(OS);
57 : return Msg;
58 : }
59 :
60 : /// Convert this error to a std::error_code.
61 : ///
62 : /// This is a temporary crutch to enable interaction with code still
63 : /// using std::error_code. It will be removed in the future.
64 : virtual std::error_code convertToErrorCode() const = 0;
65 :
66 : // Returns the class ID for this type.
67 : static const void *classID() { return &ID; }
68 :
69 : // Returns the class ID for the dynamic type of this ErrorInfoBase instance.
70 : virtual const void *dynamicClassID() const = 0;
71 :
72 : // Check whether this instance is a subclass of the class identified by
73 : // ClassID.
74 : virtual bool isA(const void *const ClassID) const {
75 : return ClassID == classID();
76 : }
77 :
78 : // Check whether this instance is a subclass of ErrorInfoT.
79 : template <typename ErrorInfoT> bool isA() const {
80 : return isA(ErrorInfoT::classID());
81 : }
82 :
83 : private:
84 : virtual void anchor();
85 :
86 : static char ID;
87 : };
88 :
89 : /// Lightweight error class with error context and mandatory checking.
90 : ///
91 : /// Instances of this class wrap a ErrorInfoBase pointer. Failure states
92 : /// are represented by setting the pointer to a ErrorInfoBase subclass
93 : /// instance containing information describing the failure. Success is
94 : /// represented by a null pointer value.
95 : ///
96 : /// Instances of Error also contains a 'Checked' flag, which must be set
97 : /// before the destructor is called, otherwise the destructor will trigger a
98 : /// runtime error. This enforces at runtime the requirement that all Error
99 : /// instances be checked or returned to the caller.
100 : ///
101 : /// There are two ways to set the checked flag, depending on what state the
102 : /// Error instance is in. For Error instances indicating success, it
103 : /// is sufficient to invoke the boolean conversion operator. E.g.:
104 : ///
105 : /// @code{.cpp}
106 : /// Error foo(<...>);
107 : ///
108 : /// if (auto E = foo(<...>))
109 : /// return E; // <- Return E if it is in the error state.
110 : /// // We have verified that E was in the success state. It can now be safely
111 : /// // destroyed.
112 : /// @endcode
113 : ///
114 : /// A success value *can not* be dropped. For example, just calling 'foo(<...>)'
115 : /// without testing the return value will raise a runtime error, even if foo
116 : /// returns success.
117 : ///
118 : /// For Error instances representing failure, you must use either the
119 : /// handleErrors or handleAllErrors function with a typed handler. E.g.:
120 : ///
121 : /// @code{.cpp}
122 : /// class MyErrorInfo : public ErrorInfo<MyErrorInfo> {
123 : /// // Custom error info.
124 : /// };
125 : ///
126 : /// Error foo(<...>) { return make_error<MyErrorInfo>(...); }
127 : ///
128 : /// auto E = foo(<...>); // <- foo returns failure with MyErrorInfo.
129 : /// auto NewE =
130 : /// handleErrors(std::move(E),
131 : /// [](const MyErrorInfo &M) {
132 : /// // Deal with the error.
133 : /// },
134 : /// [](std::unique_ptr<OtherError> M) -> Error {
135 : /// if (canHandle(*M)) {
136 : /// // handle error.
137 : /// return Error::success();
138 : /// }
139 : /// // Couldn't handle this error instance. Pass it up the stack.
140 : /// return Error(std::move(M));
141 : /// });
142 : /// // Note - The error passed to handleErrors will be marked as checked. If
143 : /// // there is no matched handler, a new error with the same payload is
144 : /// // created and returned.
145 : /// // The handlers take the error checked by handleErrors as an argument,
146 : /// // which can be used to retrieve more information. If a new error is
147 : /// // created by a handler, it will be passed back to the caller of
148 : /// // handleErrors and needs to be checked or return up to the stack.
149 : /// // Otherwise, the passed-in error is considered consumed.
150 : /// @endcode
151 : ///
152 : /// The handleAllErrors function is identical to handleErrors, except
153 : /// that it has a void return type, and requires all errors to be handled and
154 : /// no new errors be returned. It prevents errors (assuming they can all be
155 : /// handled) from having to be bubbled all the way to the top-level.
156 : ///
157 : /// *All* Error instances must be checked before destruction, even if
158 : /// they're moved-assigned or constructed from Success values that have already
159 : /// been checked. This enforces checking through all levels of the call stack.
160 : class [[nodiscard]] Error {
161 : // ErrorList needs to be able to yank ErrorInfoBase pointers out of Errors
162 : // to add to the error list. It can't rely on handleErrors for this, since
163 : // handleErrors does not support ErrorList handlers.
164 : friend class ErrorList;
165 :
166 : // handleErrors needs to be able to set the Checked flag.
167 : template <typename... HandlerTs>
168 : friend Error handleErrors(Error E, HandlerTs &&... Handlers);
169 : // visitErrors needs direct access to the payload.
170 : template <typename HandlerT>
171 : friend void visitErrors(const Error &E, HandlerT H);
172 :
173 : // Expected<T> needs to be able to steal the payload when constructed from an
174 : // error.
175 : template <typename T> friend class Expected;
176 :
177 : // wrap needs to be able to steal the payload.
178 : friend LLVMErrorRef wrap(Error);
179 :
180 : protected:
181 : /// Create a success value. Prefer using 'Error::success()' for readability
182 0 : Error() {
183 0 : setPtr(nullptr);
184 0 : setChecked(false);
185 0 : }
186 :
187 : public:
188 : /// Create a success value.
189 : static ErrorSuccess success();
190 :
191 : // Errors are not copy-constructable.
192 : Error(const Error &Other) = delete;
193 :
194 : /// Move-construct an error value. The newly constructed error is considered
195 : /// unchecked, even if the source error had been checked. The original error
196 : /// becomes a checked Success value, regardless of its original state.
197 0 : Error(Error &&Other) {
198 0 : setChecked(true);
199 0 : *this = std::move(Other);
200 0 : }
201 :
202 : /// Create an error value. Prefer using the 'make_error' function, but
203 : /// this constructor can be useful when "re-throwing" errors from handlers.
204 0 : Error(std::unique_ptr<ErrorInfoBase> Payload) {
205 0 : setPtr(Payload.release());
206 0 : setChecked(false);
207 0 : }
208 :
209 : // Errors are not copy-assignable.
210 : Error &operator=(const Error &Other) = delete;
211 :
212 : /// Move-assign an error value. The current error must represent success, you
213 : /// you cannot overwrite an unhandled error. The current error is then
214 : /// considered unchecked. The source error becomes a checked success value,
215 : /// regardless of its original state.
216 0 : Error &operator=(Error &&Other) {
217 : // Don't allow overwriting of unchecked values.
218 0 : assertIsChecked();
219 0 : setPtr(Other.getPtr());
220 :
221 : // This Error is unchecked, even if the source error was checked.
222 0 : setChecked(false);
223 :
224 : // Null out Other's payload and set its checked bit.
225 0 : Other.setPtr(nullptr);
226 0 : Other.setChecked(true);
227 :
228 0 : return *this;
229 : }
230 :
231 : /// Destroy a Error. Fails with a call to abort() if the error is
232 : /// unchecked.
233 48888 : ~Error() {
234 48888 : assertIsChecked();
235 48888 : delete getPtr();
236 48888 : }
237 :
238 : /// Bool conversion. Returns true if this Error is in a failure state,
239 : /// and false if it is in an accept state. If the error is in a Success state
240 : /// it will be considered checked.
241 48888 : explicit operator bool() {
242 48888 : setChecked(getPtr() == nullptr);
243 48888 : return getPtr() != nullptr;
244 : }
245 :
246 : /// Check whether one error is a subclass of another.
247 : template <typename ErrT> bool isA() const {
248 : return getPtr() && getPtr()->isA(ErrT::classID());
249 : }
250 :
251 : /// Returns the dynamic class id of this error, or null if this is a success
252 : /// value.
253 : const void* dynamicClassID() const {
254 : if (!getPtr())
255 : return nullptr;
256 : return getPtr()->dynamicClassID();
257 : }
258 :
259 : private:
260 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
261 : // assertIsChecked() happens very frequently, but under normal circumstances
262 : // is supposed to be a no-op. So we want it to be inlined, but having a bunch
263 : // of debug prints can cause the function to be too large for inlining. So
264 : // it's important that we define this function out of line so that it can't be
265 : // inlined.
266 : [[noreturn]] void fatalUncheckedError() const;
267 : #endif
268 :
269 48888 : void assertIsChecked() {
270 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
271 : if (LLVM_UNLIKELY(!getChecked() || getPtr()))
272 : fatalUncheckedError();
273 : #endif
274 48888 : }
275 :
276 146664 : ErrorInfoBase *getPtr() const {
277 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
278 : return reinterpret_cast<ErrorInfoBase*>(
279 : reinterpret_cast<uintptr_t>(Payload) &
280 : ~static_cast<uintptr_t>(0x1));
281 : #else
282 146664 : return Payload;
283 : #endif
284 : }
285 :
286 0 : void setPtr(ErrorInfoBase *EI) {
287 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
288 : Payload = reinterpret_cast<ErrorInfoBase*>(
289 : (reinterpret_cast<uintptr_t>(EI) &
290 : ~static_cast<uintptr_t>(0x1)) |
291 : (reinterpret_cast<uintptr_t>(Payload) & 0x1));
292 : #else
293 0 : Payload = EI;
294 : #endif
295 0 : }
296 :
297 : bool getChecked() const {
298 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
299 : return (reinterpret_cast<uintptr_t>(Payload) & 0x1) == 0;
300 : #else
301 : return true;
302 : #endif
303 : }
304 :
305 48888 : void setChecked(bool V) {
306 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
307 : Payload = reinterpret_cast<ErrorInfoBase*>(
308 : (reinterpret_cast<uintptr_t>(Payload) &
309 : ~static_cast<uintptr_t>(0x1)) |
310 : (V ? 0 : 1));
311 : #endif
312 48888 : }
313 :
314 : std::unique_ptr<ErrorInfoBase> takePayload() {
315 : std::unique_ptr<ErrorInfoBase> Tmp(getPtr());
316 : setPtr(nullptr);
317 : setChecked(true);
318 : return Tmp;
319 : }
320 :
321 : friend raw_ostream &operator<<(raw_ostream &OS, const Error &E) {
322 : if (auto *P = E.getPtr())
323 : P->log(OS);
324 : else
325 : OS << "success";
326 : return OS;
327 : }
328 :
329 : ErrorInfoBase *Payload = nullptr;
330 : };
331 :
332 : /// Subclass of Error for the sole purpose of identifying the success path in
333 : /// the type system. This allows to catch invalid conversion to Expected<T> at
334 : /// compile time.
335 : class ErrorSuccess final : public Error {};
336 :
337 0 : inline ErrorSuccess Error::success() { return ErrorSuccess(); }
338 :
339 : /// Make a Error instance representing failure using the given error info
340 : /// type.
341 : template <typename ErrT, typename... ArgTs> Error make_error(ArgTs &&... Args) {
342 : return Error(std::make_unique<ErrT>(std::forward<ArgTs>(Args)...));
343 : }
344 :
345 : /// Base class for user error types. Users should declare their error types
346 : /// like:
347 : ///
348 : /// class MyError : public ErrorInfo<MyError> {
349 : /// ....
350 : /// };
351 : ///
352 : /// This class provides an implementation of the ErrorInfoBase::kind
353 : /// method, which is used by the Error RTTI system.
354 : template <typename ThisErrT, typename ParentErrT = ErrorInfoBase>
355 : class ErrorInfo : public ParentErrT {
356 : public:
357 : using ParentErrT::ParentErrT; // inherit constructors
358 :
359 : static const void *classID() { return &ThisErrT::ID; }
360 :
361 : const void *dynamicClassID() const override { return &ThisErrT::ID; }
362 :
363 : bool isA(const void *const ClassID) const override {
364 : return ClassID == classID() || ParentErrT::isA(ClassID);
365 : }
366 : };
367 :
368 : /// Special ErrorInfo subclass representing a list of ErrorInfos.
369 : /// Instances of this class are constructed by joinError.
370 : class ErrorList final : public ErrorInfo<ErrorList> {
371 : // handleErrors needs to be able to iterate the payload list of an
372 : // ErrorList.
373 : template <typename... HandlerTs>
374 : friend Error handleErrors(Error E, HandlerTs &&... Handlers);
375 : // visitErrors needs to be able to iterate the payload list of an
376 : // ErrorList.
377 : template <typename HandlerT>
378 : friend void visitErrors(const Error &E, HandlerT H);
379 :
380 : // joinErrors is implemented in terms of join.
381 : friend Error joinErrors(Error, Error);
382 :
383 : public:
384 : void log(raw_ostream &OS) const override {
385 : OS << "Multiple errors:\n";
386 : for (const auto &ErrPayload : Payloads) {
387 : ErrPayload->log(OS);
388 : OS << "\n";
389 : }
390 : }
391 :
392 : std::error_code convertToErrorCode() const override;
393 :
394 : // Used by ErrorInfo::classID.
395 : static char ID;
396 :
397 : private:
398 : ErrorList(std::unique_ptr<ErrorInfoBase> Payload1,
399 : std::unique_ptr<ErrorInfoBase> Payload2) {
400 : assert(!Payload1->isA<ErrorList>() && !Payload2->isA<ErrorList>() &&
401 : "ErrorList constructor payloads should be singleton errors");
402 : Payloads.push_back(std::move(Payload1));
403 : Payloads.push_back(std::move(Payload2));
404 : }
405 :
406 : static Error join(Error E1, Error E2) {
407 : if (!E1)
408 : return E2;
409 : if (!E2)
410 : return E1;
411 : if (E1.isA<ErrorList>()) {
412 : auto &E1List = static_cast<ErrorList &>(*E1.getPtr());
413 : if (E2.isA<ErrorList>()) {
414 : auto E2Payload = E2.takePayload();
415 : auto &E2List = static_cast<ErrorList &>(*E2Payload);
416 : for (auto &Payload : E2List.Payloads)
417 : E1List.Payloads.push_back(std::move(Payload));
418 : } else
419 : E1List.Payloads.push_back(E2.takePayload());
420 :
421 : return E1;
422 : }
423 : if (E2.isA<ErrorList>()) {
424 : auto &E2List = static_cast<ErrorList &>(*E2.getPtr());
425 : E2List.Payloads.insert(E2List.Payloads.begin(), E1.takePayload());
426 : return E2;
427 : }
428 : return Error(std::unique_ptr<ErrorList>(
429 : new ErrorList(E1.takePayload(), E2.takePayload())));
430 : }
431 :
432 : std::vector<std::unique_ptr<ErrorInfoBase>> Payloads;
433 : };
434 :
435 : /// Concatenate errors. The resulting Error is unchecked, and contains the
436 : /// ErrorInfo(s), if any, contained in E1, followed by the
437 : /// ErrorInfo(s), if any, contained in E2.
438 : inline Error joinErrors(Error E1, Error E2) {
439 : return ErrorList::join(std::move(E1), std::move(E2));
440 : }
441 :
442 : /// Tagged union holding either a T or a Error.
443 : ///
444 : /// This class parallels ErrorOr, but replaces error_code with Error. Since
445 : /// Error cannot be copied, this class replaces getError() with
446 : /// takeError(). It also adds an bool errorIsA<ErrT>() method for testing the
447 : /// error class type.
448 : ///
449 : /// Example usage of 'Expected<T>' as a function return type:
450 : ///
451 : /// @code{.cpp}
452 : /// Expected<int> myDivide(int A, int B) {
453 : /// if (B == 0) {
454 : /// // return an Error
455 : /// return createStringError(inconvertibleErrorCode(),
456 : /// "B must not be zero!");
457 : /// }
458 : /// // return an integer
459 : /// return A / B;
460 : /// }
461 : /// @endcode
462 : ///
463 : /// Checking the results of to a function returning 'Expected<T>':
464 : /// @code{.cpp}
465 : /// if (auto E = Result.takeError()) {
466 : /// // We must consume the error. Typically one of:
467 : /// // - return the error to our caller
468 : /// // - toString(), when logging
469 : /// // - consumeError(), to silently swallow the error
470 : /// // - handleErrors(), to distinguish error types
471 : /// errs() << "Problem with division " << toString(std::move(E)) << "\n";
472 : /// return;
473 : /// }
474 : /// // use the result
475 : /// outs() << "The answer is " << *Result << "\n";
476 : /// @endcode
477 : ///
478 : /// For unit-testing a function returning an 'Expected<T>', see the
479 : /// 'EXPECT_THAT_EXPECTED' macros in llvm/Testing/Support/Error.h
480 :
481 : template <class T> class [[nodiscard]] Expected {
482 : template <class T1> friend class ExpectedAsOutParameter;
483 : template <class OtherT> friend class Expected;
484 :
485 : static constexpr bool isRef = std::is_reference_v<T>;
486 :
487 : using wrap = std::reference_wrapper<std::remove_reference_t<T>>;
488 :
489 : using error_type = std::unique_ptr<ErrorInfoBase>;
490 :
491 : public:
492 : using storage_type = std::conditional_t<isRef, wrap, T>;
493 : using value_type = T;
494 :
495 : private:
496 : using reference = std::remove_reference_t<T> &;
497 : using const_reference = const std::remove_reference_t<T> &;
498 : using pointer = std::remove_reference_t<T> *;
499 : using const_pointer = const std::remove_reference_t<T> *;
500 :
501 : public:
502 : /// Create an Expected<T> error value from the given Error.
503 : Expected(Error &&Err)
504 : : HasError(true)
505 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
506 : // Expected is unchecked upon construction in Debug builds.
507 : , Unchecked(true)
508 : #endif
509 : {
510 : assert(Err && "Cannot create Expected<T> from Error success value.");
511 : new (getErrorStorage()) error_type(Err.takePayload());
512 : }
513 :
514 : /// Forbid to convert from Error::success() implicitly, this avoids having
515 : /// Expected<T> foo() { return Error::success(); } which compiles otherwise
516 : /// but triggers the assertion above.
517 : Expected(ErrorSuccess) = delete;
518 :
519 : /// Create an Expected<T> success value from the given OtherT value, which
520 : /// must be convertible to T.
521 : template <typename OtherT>
522 : Expected(OtherT &&Val,
523 : std::enable_if_t<std::is_convertible_v<OtherT, T>> * = nullptr)
524 : : HasError(false)
525 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
526 : // Expected is unchecked upon construction in Debug builds.
527 : ,
528 : Unchecked(true)
529 : #endif
530 : {
531 : new (getStorage()) storage_type(std::forward<OtherT>(Val));
532 : }
533 :
534 : /// Move construct an Expected<T> value.
535 : Expected(Expected &&Other) { moveConstruct(std::move(Other)); }
536 :
537 : /// Move construct an Expected<T> value from an Expected<OtherT>, where OtherT
538 : /// must be convertible to T.
539 : template <class OtherT>
540 : Expected(Expected<OtherT> &&Other,
541 : std::enable_if_t<std::is_convertible_v<OtherT, T>> * = nullptr) {
542 : moveConstruct(std::move(Other));
543 : }
544 :
545 : /// Move construct an Expected<T> value from an Expected<OtherT>, where OtherT
546 : /// isn't convertible to T.
547 : template <class OtherT>
548 : explicit Expected(
549 : Expected<OtherT> &&Other,
550 : std::enable_if_t<!std::is_convertible_v<OtherT, T>> * = nullptr) {
551 : moveConstruct(std::move(Other));
552 : }
553 :
554 : /// Move-assign from another Expected<T>.
555 : Expected &operator=(Expected &&Other) {
556 : moveAssign(std::move(Other));
557 : return *this;
558 : }
559 :
560 : /// Destroy an Expected<T>.
561 45 : ~Expected() {
562 45 : assertIsChecked();
563 45 : if (!HasError)
564 45 : getStorage()->~storage_type();
565 : else
566 0 : getErrorStorage()->~error_type();
567 45 : }
568 :
569 : /// Return false if there is an error.
570 45 : explicit operator bool() {
571 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
572 : Unchecked = HasError;
573 : #endif
574 45 : return !HasError;
575 : }
576 :
577 : /// Returns a reference to the stored T value.
578 45 : reference get() {
579 45 : assertIsChecked();
580 45 : return *getStorage();
581 : }
582 :
583 : /// Returns a const reference to the stored T value.
584 : const_reference get() const {
585 : assertIsChecked();
586 : return const_cast<Expected<T> *>(this)->get();
587 : }
588 :
589 : /// Returns \a takeError() after moving the held T (if any) into \p V.
590 : template <class OtherT>
591 : Error moveInto(
592 : OtherT &Value,
593 : std::enable_if_t<std::is_assignable_v<OtherT &, T &&>> * = nullptr) && {
594 : if (*this)
595 : Value = std::move(get());
596 : return takeError();
597 : }
598 :
599 : /// Check that this Expected<T> is an error of type ErrT.
600 : template <typename ErrT> bool errorIsA() const {
601 : return HasError && (*getErrorStorage())->template isA<ErrT>();
602 : }
603 :
604 : /// Take ownership of the stored error.
605 : /// After calling this the Expected<T> is in an indeterminate state that can
606 : /// only be safely destructed. No further calls (beside the destructor) should
607 : /// be made on the Expected<T> value.
608 0 : Error takeError() {
609 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
610 : Unchecked = false;
611 : #endif
612 0 : return HasError ? Error(std::move(*getErrorStorage())) : Error::success();
613 : }
614 :
615 : /// Returns a pointer to the stored T value.
616 : pointer operator->() {
617 : assertIsChecked();
618 : return toPointer(getStorage());
619 : }
620 :
621 : /// Returns a const pointer to the stored T value.
622 : const_pointer operator->() const {
623 : assertIsChecked();
624 : return toPointer(getStorage());
625 : }
626 :
627 : /// Returns a reference to the stored T value.
628 : reference operator*() {
629 : assertIsChecked();
630 : return *getStorage();
631 : }
632 :
633 : /// Returns a const reference to the stored T value.
634 : const_reference operator*() const {
635 : assertIsChecked();
636 : return *getStorage();
637 : }
638 :
639 : private:
640 : template <class T1>
641 : static bool compareThisIfSameType(const T1 &a, const T1 &b) {
642 : return &a == &b;
643 : }
644 :
645 : template <class T1, class T2>
646 : static bool compareThisIfSameType(const T1 &, const T2 &) {
647 : return false;
648 : }
649 :
650 : template <class OtherT> void moveConstruct(Expected<OtherT> &&Other) {
651 : HasError = Other.HasError;
652 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
653 : Unchecked = true;
654 : Other.Unchecked = false;
655 : #endif
656 :
657 : if (!HasError)
658 : new (getStorage()) storage_type(std::move(*Other.getStorage()));
659 : else
660 : new (getErrorStorage()) error_type(std::move(*Other.getErrorStorage()));
661 : }
662 :
663 : template <class OtherT> void moveAssign(Expected<OtherT> &&Other) {
664 : assertIsChecked();
665 :
666 : if (compareThisIfSameType(*this, Other))
667 : return;
668 :
669 : this->~Expected();
670 : new (this) Expected(std::move(Other));
671 : }
672 :
673 : pointer toPointer(pointer Val) { return Val; }
674 :
675 : const_pointer toPointer(const_pointer Val) const { return Val; }
676 :
677 : pointer toPointer(wrap *Val) { return &Val->get(); }
678 :
679 : const_pointer toPointer(const wrap *Val) const { return &Val->get(); }
680 :
681 90 : storage_type *getStorage() {
682 90 : assert(!HasError && "Cannot get value when an error exists!");
683 90 : return reinterpret_cast<storage_type *>(&TStorage);
684 : }
685 :
686 : const storage_type *getStorage() const {
687 : assert(!HasError && "Cannot get value when an error exists!");
688 : return reinterpret_cast<const storage_type *>(&TStorage);
689 : }
690 :
691 0 : error_type *getErrorStorage() {
692 0 : assert(HasError && "Cannot get error when a value exists!");
693 0 : return reinterpret_cast<error_type *>(&ErrorStorage);
694 : }
695 :
696 : const error_type *getErrorStorage() const {
697 : assert(HasError && "Cannot get error when a value exists!");
698 : return reinterpret_cast<const error_type *>(&ErrorStorage);
699 : }
700 :
701 : // Used by ExpectedAsOutParameter to reset the checked flag.
702 : void setUnchecked() {
703 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
704 : Unchecked = true;
705 : #endif
706 : }
707 :
708 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
709 : [[noreturn]] LLVM_ATTRIBUTE_NOINLINE void fatalUncheckedExpected() const {
710 : dbgs() << "Expected<T> must be checked before access or destruction.\n";
711 : if (HasError) {
712 : dbgs() << "Unchecked Expected<T> contained error:\n";
713 : (*getErrorStorage())->log(dbgs());
714 : } else
715 : dbgs() << "Expected<T> value was in success state. (Note: Expected<T> "
716 : "values in success mode must still be checked prior to being "
717 : "destroyed).\n";
718 : abort();
719 : }
720 : #endif
721 :
722 90 : void assertIsChecked() const {
723 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
724 : if (LLVM_UNLIKELY(Unchecked))
725 : fatalUncheckedExpected();
726 : #endif
727 90 : }
728 :
729 : union {
730 : AlignedCharArrayUnion<storage_type> TStorage;
731 : AlignedCharArrayUnion<error_type> ErrorStorage;
732 : };
733 : bool HasError : 1;
734 : #if LLVM_ENABLE_ABI_BREAKING_CHECKS
735 : bool Unchecked : 1;
736 : #endif
737 : };
738 :
739 : /// Report a serious error, calling any installed error handler. See
740 : /// ErrorHandling.h.
741 : [[noreturn]] void report_fatal_error(Error Err, bool gen_crash_diag = true);
742 :
743 : /// Report a fatal error if Err is a failure value.
744 : ///
745 : /// This function can be used to wrap calls to fallible functions ONLY when it
746 : /// is known that the Error will always be a success value. E.g.
747 : ///
748 : /// @code{.cpp}
749 : /// // foo only attempts the fallible operation if DoFallibleOperation is
750 : /// // true. If DoFallibleOperation is false then foo always returns
751 : /// // Error::success().
752 : /// Error foo(bool DoFallibleOperation);
753 : ///
754 : /// cantFail(foo(false));
755 : /// @endcode
756 : inline void cantFail(Error Err, const char *Msg = nullptr) {
757 : if (Err) {
758 : if (!Msg)
759 : Msg = "Failure value returned from cantFail wrapped call";
760 : #ifndef NDEBUG
761 : std::string Str;
762 : raw_string_ostream OS(Str);
763 : OS << Msg << "\n" << Err;
764 : Msg = Str.c_str();
765 : #endif
766 : llvm_unreachable(Msg);
767 : }
768 : }
769 :
770 : /// Report a fatal error if ValOrErr is a failure value, otherwise unwraps and
771 : /// returns the contained value.
772 : ///
773 : /// This function can be used to wrap calls to fallible functions ONLY when it
774 : /// is known that the Error will always be a success value. E.g.
775 : ///
776 : /// @code{.cpp}
777 : /// // foo only attempts the fallible operation if DoFallibleOperation is
778 : /// // true. If DoFallibleOperation is false then foo always returns an int.
779 : /// Expected<int> foo(bool DoFallibleOperation);
780 : ///
781 : /// int X = cantFail(foo(false));
782 : /// @endcode
783 : template <typename T>
784 : T cantFail(Expected<T> ValOrErr, const char *Msg = nullptr) {
785 : if (ValOrErr)
786 : return std::move(*ValOrErr);
787 : else {
788 : if (!Msg)
789 : Msg = "Failure value returned from cantFail wrapped call";
790 : #ifndef NDEBUG
791 : std::string Str;
792 : raw_string_ostream OS(Str);
793 : auto E = ValOrErr.takeError();
794 : OS << Msg << "\n" << E;
795 : Msg = Str.c_str();
796 : #endif
797 : llvm_unreachable(Msg);
798 : }
799 : }
800 :
801 : /// Report a fatal error if ValOrErr is a failure value, otherwise unwraps and
802 : /// returns the contained reference.
803 : ///
804 : /// This function can be used to wrap calls to fallible functions ONLY when it
805 : /// is known that the Error will always be a success value. E.g.
806 : ///
807 : /// @code{.cpp}
808 : /// // foo only attempts the fallible operation if DoFallibleOperation is
809 : /// // true. If DoFallibleOperation is false then foo always returns a Bar&.
810 : /// Expected<Bar&> foo(bool DoFallibleOperation);
811 : ///
812 : /// Bar &X = cantFail(foo(false));
813 : /// @endcode
814 : template <typename T>
815 : T& cantFail(Expected<T&> ValOrErr, const char *Msg = nullptr) {
816 : if (ValOrErr)
817 : return *ValOrErr;
818 : else {
819 : if (!Msg)
820 : Msg = "Failure value returned from cantFail wrapped call";
821 : #ifndef NDEBUG
822 : std::string Str;
823 : raw_string_ostream OS(Str);
824 : auto E = ValOrErr.takeError();
825 : OS << Msg << "\n" << E;
826 : Msg = Str.c_str();
827 : #endif
828 : llvm_unreachable(Msg);
829 : }
830 : }
831 :
832 : /// Helper for testing applicability of, and applying, handlers for
833 : /// ErrorInfo types.
834 : template <typename HandlerT>
835 : class ErrorHandlerTraits
836 : : public ErrorHandlerTraits<
837 : decltype(&std::remove_reference_t<HandlerT>::operator())> {};
838 :
839 : // Specialization functions of the form 'Error (const ErrT&)'.
840 : template <typename ErrT> class ErrorHandlerTraits<Error (&)(ErrT &)> {
841 : public:
842 : static bool appliesTo(const ErrorInfoBase &E) {
843 : return E.template isA<ErrT>();
844 : }
845 :
846 : template <typename HandlerT>
847 : static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
848 : assert(appliesTo(*E) && "Applying incorrect handler");
849 : return H(static_cast<ErrT &>(*E));
850 : }
851 : };
852 :
853 : // Specialization functions of the form 'void (const ErrT&)'.
854 : template <typename ErrT> class ErrorHandlerTraits<void (&)(ErrT &)> {
855 : public:
856 : static bool appliesTo(const ErrorInfoBase &E) {
857 : return E.template isA<ErrT>();
858 : }
859 :
860 : template <typename HandlerT>
861 : static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
862 : assert(appliesTo(*E) && "Applying incorrect handler");
863 : H(static_cast<ErrT &>(*E));
864 : return Error::success();
865 : }
866 : };
867 :
868 : /// Specialization for functions of the form 'Error (std::unique_ptr<ErrT>)'.
869 : template <typename ErrT>
870 : class ErrorHandlerTraits<Error (&)(std::unique_ptr<ErrT>)> {
871 : public:
872 : static bool appliesTo(const ErrorInfoBase &E) {
873 : return E.template isA<ErrT>();
874 : }
875 :
876 : template <typename HandlerT>
877 : static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
878 : assert(appliesTo(*E) && "Applying incorrect handler");
879 : std::unique_ptr<ErrT> SubE(static_cast<ErrT *>(E.release()));
880 : return H(std::move(SubE));
881 : }
882 : };
883 :
884 : /// Specialization for functions of the form 'void (std::unique_ptr<ErrT>)'.
885 : template <typename ErrT>
886 : class ErrorHandlerTraits<void (&)(std::unique_ptr<ErrT>)> {
887 : public:
888 : static bool appliesTo(const ErrorInfoBase &E) {
889 : return E.template isA<ErrT>();
890 : }
891 :
892 : template <typename HandlerT>
893 : static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
894 : assert(appliesTo(*E) && "Applying incorrect handler");
895 : std::unique_ptr<ErrT> SubE(static_cast<ErrT *>(E.release()));
896 : H(std::move(SubE));
897 : return Error::success();
898 : }
899 : };
900 :
901 : // Specialization for member functions of the form 'RetT (const ErrT&)'.
902 : template <typename C, typename RetT, typename ErrT>
903 : class ErrorHandlerTraits<RetT (C::*)(ErrT &)>
904 : : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
905 :
906 : // Specialization for member functions of the form 'RetT (const ErrT&) const'.
907 : template <typename C, typename RetT, typename ErrT>
908 : class ErrorHandlerTraits<RetT (C::*)(ErrT &) const>
909 : : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
910 :
911 : // Specialization for member functions of the form 'RetT (const ErrT&)'.
912 : template <typename C, typename RetT, typename ErrT>
913 : class ErrorHandlerTraits<RetT (C::*)(const ErrT &)>
914 : : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
915 :
916 : // Specialization for member functions of the form 'RetT (const ErrT&) const'.
917 : template <typename C, typename RetT, typename ErrT>
918 : class ErrorHandlerTraits<RetT (C::*)(const ErrT &) const>
919 : : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
920 :
921 : /// Specialization for member functions of the form
922 : /// 'RetT (std::unique_ptr<ErrT>)'.
923 : template <typename C, typename RetT, typename ErrT>
924 : class ErrorHandlerTraits<RetT (C::*)(std::unique_ptr<ErrT>)>
925 : : public ErrorHandlerTraits<RetT (&)(std::unique_ptr<ErrT>)> {};
926 :
927 : /// Specialization for member functions of the form
928 : /// 'RetT (std::unique_ptr<ErrT>) const'.
929 : template <typename C, typename RetT, typename ErrT>
930 : class ErrorHandlerTraits<RetT (C::*)(std::unique_ptr<ErrT>) const>
931 : : public ErrorHandlerTraits<RetT (&)(std::unique_ptr<ErrT>)> {};
932 :
933 : inline Error handleErrorImpl(std::unique_ptr<ErrorInfoBase> Payload) {
934 : return Error(std::move(Payload));
935 : }
936 :
937 : template <typename HandlerT, typename... HandlerTs>
938 : Error handleErrorImpl(std::unique_ptr<ErrorInfoBase> Payload,
939 : HandlerT &&Handler, HandlerTs &&... Handlers) {
940 : if (ErrorHandlerTraits<HandlerT>::appliesTo(*Payload))
941 : return ErrorHandlerTraits<HandlerT>::apply(std::forward<HandlerT>(Handler),
942 : std::move(Payload));
943 : return handleErrorImpl(std::move(Payload),
944 : std::forward<HandlerTs>(Handlers)...);
945 : }
946 :
947 : /// Pass the ErrorInfo(s) contained in E to their respective handlers. Any
948 : /// unhandled errors (or Errors returned by handlers) are re-concatenated and
949 : /// returned.
950 : /// Because this function returns an error, its result must also be checked
951 : /// or returned. If you intend to handle all errors use handleAllErrors
952 : /// (which returns void, and will abort() on unhandled errors) instead.
953 : template <typename... HandlerTs>
954 : Error handleErrors(Error E, HandlerTs &&... Hs) {
955 : if (!E)
956 : return Error::success();
957 :
958 : std::unique_ptr<ErrorInfoBase> Payload = E.takePayload();
959 :
960 : if (Payload->isA<ErrorList>()) {
961 : ErrorList &List = static_cast<ErrorList &>(*Payload);
962 : Error R;
963 : for (auto &P : List.Payloads)
964 : R = ErrorList::join(
965 : std::move(R),
966 : handleErrorImpl(std::move(P), std::forward<HandlerTs>(Hs)...));
967 : return R;
968 : }
969 :
970 : return handleErrorImpl(std::move(Payload), std::forward<HandlerTs>(Hs)...);
971 : }
972 :
973 : /// Behaves the same as handleErrors, except that by contract all errors
974 : /// *must* be handled by the given handlers (i.e. there must be no remaining
975 : /// errors after running the handlers, or llvm_unreachable is called).
976 : template <typename... HandlerTs>
977 : void handleAllErrors(Error E, HandlerTs &&... Handlers) {
978 : cantFail(handleErrors(std::move(E), std::forward<HandlerTs>(Handlers)...));
979 : }
980 :
981 : /// Check that E is a non-error, then drop it.
982 : /// If E is an error, llvm_unreachable will be called.
983 : inline void handleAllErrors(Error E) {
984 : cantFail(std::move(E));
985 : }
986 :
987 : /// Visit all the ErrorInfo(s) contained in E by passing them to the respective
988 : /// handler, without consuming the error.
989 : template <typename HandlerT> void visitErrors(const Error &E, HandlerT H) {
990 : const ErrorInfoBase *Payload = E.getPtr();
991 : if (!Payload)
992 : return;
993 :
994 : if (Payload->isA<ErrorList>()) {
995 : const ErrorList &List = static_cast<const ErrorList &>(*Payload);
996 : for (const auto &P : List.Payloads)
997 : H(*P);
998 : return;
999 : }
1000 :
1001 : return H(*Payload);
1002 : }
1003 :
1004 : /// Handle any errors (if present) in an Expected<T>, then try a recovery path.
1005 : ///
1006 : /// If the incoming value is a success value it is returned unmodified. If it
1007 : /// is a failure value then it the contained error is passed to handleErrors.
1008 : /// If handleErrors is able to handle the error then the RecoveryPath functor
1009 : /// is called to supply the final result. If handleErrors is not able to
1010 : /// handle all errors then the unhandled errors are returned.
1011 : ///
1012 : /// This utility enables the follow pattern:
1013 : ///
1014 : /// @code{.cpp}
1015 : /// enum FooStrategy { Aggressive, Conservative };
1016 : /// Expected<Foo> foo(FooStrategy S);
1017 : ///
1018 : /// auto ResultOrErr =
1019 : /// handleExpected(
1020 : /// foo(Aggressive),
1021 : /// []() { return foo(Conservative); },
1022 : /// [](AggressiveStrategyError&) {
1023 : /// // Implicitly conusme this - we'll recover by using a conservative
1024 : /// // strategy.
1025 : /// });
1026 : ///
1027 : /// @endcode
1028 : template <typename T, typename RecoveryFtor, typename... HandlerTs>
1029 : Expected<T> handleExpected(Expected<T> ValOrErr, RecoveryFtor &&RecoveryPath,
1030 : HandlerTs &&... Handlers) {
1031 : if (ValOrErr)
1032 : return ValOrErr;
1033 :
1034 : if (auto Err = handleErrors(ValOrErr.takeError(),
1035 : std::forward<HandlerTs>(Handlers)...))
1036 : return std::move(Err);
1037 :
1038 : return RecoveryPath();
1039 : }
1040 :
1041 : /// Log all errors (if any) in E to OS. If there are any errors, ErrorBanner
1042 : /// will be printed before the first one is logged. A newline will be printed
1043 : /// after each error.
1044 : ///
1045 : /// This function is compatible with the helpers from Support/WithColor.h. You
1046 : /// can pass any of them as the OS. Please consider using them instead of
1047 : /// including 'error: ' in the ErrorBanner.
1048 : ///
1049 : /// This is useful in the base level of your program to allow clean termination
1050 : /// (allowing clean deallocation of resources, etc.), while reporting error
1051 : /// information to the user.
1052 : void logAllUnhandledErrors(Error E, raw_ostream &OS, Twine ErrorBanner = {});
1053 :
1054 : /// Write all error messages (if any) in E to a string. The newline character
1055 : /// is used to separate error messages.
1056 : std::string toString(Error E);
1057 :
1058 : /// Like toString(), but does not consume the error. This can be used to print
1059 : /// a warning while retaining the original error object.
1060 : std::string toStringWithoutConsuming(const Error &E);
1061 :
1062 : /// Consume a Error without doing anything. This method should be used
1063 : /// only where an error can be considered a reasonable and expected return
1064 : /// value.
1065 : ///
1066 : /// Uses of this method are potentially indicative of design problems: If it's
1067 : /// legitimate to do nothing while processing an "error", the error-producer
1068 : /// might be more clearly refactored to return an std::optional<T>.
1069 : inline void consumeError(Error Err) {
1070 : handleAllErrors(std::move(Err), [](const ErrorInfoBase &) {});
1071 : }
1072 :
1073 : /// Convert an Expected to an Optional without doing anything. This method
1074 : /// should be used only where an error can be considered a reasonable and
1075 : /// expected return value.
1076 : ///
1077 : /// Uses of this method are potentially indicative of problems: perhaps the
1078 : /// error should be propagated further, or the error-producer should just
1079 : /// return an Optional in the first place.
1080 : template <typename T> std::optional<T> expectedToOptional(Expected<T> &&E) {
1081 : if (E)
1082 : return std::move(*E);
1083 : consumeError(E.takeError());
1084 : return std::nullopt;
1085 : }
1086 :
1087 : template <typename T> std::optional<T> expectedToStdOptional(Expected<T> &&E) {
1088 : if (E)
1089 : return std::move(*E);
1090 : consumeError(E.takeError());
1091 : return std::nullopt;
1092 : }
1093 :
1094 : /// Helper for converting an Error to a bool.
1095 : ///
1096 : /// This method returns true if Err is in an error state, or false if it is
1097 : /// in a success state. Puts Err in a checked state in both cases (unlike
1098 : /// Error::operator bool(), which only does this for success states).
1099 : inline bool errorToBool(Error Err) {
1100 : bool IsError = static_cast<bool>(Err);
1101 : if (IsError)
1102 : consumeError(std::move(Err));
1103 : return IsError;
1104 : }
1105 :
1106 : /// Helper for Errors used as out-parameters.
1107 : ///
1108 : /// This helper is for use with the Error-as-out-parameter idiom, where an error
1109 : /// is passed to a function or method by reference, rather than being returned.
1110 : /// In such cases it is helpful to set the checked bit on entry to the function
1111 : /// so that the error can be written to (unchecked Errors abort on assignment)
1112 : /// and clear the checked bit on exit so that clients cannot accidentally forget
1113 : /// to check the result. This helper performs these actions automatically using
1114 : /// RAII:
1115 : ///
1116 : /// @code{.cpp}
1117 : /// Result foo(Error &Err) {
1118 : /// ErrorAsOutParameter ErrAsOutParam(&Err); // 'Checked' flag set
1119 : /// // <body of foo>
1120 : /// // <- 'Checked' flag auto-cleared when ErrAsOutParam is destructed.
1121 : /// }
1122 : /// @endcode
1123 : ///
1124 : /// ErrorAsOutParameter takes an Error* rather than Error& so that it can be
1125 : /// used with optional Errors (Error pointers that are allowed to be null). If
1126 : /// ErrorAsOutParameter took an Error reference, an instance would have to be
1127 : /// created inside every condition that verified that Error was non-null. By
1128 : /// taking an Error pointer we can just create one instance at the top of the
1129 : /// function.
1130 : class ErrorAsOutParameter {
1131 : public:
1132 : ErrorAsOutParameter(Error *Err) : Err(Err) {
1133 : // Raise the checked bit if Err is success.
1134 : if (Err)
1135 : (void)!!*Err;
1136 : }
1137 :
1138 : ~ErrorAsOutParameter() {
1139 : // Clear the checked bit.
1140 : if (Err && !*Err)
1141 : *Err = Error::success();
1142 : }
1143 :
1144 : private:
1145 : Error *Err;
1146 : };
1147 :
1148 : /// Helper for Expected<T>s used as out-parameters.
1149 : ///
1150 : /// See ErrorAsOutParameter.
1151 : template <typename T>
1152 : class ExpectedAsOutParameter {
1153 : public:
1154 : ExpectedAsOutParameter(Expected<T> *ValOrErr)
1155 : : ValOrErr(ValOrErr) {
1156 : if (ValOrErr)
1157 : (void)!!*ValOrErr;
1158 : }
1159 :
1160 : ~ExpectedAsOutParameter() {
1161 : if (ValOrErr)
1162 : ValOrErr->setUnchecked();
1163 : }
1164 :
1165 : private:
1166 : Expected<T> *ValOrErr;
1167 : };
1168 :
1169 : /// This class wraps a std::error_code in a Error.
1170 : ///
1171 : /// This is useful if you're writing an interface that returns a Error
1172 : /// (or Expected) and you want to call code that still returns
1173 : /// std::error_codes.
1174 : class ECError : public ErrorInfo<ECError> {
1175 : friend Error errorCodeToError(std::error_code);
1176 :
1177 : void anchor() override;
1178 :
1179 : public:
1180 : void setErrorCode(std::error_code EC) { this->EC = EC; }
1181 : std::error_code convertToErrorCode() const override { return EC; }
1182 : void log(raw_ostream &OS) const override { OS << EC.message(); }
1183 :
1184 : // Used by ErrorInfo::classID.
1185 : static char ID;
1186 :
1187 : protected:
1188 : ECError() = default;
1189 : ECError(std::error_code EC) : EC(EC) {}
1190 :
1191 : std::error_code EC;
1192 : };
1193 :
1194 : /// The value returned by this function can be returned from convertToErrorCode
1195 : /// for Error values where no sensible translation to std::error_code exists.
1196 : /// It should only be used in this situation, and should never be used where a
1197 : /// sensible conversion to std::error_code is available, as attempts to convert
1198 : /// to/from this error will result in a fatal error. (i.e. it is a programmatic
1199 : /// error to try to convert such a value).
1200 : std::error_code inconvertibleErrorCode();
1201 :
1202 : /// Helper for converting an std::error_code to a Error.
1203 : Error errorCodeToError(std::error_code EC);
1204 :
1205 : /// Helper for converting an ECError to a std::error_code.
1206 : ///
1207 : /// This method requires that Err be Error() or an ECError, otherwise it
1208 : /// will trigger a call to abort().
1209 : std::error_code errorToErrorCode(Error Err);
1210 :
1211 : /// Helper to get errno as an std::error_code.
1212 : ///
1213 : /// errno should always be represented using the generic category as that's what
1214 : /// both libc++ and libstdc++ do. On POSIX systems you can also represent them
1215 : /// using the system category, however this makes them compare differently for
1216 : /// values outside of those used by `std::errc` if one is generic and the other
1217 : /// is system.
1218 : ///
1219 : /// See the libc++ and libstdc++ implementations of `default_error_condition` on
1220 : /// the system category for more details on what the difference is.
1221 : inline std::error_code errnoAsErrorCode() {
1222 : return std::error_code(errno, std::generic_category());
1223 : }
1224 :
1225 : /// Convert an ErrorOr<T> to an Expected<T>.
1226 : template <typename T> Expected<T> errorOrToExpected(ErrorOr<T> &&EO) {
1227 : if (auto EC = EO.getError())
1228 : return errorCodeToError(EC);
1229 : return std::move(*EO);
1230 : }
1231 :
1232 : /// Convert an Expected<T> to an ErrorOr<T>.
1233 : template <typename T> ErrorOr<T> expectedToErrorOr(Expected<T> &&E) {
1234 : if (auto Err = E.takeError())
1235 : return errorToErrorCode(std::move(Err));
1236 : return std::move(*E);
1237 : }
1238 :
1239 : /// This class wraps a string in an Error.
1240 : ///
1241 : /// StringError is useful in cases where the client is not expected to be able
1242 : /// to consume the specific error message programmatically (for example, if the
1243 : /// error message is to be presented to the user).
1244 : ///
1245 : /// StringError can also be used when additional information is to be printed
1246 : /// along with a error_code message. Depending on the constructor called, this
1247 : /// class can either display:
1248 : /// 1. the error_code message (ECError behavior)
1249 : /// 2. a string
1250 : /// 3. the error_code message and a string
1251 : ///
1252 : /// These behaviors are useful when subtyping is required; for example, when a
1253 : /// specific library needs an explicit error type. In the example below,
1254 : /// PDBError is derived from StringError:
1255 : ///
1256 : /// @code{.cpp}
1257 : /// Expected<int> foo() {
1258 : /// return llvm::make_error<PDBError>(pdb_error_code::dia_failed_loading,
1259 : /// "Additional information");
1260 : /// }
1261 : /// @endcode
1262 : ///
1263 : class StringError : public ErrorInfo<StringError> {
1264 : public:
1265 : static char ID;
1266 :
1267 : StringError(std::string &&S, std::error_code EC, bool PrintMsgOnly);
1268 : /// Prints EC + S and converts to EC.
1269 : StringError(std::error_code EC, const Twine &S = Twine());
1270 : /// Prints S and converts to EC.
1271 : StringError(const Twine &S, std::error_code EC);
1272 :
1273 : void log(raw_ostream &OS) const override;
1274 : std::error_code convertToErrorCode() const override;
1275 :
1276 : const std::string &getMessage() const { return Msg; }
1277 :
1278 : private:
1279 : std::string Msg;
1280 : std::error_code EC;
1281 : const bool PrintMsgOnly = false;
1282 : };
1283 :
1284 : /// Create formatted StringError object.
1285 : template <typename... Ts>
1286 : inline Error createStringError(std::error_code EC, char const *Fmt,
1287 : const Ts &... Vals) {
1288 : std::string Buffer;
1289 : raw_string_ostream(Buffer) << format(Fmt, Vals...);
1290 : return make_error<StringError>(Buffer, EC);
1291 : }
1292 :
1293 : Error createStringError(std::string &&Msg, std::error_code EC);
1294 :
1295 : inline Error createStringError(std::error_code EC, const char *S) {
1296 : return createStringError(std::string(S), EC);
1297 : }
1298 :
1299 : inline Error createStringError(std::error_code EC, const Twine &S) {
1300 : return createStringError(S.str(), EC);
1301 : }
1302 :
1303 : /// Create a StringError with an inconvertible error code.
1304 : inline Error createStringError(const Twine &S) {
1305 : return createStringError(llvm::inconvertibleErrorCode(), S);
1306 : }
1307 :
1308 : template <typename... Ts>
1309 : inline Error createStringError(char const *Fmt, const Ts &...Vals) {
1310 : return createStringError(llvm::inconvertibleErrorCode(), Fmt, Vals...);
1311 : }
1312 :
1313 : template <typename... Ts>
1314 : inline Error createStringError(std::errc EC, char const *Fmt,
1315 : const Ts &... Vals) {
1316 : return createStringError(std::make_error_code(EC), Fmt, Vals...);
1317 : }
1318 :
1319 : /// This class wraps a filename and another Error.
1320 : ///
1321 : /// In some cases, an error needs to live along a 'source' name, in order to
1322 : /// show more detailed information to the user.
1323 : class FileError final : public ErrorInfo<FileError> {
1324 :
1325 : friend Error createFileError(const Twine &, Error);
1326 : friend Error createFileError(const Twine &, size_t, Error);
1327 :
1328 : public:
1329 : void log(raw_ostream &OS) const override {
1330 : assert(Err && "Trying to log after takeError().");
1331 : OS << "'" << FileName << "': ";
1332 : if (Line)
1333 : OS << "line " << *Line << ": ";
1334 : Err->log(OS);
1335 : }
1336 :
1337 : std::string messageWithoutFileInfo() const {
1338 : std::string Msg;
1339 : raw_string_ostream OS(Msg);
1340 : Err->log(OS);
1341 : return Msg;
1342 : }
1343 :
1344 : StringRef getFileName() const { return FileName; }
1345 :
1346 : Error takeError() { return Error(std::move(Err)); }
1347 :
1348 : std::error_code convertToErrorCode() const override;
1349 :
1350 : // Used by ErrorInfo::classID.
1351 : static char ID;
1352 :
1353 : private:
1354 : FileError(const Twine &F, std::optional<size_t> LineNum,
1355 : std::unique_ptr<ErrorInfoBase> E) {
1356 : assert(E && "Cannot create FileError from Error success value.");
1357 : FileName = F.str();
1358 : Err = std::move(E);
1359 : Line = std::move(LineNum);
1360 : }
1361 :
1362 : static Error build(const Twine &F, std::optional<size_t> Line, Error E) {
1363 : std::unique_ptr<ErrorInfoBase> Payload;
1364 : handleAllErrors(std::move(E),
1365 : [&](std::unique_ptr<ErrorInfoBase> EIB) -> Error {
1366 : Payload = std::move(EIB);
1367 : return Error::success();
1368 : });
1369 : return Error(
1370 : std::unique_ptr<FileError>(new FileError(F, Line, std::move(Payload))));
1371 : }
1372 :
1373 : std::string FileName;
1374 : std::optional<size_t> Line;
1375 : std::unique_ptr<ErrorInfoBase> Err;
1376 : };
1377 :
1378 : /// Concatenate a source file path and/or name with an Error. The resulting
1379 : /// Error is unchecked.
1380 : inline Error createFileError(const Twine &F, Error E) {
1381 : return FileError::build(F, std::optional<size_t>(), std::move(E));
1382 : }
1383 :
1384 : /// Concatenate a source file path and/or name with line number and an Error.
1385 : /// The resulting Error is unchecked.
1386 : inline Error createFileError(const Twine &F, size_t Line, Error E) {
1387 : return FileError::build(F, std::optional<size_t>(Line), std::move(E));
1388 : }
1389 :
1390 : /// Concatenate a source file path and/or name with a std::error_code
1391 : /// to form an Error object.
1392 : inline Error createFileError(const Twine &F, std::error_code EC) {
1393 : return createFileError(F, errorCodeToError(EC));
1394 : }
1395 :
1396 : /// Concatenate a source file path and/or name with line number and
1397 : /// std::error_code to form an Error object.
1398 : inline Error createFileError(const Twine &F, size_t Line, std::error_code EC) {
1399 : return createFileError(F, Line, errorCodeToError(EC));
1400 : }
1401 :
1402 : Error createFileError(const Twine &F, ErrorSuccess) = delete;
1403 :
1404 : /// Helper for check-and-exit error handling.
1405 : ///
1406 : /// For tool use only. NOT FOR USE IN LIBRARY CODE.
1407 : ///
1408 : class ExitOnError {
1409 : public:
1410 : /// Create an error on exit helper.
1411 : ExitOnError(std::string Banner = "", int DefaultErrorExitCode = 1)
1412 : : Banner(std::move(Banner)),
1413 : GetExitCode([=](const Error &) { return DefaultErrorExitCode; }) {}
1414 :
1415 : /// Set the banner string for any errors caught by operator().
1416 : void setBanner(std::string Banner) { this->Banner = std::move(Banner); }
1417 :
1418 : /// Set the exit-code mapper function.
1419 : void setExitCodeMapper(std::function<int(const Error &)> GetExitCode) {
1420 : this->GetExitCode = std::move(GetExitCode);
1421 : }
1422 :
1423 : /// Check Err. If it's in a failure state log the error(s) and exit.
1424 : void operator()(Error Err) const { checkError(std::move(Err)); }
1425 :
1426 : /// Check E. If it's in a success state then return the contained value. If
1427 : /// it's in a failure state log the error(s) and exit.
1428 : template <typename T> T operator()(Expected<T> &&E) const {
1429 : checkError(E.takeError());
1430 : return std::move(*E);
1431 : }
1432 :
1433 : /// Check E. If it's in a success state then return the contained reference. If
1434 : /// it's in a failure state log the error(s) and exit.
1435 : template <typename T> T& operator()(Expected<T&> &&E) const {
1436 : checkError(E.takeError());
1437 : return *E;
1438 : }
1439 :
1440 : private:
1441 : void checkError(Error Err) const {
1442 : if (Err) {
1443 : int ExitCode = GetExitCode(Err);
1444 : logAllUnhandledErrors(std::move(Err), errs(), Banner);
1445 : exit(ExitCode);
1446 : }
1447 : }
1448 :
1449 : std::string Banner;
1450 : std::function<int(const Error &)> GetExitCode;
1451 : };
1452 :
1453 : /// Conversion from Error to LLVMErrorRef for C error bindings.
1454 : inline LLVMErrorRef wrap(Error Err) {
1455 : return reinterpret_cast<LLVMErrorRef>(Err.takePayload().release());
1456 : }
1457 :
1458 : /// Conversion from LLVMErrorRef to Error for C error bindings.
1459 : inline Error unwrap(LLVMErrorRef ErrRef) {
1460 : return Error(std::unique_ptr<ErrorInfoBase>(
1461 : reinterpret_cast<ErrorInfoBase *>(ErrRef)));
1462 : }
1463 :
1464 : } // end namespace llvm
1465 :
1466 : #endif // LLVM_SUPPORT_ERROR_H
|
