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 =
 214           typename futures::detail::FunctionReferenceToPointer<F>::type,
 215       typename R = futures::detail::callableResult<T, FF>>
 216   typename R::Return then(F&& func) {
 217     typedef typename R::Arg Arguments;
 218     return thenImplementation<FF, R>(std::forward<FF>(func), Arguments());
 219   }
 220
 221   /// Variant where func is an member function
 222   ///
 223   ///   struct Worker { R doWork(Try<T>); }
 224   ///
 225   ///   Worker *w;
 226   ///   Future<R> f2 = f1.then(&Worker::doWork, w);
 227   ///
 228   /// This is just sugar for
 229   ///
 230   ///   f1.then(std::bind(&Worker::doWork, w));
 231   template <typename R, typename Caller, typename... Args>
 232   Future<typename isFuture<R>::Inner>
 233   then(R(Caller::*func)(Args...), Caller *instance);
 234
 235   /// Execute the callback via the given Executor. The executor doesn't stick.
 236   ///
 237   /// Contrast
 238   ///
 239   ///   f.via(x).then(b).then(c)
 240   ///
 241   /// with
 242   ///
 243   ///   f.then(x, b).then(c)
 244   ///
 245   /// In the former both b and c execute via x. In the latter, only b executes
 246   /// via x, and c executes via the same executor (if any) that f had.
 247   template <class Executor, class Arg, class... Args>
 248   auto then(Executor* x, Arg&& arg, Args&&... args) {
 249     auto oldX = getExecutor();
 250     setExecutor(x);
 251     return this->then(std::forward<Arg>(arg), std::forward<Args>(args)...)
 252         .via(oldX);
 253   }
 254
 255   /// Convenience method for ignoring the value and creating a Future<Unit>.
 256   /// Exceptions still propagate.
 257   Future<Unit> then();
 258
 259   /// Set an error callback for this Future. The callback should take a single
 260   /// argument of the type that you want to catch, and should return a value of
 261   /// the same type as this Future, or a Future of that type (see overload
 262   /// below). For instance,
 263   ///
 264   /// makeFuture()
 265   ///   .then([] {
 266   ///     throw std::runtime_error("oh no!");
 267   ///     return 42;
 268   ///   })
 269   ///   .onError([] (std::runtime_error& e) {
 270   ///     LOG(INFO) << "std::runtime_error: " << e.what();
 271   ///     return -1; // or makeFuture<int>(-1)
 272   ///   });
 273   template <class F>
 274   typename std::enable_if<
 275       !futures::detail::callableWith<F, exception_wrapper>::value &&
 276           !futures::detail::Extract<F>::ReturnsFuture::value,
 277       Future<T>>::type
 278   onError(F&& func);
 279
 280   /// Overload of onError where the error callback returns a Future<T>
 281   template <class F>
 282   typename std::enable_if<
 283       !futures::detail::callableWith<F, exception_wrapper>::value &&
 284           futures::detail::Extract<F>::ReturnsFuture::value,
 285       Future<T>>::type
 286   onError(F&& func);
 287
 288   /// Overload of onError that takes exception_wrapper and returns Future<T>
 289   template <class F>
 290   typename std::enable_if<
 291       futures::detail::callableWith<F, exception_wrapper>::value &&
 292           futures::detail::Extract<F>::ReturnsFuture::value,
 293       Future<T>>::type
 294   onError(F&& func);
 295
 296   /// Overload of onError that takes exception_wrapper and returns T
 297   template <class F>
 298   typename std::enable_if<
 299       futures::detail::callableWith<F, exception_wrapper>::value &&
 300           !futures::detail::Extract<F>::ReturnsFuture::value,
 301       Future<T>>::type
 302   onError(F&& func);
 303
 304   /// func is like std::function<void()> and is executed unconditionally, and
 305   /// the value/exception is passed through to the resulting Future.
 306   /// func shouldn't throw, but if it does it will be captured and propagated,
 307   /// and discard any value/exception that this Future has obtained.
 308   template <class F>
 309   Future<T> ensure(F&& func);
 310
 311   /// Like onError, but for timeouts. example:
 312   ///
 313   ///   Future<int> f = makeFuture<int>(42)
 314   ///     .delayed(long_time)
 315   ///     .onTimeout(short_time,
 316   ///       []() -> int{ return -1; });
 317   ///
 318   /// or perhaps
 319   ///
 320   ///   Future<int> f = makeFuture<int>(42)
 321   ///     .delayed(long_time)
 322   ///     .onTimeout(short_time,
 323   ///       []() { return makeFuture<int>(some_exception); });
 324   template <class F>
 325   Future<T> onTimeout(Duration, F&& func, Timekeeper* = nullptr);
 326
 327   /// This is not the method you're looking for.
 328   ///
 329   /// This needs to be public because it's used by make* and when*, and it's
 330   /// not worth listing all those and their fancy template signatures as
 331   /// friends. But it's not for public consumption.
 332   template <class F>
 333   void setCallback_(F&& func);
 334
 335   /// A Future's callback is executed when all three of these conditions have
 336   /// become true: it has a value (set by the Promise), it has a callback (set
 337   /// by then), and it is active (active by default).
 338   ///
 339   /// Inactive Futures will activate upon destruction.
 340   FOLLY_DEPRECATED("do not use") Future<T>& activate() & {
 341     core_->activate();
 342     return *this;
 343   }
 344   FOLLY_DEPRECATED("do not use") Future<T>& deactivate() & {
 345     core_->deactivate();
 346     return *this;
 347   }
 348   FOLLY_DEPRECATED("do not use") Future<T> activate() && {
 349     core_->activate();
 350     return std::move(*this);
 351   }
 352   FOLLY_DEPRECATED("do not use") Future<T> deactivate() && {
 353     core_->deactivate();
 354     return std::move(*this);
 355   }
 356
 357   bool isActive() {
 358     return core_->isActive();
 359   }
 360
 361   template <class E>
 362   void raise(E&& exception) {
 363     raise(make_exception_wrapper<typename std::remove_reference<E>::type>(
 364         std::forward<E>(exception)));
 365   }
 366
 367   /// Raise an interrupt. If the promise holder has an interrupt
 368   /// handler it will be called and potentially stop asynchronous work from
 369   /// being done. This is advisory only - a promise holder may not set an
 370   /// interrupt handler, or may do anything including ignore. But, if you know
 371   /// your future supports this the most likely result is stopping or
 372   /// preventing the asynchronous operation (if in time), and the promise
 373   /// holder setting an exception on the future. (That may happen
 374   /// asynchronously, of course.)
 375   void raise(exception_wrapper interrupt);
 376
 377   void cancel() {
 378     raise(FutureCancellation());
 379   }
 380
 381   /// Throw TimedOut if this Future does not complete within the given
 382   /// duration from now. The optional Timeekeeper is as with futures::sleep().
 383   Future<T> within(Duration, Timekeeper* = nullptr);
 384
 385   /// Throw the given exception if this Future does not complete within the
 386   /// given duration from now. The optional Timeekeeper is as with
 387   /// futures::sleep().
 388   template <class E>
 389   Future<T> within(Duration, E exception, Timekeeper* = nullptr);
 390
 391   /// Delay the completion of this Future for at least this duration from
 392   /// now. The optional Timekeeper is as with futures::sleep().
 393   Future<T> delayed(Duration, Timekeeper* = nullptr);
 394
 395   /// Block until this Future is complete. Returns a reference to this Future.
 396   Future<T>& wait() &;
 397
 398   /// Overload of wait() for rvalue Futures
 399   Future<T>&& wait() &&;
 400
 401   /// Block until this Future is complete or until the given Duration passes.
 402   /// Returns a reference to this Future
 403   Future<T>& wait(Duration) &;
 404
 405   /// Overload of wait(Duration) for rvalue Futures
 406   Future<T>&& wait(Duration) &&;
 407
 408   /// Call e->drive() repeatedly until the future is fulfilled. Examples
 409   /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
 410   /// reference to this Future so that you can chain calls if desired.
 411   /// value (moved out), or throws the exception.
 412   Future<T>& waitVia(DrivableExecutor* e) &;
 413
 414   /// Overload of waitVia() for rvalue Futures
 415   Future<T>&& waitVia(DrivableExecutor* e) &&;
 416
 417   /// If the value in this Future is equal to the given Future, when they have
 418   /// both completed, the value of the resulting Future<bool> will be true. It
 419   /// will be false otherwise (including when one or both Futures have an
 420   /// exception)
 421   Future<bool> willEqual(Future<T>&);
 422
 423   /// predicate behaves like std::function<bool(T const&)>
 424   /// If the predicate does not obtain with the value, the result
 425   /// is a folly::PredicateDoesNotObtain exception
 426   template <class F>
 427   Future<T> filter(F&& predicate);
 428
 429   /// Like reduce, but works on a Future<std::vector<T / Try<T>>>, for example
 430   /// the result of collect or collectAll
 431   template <class I, class F>
 432   Future<I> reduce(I&& initial, F&& func);
 433
 434   /// Create a Future chain from a sequence of callbacks. i.e.
 435   ///
 436   ///   f.then(a).then(b).then(c)
 437   ///
 438   /// where f is a Future<A> and the result of the chain is a Future<D>
 439   /// becomes
 440   ///
 441   ///   f.thenMulti(a, b, c);
 442   template <class Callback, class... Callbacks>
 443   auto thenMulti(Callback&& fn, Callbacks&&... fns) {
 444     // thenMulti with two callbacks is just then(a).thenMulti(b, ...)
 445     return then(std::forward<Callback>(fn))
 446         .thenMulti(std::forward<Callbacks>(fns)...);
 447   }
 448
 449   template <class Callback>
 450   auto thenMulti(Callback&& fn) {
 451     // thenMulti with one callback is just a then
 452     return then(std::forward<Callback>(fn));
 453   }
 454
 455   /// Create a Future chain from a sequence of callbacks. i.e.
 456   ///
 457   ///   f.via(executor).then(a).then(b).then(c).via(oldExecutor)
 458   ///
 459   /// where f is a Future<A> and the result of the chain is a Future<D>
 460   /// becomes
 461   ///
 462   ///   f.thenMultiWithExecutor(executor, a, b, c);
 463   template <class Callback, class... Callbacks>
 464   auto thenMultiWithExecutor(Executor* x, Callback&& fn, Callbacks&&... fns) {
 465     // thenMultiExecutor with two callbacks is
 466     // via(x).then(a).thenMulti(b, ...).via(oldX)
 467     auto oldX = getExecutor();
 468     setExecutor(x);
 469     return then(std::forward<Callback>(fn))
 470         .thenMulti(std::forward<Callbacks>(fns)...)
 471         .via(oldX);
 472   }
 473
 474   template <class Callback>
 475   auto thenMultiWithExecutor(Executor* x, Callback&& fn) {
 476     // thenMulti with one callback is just a then with an executor
 477     return then(x, std::forward<Callback>(fn));
 478   }
 479
 480   /// Discard a result, but propagate an exception.
 481   Future<Unit> unit() {
 482     return then([]{ return Unit{}; });
 483   }
 484
 485  protected:
 486   typedef futures::detail::Core<T>* corePtr;
 487
 488   // shared core state object
 489   corePtr core_;
 490
 491   explicit
 492   Future(corePtr obj) : core_(obj) {}
 493
 494   explicit Future(futures::detail::EmptyConstruct) noexcept;
 495
 496   void detach();
 497
 498   void throwIfInvalid() const;
 499
 500   friend class Promise<T>;
 501   template <class> friend class Future;
 502
 503   template <class T2>
 504   friend Future<T2> makeFuture(Try<T2>&&);
 505
 506   /// Repeat the given future (i.e., the computation it contains)
 507   /// n times.
 508   ///
 509   /// thunk behaves like std::function<Future<T2>(void)>
 510   template <class F>
 511   friend Future<Unit> times(int n, F&& thunk);
 512
 513   /// Carry out the computation contained in the given future if
 514   /// the predicate holds.
 515   ///
 516   /// thunk behaves like std::function<Future<T2>(void)>
 517   template <class F>
 518   friend Future<Unit> when(bool p, F&& thunk);
 519
 520   /// Carry out the computation contained in the given future if
 521   /// while the predicate continues to hold.
 522   ///
 523   /// thunk behaves like std::function<Future<T2>(void)>
 524   ///
 525   /// predicate behaves like std::function<bool(void)>
 526   template <class P, class F>
 527   friend Future<Unit> whileDo(P&& predicate, F&& thunk);
 528
 529   // Variant: returns a value
 530   // e.g. f.then([](Try<T> t){ return t.value(); });
 531   template <typename F, typename R, bool isTry, typename... Args>
 532   typename std::enable_if<!R::ReturnsFuture::value, typename R::Return>::type
 533   thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
 534
 535   // Variant: returns a Future
 536   // e.g. f.then([](Try<T> t){ return makeFuture<T>(t); });
 537   template <typename F, typename R, bool isTry, typename... Args>
 538   typename std::enable_if<R::ReturnsFuture::value, typename R::Return>::type
 539   thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
 540
 541   Executor* getExecutor() { return core_->getExecutor(); }
 542   void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
 543     core_->setExecutor(x, priority);
 544   }
 545 };
 546
 547 } // folly
 548
 549 #include <folly/futures/Future-inl.h>