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