contrib/llvm/include/llvm/Support/Error.h

   1 //===- llvm/Support/Error.h - Recoverable error handling --------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file defines an API used to report recoverable errors.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_SUPPORT_ERROR_H
  15 #define LLVM_SUPPORT_ERROR_H
  16
  17 #include "llvm/ADT/SmallVector.h"
  18 #include "llvm/ADT/STLExtras.h"
  19 #include "llvm/ADT/StringExtras.h"
  20 #include "llvm/ADT/Twine.h"
  21 #include "llvm/Config/abi-breaking.h"
  22 #include "llvm/Support/AlignOf.h"
  23 #include "llvm/Support/Compiler.h"
  24 #include "llvm/Support/Debug.h"
  25 #include "llvm/Support/ErrorHandling.h"
  26 #include "llvm/Support/ErrorOr.h"
  27 #include "llvm/Support/raw_ostream.h"
  28 #include <algorithm>
  29 #include <cassert>
  30 #include <cstdint>
  31 #include <cstdlib>
  32 #include <functional>
  33 #include <memory>
  34 #include <new>
  35 #include <string>
  36 #include <system_error>
  37 #include <type_traits>
  38 #include <utility>
  39 #include <vector>
  40
  41 namespace llvm {
  42
  43 class ErrorSuccess;
  44
  45 /// Base class for error info classes. Do not extend this directly: Extend
  46 /// the ErrorInfo template subclass instead.
  47 class ErrorInfoBase {
  48 public:
  49   virtual ~ErrorInfoBase() = default;
  50
  51   /// Print an error message to an output stream.
  52   virtual void log(raw_ostream &OS) const = 0;
  53
  54   /// Return the error message as a string.
  55   virtual std::string message() const {
  56     std::string Msg;
  57     raw_string_ostream OS(Msg);
  58     log(OS);
  59     return OS.str();
  60   }
  61
  62   /// Convert this error to a std::error_code.
  63   ///
  64   /// This is a temporary crutch to enable interaction with code still
  65   /// using std::error_code. It will be removed in the future.
  66   virtual std::error_code convertToErrorCode() const = 0;
  67
  68   // Returns the class ID for this type.
  69   static const void *classID() { return &ID; }
  70
  71   // Returns the class ID for the dynamic type of this ErrorInfoBase instance.
  72   virtual const void *dynamicClassID() const = 0;
  73
  74   // Check whether this instance is a subclass of the class identified by
  75   // ClassID.
  76   virtual bool isA(const void *const ClassID) const {
  77     return ClassID == classID();
  78   }
  79
  80   // Check whether this instance is a subclass of ErrorInfoT.
  81   template <typename ErrorInfoT> bool isA() const {
  82     return isA(ErrorInfoT::classID());
  83   }
  84
  85 private:
  86   virtual void anchor();
  87
  88   static char ID;
  89 };
  90
  91 /// Lightweight error class with error context and mandatory checking.
  92 ///
  93 /// Instances of this class wrap a ErrorInfoBase pointer. Failure states
  94 /// are represented by setting the pointer to a ErrorInfoBase subclass
  95 /// instance containing information describing the failure. Success is
  96 /// represented by a null pointer value.
  97 ///
  98 /// Instances of Error also contains a 'Checked' flag, which must be set
  99 /// before the destructor is called, otherwise the destructor will trigger a
 100 /// runtime error. This enforces at runtime the requirement that all Error
 101 /// instances be checked or returned to the caller.
 102 ///
 103 /// There are two ways to set the checked flag, depending on what state the
 104 /// Error instance is in. For Error instances indicating success, it
 105 /// is sufficient to invoke the boolean conversion operator. E.g.:
 106 ///
 107 ///   @code{.cpp}
 108 ///   Error foo(<...>);
 109 ///
 110 ///   if (auto E = foo(<...>))
 111 ///     return E; // <- Return E if it is in the error state.
 112 ///   // We have verified that E was in the success state. It can now be safely
 113 ///   // destroyed.
 114 ///   @endcode
 115 ///
 116 /// A success value *can not* be dropped. For example, just calling 'foo(<...>)'
 117 /// without testing the return value will raise a runtime error, even if foo
 118 /// returns success.
 119 ///
 120 /// For Error instances representing failure, you must use either the
 121 /// handleErrors or handleAllErrors function with a typed handler. E.g.:
 122 ///
 123 ///   @code{.cpp}
 124 ///   class MyErrorInfo : public ErrorInfo<MyErrorInfo> {
 125 ///     // Custom error info.
 126 ///   };
 127 ///
 128 ///   Error foo(<...>) { return make_error<MyErrorInfo>(...); }
 129 ///
 130 ///   auto E = foo(<...>); // <- foo returns failure with MyErrorInfo.
 131 ///   auto NewE =
 132 ///     handleErrors(E,
 133 ///       [](const MyErrorInfo &M) {
 134 ///         // Deal with the error.
 135 ///       },
 136 ///       [](std::unique_ptr<OtherError> M) -> Error {
 137 ///         if (canHandle(*M)) {
 138 ///           // handle error.
 139 ///           return Error::success();
 140 ///         }
 141 ///         // Couldn't handle this error instance. Pass it up the stack.
 142 ///         return Error(std::move(M));
 143 ///       );
 144 ///   // Note - we must check or return NewE in case any of the handlers
 145 ///   // returned a new error.
 146 ///   @endcode
 147 ///
 148 /// The handleAllErrors function is identical to handleErrors, except
 149 /// that it has a void return type, and requires all errors to be handled and
 150 /// no new errors be returned. It prevents errors (assuming they can all be
 151 /// handled) from having to be bubbled all the way to the top-level.
 152 ///
 153 /// *All* Error instances must be checked before destruction, even if
 154 /// they're moved-assigned or constructed from Success values that have already
 155 /// been checked. This enforces checking through all levels of the call stack.
 156 class LLVM_NODISCARD Error {
 157   // ErrorList needs to be able to yank ErrorInfoBase pointers out of this
 158   // class to add to the error list.
 159   friend class ErrorList;
 160
 161   // handleErrors needs to be able to set the Checked flag.
 162   template <typename... HandlerTs>
 163   friend Error handleErrors(Error E, HandlerTs &&... Handlers);
 164
 165   // Expected<T> needs to be able to steal the payload when constructed from an
 166   // error.
 167   template <typename T> friend class Expected;
 168
 169 protected:
 170   /// Create a success value. Prefer using 'Error::success()' for readability
 171   Error() {
 172     setPtr(nullptr);
 173     setChecked(false);
 174   }
 175
 176 public:
 177   /// Create a success value.
 178   static ErrorSuccess success();
 179
 180   // Errors are not copy-constructable.
 181   Error(const Error &Other) = delete;
 182
 183   /// Move-construct an error value. The newly constructed error is considered
 184   /// unchecked, even if the source error had been checked. The original error
 185   /// becomes a checked Success value, regardless of its original state.
 186   Error(Error &&Other) {
 187     setChecked(true);
 188     *this = std::move(Other);
 189   }
 190
 191   /// Create an error value. Prefer using the 'make_error' function, but
 192   /// this constructor can be useful when "re-throwing" errors from handlers.
 193   Error(std::unique_ptr<ErrorInfoBase> Payload) {
 194     setPtr(Payload.release());
 195     setChecked(false);
 196   }
 197
 198   // Errors are not copy-assignable.
 199   Error &operator=(const Error &Other) = delete;
 200
 201   /// Move-assign an error value. The current error must represent success, you
 202   /// you cannot overwrite an unhandled error. The current error is then
 203   /// considered unchecked. The source error becomes a checked success value,
 204   /// regardless of its original state.
 205   Error &operator=(Error &&Other) {
 206     // Don't allow overwriting of unchecked values.
 207     assertIsChecked();
 208     setPtr(Other.getPtr());
 209
 210     // This Error is unchecked, even if the source error was checked.
 211     setChecked(false);
 212
 213     // Null out Other's payload and set its checked bit.
 214     Other.setPtr(nullptr);
 215     Other.setChecked(true);
 216
 217     return *this;
 218   }
 219
 220   /// Destroy a Error. Fails with a call to abort() if the error is
 221   /// unchecked.
 222   ~Error() {
 223     assertIsChecked();
 224     delete getPtr();
 225   }
 226
 227   /// Bool conversion. Returns true if this Error is in a failure state,
 228   /// and false if it is in an accept state. If the error is in a Success state
 229   /// it will be considered checked.
 230   explicit operator bool() {
 231     setChecked(getPtr() == nullptr);
 232     return getPtr() != nullptr;
 233   }
 234
 235   /// Check whether one error is a subclass of another.
 236   template <typename ErrT> bool isA() const {
 237     return getPtr() && getPtr()->isA(ErrT::classID());
 238   }
 239
 240   /// Returns the dynamic class id of this error, or null if this is a success
 241   /// value.
 242   const void* dynamicClassID() const {
 243     if (!getPtr())
 244       return nullptr;
 245     return getPtr()->dynamicClassID();
 246   }
 247
 248 private:
 249 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 250   // assertIsChecked() happens very frequently, but under normal circumstances
 251   // is supposed to be a no-op.  So we want it to be inlined, but having a bunch
 252   // of debug prints can cause the function to be too large for inlining.  So
 253   // it's important that we define this function out of line so that it can't be
 254   // inlined.
 255   LLVM_ATTRIBUTE_NORETURN
 256   void fatalUncheckedError() const;
 257 #endif
 258
 259   void assertIsChecked() {
 260 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 261     if (LLVM_UNLIKELY(!getChecked() || getPtr()))
 262       fatalUncheckedError();
 263 #endif
 264   }
 265
 266   ErrorInfoBase *getPtr() const {
 267     return reinterpret_cast<ErrorInfoBase*>(
 268              reinterpret_cast<uintptr_t>(Payload) &
 269              ~static_cast<uintptr_t>(0x1));
 270   }
 271
 272   void setPtr(ErrorInfoBase *EI) {
 273 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 274     Payload = reinterpret_cast<ErrorInfoBase*>(
 275                 (reinterpret_cast<uintptr_t>(EI) &
 276                  ~static_cast<uintptr_t>(0x1)) |
 277                 (reinterpret_cast<uintptr_t>(Payload) & 0x1));
 278 #else
 279     Payload = EI;
 280 #endif
 281   }
 282
 283   bool getChecked() const {
 284 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 285     return (reinterpret_cast<uintptr_t>(Payload) & 0x1) == 0;
 286 #else
 287     return true;
 288 #endif
 289   }
 290
 291   void setChecked(bool V) {
 292     Payload = reinterpret_cast<ErrorInfoBase*>(
 293                 (reinterpret_cast<uintptr_t>(Payload) &
 294                   ~static_cast<uintptr_t>(0x1)) |
 295                   (V ? 0 : 1));
 296   }
 297
 298   std::unique_ptr<ErrorInfoBase> takePayload() {
 299     std::unique_ptr<ErrorInfoBase> Tmp(getPtr());
 300     setPtr(nullptr);
 301     setChecked(true);
 302     return Tmp;
 303   }
 304
 305   ErrorInfoBase *Payload = nullptr;
 306 };
 307
 308 /// Subclass of Error for the sole purpose of identifying the success path in
 309 /// the type system. This allows to catch invalid conversion to Expected<T> at
 310 /// compile time.
 311 class ErrorSuccess : public Error {};
 312
 313 inline ErrorSuccess Error::success() { return ErrorSuccess(); }
 314
 315 /// Make a Error instance representing failure using the given error info
 316 /// type.
 317 template <typename ErrT, typename... ArgTs> Error make_error(ArgTs &&... Args) {
 318   return Error(llvm::make_unique<ErrT>(std::forward<ArgTs>(Args)...));
 319 }
 320
 321 /// Base class for user error types. Users should declare their error types
 322 /// like:
 323 ///
 324 /// class MyError : public ErrorInfo<MyError> {
 325 ///   ....
 326 /// };
 327 ///
 328 /// This class provides an implementation of the ErrorInfoBase::kind
 329 /// method, which is used by the Error RTTI system.
 330 template <typename ThisErrT, typename ParentErrT = ErrorInfoBase>
 331 class ErrorInfo : public ParentErrT {
 332 public:
 333   static const void *classID() { return &ThisErrT::ID; }
 334
 335   const void *dynamicClassID() const override { return &ThisErrT::ID; }
 336
 337   bool isA(const void *const ClassID) const override {
 338     return ClassID == classID() || ParentErrT::isA(ClassID);
 339   }
 340 };
 341
 342 /// Special ErrorInfo subclass representing a list of ErrorInfos.
 343 /// Instances of this class are constructed by joinError.
 344 class ErrorList final : public ErrorInfo<ErrorList> {
 345   // handleErrors needs to be able to iterate the payload list of an
 346   // ErrorList.
 347   template <typename... HandlerTs>
 348   friend Error handleErrors(Error E, HandlerTs &&... Handlers);
 349
 350   // joinErrors is implemented in terms of join.
 351   friend Error joinErrors(Error, Error);
 352
 353 public:
 354   void log(raw_ostream &OS) const override {
 355     OS << "Multiple errors:\n";
 356     for (auto &ErrPayload : Payloads) {
 357       ErrPayload->log(OS);
 358       OS << "\n";
 359     }
 360   }
 361
 362   std::error_code convertToErrorCode() const override;
 363
 364   // Used by ErrorInfo::classID.
 365   static char ID;
 366
 367 private:
 368   ErrorList(std::unique_ptr<ErrorInfoBase> Payload1,
 369             std::unique_ptr<ErrorInfoBase> Payload2) {
 370     assert(!Payload1->isA<ErrorList>() && !Payload2->isA<ErrorList>() &&
 371            "ErrorList constructor payloads should be singleton errors");
 372     Payloads.push_back(std::move(Payload1));
 373     Payloads.push_back(std::move(Payload2));
 374   }
 375
 376   static Error join(Error E1, Error E2) {
 377     if (!E1)
 378       return E2;
 379     if (!E2)
 380       return E1;
 381     if (E1.isA<ErrorList>()) {
 382       auto &E1List = static_cast<ErrorList &>(*E1.getPtr());
 383       if (E2.isA<ErrorList>()) {
 384         auto E2Payload = E2.takePayload();
 385         auto &E2List = static_cast<ErrorList &>(*E2Payload);
 386         for (auto &Payload : E2List.Payloads)
 387           E1List.Payloads.push_back(std::move(Payload));
 388       } else
 389         E1List.Payloads.push_back(E2.takePayload());
 390
 391       return E1;
 392     }
 393     if (E2.isA<ErrorList>()) {
 394       auto &E2List = static_cast<ErrorList &>(*E2.getPtr());
 395       E2List.Payloads.insert(E2List.Payloads.begin(), E1.takePayload());
 396       return E2;
 397     }
 398     return Error(std::unique_ptr<ErrorList>(
 399         new ErrorList(E1.takePayload(), E2.takePayload())));
 400   }
 401
 402   std::vector<std::unique_ptr<ErrorInfoBase>> Payloads;
 403 };
 404
 405 /// Concatenate errors. The resulting Error is unchecked, and contains the
 406 /// ErrorInfo(s), if any, contained in E1, followed by the
 407 /// ErrorInfo(s), if any, contained in E2.
 408 inline Error joinErrors(Error E1, Error E2) {
 409   return ErrorList::join(std::move(E1), std::move(E2));
 410 }
 411
 412 /// Tagged union holding either a T or a Error.
 413 ///
 414 /// This class parallels ErrorOr, but replaces error_code with Error. Since
 415 /// Error cannot be copied, this class replaces getError() with
 416 /// takeError(). It also adds an bool errorIsA<ErrT>() method for testing the
 417 /// error class type.
 418 template <class T> class LLVM_NODISCARD Expected {
 419   template <class T1> friend class ExpectedAsOutParameter;
 420   template <class OtherT> friend class Expected;
 421
 422   static const bool isRef = std::is_reference<T>::value;
 423
 424   using wrap = ReferenceStorage<typename std::remove_reference<T>::type>;
 425
 426   using error_type = std::unique_ptr<ErrorInfoBase>;
 427
 428 public:
 429   using storage_type = typename std::conditional<isRef, wrap, T>::type;
 430   using value_type = T;
 431
 432 private:
 433   using reference = typename std::remove_reference<T>::type &;
 434   using const_reference = const typename std::remove_reference<T>::type &;
 435   using pointer = typename std::remove_reference<T>::type *;
 436   using const_pointer = const typename std::remove_reference<T>::type *;
 437
 438 public:
 439   /// Create an Expected<T> error value from the given Error.
 440   Expected(Error Err)
 441       : HasError(true)
 442 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 443         // Expected is unchecked upon construction in Debug builds.
 444         , Unchecked(true)
 445 #endif
 446   {
 447     assert(Err && "Cannot create Expected<T> from Error success value.");
 448     new (getErrorStorage()) error_type(Err.takePayload());
 449   }
 450
 451   /// Forbid to convert from Error::success() implicitly, this avoids having
 452   /// Expected<T> foo() { return Error::success(); } which compiles otherwise
 453   /// but triggers the assertion above.
 454   Expected(ErrorSuccess) = delete;
 455
 456   /// Create an Expected<T> success value from the given OtherT value, which
 457   /// must be convertible to T.
 458   template <typename OtherT>
 459   Expected(OtherT &&Val,
 460            typename std::enable_if<std::is_convertible<OtherT, T>::value>::type
 461                * = nullptr)
 462       : HasError(false)
 463 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 464         // Expected is unchecked upon construction in Debug builds.
 465         , Unchecked(true)
 466 #endif
 467   {
 468     new (getStorage()) storage_type(std::forward<OtherT>(Val));
 469   }
 470
 471   /// Move construct an Expected<T> value.
 472   Expected(Expected &&Other) { moveConstruct(std::move(Other)); }
 473
 474   /// Move construct an Expected<T> value from an Expected<OtherT>, where OtherT
 475   /// must be convertible to T.
 476   template <class OtherT>
 477   Expected(Expected<OtherT> &&Other,
 478            typename std::enable_if<std::is_convertible<OtherT, T>::value>::type
 479                * = nullptr) {
 480     moveConstruct(std::move(Other));
 481   }
 482
 483   /// Move construct an Expected<T> value from an Expected<OtherT>, where OtherT
 484   /// isn't convertible to T.
 485   template <class OtherT>
 486   explicit Expected(
 487       Expected<OtherT> &&Other,
 488       typename std::enable_if<!std::is_convertible<OtherT, T>::value>::type * =
 489           nullptr) {
 490     moveConstruct(std::move(Other));
 491   }
 492
 493   /// Move-assign from another Expected<T>.
 494   Expected &operator=(Expected &&Other) {
 495     moveAssign(std::move(Other));
 496     return *this;
 497   }
 498
 499   /// Destroy an Expected<T>.
 500   ~Expected() {
 501     assertIsChecked();
 502     if (!HasError)
 503       getStorage()->~storage_type();
 504     else
 505       getErrorStorage()->~error_type();
 506   }
 507
 508   /// \brief Return false if there is an error.
 509   explicit operator bool() {
 510 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 511     Unchecked = HasError;
 512 #endif
 513     return !HasError;
 514   }
 515
 516   /// \brief Returns a reference to the stored T value.
 517   reference get() {
 518     assertIsChecked();
 519     return *getStorage();
 520   }
 521
 522   /// \brief Returns a const reference to the stored T value.
 523   const_reference get() const {
 524     assertIsChecked();
 525     return const_cast<Expected<T> *>(this)->get();
 526   }
 527
 528   /// \brief Check that this Expected<T> is an error of type ErrT.
 529   template <typename ErrT> bool errorIsA() const {
 530     return HasError && (*getErrorStorage())->template isA<ErrT>();
 531   }
 532
 533   /// \brief Take ownership of the stored error.
 534   /// After calling this the Expected<T> is in an indeterminate state that can
 535   /// only be safely destructed. No further calls (beside the destructor) should
 536   /// be made on the Expected<T> vaule.
 537   Error takeError() {
 538 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 539     Unchecked = false;
 540 #endif
 541     return HasError ? Error(std::move(*getErrorStorage())) : Error::success();
 542   }
 543
 544   /// \brief Returns a pointer to the stored T value.
 545   pointer operator->() {
 546     assertIsChecked();
 547     return toPointer(getStorage());
 548   }
 549
 550   /// \brief Returns a const pointer to the stored T value.
 551   const_pointer operator->() const {
 552     assertIsChecked();
 553     return toPointer(getStorage());
 554   }
 555
 556   /// \brief Returns a reference to the stored T value.
 557   reference operator*() {
 558     assertIsChecked();
 559     return *getStorage();
 560   }
 561
 562   /// \brief Returns a const reference to the stored T value.
 563   const_reference operator*() const {
 564     assertIsChecked();
 565     return *getStorage();
 566   }
 567
 568 private:
 569   template <class T1>
 570   static bool compareThisIfSameType(const T1 &a, const T1 &b) {
 571     return &a == &b;
 572   }
 573
 574   template <class T1, class T2>
 575   static bool compareThisIfSameType(const T1 &a, const T2 &b) {
 576     return false;
 577   }
 578
 579   template <class OtherT> void moveConstruct(Expected<OtherT> &&Other) {
 580     HasError = Other.HasError;
 581 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 582     Unchecked = true;
 583     Other.Unchecked = false;
 584 #endif
 585
 586     if (!HasError)
 587       new (getStorage()) storage_type(std::move(*Other.getStorage()));
 588     else
 589       new (getErrorStorage()) error_type(std::move(*Other.getErrorStorage()));
 590   }
 591
 592   template <class OtherT> void moveAssign(Expected<OtherT> &&Other) {
 593     assertIsChecked();
 594
 595     if (compareThisIfSameType(*this, Other))
 596       return;
 597
 598     this->~Expected();
 599     new (this) Expected(std::move(Other));
 600   }
 601
 602   pointer toPointer(pointer Val) { return Val; }
 603
 604   const_pointer toPointer(const_pointer Val) const { return Val; }
 605
 606   pointer toPointer(wrap *Val) { return &Val->get(); }
 607
 608   const_pointer toPointer(const wrap *Val) const { return &Val->get(); }
 609
 610   storage_type *getStorage() {
 611     assert(!HasError && "Cannot get value when an error exists!");
 612     return reinterpret_cast<storage_type *>(TStorage.buffer);
 613   }
 614
 615   const storage_type *getStorage() const {
 616     assert(!HasError && "Cannot get value when an error exists!");
 617     return reinterpret_cast<const storage_type *>(TStorage.buffer);
 618   }
 619
 620   error_type *getErrorStorage() {
 621     assert(HasError && "Cannot get error when a value exists!");
 622     return reinterpret_cast<error_type *>(ErrorStorage.buffer);
 623   }
 624
 625   const error_type *getErrorStorage() const {
 626     assert(HasError && "Cannot get error when a value exists!");
 627     return reinterpret_cast<const error_type *>(ErrorStorage.buffer);
 628   }
 629
 630   // Used by ExpectedAsOutParameter to reset the checked flag.
 631   void setUnchecked() {
 632 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 633     Unchecked = true;
 634 #endif
 635   }
 636
 637 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 638   LLVM_ATTRIBUTE_NORETURN
 639   LLVM_ATTRIBUTE_NOINLINE
 640   void fatalUncheckedExpected() const {
 641     dbgs() << "Expected<T> must be checked before access or destruction.\n";
 642     if (HasError) {
 643       dbgs() << "Unchecked Expected<T> contained error:\n";
 644       (*getErrorStorage())->log(dbgs());
 645     } else
 646       dbgs() << "Expected<T> value was in success state. (Note: Expected<T> "
 647                 "values in success mode must still be checked prior to being "
 648                 "destroyed).\n";
 649     abort();
 650   }
 651 #endif
 652
 653   void assertIsChecked() {
 654 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 655     if (LLVM_UNLIKELY(Unchecked))
 656       fatalUncheckedExpected();
 657 #endif
 658   }
 659
 660   union {
 661     AlignedCharArrayUnion<storage_type> TStorage;
 662     AlignedCharArrayUnion<error_type> ErrorStorage;
 663   };
 664   bool HasError : 1;
 665 #if LLVM_ENABLE_ABI_BREAKING_CHECKS
 666   bool Unchecked : 1;
 667 #endif
 668 };
 669
 670 /// Report a serious error, calling any installed error handler. See
 671 /// ErrorHandling.h.
 672 LLVM_ATTRIBUTE_NORETURN void report_fatal_error(Error Err,
 673                                                 bool gen_crash_diag = true);
 674
 675 /// Report a fatal error if Err is a failure value.
 676 ///
 677 /// This function can be used to wrap calls to fallible functions ONLY when it
 678 /// is known that the Error will always be a success value. E.g.
 679 ///
 680 ///   @code{.cpp}
 681 ///   // foo only attempts the fallible operation if DoFallibleOperation is
 682 ///   // true. If DoFallibleOperation is false then foo always returns
 683 ///   // Error::success().
 684 ///   Error foo(bool DoFallibleOperation);
 685 ///
 686 ///   cantFail(foo(false));
 687 ///   @endcode
 688 inline void cantFail(Error Err, const char *Msg = nullptr) {
 689   if (Err) {
 690     if (!Msg)
 691       Msg = "Failure value returned from cantFail wrapped call";
 692     llvm_unreachable(Msg);
 693   }
 694 }
 695
 696 /// Report a fatal error if ValOrErr is a failure value, otherwise unwraps and
 697 /// returns the contained value.
 698 ///
 699 /// This function can be used to wrap calls to fallible functions ONLY when it
 700 /// is known that the Error will always be a success value. E.g.
 701 ///
 702 ///   @code{.cpp}
 703 ///   // foo only attempts the fallible operation if DoFallibleOperation is
 704 ///   // true. If DoFallibleOperation is false then foo always returns an int.
 705 ///   Expected<int> foo(bool DoFallibleOperation);
 706 ///
 707 ///   int X = cantFail(foo(false));
 708 ///   @endcode
 709 template <typename T>
 710 T cantFail(Expected<T> ValOrErr, const char *Msg = nullptr) {
 711   if (ValOrErr)
 712     return std::move(*ValOrErr);
 713   else {
 714     if (!Msg)
 715       Msg = "Failure value returned from cantFail wrapped call";
 716     llvm_unreachable(Msg);
 717   }
 718 }
 719
 720 /// Report a fatal error if ValOrErr is a failure value, otherwise unwraps and
 721 /// returns the contained reference.
 722 ///
 723 /// This function can be used to wrap calls to fallible functions ONLY when it
 724 /// is known that the Error will always be a success value. E.g.
 725 ///
 726 ///   @code{.cpp}
 727 ///   // foo only attempts the fallible operation if DoFallibleOperation is
 728 ///   // true. If DoFallibleOperation is false then foo always returns a Bar&.
 729 ///   Expected<Bar&> foo(bool DoFallibleOperation);
 730 ///
 731 ///   Bar &X = cantFail(foo(false));
 732 ///   @endcode
 733 template <typename T>
 734 T& cantFail(Expected<T&> ValOrErr, const char *Msg = nullptr) {
 735   if (ValOrErr)
 736     return *ValOrErr;
 737   else {
 738     if (!Msg)
 739       Msg = "Failure value returned from cantFail wrapped call";
 740     llvm_unreachable(Msg);
 741   }
 742 }
 743
 744 /// Helper for testing applicability of, and applying, handlers for
 745 /// ErrorInfo types.
 746 template <typename HandlerT>
 747 class ErrorHandlerTraits
 748     : public ErrorHandlerTraits<decltype(
 749           &std::remove_reference<HandlerT>::type::operator())> {};
 750
 751 // Specialization functions of the form 'Error (const ErrT&)'.
 752 template <typename ErrT> class ErrorHandlerTraits<Error (&)(ErrT &)> {
 753 public:
 754   static bool appliesTo(const ErrorInfoBase &E) {
 755     return E.template isA<ErrT>();
 756   }
 757
 758   template <typename HandlerT>
 759   static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
 760     assert(appliesTo(*E) && "Applying incorrect handler");
 761     return H(static_cast<ErrT &>(*E));
 762   }
 763 };
 764
 765 // Specialization functions of the form 'void (const ErrT&)'.
 766 template <typename ErrT> class ErrorHandlerTraits<void (&)(ErrT &)> {
 767 public:
 768   static bool appliesTo(const ErrorInfoBase &E) {
 769     return E.template isA<ErrT>();
 770   }
 771
 772   template <typename HandlerT>
 773   static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
 774     assert(appliesTo(*E) && "Applying incorrect handler");
 775     H(static_cast<ErrT &>(*E));
 776     return Error::success();
 777   }
 778 };
 779
 780 /// Specialization for functions of the form 'Error (std::unique_ptr<ErrT>)'.
 781 template <typename ErrT>
 782 class ErrorHandlerTraits<Error (&)(std::unique_ptr<ErrT>)> {
 783 public:
 784   static bool appliesTo(const ErrorInfoBase &E) {
 785     return E.template isA<ErrT>();
 786   }
 787
 788   template <typename HandlerT>
 789   static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
 790     assert(appliesTo(*E) && "Applying incorrect handler");
 791     std::unique_ptr<ErrT> SubE(static_cast<ErrT *>(E.release()));
 792     return H(std::move(SubE));
 793   }
 794 };
 795
 796 /// Specialization for functions of the form 'void (std::unique_ptr<ErrT>)'.
 797 template <typename ErrT>
 798 class ErrorHandlerTraits<void (&)(std::unique_ptr<ErrT>)> {
 799 public:
 800   static bool appliesTo(const ErrorInfoBase &E) {
 801     return E.template isA<ErrT>();
 802   }
 803
 804   template <typename HandlerT>
 805   static Error apply(HandlerT &&H, std::unique_ptr<ErrorInfoBase> E) {
 806     assert(appliesTo(*E) && "Applying incorrect handler");
 807     std::unique_ptr<ErrT> SubE(static_cast<ErrT *>(E.release()));
 808     H(std::move(SubE));
 809     return Error::success();
 810   }
 811 };
 812
 813 // Specialization for member functions of the form 'RetT (const ErrT&)'.
 814 template <typename C, typename RetT, typename ErrT>
 815 class ErrorHandlerTraits<RetT (C::*)(ErrT &)>
 816     : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
 817
 818 // Specialization for member functions of the form 'RetT (const ErrT&) const'.
 819 template <typename C, typename RetT, typename ErrT>
 820 class ErrorHandlerTraits<RetT (C::*)(ErrT &) const>
 821     : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
 822
 823 // Specialization for member functions of the form 'RetT (const ErrT&)'.
 824 template <typename C, typename RetT, typename ErrT>
 825 class ErrorHandlerTraits<RetT (C::*)(const ErrT &)>
 826     : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
 827
 828 // Specialization for member functions of the form 'RetT (const ErrT&) const'.
 829 template <typename C, typename RetT, typename ErrT>
 830 class ErrorHandlerTraits<RetT (C::*)(const ErrT &) const>
 831     : public ErrorHandlerTraits<RetT (&)(ErrT &)> {};
 832
 833 /// Specialization for member functions of the form
 834 /// 'RetT (std::unique_ptr<ErrT>)'.
 835 template <typename C, typename RetT, typename ErrT>
 836 class ErrorHandlerTraits<RetT (C::*)(std::unique_ptr<ErrT>)>
 837     : public ErrorHandlerTraits<RetT (&)(std::unique_ptr<ErrT>)> {};
 838
 839 /// Specialization for member functions of the form
 840 /// 'RetT (std::unique_ptr<ErrT>) const'.
 841 template <typename C, typename RetT, typename ErrT>
 842 class ErrorHandlerTraits<RetT (C::*)(std::unique_ptr<ErrT>) const>
 843     : public ErrorHandlerTraits<RetT (&)(std::unique_ptr<ErrT>)> {};
 844
 845 inline Error handleErrorImpl(std::unique_ptr<ErrorInfoBase> Payload) {
 846   return Error(std::move(Payload));
 847 }
 848
 849 template <typename HandlerT, typename... HandlerTs>
 850 Error handleErrorImpl(std::unique_ptr<ErrorInfoBase> Payload,
 851                       HandlerT &&Handler, HandlerTs &&... Handlers) {
 852   if (ErrorHandlerTraits<HandlerT>::appliesTo(*Payload))
 853     return ErrorHandlerTraits<HandlerT>::apply(std::forward<HandlerT>(Handler),
 854                                                std::move(Payload));
 855   return handleErrorImpl(std::move(Payload),
 856                          std::forward<HandlerTs>(Handlers)...);
 857 }
 858
 859 /// Pass the ErrorInfo(s) contained in E to their respective handlers. Any
 860 /// unhandled errors (or Errors returned by handlers) are re-concatenated and
 861 /// returned.
 862 /// Because this function returns an error, its result must also be checked
 863 /// or returned. If you intend to handle all errors use handleAllErrors
 864 /// (which returns void, and will abort() on unhandled errors) instead.
 865 template <typename... HandlerTs>
 866 Error handleErrors(Error E, HandlerTs &&... Hs) {
 867   if (!E)
 868     return Error::success();
 869
 870   std::unique_ptr<ErrorInfoBase> Payload = E.takePayload();
 871
 872   if (Payload->isA<ErrorList>()) {
 873     ErrorList &List = static_cast<ErrorList &>(*Payload);
 874     Error R;
 875     for (auto &P : List.Payloads)
 876       R = ErrorList::join(
 877           std::move(R),
 878           handleErrorImpl(std::move(P), std::forward<HandlerTs>(Hs)...));
 879     return R;
 880   }
 881
 882   return handleErrorImpl(std::move(Payload), std::forward<HandlerTs>(Hs)...);
 883 }
 884
 885 /// Behaves the same as handleErrors, except that it requires that all
 886 /// errors be handled by the given handlers. If any unhandled error remains
 887 /// after the handlers have run, report_fatal_error() will be called.
 888 template <typename... HandlerTs>
 889 void handleAllErrors(Error E, HandlerTs &&... Handlers) {
 890   cantFail(handleErrors(std::move(E), std::forward<HandlerTs>(Handlers)...));
 891 }
 892
 893 /// Check that E is a non-error, then drop it.
 894 /// If E is an error report_fatal_error will be called.
 895 inline void handleAllErrors(Error E) {
 896   cantFail(std::move(E));
 897 }
 898
 899 /// Handle any errors (if present) in an Expected<T>, then try a recovery path.
 900 ///
 901 /// If the incoming value is a success value it is returned unmodified. If it
 902 /// is a failure value then it the contained error is passed to handleErrors.
 903 /// If handleErrors is able to handle the error then the RecoveryPath functor
 904 /// is called to supply the final result. If handleErrors is not able to
 905 /// handle all errors then the unhandled errors are returned.
 906 ///
 907 /// This utility enables the follow pattern:
 908 ///
 909 ///   @code{.cpp}
 910 ///   enum FooStrategy { Aggressive, Conservative };
 911 ///   Expected<Foo> foo(FooStrategy S);
 912 ///
 913 ///   auto ResultOrErr =
 914 ///     handleExpected(
 915 ///       foo(Aggressive),
 916 ///       []() { return foo(Conservative); },
 917 ///       [](AggressiveStrategyError&) {
 918 ///         // Implicitly conusme this - we'll recover by using a conservative
 919 ///         // strategy.
 920 ///       });
 921 ///
 922 ///   @endcode
 923 template <typename T, typename RecoveryFtor, typename... HandlerTs>
 924 Expected<T> handleExpected(Expected<T> ValOrErr, RecoveryFtor &&RecoveryPath,
 925                            HandlerTs &&... Handlers) {
 926   if (ValOrErr)
 927     return ValOrErr;
 928
 929   if (auto Err = handleErrors(ValOrErr.takeError(),
 930                               std::forward<HandlerTs>(Handlers)...))
 931     return std::move(Err);
 932
 933   return RecoveryPath();
 934 }
 935
 936 /// Log all errors (if any) in E to OS. If there are any errors, ErrorBanner
 937 /// will be printed before the first one is logged. A newline will be printed
 938 /// after each error.
 939 ///
 940 /// This is useful in the base level of your program to allow clean termination
 941 /// (allowing clean deallocation of resources, etc.), while reporting error
 942 /// information to the user.
 943 void logAllUnhandledErrors(Error E, raw_ostream &OS, Twine ErrorBanner);
 944
 945 /// Write all error messages (if any) in E to a string. The newline character
 946 /// is used to separate error messages.
 947 inline std::string toString(Error E) {
 948   SmallVector<std::string, 2> Errors;
 949   handleAllErrors(std::move(E), [&Errors](const ErrorInfoBase &EI) {
 950     Errors.push_back(EI.message());
 951   });
 952   return join(Errors.begin(), Errors.end(), "\n");
 953 }
 954
 955 /// Consume a Error without doing anything. This method should be used
 956 /// only where an error can be considered a reasonable and expected return
 957 /// value.
 958 ///
 959 /// Uses of this method are potentially indicative of design problems: If it's
 960 /// legitimate to do nothing while processing an "error", the error-producer
 961 /// might be more clearly refactored to return an Optional<T>.
 962 inline void consumeError(Error Err) {
 963   handleAllErrors(std::move(Err), [](const ErrorInfoBase &) {});
 964 }
 965
 966 /// Helper for Errors used as out-parameters.
 967 ///
 968 /// This helper is for use with the Error-as-out-parameter idiom, where an error
 969 /// is passed to a function or method by reference, rather than being returned.
 970 /// In such cases it is helpful to set the checked bit on entry to the function
 971 /// so that the error can be written to (unchecked Errors abort on assignment)
 972 /// and clear the checked bit on exit so that clients cannot accidentally forget
 973 /// to check the result. This helper performs these actions automatically using
 974 /// RAII:
 975 ///
 976 ///   @code{.cpp}
 977 ///   Result foo(Error &Err) {
 978 ///     ErrorAsOutParameter ErrAsOutParam(&Err); // 'Checked' flag set
 979 ///     // <body of foo>
 980 ///     // <- 'Checked' flag auto-cleared when ErrAsOutParam is destructed.
 981 ///   }
 982 ///   @endcode
 983 ///
 984 /// ErrorAsOutParameter takes an Error* rather than Error& so that it can be
 985 /// used with optional Errors (Error pointers that are allowed to be null). If
 986 /// ErrorAsOutParameter took an Error reference, an instance would have to be
 987 /// created inside every condition that verified that Error was non-null. By
 988 /// taking an Error pointer we can just create one instance at the top of the
 989 /// function.
 990 class ErrorAsOutParameter {
 991 public:
 992   ErrorAsOutParameter(Error *Err) : Err(Err) {
 993     // Raise the checked bit if Err is success.
 994     if (Err)
 995       (void)!!*Err;
 996   }
 997
 998   ~ErrorAsOutParameter() {
 999     // Clear the checked bit.
1000     if (Err && !*Err)
1001       *Err = Error::success();
1002   }
1003
1004 private:
1005   Error *Err;
1006 };
1007
1008 /// Helper for Expected<T>s used as out-parameters.
1009 ///
1010 /// See ErrorAsOutParameter.
1011 template <typename T>
1012 class ExpectedAsOutParameter {
1013 public:
1014   ExpectedAsOutParameter(Expected<T> *ValOrErr)
1015     : ValOrErr(ValOrErr) {
1016     if (ValOrErr)
1017       (void)!!*ValOrErr;
1018   }
1019
1020   ~ExpectedAsOutParameter() {
1021     if (ValOrErr)
1022       ValOrErr->setUnchecked();
1023   }
1024
1025 private:
1026   Expected<T> *ValOrErr;
1027 };
1028
1029 /// This class wraps a std::error_code in a Error.
1030 ///
1031 /// This is useful if you're writing an interface that returns a Error
1032 /// (or Expected) and you want to call code that still returns
1033 /// std::error_codes.
1034 class ECError : public ErrorInfo<ECError> {
1035   friend Error errorCodeToError(std::error_code);
1036
1037 public:
1038   void setErrorCode(std::error_code EC) { this->EC = EC; }
1039   std::error_code convertToErrorCode() const override { return EC; }
1040   void log(raw_ostream &OS) const override { OS << EC.message(); }
1041
1042   // Used by ErrorInfo::classID.
1043   static char ID;
1044
1045 protected:
1046   ECError() = default;
1047   ECError(std::error_code EC) : EC(EC) {}
1048
1049   std::error_code EC;
1050 };
1051
1052 /// The value returned by this function can be returned from convertToErrorCode
1053 /// for Error values where no sensible translation to std::error_code exists.
1054 /// It should only be used in this situation, and should never be used where a
1055 /// sensible conversion to std::error_code is available, as attempts to convert
1056 /// to/from this error will result in a fatal error. (i.e. it is a programmatic
1057 ///error to try to convert such a value).
1058 std::error_code inconvertibleErrorCode();
1059
1060 /// Helper for converting an std::error_code to a Error.
1061 Error errorCodeToError(std::error_code EC);
1062
1063 /// Helper for converting an ECError to a std::error_code.
1064 ///
1065 /// This method requires that Err be Error() or an ECError, otherwise it
1066 /// will trigger a call to abort().
1067 std::error_code errorToErrorCode(Error Err);
1068
1069 /// Convert an ErrorOr<T> to an Expected<T>.
1070 template <typename T> Expected<T> errorOrToExpected(ErrorOr<T> &&EO) {
1071   if (auto EC = EO.getError())
1072     return errorCodeToError(EC);
1073   return std::move(*EO);
1074 }
1075
1076 /// Convert an Expected<T> to an ErrorOr<T>.
1077 template <typename T> ErrorOr<T> expectedToErrorOr(Expected<T> &&E) {
1078   if (auto Err = E.takeError())
1079     return errorToErrorCode(std::move(Err));
1080   return std::move(*E);
1081 }
1082
1083 /// This class wraps a string in an Error.
1084 ///
1085 /// StringError is useful in cases where the client is not expected to be able
1086 /// to consume the specific error message programmatically (for example, if the
1087 /// error message is to be presented to the user).
1088 class StringError : public ErrorInfo<StringError> {
1089 public:
1090   static char ID;
1091
1092   StringError(const Twine &S, std::error_code EC);
1093
1094   void log(raw_ostream &OS) const override;
1095   std::error_code convertToErrorCode() const override;
1096
1097   const std::string &getMessage() const { return Msg; }
1098
1099 private:
1100   std::string Msg;
1101   std::error_code EC;
1102 };
1103
1104 /// Helper for check-and-exit error handling.
1105 ///
1106 /// For tool use only. NOT FOR USE IN LIBRARY CODE.
1107 ///
1108 class ExitOnError {
1109 public:
1110   /// Create an error on exit helper.
1111   ExitOnError(std::string Banner = "", int DefaultErrorExitCode = 1)
1112       : Banner(std::move(Banner)),
1113         GetExitCode([=](const Error &) { return DefaultErrorExitCode; }) {}
1114
1115   /// Set the banner string for any errors caught by operator().
1116   void setBanner(std::string Banner) { this->Banner = std::move(Banner); }
1117
1118   /// Set the exit-code mapper function.
1119   void setExitCodeMapper(std::function<int(const Error &)> GetExitCode) {
1120     this->GetExitCode = std::move(GetExitCode);
1121   }
1122
1123   /// Check Err. If it's in a failure state log the error(s) and exit.
1124   void operator()(Error Err) const { checkError(std::move(Err)); }
1125
1126   /// Check E. If it's in a success state then return the contained value. If
1127   /// it's in a failure state log the error(s) and exit.
1128   template <typename T> T operator()(Expected<T> &&E) const {
1129     checkError(E.takeError());
1130     return std::move(*E);
1131   }
1132
1133   /// Check E. If it's in a success state then return the contained reference. If
1134   /// it's in a failure state log the error(s) and exit.
1135   template <typename T> T& operator()(Expected<T&> &&E) const {
1136     checkError(E.takeError());
1137     return *E;
1138   }
1139
1140 private:
1141   void checkError(Error Err) const {
1142     if (Err) {
1143       int ExitCode = GetExitCode(Err);
1144       logAllUnhandledErrors(std::move(Err), errs(), Banner);
1145       exit(ExitCode);
1146     }
1147   }
1148
1149   std::string Banner;
1150   std::function<int(const Error &)> GetExitCode;
1151 };
1152
1153 } // end namespace llvm
1154
1155 #endif // LLVM_SUPPORT_ERROR_H