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   template <class OtherT> friend class ErrorOr;
 166   static const bool isRef = is_reference<T>::value;
 167   typedef ReferenceStorage<typename remove_reference<T>::type> wrap;
 168
 169 public:
 170   typedef typename
 171     conditional< isRef
 172                , wrap
 173                , T
 174                >::type storage_type;
 175
 176 private:
 177   typedef typename remove_reference<T>::type &reference;
 178   typedef typename remove_reference<T>::type *pointer;
 179
 180 public:
 181   ErrorOr() : IsValid(false) {}
 182
 183   ErrorOr(llvm::error_code EC) : HasError(true), IsValid(true) {
 184     Error = new ErrorHolderBase;
 185     Error->Error = EC;
 186     Error->HasUserData = false;
 187   }
 188
 189   template<class UserDataT>
 190   ErrorOr(UserDataT UD, typename
 191           enable_if_c<ErrorOrUserDataTraits<UserDataT>::value>::type* = 0)
 192     : HasError(true), IsValid(true) {
 193     Error = new ErrorHolder<UserDataT>(llvm_move(UD));
 194     Error->Error = ErrorOrUserDataTraits<UserDataT>::error();
 195     Error->HasUserData = true;
 196   }
 197
 198   ErrorOr(T Val) : HasError(false), IsValid(true) {
 199     new (get()) storage_type(moveIfMoveConstructible<storage_type>(Val));
 200   }
 201
 202   template <class OtherT>
 203   ErrorOr(ErrorOr<OtherT> &Other) : IsValid(false) {
 204     // Construct an invalid ErrorOr if other is invalid.
 205     if (!Other.IsValid)
 206       return;
 207     if (!Other.HasError) {
 208       // Get the other value.
 209       new (get()) storage_type(*Other.get());
 210       HasError = false;
 211     } else {
 212       // Get other's error.
 213       Error = Other.Error;
 214       HasError = true;
 215       Error->aquire();
 216     }
 217
 218     IsValid = true;
 219   }
 220
 221   ErrorOr &operator =(const ErrorOr &Other) {
 222     if (this == &Other)
 223       return *this;
 224
 225     this->~ErrorOr();
 226     new (this) ErrorOr(Other);
 227
 228     return *this;
 229   }
 230
 231 #if LLVM_HAS_RVALUE_REFERENCES
 232   template <class OtherT>
 233   ErrorOr(ErrorOr<OtherT> &&Other) : IsValid(false) {
 234     // Construct an invalid ErrorOr if other is invalid.
 235     if (!Other.IsValid)
 236       return;
 237     if (!Other.HasError) {
 238       // Get the other value.
 239       IsValid = true;
 240       new (get()) storage_type(std::move(*Other.get()));
 241       HasError = false;
 242       // Tell other not to do any destruction.
 243       Other.IsValid = false;
 244     } else {
 245       // Get other's error.
 246       Error = Other.Error;
 247       HasError = true;
 248       // Tell other not to do any destruction.
 249       Other.IsValid = false;
 250     }
 251
 252     IsValid = true;
 253   }
 254
 255   ErrorOr &operator =(ErrorOr &&Other) {
 256     if (this == &Other)
 257       return *this;
 258
 259     this->~ErrorOr();
 260     new (this) ErrorOr(std::move(Other));
 261
 262     return *this;
 263   }
 264 #endif
 265
 266   ~ErrorOr() {
 267     if (!IsValid)
 268       return;
 269     if (HasError)
 270       Error->release();
 271     else
 272       get()->~storage_type();
 273   }
 274
 275   template<class ET>
 276   ET getError() const {
 277     assert(IsValid && "Cannot get the error of a default constructed ErrorOr!");
 278     assert(HasError && "Cannot get an error if none exists!");
 279     assert(ErrorOrUserDataTraits<ET>::error() == Error->Error &&
 280            "Incorrect user error data type for error!");
 281     if (!Error->HasUserData)
 282       return ET();
 283     return reinterpret_cast<const ErrorHolder<ET>*>(Error)->UserData;
 284   }
 285
 286   typedef void (*unspecified_bool_type)();
 287   static void unspecified_bool_true() {}
 288
 289   /// \brief Return false if there is an error.
 290   operator unspecified_bool_type() const {
 291     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 292     return HasError ? 0 : unspecified_bool_true;
 293   }
 294
 295   operator llvm::error_code() const {
 296     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 297     return HasError ? Error->Error : llvm::error_code::success();
 298   }
 299
 300   pointer operator ->() {
 301     return toPointer(get());
 302   }
 303
 304   reference operator *() {
 305     return *get();
 306   }
 307
 308 private:
 309   pointer toPointer(pointer Val) {
 310     return Val;
 311   }
 312
 313   pointer toPointer(wrap *Val) {
 314     return &Val->get();
 315   }
 316
 317   storage_type *get() {
 318     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 319     assert(!HasError && "Cannot get value when an error exists!");
 320     return reinterpret_cast<storage_type*>(TStorage.buffer);
 321   }
 322
 323   const storage_type *get() const {
 324     assert(IsValid && "Can't do anything on a default constructed ErrorOr!");
 325     assert(!HasError && "Cannot get value when an error exists!");
 326     return reinterpret_cast<const storage_type*>(TStorage.buffer);
 327   }
 328
 329   union {
 330     AlignedCharArrayUnion<storage_type> TStorage;
 331     ErrorHolderBase *Error;
 332   };
 333   bool HasError : 1;
 334   bool IsValid : 1;
 335 };
 336
 337 // ErrorOr specialization for void.
 338 template <>
 339 class ErrorOr<void> {
 340 public:
 341   ErrorOr() : Error(0, 0) {}
 342
 343   ErrorOr(llvm::error_code EC) : Error(0, 0) {
 344     if (EC == errc::success) {
 345       Error.setInt(1);
 346       return;
 347     }
 348     ErrorHolderBase *E = new ErrorHolderBase;
 349     E->Error = EC;
 350     E->HasUserData = false;
 351     Error.setPointer(E);
 352   }
 353
 354   template<class UserDataT>
 355   ErrorOr(UserDataT UD, typename
 356           enable_if_c<ErrorOrUserDataTraits<UserDataT>::value>::type* = 0)
 357       : Error(0, 0) {
 358     ErrorHolderBase *E = new ErrorHolder<UserDataT>(llvm_move(UD));
 359     E->Error = ErrorOrUserDataTraits<UserDataT>::error();
 360     E->HasUserData = true;
 361     Error.setPointer(E);
 362   }
 363
 364   ErrorOr(const ErrorOr &Other) : Error(0, 0) {
 365     Error = Other.Error;
 366     if (Other.Error.getPointer()->Error) {
 367       Error.getPointer()->aquire();
 368     }
 369   }
 370
 371   ErrorOr &operator =(const ErrorOr &Other) {
 372     if (this == &Other)
 373       return *this;
 374
 375     this->~ErrorOr();
 376     new (this) ErrorOr(Other);
 377
 378     return *this;
 379   }
 380
 381 #if LLVM_HAS_RVALUE_REFERENCES
 382   ErrorOr(ErrorOr &&Other) : Error(0) {
 383     // Get other's error.
 384     Error = Other.Error;
 385     // Tell other not to do any destruction.
 386     Other.Error.setPointer(0);
 387   }
 388
 389   ErrorOr &operator =(ErrorOr &&Other) {
 390     if (this == &Other)
 391       return *this;
 392
 393     this->~ErrorOr();
 394     new (this) ErrorOr(std::move(Other));
 395
 396     return *this;
 397   }
 398 #endif
 399
 400   ~ErrorOr() {
 401     if (Error.getPointer())
 402       Error.getPointer()->release();
 403   }
 404
 405   template<class ET>
 406   ET getError() const {
 407     assert(ErrorOrUserDataTraits<ET>::error() == *this &&
 408            "Incorrect user error data type for error!");
 409     if (!Error.getPointer()->HasUserData)
 410       return ET();
 411     return reinterpret_cast<const ErrorHolder<ET> *>(
 412         Error.getPointer())->UserData;
 413   }
 414
 415   typedef void (*unspecified_bool_type)();
 416   static void unspecified_bool_true() {}
 417
 418   /// \brief Return false if there is an error.
 419   operator unspecified_bool_type() const {
 420     return Error.getInt() ? unspecified_bool_true : 0;
 421   }
 422
 423   operator llvm::error_code() const {
 424     return Error.getInt() ? make_error_code(errc::success)
 425                           : Error.getPointer()->Error;
 426   }
 427
 428 private:
 429   // If the bit is 1, the error is success.
 430   llvm::PointerIntPair<ErrorHolderBase *, 1> Error;
 431 };
 432
 433 template<class T, class E>
 434 typename enable_if_c<is_error_code_enum<E>::value ||
 435                      is_error_condition_enum<E>::value, bool>::type
 436 operator ==(ErrorOr<T> &Err, E Code) {
 437   return error_code(Err) == Code;
 438 }
 439 } // end namespace llvm
 440
 441 #endif