folly/Try.h

   1 /*
   2  * Copyright 2017 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #pragma once
  18
  19 #include <folly/ExceptionWrapper.h>
  20 #include <folly/Likely.h>
  21 #include <folly/Memory.h>
  22 #include <folly/Portability.h>
  23 #include <folly/Unit.h>
  24 #include <exception>
  25 #include <stdexcept>
  26 #include <type_traits>
  27 #include <utility>
  28
  29 namespace folly {
  30
  31 class TryException : public std::logic_error {
  32  public:
  33   using std::logic_error::logic_error;
  34 };
  35
  36 class UsingUninitializedTry : public TryException {
  37  public:
  38   UsingUninitializedTry() : TryException("Using uninitialized try") {}
  39 };
  40
  41 /*
  42  * Try<T> is a wrapper that contains either an instance of T, an exception, or
  43  * nothing. Exceptions are stored as exception_wrappers so that the user can
  44  * minimize rethrows if so desired.
  45  *
  46  * To represent success or a captured exception, use Try<Unit>.
  47  */
  48 template <class T>
  49 class Try {
  50   static_assert(!std::is_reference<T>::value,
  51                 "Try may not be used with reference types");
  52
  53   enum class Contains {
  54     VALUE,
  55     EXCEPTION,
  56     NOTHING,
  57   };
  58
  59  public:
  60   /*
  61    * The value type for the Try
  62    */
  63   typedef T element_type;
  64
  65   /*
  66    * Construct an empty Try
  67    */
  68   Try() : contains_(Contains::NOTHING) {}
  69
  70   /*
  71    * Construct a Try with a value by copy
  72    *
  73    * @param v The value to copy in
  74    */
  75   explicit Try(const T& v) : contains_(Contains::VALUE), value_(v) {}
  76
  77   /*
  78    * Construct a Try with a value by move
  79    *
  80    * @param v The value to move in
  81    */
  82   explicit Try(T&& v) : contains_(Contains::VALUE), value_(std::move(v)) {}
  83
  84   /// Implicit conversion from Try<void> to Try<Unit>
  85   template <class T2 = T>
  86   /* implicit */
  87   Try(typename std::enable_if<std::is_same<Unit, T2>::value,
  88                               Try<void> const&>::type t);
  89
  90   /*
  91    * Construct a Try with an exception_wrapper
  92    *
  93    * @param e The exception_wrapper
  94    */
  95   explicit Try(exception_wrapper e)
  96       : contains_(Contains::EXCEPTION), e_(std::move(e)) {}
  97
  98   /*
  99    * DEPRECATED
 100    * Construct a Try with an exception_pointer
 101    *
 102    * @param ep The exception_pointer. Will be rethrown.
 103    */
 104   FOLLY_DEPRECATED("use Try(exception_wrapper)")
 105   explicit Try(std::exception_ptr ep)
 106     : contains_(Contains::EXCEPTION) {
 107     try {
 108       std::rethrow_exception(ep);
 109     } catch (std::exception& e) {
 110       e_ = exception_wrapper(std::current_exception(), e);
 111     } catch (...) {
 112       e_ = exception_wrapper(std::current_exception());
 113     }
 114   }
 115
 116   // Move constructor
 117   Try(Try<T>&& t) noexcept;
 118   // Move assigner
 119   Try& operator=(Try<T>&& t) noexcept;
 120
 121   // Copy constructor
 122   Try(const Try& t);
 123   // Copy assigner
 124   Try& operator=(const Try& t);
 125
 126   ~Try();
 127
 128   /*
 129    * Get a mutable reference to the contained value. If the Try contains an
 130    * exception it will be rethrown.
 131    *
 132    * @returns mutable reference to the contained value
 133    */
 134   T& value()&;
 135   /*
 136    * Get a rvalue reference to the contained value. If the Try contains an
 137    * exception it will be rethrown.
 138    *
 139    * @returns rvalue reference to the contained value
 140    */
 141   T&& value()&&;
 142   /*
 143    * Get a const reference to the contained value. If the Try contains an
 144    * exception it will be rethrown.
 145    *
 146    * @returns const reference to the contained value
 147    */
 148   const T& value() const&;
 149
 150   /*
 151    * If the Try contains an exception, rethrow it. Otherwise do nothing.
 152    */
 153   void throwIfFailed() const;
 154
 155   /*
 156    * Const dereference operator. If the Try contains an exception it will be
 157    * rethrown.
 158    *
 159    * @returns const reference to the contained value
 160    */
 161   const T& operator*() const { return value(); }
 162   /*
 163    * Dereference operator. If the Try contains an exception it will be rethrown.
 164    *
 165    * @returns mutable reference to the contained value
 166    */
 167   T& operator*() { return value(); }
 168
 169   /*
 170    * Const arrow operator. If the Try contains an exception it will be
 171    * rethrown.
 172    *
 173    * @returns const reference to the contained value
 174    */
 175   const T* operator->() const { return &value(); }
 176   /*
 177    * Arrow operator. If the Try contains an exception it will be rethrown.
 178    *
 179    * @returns mutable reference to the contained value
 180    */
 181   T* operator->() { return &value(); }
 182
 183   /*
 184    * @returns True if the Try contains a value, false otherwise
 185    */
 186   bool hasValue() const { return contains_ == Contains::VALUE; }
 187   /*
 188    * @returns True if the Try contains an exception, false otherwise
 189    */
 190   bool hasException() const { return contains_ == Contains::EXCEPTION; }
 191
 192   /*
 193    * @returns True if the Try contains an exception of type Ex, false otherwise
 194    */
 195   template <class Ex>
 196   bool hasException() const {
 197     return hasException() && e_.is_compatible_with<Ex>();
 198   }
 199
 200   exception_wrapper& exception() {
 201     if (UNLIKELY(!hasException())) {
 202       throw TryException("exception(): Try does not contain an exception");
 203     }
 204     return e_;
 205   }
 206
 207   const exception_wrapper& exception() const {
 208     if (UNLIKELY(!hasException())) {
 209       throw TryException("exception(): Try does not contain an exception");
 210     }
 211     return e_;
 212   }
 213
 214   /*
 215    * @returns a pointer to the `std::exception` held by `*this`, if one is held;
 216    *          otherwise, returns `nullptr`.
 217    */
 218   std::exception* tryGetExceptionObject() {
 219     return hasException() ? e_.get_exception() : nullptr;
 220   }
 221   std::exception const* tryGetExceptionObject() const {
 222     return hasException() ? e_.get_exception() : nullptr;
 223   }
 224
 225   /*
 226    * @returns a pointer to the `Ex` held by `*this`, if it holds an object whose
 227    *          type `From` permits `std::is_convertible<From*, Ex*>`; otherwise,
 228    *          returns `nullptr`.
 229    */
 230   template <class E>
 231   E* tryGetExceptionObject() {
 232     return hasException() ? e_.get_exception<E>() : nullptr;
 233   }
 234   template <class E>
 235   E const* tryGetExceptionObject() const {
 236     return hasException() ? e_.get_exception<E>() : nullptr;
 237   }
 238
 239   /*
 240    * If the Try contains an exception and it is of type Ex, execute func(Ex)
 241    *
 242    * @param func a function that takes a single parameter of type const Ex&
 243    *
 244    * @returns True if the Try held an Ex and func was executed, false otherwise
 245    */
 246   template <class Ex, class F>
 247   bool withException(F func) {
 248     if (!hasException()) {
 249       return false;
 250     }
 251     return e_.with_exception(std::move(func));
 252   }
 253   template <class Ex, class F>
 254   bool withException(F func) const {
 255     if (!hasException()) {
 256       return false;
 257     }
 258     return e_.with_exception(std::move(func));
 259   }
 260
 261   template <bool isTry, typename R>
 262   typename std::enable_if<isTry, R>::type get() {
 263     return std::forward<R>(*this);
 264   }
 265
 266   template <bool isTry, typename R>
 267   typename std::enable_if<!isTry, R>::type get() {
 268     return std::forward<R>(value());
 269   }
 270
 271  private:
 272   Contains contains_;
 273   union {
 274     T value_;
 275     exception_wrapper e_;
 276   };
 277 };
 278
 279 /*
 280  * Specialization of Try for void value type. Encapsulates either success or an
 281  * exception.
 282  */
 283 template <>
 284 class Try<void> {
 285  public:
 286   /*
 287    * The value type for the Try
 288    */
 289   typedef void element_type;
 290
 291   // Construct a Try holding a successful and void result
 292   Try() : hasValue_(true) {}
 293
 294   /*
 295    * Construct a Try with an exception_wrapper
 296    *
 297    * @param e The exception_wrapper
 298    */
 299   explicit Try(exception_wrapper e) : hasValue_(false), e_(std::move(e)) {}
 300
 301   /*
 302    * DEPRECATED
 303    * Construct a Try with an exception_pointer
 304    *
 305    * @param ep The exception_pointer. Will be rethrown.
 306    */
 307   FOLLY_DEPRECATED("use Try(exception_wrapper)")
 308   explicit Try(std::exception_ptr ep) : hasValue_(false) {
 309     try {
 310       std::rethrow_exception(ep);
 311     } catch (const std::exception& e) {
 312       e_ = exception_wrapper(std::current_exception(), e);
 313     } catch (...) {
 314       e_ = exception_wrapper(std::current_exception());
 315     }
 316   }
 317
 318   // Copy assigner
 319   Try& operator=(const Try<void>& t) {
 320     hasValue_ = t.hasValue_;
 321     e_ = t.e_;
 322     return *this;
 323   }
 324   // Copy constructor
 325   Try(const Try<void>& t) {
 326     *this = t;
 327   }
 328
 329   // If the Try contains an exception, throws it
 330   void value() const { throwIfFailed(); }
 331   // Dereference operator. If the Try contains an exception, throws it
 332   void operator*() const { return value(); }
 333
 334   // If the Try contains an exception, throws it
 335   inline void throwIfFailed() const;
 336
 337   // @returns False if the Try contains an exception, true otherwise
 338   bool hasValue() const { return hasValue_; }
 339   // @returns True if the Try contains an exception, false otherwise
 340   bool hasException() const { return !hasValue_; }
 341
 342   // @returns True if the Try contains an exception of type Ex, false otherwise
 343   template <class Ex>
 344   bool hasException() const {
 345     return hasException() && e_.is_compatible_with<Ex>();
 346   }
 347
 348   /*
 349    * @throws TryException if the Try doesn't contain an exception
 350    *
 351    * @returns mutable reference to the exception contained by this Try
 352    */
 353   exception_wrapper& exception() {
 354     if (UNLIKELY(!hasException())) {
 355       throw TryException("exception(): Try does not contain an exception");
 356     }
 357     return e_;
 358   }
 359
 360   const exception_wrapper& exception() const {
 361     if (UNLIKELY(!hasException())) {
 362       throw TryException("exception(): Try does not contain an exception");
 363     }
 364     return e_;
 365   }
 366
 367   /*
 368    * @returns a pointer to the `std::exception` held by `*this`, if one is held;
 369    *          otherwise, returns `nullptr`.
 370    */
 371   std::exception* tryGetExceptionObject() {
 372     return hasException() ? e_.get_exception() : nullptr;
 373   }
 374   std::exception const* tryGetExceptionObject() const {
 375     return hasException() ? e_.get_exception() : nullptr;
 376   }
 377
 378   /*
 379    * @returns a pointer to the `Ex` held by `*this`, if it holds an object whose
 380    *          type `From` permits `std::is_convertible<From*, Ex*>`; otherwise,
 381    *          returns `nullptr`.
 382    */
 383   template <class E>
 384   E* tryGetExceptionObject() {
 385     return hasException() ? e_.get_exception<E>() : nullptr;
 386   }
 387   template <class E>
 388   E const* tryGetExceptionObject() const {
 389     return hasException() ? e_.get_exception<E>() : nullptr;
 390   }
 391
 392   /*
 393    * If the Try contains an exception and it is of type Ex, execute func(Ex)
 394    *
 395    * @param func a function that takes a single parameter of type const Ex&
 396    *
 397    * @returns True if the Try held an Ex and func was executed, false otherwise
 398    */
 399   template <class Ex, class F>
 400   bool withException(F func) {
 401     if (!hasException()) {
 402       return false;
 403     }
 404     return e_.with_exception(std::move(func));
 405   }
 406   template <class Ex, class F>
 407   bool withException(F func) const {
 408     if (!hasException()) {
 409       return false;
 410     }
 411     return e_.with_exception(std::move(func));
 412   }
 413
 414   template <bool, typename R>
 415   R get() {
 416     return std::forward<R>(*this);
 417   }
 418
 419  private:
 420   bool hasValue_;
 421   exception_wrapper e_;
 422 };
 423
 424 /*
 425  * Extracts value from try and returns it. Throws if try contained an exception.
 426  *
 427  * @param t Try to extract value from
 428  *
 429  * @returns value contained in t
 430  */
 431 template <typename T>
 432 T moveFromTry(Try<T>& t);
 433
 434 /*
 435  * Throws if try contained an exception.
 436  *
 437  * @param t Try to move from
 438  */
 439 void moveFromTry(Try<void>& t);
 440
 441 /*
 442  * @param f a function to execute and capture the result of (value or exception)
 443  *
 444  * @returns Try holding the result of f
 445  */
 446 template <typename F>
 447 typename std::enable_if<
 448   !std::is_same<typename std::result_of<F()>::type, void>::value,
 449   Try<typename std::result_of<F()>::type>>::type
 450 makeTryWith(F&& f);
 451
 452 /*
 453  * Specialization of makeTryWith for void return
 454  *
 455  * @param f a function to execute and capture the result of
 456  *
 457  * @returns Try<void> holding the result of f
 458  */
 459 template <typename F>
 460 typename std::enable_if<
 461   std::is_same<typename std::result_of<F()>::type, void>::value,
 462   Try<void>>::type
 463 makeTryWith(F&& f);
 464
 465 template <typename... Ts>
 466 std::tuple<Ts...> unwrapTryTuple(std::tuple<folly::Try<Ts>...>&& ts);
 467
 468 } // folly
 469
 470 #include <folly/Try-inl.h>