include/llvm/Support/ErrorOr.h

   1 //===- llvm/Support/ErrorOr.h - Error Smart Pointer -----------------------===//
   2 //
   3 //                             The LLVM Linker
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 ///
  10 /// \file
  11 ///
  12 /// Provides ErrorOr<T> smart pointer.
  13 ///
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_SUPPORT_ERROR_OR_H
  17 #define LLVM_SUPPORT_ERROR_OR_H
  18
  19 #include "llvm/ADT/PointerIntPair.h"
  20 #include "llvm/Support/AlignOf.h"
  21 #include "llvm/Support/system_error.h"
  22 #include "llvm/Support/type_traits.h"
  23
  24 #include <cassert>
  25 #if LLVM_HAS_CXX11_TYPETRAITS
  26 #include <type_traits>
  27 #endif
  28
  29 namespace llvm {
  30 struct ErrorHolderBase {
  31   error_code Error;
  32   uint16_t RefCount;
  33   bool HasUserData;
  34
  35   ErrorHolderBase() : RefCount(1) {}
  36
  37   void aquire() {
  38     ++RefCount;
  39   }
  40
  41   void release() {
  42     if (--RefCount == 0)
  43       delete this;
  44   }
  45
  46 protected:
  47   virtual ~ErrorHolderBase() {}
  48 };
  49
  50 template<class T>
  51 struct ErrorHolder : ErrorHolderBase {
  52 #if LLVM_HAS_RVALUE_REFERENCES
  53   ErrorHolder(T &&UD) : UserData(llvm_move(UD)) {}
  54 #else
  55   ErrorHolder(T &UD) : UserData(UD) {}
  56 #endif
  57   T UserData;
  58 };
  59
  60 template<class Tp> struct ErrorOrUserDataTraits : llvm::false_type {};
  61
  62 #if LLVM_HAS_CXX11_TYPETRAITS && LLVM_HAS_RVALUE_REFERENCES
  63 template<class T, class V>
  64 typename std::enable_if< std::is_constructible<T, V>::value
  65                        , typename std::remove_reference<V>::type>::type &&
  66  moveIfMoveConstructible(V &Val) {
  67   return std::move(Val);
  68 }
  69
  70 template<class T, class V>
  71 typename std::enable_if< !std::is_constructible<T, V>::value
  72                        , typename std::remove_reference<V>::type>::type &
  73 moveIfMoveConstructible(V &Val) {
  74   return Val;
  75 }
  76 #else
  77 template<class T, class V>
  78 V &moveIfMoveConstructible(V &Val) {
  79   return Val;
  80 }
  81 #endif
  82
  83 /// \brief Stores a reference that can be changed.
  84 template <typename T>
  85 class ReferenceStorage {
  86   T *Storage;
  87
  88 public:
  89   ReferenceStorage(T &Ref) : Storage(&Ref) {}
  90
  91   operator T &() const { return *Storage; }
  92   T &get() const { return *Storage; }
  93 };
  94
  95 /// \brief Represents either an error or a value T.
  96 ///
  97 /// ErrorOr<T> is a pointer-like class that represents the result of an
  98 /// operation. The result is either an error, or a value of type T. This is
  99 /// designed to emulate the usage of returning a pointer where nullptr indicates
 100 /// failure. However instead of just knowing that the operation failed, we also
 101 /// have an error_code and optional user data that describes why it failed.
 102 ///
 103 /// It is used like the following.
 104 /// \code
 105 ///   ErrorOr<Buffer> getBuffer();
 106 ///   void handleError(error_code ec);
 107 ///
 108 ///   auto buffer = getBuffer();
 109 ///   if (!buffer)
 110 ///     handleError(buffer);
 111 ///   buffer->write("adena");
 112 /// \endcode
 113 ///
 114 /// ErrorOr<T> also supports user defined data for specific error_codes. To use
 115 /// this feature you must first add a template specialization of
 116 /// ErrorOrUserDataTraits derived from std::true_type for your type in the lld
 117 /// namespace. This specialization must have a static error_code error()
 118 /// function that returns the error_code this data is used with.
 119 ///
 120 /// getError<UserData>() may be called to get either the stored user data, or
 121 /// a default constructed UserData if none was stored.
 122 ///
 123 /// Example:
 124 /// \code
 125 ///   struct InvalidArgError {
 126 ///     InvalidArgError() {}
 127 ///     InvalidArgError(std::string S) : ArgName(S) {}
 128 ///     std::string ArgName;
 129 ///   };
 130 ///
 131 ///   namespace llvm {
 132 ///   template<>
 133 ///   struct ErrorOrUserDataTraits<InvalidArgError> : std::true_type {
 134 ///     static error_code error() {
 135 ///       return make_error_code(errc::invalid_argument);
 136 ///     }
 137 ///   };
 138 ///   } // end namespace llvm
 139 ///
 140 ///   using namespace llvm;
 141 ///
 142 ///   ErrorOr<int> foo() {
 143 ///     return InvalidArgError("adena");
 144 ///   }
 145 ///
 146 ///   int main() {
 147 ///     auto a = foo();
 148 ///     if (!a && error_code(a) == errc::invalid_argument)
 149 ///       llvm::errs() << a.getError<InvalidArgError>().ArgName << "\n";
 150 ///   }
 151 /// \endcode
 152 ///
 153 /// An implicit conversion to bool provides a way to check if there was an
 154 /// error. The unary * and -> operators provide pointer like access to the
 155 /// value. Accessing the value when there is an error has undefined behavior.
 156 ///
 157 /// When T is a reference type the behaivor is slightly different. The reference
 158 /// is held in a std::reference_wrapper<std::remove_reference<T>::type>, and
 159 /// there is special handling to make operator -> work as if T was not a
 160 /// reference.
 161 ///
 162 /// T cannot be a rvalue reference.
 163 template<class T>
 164 class ErrorOr {
 165   static const bool isRef = is_reference<T>::value;
 166   typedef ReferenceStorage<typename remove_reference<T>::type> wrap;
 167
 168 public:
 169   typedef typename
 170     conditional< isRef
 171                , wrap
 172                , T
 173                >::type storage_type;
 174
 175 private:
 176   typedef typename remove_reference<T>::type &reference;
 177   typedef typename remove_reference<T>::type *pointer;
 178
 179 public:
 180   ErrorOr() : IsValid(false) {}
 181
 182   ErrorOr(llvm::error_code EC) : HasError(true), IsValid(true) {
 183     Error = new ErrorHolderBase;
 184     Error->Error = EC;
 185     Error->HasUserData = false;
 186   }
 187
 188   template<class UserDataT>
 189   ErrorOr(UserDataT UD, typename
 190           enable_if_c<ErrorOrUserDataTraits<UserDataT>::value>::type* = 0)
 191     : HasError(true), IsValid(true) {
 192     Error = new ErrorHolder<UserDataT>(llvm_move(UD));
 193     Error->Error = ErrorOrUserDataTraits<UserDataT>::error();
 194     Error->HasUserData = true;
 195   }
 196
 197   ErrorOr(T Val) : HasError(false), IsValid(true) {
 198     new (get()) storage_type(moveIfMoveConstructible<storage_type>(Val));
 199   }
 200
 201   ErrorOr(const ErrorOr &Other) : IsValid(false) {
 202     // Construct an invalid ErrorOr if other is invalid.
 203     if (!Other.IsValid)
 204       return;
 205     IsValid = true;
 206     if (!Other.HasError) {
 207       // Get the other value.
 208       HasError = false;
 209       new (get()) storage_type(*Other.get());
 210     } else {
 211       // Get other's error.
 212       Error = Other.Error;
 213       HasError = true;
 214       Error->aquire();
 215     }
 216   }
 217
 218   ErrorOr &operator =(const ErrorOr &Other) {
 219     if (this == &Other)
 220       return *this;
 221
 222     this->~ErrorOr();
 223     new (this) ErrorOr(Other);
 224
 225     return *this;
 226   }
 227
 228 #if LLVM_HAS_RVALUE_REFERENCES
 229   ErrorOr(ErrorOr &&Other) : IsValid(false) {
 230     // Construct an invalid ErrorOr if other is invalid.
 231     if (!Other.IsValid)
 232       return;
 233     IsValid = true;
 234     if (!Other.HasError) {
 235       // Get the other value.
 236       HasError = false;
 237       new (get()) storage_type(std::move(*Other.get()));
 238       // Tell other not to do any destruction.
 239       Other.IsValid = false;
 240     } else {
 241       // Get other's error.
 242       Error = Other.Error;
 243       HasError = true;
 244       // Tell other not to do any destruction.
 245       Other.IsValid = false;
 246     }
 247   }
 248
 249   ErrorOr &operator =(ErrorOr &&Other) {
 250     if (this == &Other)
 251       return *this;
 252
 253     this->~ErrorOr();
 254     new (this) ErrorOr(std::move(Other));
 255
 256     return *this;
 257   }
 258 #endif
 259
 260   ~ErrorOr() {
 261     if (!IsValid)
 262       return;
 263     if (HasError)
 264       Error->release();
 265     else
 266       get()->~storage_type();
 267   }
 268
 269   template<class ET>
 270   ET getError() const {
 271     assert(IsValid && "Cannot get the error of a default constructed ErrorOr!");
 272     assert(HasError && "Cannot get an error if none exists!");
 273     assert(ErrorOrUserDataTraits<ET>::error() == Error->Error &&
 274            "Incorrect user error data type for error!");
 275     if (!Error->HasUserData)
 276       return ET();
 277     return reinterpret_cast<const ErrorHolder<ET>*>(Error)->UserData;
 278   }
 279
 280   typedef void (*unspecified_bool_type)();
 281   static void unspecified_bool_true() {}
 282
 283   /// \brief Return false if there is an error.
 284   operator unspecified_bool_type() const {
 285     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 286     return HasError ? 0 : unspecified_bool_true;
 287   }
 288
 289   operator llvm::error_code() const {
 290     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 291     return HasError ? Error->Error : llvm::error_code::success();
 292   }
 293
 294   pointer operator ->() {
 295     return toPointer(get());
 296   }
 297
 298   reference operator *() {
 299     return *get();
 300   }
 301
 302 private:
 303   pointer toPointer(pointer Val) {
 304     return Val;
 305   }
 306
 307   pointer toPointer(wrap *Val) {
 308     return &Val->get();
 309   }
 310
 311 protected:
 312   storage_type *get() {
 313     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 314     assert(!HasError && "Cannot get value when an error exists!");
 315     return reinterpret_cast<storage_type*>(TStorage.buffer);
 316   }
 317
 318   const storage_type *get() const {
 319     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 320     assert(!HasError && "Cannot get value when an error exists!");
 321     return reinterpret_cast<const storage_type*>(TStorage.buffer);
 322   }
 323
 324   union {
 325     AlignedCharArrayUnion<storage_type> TStorage;
 326     ErrorHolderBase *Error;
 327   };
 328   bool HasError : 1;
 329   bool IsValid : 1;
 330 };
 331
 332 // ErrorOr specialization for void.
 333 template <>
 334 class ErrorOr<void> {
 335 public:
 336   ErrorOr() : Error(0, 0) {}
 337
 338   ErrorOr(llvm::error_code EC) : Error(0, 0) {
 339     if (EC == errc::success) {
 340       Error.setInt(1);
 341       return;
 342     }
 343     ErrorHolderBase *E = new ErrorHolderBase;
 344     E->Error = EC;
 345     E->HasUserData = false;
 346     Error.setPointer(E);
 347   }
 348
 349   template<class UserDataT>
 350   ErrorOr(UserDataT UD, typename
 351           enable_if_c<ErrorOrUserDataTraits<UserDataT>::value>::type* = 0)
 352       : Error(0, 0) {
 353     ErrorHolderBase *E = new ErrorHolder<UserDataT>(llvm_move(UD));
 354     E->Error = ErrorOrUserDataTraits<UserDataT>::error();
 355     E->HasUserData = true;
 356     Error.setPointer(E);
 357   }
 358
 359   ErrorOr(const ErrorOr &Other) : Error(0, 0) {
 360     Error = Other.Error;
 361     if (Other.Error.getPointer()->Error) {
 362       Error.getPointer()->aquire();
 363     }
 364   }
 365
 366   ErrorOr &operator =(const ErrorOr &Other) {
 367     if (this == &Other)
 368       return *this;
 369
 370     this->~ErrorOr();
 371     new (this) ErrorOr(Other);
 372
 373     return *this;
 374   }
 375
 376 #if LLVM_HAS_RVALUE_REFERENCES
 377   ErrorOr(ErrorOr &&Other) : Error(0) {
 378     // Get other's error.
 379     Error = Other.Error;
 380     // Tell other not to do any destruction.
 381     Other.Error.setPointer(0);
 382   }
 383
 384   ErrorOr &operator =(ErrorOr &&Other) {
 385     if (this == &Other)
 386       return *this;
 387
 388     this->~ErrorOr();
 389     new (this) ErrorOr(std::move(Other));
 390
 391     return *this;
 392   }
 393 #endif
 394
 395   ~ErrorOr() {
 396     if (Error.getPointer())
 397       Error.getPointer()->release();
 398   }
 399
 400   template<class ET>
 401   ET getError() const {
 402     assert(ErrorOrUserDataTraits<ET>::error() == *this &&
 403            "Incorrect user error data type for error!");
 404     if (!Error.getPointer()->HasUserData)
 405       return ET();
 406     return reinterpret_cast<const ErrorHolder<ET> *>(
 407         Error.getPointer())->UserData;
 408   }
 409
 410   typedef void (*unspecified_bool_type)();
 411   static void unspecified_bool_true() {}
 412
 413   /// \brief Return false if there is an error.
 414   operator unspecified_bool_type() const {
 415     return Error.getInt() ? unspecified_bool_true : 0;
 416   }
 417
 418   operator llvm::error_code() const {
 419     return Error.getInt() ? make_error_code(errc::success)
 420                           : Error.getPointer()->Error;
 421   }
 422
 423 private:
 424   // If the bit is 1, the error is success.
 425   llvm::PointerIntPair<ErrorHolderBase *, 1> Error;
 426 };
 427
 428 template<class T, class E>
 429 typename enable_if_c<is_error_code_enum<E>::value ||
 430                      is_error_condition_enum<E>::value, bool>::type
 431 operator ==(ErrorOr<T> &Err, E Code) {
 432   return error_code(Err) == Code;
 433 }
 434 } // end namespace llvm
 435
 436 #endif