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/Try.h>
  29 #include <folly/Utility.h>
  30 #include <folly/futures/DrivableExecutor.h>
  31 #include <folly/futures/FutureException.h>
  32 #include <folly/futures/Promise.h>
  33 #include <folly/futures/detail/Types.h>
  34
  35 // boring predeclarations and details
  36 #include <folly/futures/Future-pre.h>
  37
  38 // not-boring helpers, e.g. all in folly::futures, makeFuture variants, etc.
  39 // Needs to be included after Future-pre.h and before Future-inl.h
  40 #include <folly/futures/helpers.h>
  41
  42 namespace folly {
  43
  44 template <class T>
  45 class Future {
  46  public:
  47   typedef T value_type;
  48
  49   static Future<T> makeEmpty(); // equivalent to moved-from
  50
  51   // not copyable
  52   Future(Future const&) = delete;
  53   Future& operator=(Future const&) = delete;
  54
  55   // movable
  56   Future(Future&&) noexcept;
  57   Future& operator=(Future&&) noexcept;
  58
  59   // converting move
  60   template <
  61       class T2,
  62       typename std::enable_if<
  63           !std::is_same<T, typename std::decay<T2>::type>::value &&
  64               std::is_constructible<T, T2&&>::value &&
  65               std::is_convertible<T2&&, T>::value,
  66           int>::type = 0>
  67   /* implicit */ Future(Future<T2>&&);
  68   template <
  69       class T2,
  70       typename std::enable_if<
  71           !std::is_same<T, typename std::decay<T2>::type>::value &&
  72               std::is_constructible<T, T2&&>::value &&
  73               !std::is_convertible<T2&&, T>::value,
  74           int>::type = 0>
  75   explicit Future(Future<T2>&&);
  76   template <
  77       class T2,
  78       typename std::enable_if<
  79           !std::is_same<T, typename std::decay<T2>::type>::value &&
  80               std::is_constructible<T, T2&&>::value,
  81           int>::type = 0>
  82   Future& operator=(Future<T2>&&);
  83
  84   /// Construct a Future from a value (perfect forwarding)
  85   template <class T2 = T, typename =
  86             typename std::enable_if<
  87               !isFuture<typename std::decay<T2>::type>::value>::type>
  88   /* implicit */ Future(T2&& val);
  89
  90   template <class T2 = T>
  91   /* implicit */ Future(
  92       typename std::enable_if<std::is_same<Unit, T2>::value>::type* = nullptr);
  93
  94   template <
  95       class... Args,
  96       typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
  97           type = 0>
  98   explicit Future(in_place_t, Args&&... args);
  99
 100   ~Future();
 101
 102   /** Return the reference to result. Should not be called if !isReady().
 103     Will rethrow the exception if an exception has been
 104     captured.
 105     */
 106   typename std::add_lvalue_reference<T>::type
 107   value();
 108   typename std::add_lvalue_reference<const T>::type
 109   value() const;
 110
 111   /// Returns an inactive Future which will call back on the other side of
 112   /// executor (when it is activated).
 113   ///
 114   /// NB remember that Futures activate when they destruct. This is good,
 115   /// it means that this will work:
 116   ///
 117   ///   f.via(e).then(a).then(b);
 118   ///
 119   /// a and b will execute in the same context (the far side of e), because
 120   /// the Future (temporary variable) created by via(e) does not call back
 121   /// until it destructs, which is after then(a) and then(b) have been wired
 122   /// up.
 123   ///
 124   /// But this is still racy:
 125   ///
 126   ///   f = f.via(e).then(a);
 127   ///   f.then(b);
 128   // The ref-qualifier allows for `this` to be moved out so we
 129   // don't get access-after-free situations in chaining.
 130   // https://akrzemi1.wordpress.com/2014/06/02/ref-qualifiers/
 131   inline Future<T> via(
 132       Executor* executor,
 133       int8_t priority = Executor::MID_PRI) &&;
 134
 135   /// This variant creates a new future, where the ref-qualifier && version
 136   /// moves `this` out. This one is less efficient but avoids confusing users
 137   /// when "return f.via(x);" fails.
 138   inline Future<T> via(
 139       Executor* executor,
 140       int8_t priority = Executor::MID_PRI) &;
 141
 142   /** True when the result (or exception) is ready. */
 143   bool isReady() const;
 144
 145   /// sugar for getTry().hasValue()
 146   bool hasValue();
 147
 148   /// sugar for getTry().hasException()
 149   bool hasException();
 150
 151   /** A reference to the Try of the value */
 152   Try<T>& getTry();
 153
 154   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 155   /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
 156   /// reference to the Try of the value.
 157   Try<T>& getTryVia(DrivableExecutor* e);
 158
 159   /// If the promise has been fulfilled, return an Optional with the Try<T>.
 160   /// Otherwise return an empty Optional.
 161   /// Note that this moves the Try<T> out.
 162   Optional<Try<T>> poll();
 163
 164   /// Block until the future is fulfilled. Returns the value (moved out), or
 165   /// throws the exception. The future must not already have a callback.
 166   T get();
 167
 168   /// Block until the future is fulfilled, or until timed out. Returns the
 169   /// value (moved out), or throws the exception (which might be a TimedOut
 170   /// exception).
 171   T get(Duration dur);
 172
 173   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 174   /// of DrivableExecutor include EventBase and ManualExecutor. Returns the
 175   /// value (moved out), or throws the exception.
 176   T getVia(DrivableExecutor* e);
 177
 178   /// Unwraps the case of a Future<Future<T>> instance, and returns a simple
 179   /// Future<T> instance.
 180   template <class F = T>
 181   typename std::enable_if<isFuture<F>::value,
 182                           Future<typename isFuture<T>::Inner>>::type
 183   unwrap();
 184
 185   /** When this Future has completed, execute func which is a function that
 186     takes one of:
 187       (const) Try<T>&&
 188       (const) Try<T>&
 189       (const) Try<T>
 190       (const) T&&
 191       (const) T&
 192       (const) T
 193       (void)
 194
 195     Func shall return either another Future or a value.
 196
 197     A Future for the return type of func is returned.
 198
 199     Future<string> f2 = f1.then([](Try<T>&&) { return string("foo"); });
 200
 201     The Future given to the functor is ready, and the functor may call
 202     value(), which may rethrow if this has captured an exception. If func
 203     throws, the exception will be captured in the Future that is returned.
 204     */
 205   // gcc 4.8 requires that we cast function reference types to function pointer
 206   // types. Fore more details see the comment on FunctionReferenceToPointer
 207   // in Future-pre.h.
 208   // gcc versions 4.9 and above (as well as clang) do not require this hack.
 209   // For those, the FF tenplate parameter can be removed and occurences of FF
 210   // replaced with F.
 211   template <
 212       typename F,
 213       typename FF = typename detail::FunctionReferenceToPointer<F>::type,
 214       typename R = detail::callableResult<T, FF>>
 215   typename R::Return then(F&& func) {
 216     typedef typename R::Arg Arguments;
 217     return thenImplementation<FF, R>(std::forward<FF>(func), Arguments());
 218   }
 219
 220   /// Variant where func is an member function
 221   ///
 222   ///   struct Worker { R doWork(Try<T>); }
 223   ///
 224   ///   Worker *w;
 225   ///   Future<R> f2 = f1.then(&Worker::doWork, w);
 226   ///
 227   /// This is just sugar for
 228   ///
 229   ///   f1.then(std::bind(&Worker::doWork, w));
 230   template <typename R, typename Caller, typename... Args>
 231   Future<typename isFuture<R>::Inner>
 232   then(R(Caller::*func)(Args...), Caller *instance);
 233
 234   /// Execute the callback via the given Executor. The executor doesn't stick.
 235   ///
 236   /// Contrast
 237   ///
 238   ///   f.via(x).then(b).then(c)
 239   ///
 240   /// with
 241   ///
 242   ///   f.then(x, b).then(c)
 243   ///
 244   /// In the former both b and c execute via x. In the latter, only b executes
 245   /// via x, and c executes via the same executor (if any) that f had.
 246   template <class Executor, class Arg, class... Args>
 247   auto then(Executor* x, Arg&& arg, Args&&... args) {
 248     auto oldX = getExecutor();
 249     setExecutor(x);
 250     return this->then(std::forward<Arg>(arg), std::forward<Args>(args)...)
 251         .via(oldX);
 252   }
 253
 254   /// Convenience method for ignoring the value and creating a Future<Unit>.
 255   /// Exceptions still propagate.
 256   Future<Unit> then();
 257
 258   /// Set an error callback for this Future. The callback should take a single
 259   /// argument of the type that you want to catch, and should return a value of
 260   /// the same type as this Future, or a Future of that type (see overload
 261   /// below). For instance,
 262   ///
 263   /// makeFuture()
 264   ///   .then([] {
 265   ///     throw std::runtime_error("oh no!");
 266   ///     return 42;
 267   ///   })
 268   ///   .onError([] (std::runtime_error& e) {
 269   ///     LOG(INFO) << "std::runtime_error: " << e.what();
 270   ///     return -1; // or makeFuture<int>(-1)
 271   ///   });
 272   template <class F>
 273   typename std::enable_if<
 274     !detail::callableWith<F, exception_wrapper>::value &&
 275     !detail::Extract<F>::ReturnsFuture::value,
 276     Future<T>>::type
 277   onError(F&& func);
 278
 279   /// Overload of onError where the error callback returns a Future<T>
 280   template <class F>
 281   typename std::enable_if<
 282     !detail::callableWith<F, exception_wrapper>::value &&
 283     detail::Extract<F>::ReturnsFuture::value,
 284     Future<T>>::type
 285   onError(F&& func);
 286
 287   /// Overload of onError that takes exception_wrapper and returns Future<T>
 288   template <class F>
 289   typename std::enable_if<
 290     detail::callableWith<F, exception_wrapper>::value &&
 291     detail::Extract<F>::ReturnsFuture::value,
 292     Future<T>>::type
 293   onError(F&& func);
 294
 295   /// Overload of onError that takes exception_wrapper and returns T
 296   template <class F>
 297   typename std::enable_if<
 298     detail::callableWith<F, exception_wrapper>::value &&
 299     !detail::Extract<F>::ReturnsFuture::value,
 300     Future<T>>::type
 301   onError(F&& func);
 302
 303   /// func is like std::function<void()> and is executed unconditionally, and
 304   /// the value/exception is passed through to the resulting Future.
 305   /// func shouldn't throw, but if it does it will be captured and propagated,
 306   /// and discard any value/exception that this Future has obtained.
 307   template <class F>
 308   Future<T> ensure(F&& func);
 309
 310   /// Like onError, but for timeouts. example:
 311   ///
 312   ///   Future<int> f = makeFuture<int>(42)
 313   ///     .delayed(long_time)
 314   ///     .onTimeout(short_time,
 315   ///       []() -> int{ return -1; });
 316   ///
 317   /// or perhaps
 318   ///
 319   ///   Future<int> f = makeFuture<int>(42)
 320   ///     .delayed(long_time)
 321   ///     .onTimeout(short_time,
 322   ///       []() { return makeFuture<int>(some_exception); });
 323   template <class F>
 324   Future<T> onTimeout(Duration, F&& func, Timekeeper* = nullptr);
 325
 326   /// This is not the method you're looking for.
 327   ///
 328   /// This needs to be public because it's used by make* and when*, and it's
 329   /// not worth listing all those and their fancy template signatures as
 330   /// friends. But it's not for public consumption.
 331   template <class F>
 332   void setCallback_(F&& func);
 333
 334   /// A Future's callback is executed when all three of these conditions have
 335   /// become true: it has a value (set by the Promise), it has a callback (set
 336   /// by then), and it is active (active by default).
 337   ///
 338   /// Inactive Futures will activate upon destruction.
 339   FOLLY_DEPRECATED("do not use") Future<T>& activate() & {
 340     core_->activate();
 341     return *this;
 342   }
 343   FOLLY_DEPRECATED("do not use") Future<T>& deactivate() & {
 344     core_->deactivate();
 345     return *this;
 346   }
 347   FOLLY_DEPRECATED("do not use") Future<T> activate() && {
 348     core_->activate();
 349     return std::move(*this);
 350   }
 351   FOLLY_DEPRECATED("do not use") Future<T> deactivate() && {
 352     core_->deactivate();
 353     return std::move(*this);
 354   }
 355
 356   bool isActive() {
 357     return core_->isActive();
 358   }
 359
 360   template <class E>
 361   void raise(E&& exception) {
 362     raise(make_exception_wrapper<typename std::remove_reference<E>::type>(
 363         std::forward<E>(exception)));
 364   }
 365
 366   /// Raise an interrupt. If the promise holder has an interrupt
 367   /// handler it will be called and potentially stop asynchronous work from
 368   /// being done. This is advisory only - a promise holder may not set an
 369   /// interrupt handler, or may do anything including ignore. But, if you know
 370   /// your future supports this the most likely result is stopping or
 371   /// preventing the asynchronous operation (if in time), and the promise
 372   /// holder setting an exception on the future. (That may happen
 373   /// asynchronously, of course.)
 374   void raise(exception_wrapper interrupt);
 375
 376   void cancel() {
 377     raise(FutureCancellation());
 378   }
 379
 380   /// Throw TimedOut if this Future does not complete within the given
 381   /// duration from now. The optional Timeekeeper is as with futures::sleep().
 382   Future<T> within(Duration, Timekeeper* = nullptr);
 383
 384   /// Throw the given exception if this Future does not complete within the
 385   /// given duration from now. The optional Timeekeeper is as with
 386   /// futures::sleep().
 387   template <class E>
 388   Future<T> within(Duration, E exception, Timekeeper* = nullptr);
 389
 390   /// Delay the completion of this Future for at least this duration from
 391   /// now. The optional Timekeeper is as with futures::sleep().
 392   Future<T> delayed(Duration, Timekeeper* = nullptr);
 393
 394   /// Block until this Future is complete. Returns a reference to this Future.
 395   Future<T>& wait() &;
 396
 397   /// Overload of wait() for rvalue Futures
 398   Future<T>&& wait() &&;
 399
 400   /// Block until this Future is complete or until the given Duration passes.
 401   /// Returns a reference to this Future
 402   Future<T>& wait(Duration) &;
 403
 404   /// Overload of wait(Duration) for rvalue Futures
 405   Future<T>&& wait(Duration) &&;
 406
 407   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 408   /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
 409   /// reference to this Future so that you can chain calls if desired.
 410   /// value (moved out), or throws the exception.
 411   Future<T>& waitVia(DrivableExecutor* e) &;
 412
 413   /// Overload of waitVia() for rvalue Futures
 414   Future<T>&& waitVia(DrivableExecutor* e) &&;
 415
 416   /// If the value in this Future is equal to the given Future, when they have
 417   /// both completed, the value of the resulting Future<bool> will be true. It
 418   /// will be false otherwise (including when one or both Futures have an
 419   /// exception)
 420   Future<bool> willEqual(Future<T>&);
 421
 422   /// predicate behaves like std::function<bool(T const&)>
 423   /// If the predicate does not obtain with the value, the result
 424   /// is a folly::PredicateDoesNotObtain exception
 425   template <class F>
 426   Future<T> filter(F&& predicate);
 427
 428   /// Like reduce, but works on a Future<std::vector<T / Try<T>>>, for example
 429   /// the result of collect or collectAll
 430   template <class I, class F>
 431   Future<I> reduce(I&& initial, F&& func);
 432
 433   /// Create a Future chain from a sequence of callbacks. i.e.
 434   ///
 435   ///   f.then(a).then(b).then(c)
 436   ///
 437   /// where f is a Future<A> and the result of the chain is a Future<D>
 438   /// becomes
 439   ///
 440   ///   f.thenMulti(a, b, c);
 441   template <class Callback, class... Callbacks>
 442   auto thenMulti(Callback&& fn, Callbacks&&... fns) {
 443     // thenMulti with two callbacks is just then(a).thenMulti(b, ...)
 444     return then(std::forward<Callback>(fn))
 445         .thenMulti(std::forward<Callbacks>(fns)...);
 446   }
 447
 448   template <class Callback>
 449   auto thenMulti(Callback&& fn) {
 450     // thenMulti with one callback is just a then
 451     return then(std::forward<Callback>(fn));
 452   }
 453
 454   /// Create a Future chain from a sequence of callbacks. i.e.
 455   ///
 456   ///   f.via(executor).then(a).then(b).then(c).via(oldExecutor)
 457   ///
 458   /// where f is a Future<A> and the result of the chain is a Future<D>
 459   /// becomes
 460   ///
 461   ///   f.thenMultiWithExecutor(executor, a, b, c);
 462   template <class Callback, class... Callbacks>
 463   auto thenMultiWithExecutor(Executor* x, Callback&& fn, Callbacks&&... fns) {
 464     // thenMultiExecutor with two callbacks is
 465     // via(x).then(a).thenMulti(b, ...).via(oldX)
 466     auto oldX = getExecutor();
 467     setExecutor(x);
 468     return then(std::forward<Callback>(fn))
 469         .thenMulti(std::forward<Callbacks>(fns)...)
 470         .via(oldX);
 471   }
 472
 473   template <class Callback>
 474   auto thenMultiWithExecutor(Executor* x, Callback&& fn) {
 475     // thenMulti with one callback is just a then with an executor
 476     return then(x, std::forward<Callback>(fn));
 477   }
 478
 479   /// Discard a result, but propagate an exception.
 480   Future<Unit> unit() {
 481     return then([]{ return Unit{}; });
 482   }
 483
 484  protected:
 485   typedef detail::Core<T>* corePtr;
 486
 487   // shared core state object
 488   corePtr core_;
 489
 490   explicit
 491   Future(corePtr obj) : core_(obj) {}
 492
 493   explicit Future(detail::EmptyConstruct) noexcept;
 494
 495   void detach();
 496
 497   void throwIfInvalid() const;
 498
 499   friend class Promise<T>;
 500   template <class> friend class Future;
 501
 502   template <class T2>
 503   friend Future<T2> makeFuture(Try<T2>&&);
 504
 505   /// Repeat the given future (i.e., the computation it contains)
 506   /// n times.
 507   ///
 508   /// thunk behaves like std::function<Future<T2>(void)>
 509   template <class F>
 510   friend Future<Unit> times(int n, F&& thunk);
 511
 512   /// Carry out the computation contained in the given future if
 513   /// the predicate holds.
 514   ///
 515   /// thunk behaves like std::function<Future<T2>(void)>
 516   template <class F>
 517   friend Future<Unit> when(bool p, F&& thunk);
 518
 519   /// Carry out the computation contained in the given future if
 520   /// while the predicate continues to hold.
 521   ///
 522   /// thunk behaves like std::function<Future<T2>(void)>
 523   ///
 524   /// predicate behaves like std::function<bool(void)>
 525   template <class P, class F>
 526   friend Future<Unit> whileDo(P&& predicate, F&& thunk);
 527
 528   // Variant: returns a value
 529   // e.g. f.then([](Try<T> t){ return t.value(); });
 530   template <typename F, typename R, bool isTry, typename... Args>
 531   typename std::enable_if<!R::ReturnsFuture::value, typename R::Return>::type
 532   thenImplementation(F&& func, detail::argResult<isTry, F, Args...>);
 533
 534   // Variant: returns a Future
 535   // e.g. f.then([](Try<T> t){ return makeFuture<T>(t); });
 536   template <typename F, typename R, bool isTry, typename... Args>
 537   typename std::enable_if<R::ReturnsFuture::value, typename R::Return>::type
 538   thenImplementation(F&& func, detail::argResult<isTry, F, Args...>);
 539
 540   Executor* getExecutor() { return core_->getExecutor(); }
 541   void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
 542     core_->setExecutor(x, priority);
 543   }
 544 };
 545
 546 } // folly
 547
 548 #include <folly/futures/Future-inl.h>