folly/futures/Future.h

   1 /*
   2  * Copyright 2014 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 <algorithm>
  20 #include <exception>
  21 #include <functional>
  22 #include <memory>
  23 #include <type_traits>
  24 #include <vector>
  25
  26 #include <folly/MoveWrapper.h>
  27 #include <folly/futures/Deprecated.h>
  28 #include <folly/futures/DrivableExecutor.h>
  29 #include <folly/futures/Promise.h>
  30 #include <folly/futures/Try.h>
  31 #include <folly/futures/FutureException.h>
  32 #include <folly/futures/detail/Types.h>
  33
  34 namespace folly {
  35
  36 template <class> struct Promise;
  37
  38 template <typename T>
  39 struct isFuture : std::false_type {
  40   typedef T Inner;
  41 };
  42
  43 template <typename T>
  44 struct isFuture<Future<T>> : std::true_type {
  45   typedef T Inner;
  46 };
  47
  48 template <typename T>
  49 struct isTry : std::false_type {};
  50
  51 template <typename T>
  52 struct isTry<Try<T>> : std::true_type {};
  53
  54 namespace detail {
  55
  56 template <class> struct Core;
  57 template <class...> struct VariadicContext;
  58
  59 template<typename F, typename... Args>
  60 using resultOf = decltype(std::declval<F>()(std::declval<Args>()...));
  61
  62 template <typename...>
  63 struct ArgType;
  64
  65 template <typename Arg, typename... Args>
  66 struct ArgType<Arg, Args...> {
  67   typedef Arg FirstArg;
  68 };
  69
  70 template <>
  71 struct ArgType<> {
  72   typedef void FirstArg;
  73 };
  74
  75 template <bool isTry, typename F, typename... Args>
  76 struct argResult {
  77   typedef resultOf<F, Args...> Result;
  78 };
  79
  80 template<typename F, typename... Args>
  81 struct callableWith {
  82     template<typename T,
  83              typename = detail::resultOf<T, Args...>>
  84     static constexpr std::true_type
  85     check(std::nullptr_t) { return std::true_type{}; };
  86
  87     template<typename>
  88     static constexpr std::false_type
  89     check(...) { return std::false_type{}; };
  90
  91     typedef decltype(check<F>(nullptr)) type;
  92     static constexpr bool value = type::value;
  93 };
  94
  95 template<typename T, typename F>
  96 struct callableResult {
  97   typedef typename std::conditional<
  98     callableWith<F>::value,
  99     detail::argResult<false, F>,
 100     typename std::conditional<
 101       callableWith<F, Try<T>&&>::value,
 102       detail::argResult<true, F, Try<T>&&>,
 103       typename std::conditional<
 104         callableWith<F, Try<T>&>::value,
 105         detail::argResult<true, F, Try<T>&>,
 106         typename std::conditional<
 107           callableWith<F, T&&>::value,
 108           detail::argResult<false, F, T&&>,
 109           detail::argResult<false, F, T&>>::type>::type>::type>::type Arg;
 110   typedef isFuture<typename Arg::Result> ReturnsFuture;
 111   typedef Future<typename ReturnsFuture::Inner> Return;
 112 };
 113
 114 template<typename F>
 115 struct callableResult<void, F> {
 116   typedef typename std::conditional<
 117     callableWith<F>::value,
 118     detail::argResult<false, F>,
 119     typename std::conditional<
 120       callableWith<F, Try<void>&&>::value,
 121       detail::argResult<true, F, Try<void>&&>,
 122       detail::argResult<true, F, Try<void>&>>::type>::type Arg;
 123   typedef isFuture<typename Arg::Result> ReturnsFuture;
 124   typedef Future<typename ReturnsFuture::Inner> Return;
 125 };
 126
 127 template <typename L>
 128 struct Extract : Extract<decltype(&L::operator())> { };
 129
 130 template <typename Class, typename R, typename... Args>
 131 struct Extract<R(Class::*)(Args...) const> {
 132   typedef isFuture<R> ReturnsFuture;
 133   typedef Future<typename ReturnsFuture::Inner> Return;
 134   typedef typename ReturnsFuture::Inner RawReturn;
 135   typedef typename ArgType<Args...>::FirstArg FirstArg;
 136 };
 137
 138 template <typename Class, typename R, typename... Args>
 139 struct Extract<R(Class::*)(Args...)> {
 140   typedef isFuture<R> ReturnsFuture;
 141   typedef Future<typename ReturnsFuture::Inner> Return;
 142   typedef typename ReturnsFuture::Inner RawReturn;
 143   typedef typename ArgType<Args...>::FirstArg FirstArg;
 144 };
 145
 146 } // detail
 147
 148 struct Timekeeper;
 149
 150 /// This namespace is for utility functions that would usually be static
 151 /// members of Future, except they don't make sense there because they don't
 152 /// depend on the template type (rather, on the type of their arguments in
 153 /// some cases). This is the least-bad naming scheme we could think of. Some
 154 /// of the functions herein have really-likely-to-collide names, like "map"
 155 /// and "sleep".
 156 namespace futures {
 157   /// Returns a Future that will complete after the specified duration. The
 158   /// Duration typedef of a `std::chrono` duration type indicates the
 159   /// resolution you can expect to be meaningful (milliseconds at the time of
 160   /// writing). Normally you wouldn't need to specify a Timekeeper, we will
 161   /// use the global futures timekeeper (we run a thread whose job it is to
 162   /// keep time for futures timeouts) but we provide the option for power
 163   /// users.
 164   ///
 165   /// The Timekeeper thread will be lazily created the first time it is
 166   /// needed. If your program never uses any timeouts or other time-based
 167   /// Futures you will pay no Timekeeper thread overhead.
 168   Future<void> sleep(Duration, Timekeeper* = nullptr);
 169
 170   /// Create a Future chain from a sequence of callbacks. i.e.
 171   ///
 172   ///   f.then(a).then(b).then(c);
 173   ///
 174   /// where f is a Future<A> and the result of the chain is a Future<Z>
 175   /// becomes
 176   ///
 177   ///   f.then(chain<A,Z>(a, b, c));
 178   // If anyone figures how to get chain to deduce A and Z, I'll buy you a drink.
 179   template <class A, class Z, class... Callbacks>
 180   std::function<Future<Z>(Try<A>)>
 181   chain(Callbacks... fns);
 182 }
 183
 184 template <class T>
 185 class Future {
 186  public:
 187   typedef T value_type;
 188
 189   // not copyable
 190   Future(Future const&) = delete;
 191   Future& operator=(Future const&) = delete;
 192
 193   // movable
 194   Future(Future&&) noexcept;
 195   Future& operator=(Future&&);
 196
 197   // makeFuture
 198   template <class F = T>
 199   /* implicit */
 200   Future(const typename std::enable_if<!std::is_void<F>::value, F>::type& val);
 201
 202   template <class F = T>
 203   /* implicit */
 204   Future(typename std::enable_if<!std::is_void<F>::value, F>::type&& val);
 205
 206   template <class F = T,
 207             typename std::enable_if<std::is_void<F>::value, int>::type = 0>
 208   Future();
 209
 210   ~Future();
 211
 212   /** Return the reference to result. Should not be called if !isReady().
 213     Will rethrow the exception if an exception has been
 214     captured.
 215     */
 216   typename std::add_lvalue_reference<T>::type
 217   value();
 218   typename std::add_lvalue_reference<const T>::type
 219   value() const;
 220
 221   /// Returns an inactive Future which will call back on the other side of
 222   /// executor (when it is activated).
 223   ///
 224   /// NB remember that Futures activate when they destruct. This is good,
 225   /// it means that this will work:
 226   ///
 227   ///   f.via(e).then(a).then(b);
 228   ///
 229   /// a and b will execute in the same context (the far side of e), because
 230   /// the Future (temporary variable) created by via(e) does not call back
 231   /// until it destructs, which is after then(a) and then(b) have been wired
 232   /// up.
 233   ///
 234   /// But this is still racy:
 235   ///
 236   ///   f = f.via(e).then(a);
 237   ///   f.then(b);
 238   // The ref-qualifier allows for `this` to be moved out so we
 239   // don't get access-after-free situations in chaining.
 240   // https://akrzemi1.wordpress.com/2014/06/02/ref-qualifiers/
 241   template <typename Executor>
 242   Future<T> via(Executor* executor) &&;
 243
 244   /// This variant creates a new future, where the ref-qualifier && version
 245   /// moves `this` out. This one is less efficient but avoids confusing users
 246   /// when "return f.via(x);" fails.
 247   template <typename Executor>
 248   Future<T> via(Executor* executor) &;
 249
 250   /** True when the result (or exception) is ready. */
 251   bool isReady() const;
 252
 253   /** A reference to the Try of the value */
 254   Try<T>& getTry();
 255
 256   /// Block until the future is fulfilled. Returns the value (moved out), or
 257   /// throws the exception. The future must not already have a callback.
 258   T get();
 259
 260   /// Block until the future is fulfilled, or until timed out. Returns the
 261   /// value (moved out), or throws the exception (which might be a TimedOut
 262   /// exception).
 263   T get(Duration dur);
 264
 265   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 266   /// of DrivableExecutor include EventBase and ManualExecutor. Returns the
 267   /// value (moved out), or throws the exception.
 268   T getVia(DrivableExecutor* e);
 269
 270   /** When this Future has completed, execute func which is a function that
 271     takes one of:
 272       (const) Try<T>&&
 273       (const) Try<T>&
 274       (const) Try<T>
 275       (const) T&&
 276       (const) T&
 277       (const) T
 278       (void)
 279
 280     Func shall return either another Future or a value.
 281
 282     A Future for the return type of func is returned.
 283
 284     Future<string> f2 = f1.then([](Try<T>&&) { return string("foo"); });
 285
 286     The Future given to the functor is ready, and the functor may call
 287     value(), which may rethrow if this has captured an exception. If func
 288     throws, the exception will be captured in the Future that is returned.
 289     */
 290   /* TODO n3428 and other async frameworks have something like then(scheduler,
 291      Future), we might want to support a similar API which could be
 292      implemented a little more efficiently than
 293      f.via(executor).then(callback) */
 294   template <typename F, typename R = detail::callableResult<T, F>>
 295   typename R::Return then(F func) {
 296     typedef typename R::Arg Arguments;
 297     return thenImplementation<F, R>(std::move(func), Arguments());
 298   }
 299
 300   /// Variant where func is an member function
 301   ///
 302   ///   struct Worker { R doWork(Try<T>); }
 303   ///
 304   ///   Worker *w;
 305   ///   Future<R> f2 = f1.then(&Worker::doWork, w);
 306   ///
 307   /// This is just sugar for
 308   ///
 309   ///   f1.then(std::bind(&Worker::doWork, w));
 310   template <typename R, typename Caller, typename... Args>
 311   Future<typename isFuture<R>::Inner>
 312   then(R(Caller::*func)(Args...), Caller *instance);
 313
 314   /// Convenience method for ignoring the value and creating a Future<void>.
 315   /// Exceptions still propagate.
 316   Future<void> then();
 317
 318   /// Set an error callback for this Future. The callback should take a single
 319   /// argument of the type that you want to catch, and should return a value of
 320   /// the same type as this Future, or a Future of that type (see overload
 321   /// below). For instance,
 322   ///
 323   /// makeFuture()
 324   ///   .then([] {
 325   ///     throw std::runtime_error("oh no!");
 326   ///     return 42;
 327   ///   })
 328   ///   .onError([] (std::runtime_error& e) {
 329   ///     LOG(INFO) << "std::runtime_error: " << e.what();
 330   ///     return -1; // or makeFuture<int>(-1)
 331   ///   });
 332   template <class F>
 333   typename std::enable_if<
 334     !detail::Extract<F>::ReturnsFuture::value,
 335     Future<T>>::type
 336   onError(F&& func);
 337
 338   /// Overload of onError where the error callback returns a Future<T>
 339   template <class F>
 340   typename std::enable_if<
 341     detail::Extract<F>::ReturnsFuture::value,
 342     Future<T>>::type
 343   onError(F&& func);
 344
 345   /// func is like std::function<void()> and is executed unconditionally, and
 346   /// the value/exception is passed through to the resulting Future.
 347   /// func shouldn't throw, but if it does it will be captured and propagated,
 348   /// and discard any value/exception that this Future has obtained.
 349   template <class F>
 350   Future<T> ensure(F func);
 351
 352   /// Like onError, but for timeouts. example:
 353   ///
 354   ///   Future<int> f = makeFuture<int>(42)
 355   ///     .delayed(long_time)
 356   ///     .onTimeout(short_time,
 357   ///       []() -> int{ return -1; });
 358   ///
 359   /// or perhaps
 360   ///
 361   ///   Future<int> f = makeFuture<int>(42)
 362   ///     .delayed(long_time)
 363   ///     .onTimeout(short_time,
 364   ///       []() { return makeFuture<int>(some_exception); });
 365   template <class F>
 366   Future<T> onTimeout(Duration, F&& func, Timekeeper* = nullptr);
 367
 368   /// This is not the method you're looking for.
 369   ///
 370   /// This needs to be public because it's used by make* and when*, and it's
 371   /// not worth listing all those and their fancy template signatures as
 372   /// friends. But it's not for public consumption.
 373   template <class F>
 374   void setCallback_(F&& func);
 375
 376   /// A Future's callback is executed when all three of these conditions have
 377   /// become true: it has a value (set by the Promise), it has a callback (set
 378   /// by then), and it is active (active by default).
 379   ///
 380   /// Inactive Futures will activate upon destruction.
 381   Future<T>& activate() & {
 382     core_->activate();
 383     return *this;
 384   }
 385   Future<T>& deactivate() & {
 386     core_->deactivate();
 387     return *this;
 388   }
 389   Future<T> activate() && {
 390     core_->activate();
 391     return std::move(*this);
 392   }
 393   Future<T> deactivate() && {
 394     core_->deactivate();
 395     return std::move(*this);
 396   }
 397
 398   bool isActive() {
 399     return core_->isActive();
 400   }
 401
 402   template <class E>
 403   void raise(E&& exception) {
 404     raise(make_exception_wrapper<typename std::remove_reference<E>::type>(
 405         std::move(exception)));
 406   }
 407
 408   /// Raise an interrupt. If the promise holder has an interrupt
 409   /// handler it will be called and potentially stop asynchronous work from
 410   /// being done. This is advisory only - a promise holder may not set an
 411   /// interrupt handler, or may do anything including ignore. But, if you know
 412   /// your future supports this the most likely result is stopping or
 413   /// preventing the asynchronous operation (if in time), and the promise
 414   /// holder setting an exception on the future. (That may happen
 415   /// asynchronously, of course.)
 416   void raise(exception_wrapper interrupt);
 417
 418   void cancel() {
 419     raise(FutureCancellation());
 420   }
 421
 422   /// Throw TimedOut if this Future does not complete within the given
 423   /// duration from now. The optional Timeekeeper is as with futures::sleep().
 424   Future<T> within(Duration, Timekeeper* = nullptr);
 425
 426   /// Throw the given exception if this Future does not complete within the
 427   /// given duration from now. The optional Timeekeeper is as with
 428   /// futures::sleep().
 429   template <class E>
 430   Future<T> within(Duration, E exception, Timekeeper* = nullptr);
 431
 432   /// Delay the completion of this Future for at least this duration from
 433   /// now. The optional Timekeeper is as with futures::sleep().
 434   Future<T> delayed(Duration, Timekeeper* = nullptr);
 435
 436   /// Block until this Future is complete. Returns a reference to this Future.
 437   Future<T>& wait() &;
 438
 439   /// Overload of wait() for rvalue Futures
 440   Future<T>&& wait() &&;
 441
 442   /// Block until this Future is complete or until the given Duration passes.
 443   /// Returns a reference to this Future
 444   Future<T>& wait(Duration) &;
 445
 446   /// Overload of wait(Duration) for rvalue Futures
 447   Future<T>&& wait(Duration) &&;
 448
 449   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 450   /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
 451   /// reference to this Future so that you can chain calls if desired.
 452   /// value (moved out), or throws the exception.
 453   Future<T>& waitVia(DrivableExecutor* e) &;
 454
 455   /// Overload of waitVia() for rvalue Futures
 456   Future<T>&& waitVia(DrivableExecutor* e) &&;
 457
 458  protected:
 459   typedef detail::Core<T>* corePtr;
 460
 461   // shared core state object
 462   corePtr core_;
 463
 464   explicit
 465   Future(corePtr obj) : core_(obj) {}
 466
 467   void detach();
 468
 469   void throwIfInvalid() const;
 470
 471   friend class Promise<T>;
 472   template <class> friend class Future;
 473
 474   // Variant: returns a value
 475   // e.g. f.then([](Try<T> t){ return t.value(); });
 476   template <typename F, typename R, bool isTry, typename... Args>
 477   typename std::enable_if<!R::ReturnsFuture::value, typename R::Return>::type
 478   thenImplementation(F func, detail::argResult<isTry, F, Args...>);
 479
 480   // Variant: returns a Future
 481   // e.g. f.then([](Try<T> t){ return makeFuture<T>(t); });
 482   template <typename F, typename R, bool isTry, typename... Args>
 483   typename std::enable_if<R::ReturnsFuture::value, typename R::Return>::type
 484   thenImplementation(F func, detail::argResult<isTry, F, Args...>);
 485
 486   Executor* getExecutor() { return core_->getExecutor(); }
 487   void setExecutor(Executor* x) { core_->setExecutor(x); }
 488 };
 489
 490 /**
 491   Make a completed Future by moving in a value. e.g.
 492
 493     string foo = "foo";
 494     auto f = makeFuture(std::move(foo));
 495
 496   or
 497
 498     auto f = makeFuture<string>("foo");
 499 */
 500 template <class T>
 501 Future<typename std::decay<T>::type> makeFuture(T&& t);
 502
 503 /** Make a completed void Future. */
 504 Future<void> makeFuture();
 505
 506 /** Make a completed Future by executing a function. If the function throws
 507   we capture the exception, otherwise we capture the result. */
 508 template <class F>
 509 auto makeFutureTry(
 510   F&& func,
 511   typename std::enable_if<
 512     !std::is_reference<F>::value, bool>::type sdf = false)
 513   -> Future<decltype(func())>;
 514
 515 template <class F>
 516 auto makeFutureTry(
 517   F const& func)
 518   -> Future<decltype(func())>;
 519
 520 /// Make a failed Future from an exception_ptr.
 521 /// Because the Future's type cannot be inferred you have to specify it, e.g.
 522 ///
 523 ///   auto f = makeFuture<string>(std::current_exception());
 524 template <class T>
 525 Future<T> makeFuture(std::exception_ptr const& e) DEPRECATED;
 526
 527 /// Make a failed Future from an exception_wrapper.
 528 template <class T>
 529 Future<T> makeFuture(exception_wrapper ew);
 530
 531 /** Make a Future from an exception type E that can be passed to
 532   std::make_exception_ptr(). */
 533 template <class T, class E>
 534 typename std::enable_if<std::is_base_of<std::exception, E>::value,
 535                         Future<T>>::type
 536 makeFuture(E const& e);
 537
 538 /** Make a Future out of a Try */
 539 template <class T>
 540 Future<T> makeFuture(Try<T>&& t);
 541
 542 /*
 543  * Return a new Future that will call back on the given Executor.
 544  * This is just syntactic sugar for makeFuture().via(executor)
 545  *
 546  * @param executor the Executor to call back on
 547  *
 548  * @returns a void Future that will call back on the given executor
 549  */
 550 template <typename Executor>
 551 Future<void> via(Executor* executor);
 552
 553 /** When all the input Futures complete, the returned Future will complete.
 554   Errors do not cause early termination; this Future will always succeed
 555   after all its Futures have finished (whether successfully or with an
 556   error).
 557
 558   The Futures are moved in, so your copies are invalid. If you need to
 559   chain further from these Futures, use the variant with an output iterator.
 560
 561   This function is thread-safe for Futures running on different threads. But
 562   if you are doing anything non-trivial after, you will probably want to
 563   follow with `via(executor)` because it will complete in whichever thread the
 564   last Future completes in.
 565
 566   The return type for Future<T> input is a Future<std::vector<Try<T>>>
 567   */
 568 template <class InputIterator>
 569 Future<std::vector<Try<
 570   typename std::iterator_traits<InputIterator>::value_type::value_type>>>
 571 whenAll(InputIterator first, InputIterator last);
 572
 573 /// This version takes a varying number of Futures instead of an iterator.
 574 /// The return type for (Future<T1>, Future<T2>, ...) input
 575 /// is a Future<std::tuple<Try<T1>, Try<T2>, ...>>.
 576 /// The Futures are moved in, so your copies are invalid.
 577 template <typename... Fs>
 578 typename detail::VariadicContext<
 579   typename std::decay<Fs>::type::value_type...>::type
 580 whenAll(Fs&&... fs);
 581
 582 /** The result is a pair of the index of the first Future to complete and
 583   the Try. If multiple Futures complete at the same time (or are already
 584   complete when passed in), the "winner" is chosen non-deterministically.
 585
 586   This function is thread-safe for Futures running on different threads.
 587   */
 588 template <class InputIterator>
 589 Future<std::pair<
 590   size_t,
 591   Try<typename std::iterator_traits<InputIterator>::value_type::value_type>>>
 592 whenAny(InputIterator first, InputIterator last);
 593
 594 /** when n Futures have completed, the Future completes with a vector of
 595   the index and Try of those n Futures (the indices refer to the original
 596   order, but the result vector will be in an arbitrary order)
 597
 598   Not thread safe.
 599   */
 600 template <class InputIterator>
 601 Future<std::vector<std::pair<
 602   size_t,
 603   Try<typename std::iterator_traits<InputIterator>::value_type::value_type>>>>
 604 whenN(InputIterator first, InputIterator last, size_t n);
 605
 606 } // folly
 607
 608 #include <folly/futures/Future-inl.h>