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    * If the Try contains an exception and it is of type Ex, execute func(Ex)
 216    *
 217    * @param func a function that takes a single parameter of type const Ex&
 218    *
 219    * @returns True if the Try held an Ex and func was executed, false otherwise
 220    */
 221   template <class Ex, class F>
 222   bool withException(F func) {
 223     if (!hasException()) {
 224       return false;
 225     }
 226     return e_.with_exception(std::move(func));
 227   }
 228   template <class Ex, class F>
 229   bool withException(F func) const {
 230     if (!hasException()) {
 231       return false;
 232     }
 233     return e_.with_exception(std::move(func));
 234   }
 235
 236   template <bool isTry, typename R>
 237   typename std::enable_if<isTry, R>::type get() {
 238     return std::forward<R>(*this);
 239   }
 240
 241   template <bool isTry, typename R>
 242   typename std::enable_if<!isTry, R>::type get() {
 243     return std::forward<R>(value());
 244   }
 245
 246  private:
 247   Contains contains_;
 248   union {
 249     T value_;
 250     exception_wrapper e_;
 251   };
 252 };
 253
 254 /*
 255  * Specialization of Try for void value type. Encapsulates either success or an
 256  * exception.
 257  */
 258 template <>
 259 class Try<void> {
 260  public:
 261   /*
 262    * The value type for the Try
 263    */
 264   typedef void element_type;
 265
 266   // Construct a Try holding a successful and void result
 267   Try() : hasValue_(true) {}
 268
 269   /*
 270    * Construct a Try with an exception_wrapper
 271    *
 272    * @param e The exception_wrapper
 273    */
 274   explicit Try(exception_wrapper e) : hasValue_(false), e_(std::move(e)) {}
 275
 276   /*
 277    * DEPRECATED
 278    * Construct a Try with an exception_pointer
 279    *
 280    * @param ep The exception_pointer. Will be rethrown.
 281    */
 282   FOLLY_DEPRECATED("use Try(exception_wrapper)")
 283   explicit Try(std::exception_ptr ep) : hasValue_(false) {
 284     try {
 285       std::rethrow_exception(ep);
 286     } catch (const std::exception& e) {
 287       e_ = exception_wrapper(std::current_exception(), e);
 288     } catch (...) {
 289       e_ = exception_wrapper(std::current_exception());
 290     }
 291   }
 292
 293   // Copy assigner
 294   Try& operator=(const Try<void>& t) {
 295     hasValue_ = t.hasValue_;
 296     e_ = t.e_;
 297     return *this;
 298   }
 299   // Copy constructor
 300   Try(const Try<void>& t) {
 301     *this = t;
 302   }
 303
 304   // If the Try contains an exception, throws it
 305   void value() const { throwIfFailed(); }
 306   // Dereference operator. If the Try contains an exception, throws it
 307   void operator*() const { return value(); }
 308
 309   // If the Try contains an exception, throws it
 310   inline void throwIfFailed() const;
 311
 312   // @returns False if the Try contains an exception, true otherwise
 313   bool hasValue() const { return hasValue_; }
 314   // @returns True if the Try contains an exception, false otherwise
 315   bool hasException() const { return !hasValue_; }
 316
 317   // @returns True if the Try contains an exception of type Ex, false otherwise
 318   template <class Ex>
 319   bool hasException() const {
 320     return hasException() && e_.is_compatible_with<Ex>();
 321   }
 322
 323   /*
 324    * @throws TryException if the Try doesn't contain an exception
 325    *
 326    * @returns mutable reference to the exception contained by this Try
 327    */
 328   exception_wrapper& exception() {
 329     if (UNLIKELY(!hasException())) {
 330       throw TryException("exception(): Try does not contain an exception");
 331     }
 332     return e_;
 333   }
 334
 335   const exception_wrapper& exception() const {
 336     if (UNLIKELY(!hasException())) {
 337       throw TryException("exception(): Try does not contain an exception");
 338     }
 339     return e_;
 340   }
 341
 342   /*
 343    * If the Try contains an exception and it is of type Ex, execute func(Ex)
 344    *
 345    * @param func a function that takes a single parameter of type const Ex&
 346    *
 347    * @returns True if the Try held an Ex and func was executed, false otherwise
 348    */
 349   template <class Ex, class F>
 350   bool withException(F func) {
 351     if (!hasException()) {
 352       return false;
 353     }
 354     return e_.with_exception(std::move(func));
 355   }
 356   template <class Ex, class F>
 357   bool withException(F func) const {
 358     if (!hasException()) {
 359       return false;
 360     }
 361     return e_.with_exception(std::move(func));
 362   }
 363
 364   template <bool, typename R>
 365   R get() {
 366     return std::forward<R>(*this);
 367   }
 368
 369  private:
 370   bool hasValue_;
 371   exception_wrapper e_;
 372 };
 373
 374 /*
 375  * Extracts value from try and returns it. Throws if try contained an exception.
 376  *
 377  * @param t Try to extract value from
 378  *
 379  * @returns value contained in t
 380  */
 381 template <typename T>
 382 T moveFromTry(Try<T>& t);
 383
 384 /*
 385  * Throws if try contained an exception.
 386  *
 387  * @param t Try to move from
 388  */
 389 void moveFromTry(Try<void>& t);
 390
 391 /*
 392  * @param f a function to execute and capture the result of (value or exception)
 393  *
 394  * @returns Try holding the result of f
 395  */
 396 template <typename F>
 397 typename std::enable_if<
 398   !std::is_same<typename std::result_of<F()>::type, void>::value,
 399   Try<typename std::result_of<F()>::type>>::type
 400 makeTryWith(F&& f);
 401
 402 /*
 403  * Specialization of makeTryWith for void return
 404  *
 405  * @param f a function to execute and capture the result of
 406  *
 407  * @returns Try<void> holding the result of f
 408  */
 409 template <typename F>
 410 typename std::enable_if<
 411   std::is_same<typename std::result_of<F()>::type, void>::value,
 412   Try<void>>::type
 413 makeTryWith(F&& f);
 414
 415 template <typename... Ts>
 416 std::tuple<Ts...> unwrapTryTuple(std::tuple<folly::Try<Ts>...>&& ts);
 417
 418 } // folly
 419
 420 #include <folly/Try-inl.h>