folly/futures/Future.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 <algorithm>
  20 #include <exception>
  21 #include <functional>
  22 #include <memory>
  23 #include <type_traits>
  24 #include <vector>
  25
  26 #include <folly/Optional.h>
  27 #include <folly/Portability.h>
  28 #include <folly/ScopeGuard.h>
  29 #include <folly/Try.h>
  30 #include <folly/Utility.h>
  31 #include <folly/executors/DrivableExecutor.h>
  32 #include <folly/futures/FutureException.h>
  33 #include <folly/futures/Promise.h>
  34 #include <folly/futures/detail/Types.h>
  35
  36 // boring predeclarations and details
  37 #include <folly/futures/Future-pre.h>
  38
  39 // not-boring helpers, e.g. all in folly::futures, makeFuture variants, etc.
  40 // Needs to be included after Future-pre.h and before Future-inl.h
  41 #include <folly/futures/helpers.h>
  42
  43 namespace folly {
  44
  45 template <class T>
  46 class Future;
  47
  48 template <class T>
  49 class SemiFuture;
  50
  51 namespace futures {
  52 namespace detail {
  53 template <class T>
  54 class FutureBase {
  55  public:
  56   typedef T value_type;
  57
  58   /// Construct a Future from a value (perfect forwarding)
  59   template <
  60       class T2 = T,
  61       typename = typename std::enable_if<
  62           !isFuture<typename std::decay<T2>::type>::value &&
  63           !isSemiFuture<typename std::decay<T2>::type>::value>::type>
  64   /* implicit */ FutureBase(T2&& val);
  65
  66   template <class T2 = T>
  67   /* implicit */ FutureBase(
  68       typename std::enable_if<std::is_same<Unit, T2>::value>::type*);
  69
  70   template <
  71       class... Args,
  72       typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
  73           type = 0>
  74   explicit FutureBase(in_place_t, Args&&... args);
  75
  76   FutureBase(FutureBase<T> const&) = delete;
  77   FutureBase(SemiFuture<T>&&) noexcept;
  78   FutureBase(Future<T>&&) noexcept;
  79
  80   // not copyable
  81   FutureBase(Future<T> const&) = delete;
  82   FutureBase(SemiFuture<T> const&) = delete;
  83
  84   ~FutureBase();
  85
  86   /// Returns a reference to the result, with a reference category and const-
  87   /// qualification equivalent to the reference category and const-qualification
  88   /// of the receiver.
  89   ///
  90   /// If moved-from, throws NoState.
  91   ///
  92   /// If !isReady(), throws FutureNotReady.
  93   ///
  94   /// If an exception has been captured, throws that exception.
  95   T& value() &;
  96   T const& value() const&;
  97   T&& value() &&;
  98   T const&& value() const&&;
  99
 100   /** True when the result (or exception) is ready. */
 101   bool isReady() const;
 102
 103   /// sugar for getTry().hasValue()
 104   bool hasValue();
 105
 106   /// sugar for getTry().hasException()
 107   bool hasException();
 108
 109   /** A reference to the Try of the value */
 110   Try<T>& getTry();
 111
 112   /// If the promise has been fulfilled, return an Optional with the Try<T>.
 113   /// Otherwise return an empty Optional.
 114   /// Note that this moves the Try<T> out.
 115   Optional<Try<T>> poll();
 116
 117   /// This is not the method you're looking for.
 118   ///
 119   /// This needs to be public because it's used by make* and when*, and it's
 120   /// not worth listing all those and their fancy template signatures as
 121   /// friends. But it's not for public consumption.
 122   template <class F>
 123   void setCallback_(F&& func);
 124
 125   bool isActive() {
 126     return core_->isActive();
 127   }
 128
 129   template <class E>
 130   void raise(E&& exception) {
 131     raise(make_exception_wrapper<typename std::remove_reference<E>::type>(
 132         std::forward<E>(exception)));
 133   }
 134
 135   /// Raise an interrupt. If the promise holder has an interrupt
 136   /// handler it will be called and potentially stop asynchronous work from
 137   /// being done. This is advisory only - a promise holder may not set an
 138   /// interrupt handler, or may do anything including ignore. But, if you know
 139   /// your future supports this the most likely result is stopping or
 140   /// preventing the asynchronous operation (if in time), and the promise
 141   /// holder setting an exception on the future. (That may happen
 142   /// asynchronously, of course.)
 143   void raise(exception_wrapper interrupt);
 144
 145   void cancel() {
 146     raise(FutureCancellation());
 147   }
 148
 149  protected:
 150   friend class Promise<T>;
 151   template <class>
 152   friend class SemiFuture;
 153   template <class>
 154   friend class Future;
 155
 156   using corePtr = futures::detail::Core<T>*;
 157
 158   // shared core state object
 159   corePtr core_;
 160
 161   explicit FutureBase(corePtr obj) : core_(obj) {}
 162
 163   explicit FutureBase(futures::detail::EmptyConstruct) noexcept;
 164
 165   void detach();
 166
 167   void throwIfInvalid() const;
 168
 169   template <class FutureType>
 170   void assign(FutureType&) noexcept;
 171
 172   Executor* getExecutor() {
 173     return core_->getExecutor();
 174   }
 175
 176   void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
 177     core_->setExecutor(x, priority);
 178   }
 179
 180   // Variant: returns a value
 181   // e.g. f.then([](Try<T> t){ return t.value(); });
 182   template <typename F, typename R, bool isTry, typename... Args>
 183   typename std::enable_if<!R::ReturnsFuture::value, typename R::Return>::type
 184   thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
 185
 186   // Variant: returns a Future
 187   // e.g. f.then([](Try<T> t){ return makeFuture<T>(t); });
 188   template <typename F, typename R, bool isTry, typename... Args>
 189   typename std::enable_if<R::ReturnsFuture::value, typename R::Return>::type
 190   thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
 191 };
 192 } // namespace detail
 193 } // namespace futures
 194
 195 template <class T>
 196 class SemiFuture : private futures::detail::FutureBase<T> {
 197  private:
 198   using Base = futures::detail::FutureBase<T>;
 199   using DeferredExecutor = futures::detail::DeferredExecutor;
 200
 201  public:
 202   static SemiFuture<T> makeEmpty(); // equivalent to moved-from
 203
 204   // Export public interface of FutureBase
 205   // FutureBase is inherited privately to avoid subclasses being cast to
 206   // a FutureBase pointer
 207   using typename Base::value_type;
 208
 209   /// Construct a Future from a value (perfect forwarding)
 210   template <
 211       class T2 = T,
 212       typename = typename std::enable_if<
 213           !isFuture<typename std::decay<T2>::type>::value &&
 214           !isSemiFuture<typename std::decay<T2>::type>::value>::type>
 215   /* implicit */ SemiFuture(T2&& val) : Base(std::forward<T2>(val)) {}
 216
 217   template <class T2 = T>
 218   /* implicit */ SemiFuture(
 219       typename std::enable_if<std::is_same<Unit, T2>::value>::type* p = nullptr)
 220       : Base(p) {}
 221
 222   template <
 223       class... Args,
 224       typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
 225           type = 0>
 226   explicit SemiFuture(in_place_t, Args&&... args)
 227       : Base(in_place, std::forward<Args>(args)...) {}
 228
 229   SemiFuture(SemiFuture<T> const&) = delete;
 230   // movable
 231   SemiFuture(SemiFuture<T>&&) noexcept;
 232   // safe move-constructabilty from Future
 233   /* implicit */ SemiFuture(Future<T>&&) noexcept;
 234
 235   using Base::cancel;
 236   using Base::getTry;
 237   using Base::hasException;
 238   using Base::hasValue;
 239   using Base::isActive;
 240   using Base::isReady;
 241   using Base::poll;
 242   using Base::raise;
 243   using Base::setCallback_;
 244   using Base::value;
 245
 246   SemiFuture& operator=(SemiFuture const&) = delete;
 247   SemiFuture& operator=(SemiFuture&&) noexcept;
 248   SemiFuture& operator=(Future<T>&&) noexcept;
 249
 250   /// Block until the future is fulfilled. Returns the value (moved out), or
 251   /// throws the exception. The future must not already have a callback.
 252   T get() &&;
 253
 254   /// Block until the future is fulfilled, or until timed out. Returns the
 255   /// value (moved out), or throws the exception (which might be a TimedOut
 256   /// exception).
 257   T get(Duration dur) &&;
 258
 259   /// Block until this Future is complete. Returns a reference to this Future.
 260   SemiFuture<T>& wait() &;
 261
 262   /// Overload of wait() for rvalue Futures
 263   SemiFuture<T>&& wait() &&;
 264
 265   /// Block until this Future is complete or until the given Duration passes.
 266   /// Returns a reference to this Future
 267   SemiFuture<T>& wait(Duration) &;
 268
 269   /// Overload of wait(Duration) for rvalue Futures
 270   SemiFuture<T>&& wait(Duration) &&;
 271
 272   /// Returns an inactive Future which will call back on the other side of
 273   /// executor (when it is activated).
 274   ///
 275   /// NB remember that Futures activate when they destruct. This is good,
 276   /// it means that this will work:
 277   ///
 278   ///   f.via(e).then(a).then(b);
 279   ///
 280   /// a and b will execute in the same context (the far side of e), because
 281   /// the Future (temporary variable) created by via(e) does not call back
 282   /// until it destructs, which is after then(a) and then(b) have been wired
 283   /// up.
 284   ///
 285   /// But this is still racy:
 286   ///
 287   ///   f = f.via(e).then(a);
 288   ///   f.then(b);
 289   // The ref-qualifier allows for `this` to be moved out so we
 290   // don't get access-after-free situations in chaining.
 291   // https://akrzemi1.wordpress.com/2014/06/02/ref-qualifiers/
 292   inline Future<T> via(
 293       Executor* executor,
 294       int8_t priority = Executor::MID_PRI) &&;
 295
 296   /**
 297    * Defer work to run on the consumer of the future.
 298    * This work will be run eithe ron an executor that the caller sets on the
 299    * SemiFuture, or inline with the call to .get().
 300    * NB: This is a custom method because boost-blocking executors is a
 301    * special-case for work deferral in folly. With more general boost-blocking
 302    * support all executors would boost block and we would simply use some form
 303    * of driveable executor here.
 304    */
 305   template <typename F>
 306   SemiFuture<typename futures::detail::callableResult<T, F>::Return::value_type>
 307   defer(F&& func) &&;
 308
 309   // Public as for setCallback_
 310   // Ensure that a boostable executor performs work to chain deferred work
 311   // cleanly
 312   void boost_();
 313
 314  private:
 315   template <class>
 316   friend class futures::detail::FutureBase;
 317   template <class>
 318   friend class SemiFuture;
 319
 320   using typename Base::corePtr;
 321   using Base::setExecutor;
 322   using Base::throwIfInvalid;
 323
 324   template <class T2>
 325   friend SemiFuture<T2> makeSemiFuture(Try<T2>&&);
 326
 327   explicit SemiFuture(corePtr obj) : Base(obj) {}
 328
 329   explicit SemiFuture(futures::detail::EmptyConstruct) noexcept
 330       : Base(futures::detail::EmptyConstruct{}) {}
 331 };
 332
 333 template <class T>
 334 class Future : private futures::detail::FutureBase<T> {
 335  private:
 336   using Base = futures::detail::FutureBase<T>;
 337
 338  public:
 339   // Export public interface of FutureBase
 340   // FutureBase is inherited privately to avoid subclasses being cast to
 341   // a FutureBase pointer
 342   using typename Base::value_type;
 343
 344   /// Construct a Future from a value (perfect forwarding)
 345   template <
 346       class T2 = T,
 347       typename = typename std::enable_if<
 348           !isFuture<typename std::decay<T2>::type>::value &&
 349           !isSemiFuture<typename std::decay<T2>::type>::value>::type>
 350   /* implicit */ Future(T2&& val) : Base(std::forward<T2>(val)) {}
 351
 352   template <class T2 = T>
 353   /* implicit */ Future(
 354       typename std::enable_if<std::is_same<Unit, T2>::value>::type* p = nullptr)
 355       : Base(p) {}
 356
 357   template <
 358       class... Args,
 359       typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
 360           type = 0>
 361   explicit Future(in_place_t, Args&&... args)
 362       : Base(in_place, std::forward<Args>(args)...) {}
 363
 364   Future(Future<T> const&) = delete;
 365   // movable
 366   Future(Future<T>&&) noexcept;
 367
 368   // converting move
 369   template <
 370       class T2,
 371       typename std::enable_if<
 372           !std::is_same<T, typename std::decay<T2>::type>::value &&
 373               std::is_constructible<T, T2&&>::value &&
 374               std::is_convertible<T2&&, T>::value,
 375           int>::type = 0>
 376   /* implicit */ Future(Future<T2>&&);
 377   template <
 378       class T2,
 379       typename std::enable_if<
 380           !std::is_same<T, typename std::decay<T2>::type>::value &&
 381               std::is_constructible<T, T2&&>::value &&
 382               !std::is_convertible<T2&&, T>::value,
 383           int>::type = 0>
 384   explicit Future(Future<T2>&&);
 385   template <
 386       class T2,
 387       typename std::enable_if<
 388           !std::is_same<T, typename std::decay<T2>::type>::value &&
 389               std::is_constructible<T, T2&&>::value,
 390           int>::type = 0>
 391   Future& operator=(Future<T2>&&);
 392
 393   using Base::cancel;
 394   using Base::getTry;
 395   using Base::hasException;
 396   using Base::hasValue;
 397   using Base::isActive;
 398   using Base::isReady;
 399   using Base::poll;
 400   using Base::raise;
 401   using Base::setCallback_;
 402   using Base::value;
 403
 404   static Future<T> makeEmpty(); // equivalent to moved-from
 405
 406   // not copyable
 407   Future& operator=(Future const&) = delete;
 408
 409   // movable
 410   Future& operator=(Future&&) noexcept;
 411
 412   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 413   /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
 414   /// reference to the Try of the value.
 415   Try<T>& getTryVia(DrivableExecutor* e);
 416
 417   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 418   /// of DrivableExecutor include EventBase and ManualExecutor. Returns the
 419   /// value (moved out), or throws the exception.
 420   T getVia(DrivableExecutor* e);
 421
 422   /// Unwraps the case of a Future<Future<T>> instance, and returns a simple
 423   /// Future<T> instance.
 424   template <class F = T>
 425   typename std::
 426       enable_if<isFuture<F>::value, Future<typename isFuture<T>::Inner>>::type
 427       unwrap();
 428
 429   /// Returns an inactive Future which will call back on the other side of
 430   /// executor (when it is activated).
 431   ///
 432   /// NB remember that Futures activate when they destruct. This is good,
 433   /// it means that this will work:
 434   ///
 435   ///   f.via(e).then(a).then(b);
 436   ///
 437   /// a and b will execute in the same context (the far side of e), because
 438   /// the Future (temporary variable) created by via(e) does not call back
 439   /// until it destructs, which is after then(a) and then(b) have been wired
 440   /// up.
 441   ///
 442   /// But this is still racy:
 443   ///
 444   ///   f = f.via(e).then(a);
 445   ///   f.then(b);
 446   // The ref-qualifier allows for `this` to be moved out so we
 447   // don't get access-after-free situations in chaining.
 448   // https://akrzemi1.wordpress.com/2014/06/02/ref-qualifiers/
 449   inline Future<T> via(
 450       Executor* executor,
 451       int8_t priority = Executor::MID_PRI) &&;
 452
 453   /// This variant creates a new future, where the ref-qualifier && version
 454   /// moves `this` out. This one is less efficient but avoids confusing users
 455   /// when "return f.via(x);" fails.
 456   inline Future<T> via(
 457       Executor* executor,
 458       int8_t priority = Executor::MID_PRI) &;
 459
 460   /** When this Future has completed, execute func which is a function that
 461     takes one of:
 462       (const) Try<T>&&
 463       (const) Try<T>&
 464       (const) Try<T>
 465       (const) T&&
 466       (const) T&
 467       (const) T
 468       (void)
 469
 470     Func shall return either another Future or a value.
 471
 472     A Future for the return type of func is returned.
 473
 474     Future<string> f2 = f1.then([](Try<T>&&) { return string("foo"); });
 475
 476     The Future given to the functor is ready, and the functor may call
 477     value(), which may rethrow if this has captured an exception. If func
 478     throws, the exception will be captured in the Future that is returned.
 479     */
 480   template <typename F, typename R = futures::detail::callableResult<T, F>>
 481   typename R::Return then(F&& func) {
 482     return this->template thenImplementation<F, R>(
 483         std::forward<F>(func), typename R::Arg());
 484   }
 485
 486   /// Variant where func is an member function
 487   ///
 488   ///   struct Worker { R doWork(Try<T>); }
 489   ///
 490   ///   Worker *w;
 491   ///   Future<R> f2 = f1.then(&Worker::doWork, w);
 492   ///
 493   /// This is just sugar for
 494   ///
 495   ///   f1.then(std::bind(&Worker::doWork, w));
 496   template <typename R, typename Caller, typename... Args>
 497   Future<typename isFuture<R>::Inner> then(
 498       R (Caller::*func)(Args...),
 499       Caller* instance);
 500
 501   /// Execute the callback via the given Executor. The executor doesn't stick.
 502   ///
 503   /// Contrast
 504   ///
 505   ///   f.via(x).then(b).then(c)
 506   ///
 507   /// with
 508   ///
 509   ///   f.then(x, b).then(c)
 510   ///
 511   /// In the former both b and c execute via x. In the latter, only b executes
 512   /// via x, and c executes via the same executor (if any) that f had.
 513   template <class Executor, class Arg, class... Args>
 514   auto then(Executor* x, Arg&& arg, Args&&... args) {
 515     auto oldX = this->getExecutor();
 516     this->setExecutor(x);
 517     return this->then(std::forward<Arg>(arg), std::forward<Args>(args)...)
 518         .via(oldX);
 519   }
 520
 521   /// Convenience method for ignoring the value and creating a Future<Unit>.
 522   /// Exceptions still propagate.
 523   /// This function is identical to .unit().
 524   Future<Unit> then();
 525
 526   /// Convenience method for ignoring the value and creating a Future<Unit>.
 527   /// Exceptions still propagate.
 528   /// This function is identical to parameterless .then().
 529   Future<Unit> unit() {
 530     return then();
 531   }
 532
 533   /// Set an error callback for this Future. The callback should take a single
 534   /// argument of the type that you want to catch, and should return a value of
 535   /// the same type as this Future, or a Future of that type (see overload
 536   /// below). For instance,
 537   ///
 538   /// makeFuture()
 539   ///   .then([] {
 540   ///     throw std::runtime_error("oh no!");
 541   ///     return 42;
 542   ///   })
 543   ///   .onError([] (std::runtime_error& e) {
 544   ///     LOG(INFO) << "std::runtime_error: " << e.what();
 545   ///     return -1; // or makeFuture<int>(-1)
 546   ///   });
 547   template <class F>
 548   typename std::enable_if<
 549       !futures::detail::callableWith<F, exception_wrapper>::value &&
 550           !futures::detail::callableWith<F, exception_wrapper&>::value &&
 551           !futures::detail::Extract<F>::ReturnsFuture::value,
 552       Future<T>>::type
 553   onError(F&& func);
 554
 555   /// Overload of onError where the error callback returns a Future<T>
 556   template <class F>
 557   typename std::enable_if<
 558       !futures::detail::callableWith<F, exception_wrapper>::value &&
 559           !futures::detail::callableWith<F, exception_wrapper&>::value &&
 560           futures::detail::Extract<F>::ReturnsFuture::value,
 561       Future<T>>::type
 562   onError(F&& func);
 563
 564   /// Overload of onError that takes exception_wrapper and returns Future<T>
 565   template <class F>
 566   typename std::enable_if<
 567       futures::detail::callableWith<F, exception_wrapper>::value &&
 568           futures::detail::Extract<F>::ReturnsFuture::value,
 569       Future<T>>::type
 570   onError(F&& func);
 571
 572   /// Overload of onError that takes exception_wrapper and returns T
 573   template <class F>
 574   typename std::enable_if<
 575       futures::detail::callableWith<F, exception_wrapper>::value &&
 576           !futures::detail::Extract<F>::ReturnsFuture::value,
 577       Future<T>>::type
 578   onError(F&& func);
 579
 580   /// func is like std::function<void()> and is executed unconditionally, and
 581   /// the value/exception is passed through to the resulting Future.
 582   /// func shouldn't throw, but if it does it will be captured and propagated,
 583   /// and discard any value/exception that this Future has obtained.
 584   template <class F>
 585   Future<T> ensure(F&& func);
 586
 587   /// Like onError, but for timeouts. example:
 588   ///
 589   ///   Future<int> f = makeFuture<int>(42)
 590   ///     .delayed(long_time)
 591   ///     .onTimeout(short_time,
 592   ///       []() -> int{ return -1; });
 593   ///
 594   /// or perhaps
 595   ///
 596   ///   Future<int> f = makeFuture<int>(42)
 597   ///     .delayed(long_time)
 598   ///     .onTimeout(short_time,
 599   ///       []() { return makeFuture<int>(some_exception); });
 600   template <class F>
 601   Future<T> onTimeout(Duration, F&& func, Timekeeper* = nullptr);
 602
 603   /// A Future's callback is executed when all three of these conditions have
 604   /// become true: it has a value (set by the Promise), it has a callback (set
 605   /// by then), and it is active (active by default).
 606   ///
 607   /// Inactive Futures will activate upon destruction.
 608   FOLLY_DEPRECATED("do not use") Future<T>& activate() & {
 609     this->core_->activate();
 610     return *this;
 611   }
 612   FOLLY_DEPRECATED("do not use") Future<T>& deactivate() & {
 613     this->core_->deactivate();
 614     return *this;
 615   }
 616   FOLLY_DEPRECATED("do not use") Future<T> activate() && {
 617     this->core_->activate();
 618     return std::move(*this);
 619   }
 620   FOLLY_DEPRECATED("do not use") Future<T> deactivate() && {
 621     this->core_->deactivate();
 622     return std::move(*this);
 623   }
 624
 625   /// Throw TimedOut if this Future does not complete within the given
 626   /// duration from now. The optional Timeekeeper is as with futures::sleep().
 627   Future<T> within(Duration, Timekeeper* = nullptr);
 628
 629   /// Throw the given exception if this Future does not complete within the
 630   /// given duration from now. The optional Timeekeeper is as with
 631   /// futures::sleep().
 632   template <class E>
 633   Future<T> within(Duration, E exception, Timekeeper* = nullptr);
 634
 635   /// Delay the completion of this Future for at least this duration from
 636   /// now. The optional Timekeeper is as with futures::sleep().
 637   Future<T> delayed(Duration, Timekeeper* = nullptr);
 638
 639   /// Block until the future is fulfilled. Returns the value (moved out), or
 640   /// throws the exception. The future must not already have a callback.
 641   T get();
 642
 643   /// Block until the future is fulfilled, or until timed out. Returns the
 644   /// value (moved out), or throws the exception (which might be a TimedOut
 645   /// exception).
 646   T get(Duration dur);
 647
 648   /// Block until this Future is complete. Returns a reference to this Future.
 649   Future<T>& wait() &;
 650
 651   /// Overload of wait() for rvalue Futures
 652   Future<T>&& wait() &&;
 653
 654   /// Block until this Future is complete or until the given Duration passes.
 655   /// Returns a reference to this Future
 656   Future<T>& wait(Duration) &;
 657
 658   /// Overload of wait(Duration) for rvalue Futures
 659   Future<T>&& wait(Duration) &&;
 660
 661   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 662   /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
 663   /// reference to this Future so that you can chain calls if desired.
 664   /// value (moved out), or throws the exception.
 665   Future<T>& waitVia(DrivableExecutor* e) &;
 666
 667   /// Overload of waitVia() for rvalue Futures
 668   Future<T>&& waitVia(DrivableExecutor* e) &&;
 669
 670   /// If the value in this Future is equal to the given Future, when they have
 671   /// both completed, the value of the resulting Future<bool> will be true. It
 672   /// will be false otherwise (including when one or both Futures have an
 673   /// exception)
 674   Future<bool> willEqual(Future<T>&);
 675
 676   /// predicate behaves like std::function<bool(T const&)>
 677   /// If the predicate does not obtain with the value, the result
 678   /// is a folly::PredicateDoesNotObtain exception
 679   template <class F>
 680   Future<T> filter(F&& predicate);
 681
 682   /// Like reduce, but works on a Future<std::vector<T / Try<T>>>, for example
 683   /// the result of collect or collectAll
 684   template <class I, class F>
 685   Future<I> reduce(I&& initial, F&& func);
 686
 687   /// Create a Future chain from a sequence of callbacks. i.e.
 688   ///
 689   ///   f.then(a).then(b).then(c)
 690   ///
 691   /// where f is a Future<A> and the result of the chain is a Future<D>
 692   /// becomes
 693   ///
 694   ///   f.thenMulti(a, b, c);
 695   template <class Callback, class... Callbacks>
 696   auto thenMulti(Callback&& fn, Callbacks&&... fns) {
 697     // thenMulti with two callbacks is just then(a).thenMulti(b, ...)
 698     return then(std::forward<Callback>(fn))
 699         .thenMulti(std::forward<Callbacks>(fns)...);
 700   }
 701
 702   template <class Callback>
 703   auto thenMulti(Callback&& fn) {
 704     // thenMulti with one callback is just a then
 705     return then(std::forward<Callback>(fn));
 706   }
 707
 708   /// Create a Future chain from a sequence of callbacks. i.e.
 709   ///
 710   ///   f.via(executor).then(a).then(b).then(c).via(oldExecutor)
 711   ///
 712   /// where f is a Future<A> and the result of the chain is a Future<D>
 713   /// becomes
 714   ///
 715   ///   f.thenMultiWithExecutor(executor, a, b, c);
 716   template <class Callback, class... Callbacks>
 717   auto thenMultiWithExecutor(Executor* x, Callback&& fn, Callbacks&&... fns) {
 718     // thenMultiExecutor with two callbacks is
 719     // via(x).then(a).thenMulti(b, ...).via(oldX)
 720     auto oldX = this->getExecutor();
 721     this->setExecutor(x);
 722     return then(std::forward<Callback>(fn))
 723         .thenMulti(std::forward<Callbacks>(fns)...)
 724         .via(oldX);
 725   }
 726
 727   template <class Callback>
 728   auto thenMultiWithExecutor(Executor* x, Callback&& fn) {
 729     // thenMulti with one callback is just a then with an executor
 730     return then(x, std::forward<Callback>(fn));
 731   }
 732
 733   // Convert this Future to a SemiFuture to safely export from a library
 734   // without exposing a continuation interface
 735   SemiFuture<T> semi() {
 736     return SemiFuture<T>{std::move(*this)};
 737   }
 738
 739  protected:
 740   friend class Promise<T>;
 741   template <class>
 742   friend class futures::detail::FutureBase;
 743   template <class>
 744   friend class Future;
 745   template <class>
 746   friend class SemiFuture;
 747
 748   using Base::setExecutor;
 749   using Base::throwIfInvalid;
 750   using typename Base::corePtr;
 751
 752   explicit Future(corePtr obj) : Base(obj) {}
 753
 754   explicit Future(futures::detail::EmptyConstruct) noexcept
 755       : Base(futures::detail::EmptyConstruct{}) {}
 756
 757   template <class T2>
 758   friend Future<T2> makeFuture(Try<T2>&&);
 759
 760   /// Repeat the given future (i.e., the computation it contains)
 761   /// n times.
 762   ///
 763   /// thunk behaves like std::function<Future<T2>(void)>
 764   template <class F>
 765   friend Future<Unit> times(int n, F&& thunk);
 766
 767   /// Carry out the computation contained in the given future if
 768   /// the predicate holds.
 769   ///
 770   /// thunk behaves like std::function<Future<T2>(void)>
 771   template <class F>
 772   friend Future<Unit> when(bool p, F&& thunk);
 773
 774   /// Carry out the computation contained in the given future if
 775   /// while the predicate continues to hold.
 776   ///
 777   /// thunk behaves like std::function<Future<T2>(void)>
 778   ///
 779   /// predicate behaves like std::function<bool(void)>
 780   template <class P, class F>
 781   friend Future<Unit> whileDo(P&& predicate, F&& thunk);
 782 };
 783
 784 } // namespace folly
 785
 786 #include <folly/futures/Future-inl.h>