2 * Copyright 2017 Facebook, Inc.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
23 #include <type_traits>
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>
36 // boring predeclarations and details
37 #include <folly/futures/Future-pre.h>
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>
58 /// Construct a Future from a value (perfect forwarding)
61 typename = typename std::enable_if<
62 !isFuture<typename std::decay<T2>::type>::value>::type>
63 /* implicit */ FutureBase(T2&& val);
65 template <class T2 = T>
66 /* implicit */ FutureBase(
67 typename std::enable_if<std::is_same<Unit, T2>::value>::type*);
71 typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
73 explicit FutureBase(in_place_t, Args&&... args);
75 FutureBase(FutureBase<T> const&) = delete;
76 FutureBase(SemiFuture<T>&&) noexcept;
77 FutureBase(Future<T>&&) noexcept;
80 FutureBase(Future<T> const&) = delete;
81 FutureBase(SemiFuture<T> const&) = delete;
85 /// Returns a reference to the result, with a reference category and const-
86 /// qualification equivalent to the reference category and const-qualification
89 /// If moved-from, throws NoState.
91 /// If !isReady(), throws FutureNotReady.
93 /// If an exception has been captured, throws that exception.
95 T const& value() const&;
97 T const&& value() const&&;
99 /** True when the result (or exception) is ready. */
100 bool isReady() const;
102 /// sugar for getTry().hasValue()
105 /// sugar for getTry().hasException()
108 /** A reference to the Try of the value */
111 /// If the promise has been fulfilled, return an Optional with the Try<T>.
112 /// Otherwise return an empty Optional.
113 /// Note that this moves the Try<T> out.
114 Optional<Try<T>> poll();
116 /// This is not the method you're looking for.
118 /// This needs to be public because it's used by make* and when*, and it's
119 /// not worth listing all those and their fancy template signatures as
120 /// friends. But it's not for public consumption.
122 void setCallback_(F&& func);
125 return core_->isActive();
129 void raise(E&& exception) {
130 raise(make_exception_wrapper<typename std::remove_reference<E>::type>(
131 std::forward<E>(exception)));
134 /// Raise an interrupt. If the promise holder has an interrupt
135 /// handler it will be called and potentially stop asynchronous work from
136 /// being done. This is advisory only - a promise holder may not set an
137 /// interrupt handler, or may do anything including ignore. But, if you know
138 /// your future supports this the most likely result is stopping or
139 /// preventing the asynchronous operation (if in time), and the promise
140 /// holder setting an exception on the future. (That may happen
141 /// asynchronously, of course.)
142 void raise(exception_wrapper interrupt);
145 raise(FutureCancellation());
149 friend class Promise<T>;
151 friend class SemiFuture;
155 using corePtr = futures::detail::Core<T>*;
157 // shared core state object
160 explicit FutureBase(corePtr obj) : core_(obj) {}
162 explicit FutureBase(futures::detail::EmptyConstruct) noexcept;
166 void throwIfInvalid() const;
168 template <class FutureType>
169 void assign(FutureType&) noexcept;
171 Executor* getExecutor() {
172 return core_->getExecutor();
175 void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
176 core_->setExecutor(x, priority);
179 // Variant: returns a value
180 // e.g. f.then([](Try<T> t){ return t.value(); });
181 template <typename F, typename R, bool isTry, typename... Args>
182 typename std::enable_if<!R::ReturnsFuture::value, typename R::Return>::type
183 thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
185 // Variant: returns a Future
186 // e.g. f.then([](Try<T> t){ return makeFuture<T>(t); });
187 template <typename F, typename R, bool isTry, typename... Args>
188 typename std::enable_if<R::ReturnsFuture::value, typename R::Return>::type
189 thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
191 } // namespace detail
192 } // namespace futures
195 class SemiFuture : private futures::detail::FutureBase<T> {
197 using Base = futures::detail::FutureBase<T>;
198 using DeferredExecutor = futures::detail::DeferredExecutor;
201 static SemiFuture<T> makeEmpty(); // equivalent to moved-from
203 // Export public interface of FutureBase
204 // FutureBase is inherited privately to avoid subclasses being cast to
205 // a FutureBase pointer
206 using typename Base::value_type;
208 /// Construct a Future from a value (perfect forwarding)
211 typename = typename std::enable_if<
212 !isFuture<typename std::decay<T2>::type>::value>::type>
213 /* implicit */ SemiFuture(T2&& val) : Base(std::forward<T2>(val)) {}
215 template <class T2 = T>
216 /* implicit */ SemiFuture(
217 typename std::enable_if<std::is_same<Unit, T2>::value>::type* p = nullptr)
222 typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
224 explicit SemiFuture(in_place_t, Args&&... args)
225 : Base(in_place, std::forward<Args>(args)...) {}
227 SemiFuture(SemiFuture<T> const&) = delete;
229 SemiFuture(SemiFuture<T>&&) noexcept;
230 // safe move-constructabilty from Future
231 /* implicit */ SemiFuture(Future<T>&&) noexcept;
235 using Base::hasException;
236 using Base::hasValue;
237 using Base::isActive;
241 using Base::setCallback_;
244 SemiFuture& operator=(SemiFuture const&) = delete;
245 SemiFuture& operator=(SemiFuture&&) noexcept;
246 SemiFuture& operator=(Future<T>&&) noexcept;
248 /// Block until the future is fulfilled. Returns the value (moved out), or
249 /// throws the exception. The future must not already have a callback.
252 /// Block until the future is fulfilled, or until timed out. Returns the
253 /// value (moved out), or throws the exception (which might be a TimedOut
255 T get(Duration dur) &&;
257 /// Block until this Future is complete. Returns a reference to this Future.
258 SemiFuture<T>& wait() &;
260 /// Overload of wait() for rvalue Futures
261 SemiFuture<T>&& wait() &&;
263 /// Block until this Future is complete or until the given Duration passes.
264 /// Returns a reference to this Future
265 SemiFuture<T>& wait(Duration) &;
267 /// Overload of wait(Duration) for rvalue Futures
268 SemiFuture<T>&& wait(Duration) &&;
270 /// Returns an inactive Future which will call back on the other side of
271 /// executor (when it is activated).
273 /// NB remember that Futures activate when they destruct. This is good,
274 /// it means that this will work:
276 /// f.via(e).then(a).then(b);
278 /// a and b will execute in the same context (the far side of e), because
279 /// the Future (temporary variable) created by via(e) does not call back
280 /// until it destructs, which is after then(a) and then(b) have been wired
283 /// But this is still racy:
285 /// f = f.via(e).then(a);
287 // The ref-qualifier allows for `this` to be moved out so we
288 // don't get access-after-free situations in chaining.
289 // https://akrzemi1.wordpress.com/2014/06/02/ref-qualifiers/
290 inline Future<T> via(
292 int8_t priority = Executor::MID_PRI) &&;
295 * Defer work to run on the consumer of the future.
296 * This work will be run eithe ron an executor that the caller sets on the
297 * SemiFuture, or inline with the call to .get().
298 * NB: This is a custom method because boost-blocking executors is a
299 * special-case for work deferral in folly. With more general boost-blocking
300 * support all executors would boost block and we would simply use some form
301 * of driveable executor here.
303 template <typename F>
304 SemiFuture<typename futures::detail::callableResult<T, F>::Return::value_type>
307 // Public as for setCallback_
308 // Ensure that a boostable executor performs work to chain deferred work
314 friend class futures::detail::FutureBase;
316 friend class SemiFuture;
318 using typename Base::corePtr;
319 using Base::setExecutor;
320 using Base::throwIfInvalid;
323 friend SemiFuture<T2> makeSemiFuture(Try<T2>&&);
325 explicit SemiFuture(corePtr obj) : Base(obj) {}
327 explicit SemiFuture(futures::detail::EmptyConstruct) noexcept
328 : Base(futures::detail::EmptyConstruct{}) {}
332 class Future : private futures::detail::FutureBase<T> {
334 using Base = futures::detail::FutureBase<T>;
337 // Export public interface of FutureBase
338 // FutureBase is inherited privately to avoid subclasses being cast to
339 // a FutureBase pointer
340 using typename Base::value_type;
342 /// Construct a Future from a value (perfect forwarding)
345 typename = typename std::enable_if<
346 !isFuture<typename std::decay<T2>::type>::value>::type>
347 /* implicit */ Future(T2&& val) : Base(std::forward<T2>(val)) {}
349 template <class T2 = T>
350 /* implicit */ Future(
351 typename std::enable_if<std::is_same<Unit, T2>::value>::type* p = nullptr)
356 typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
358 explicit Future(in_place_t, Args&&... args)
359 : Base(in_place, std::forward<Args>(args)...) {}
361 Future(Future<T> const&) = delete;
363 Future(Future<T>&&) noexcept;
368 typename std::enable_if<
369 !std::is_same<T, typename std::decay<T2>::type>::value &&
370 std::is_constructible<T, T2&&>::value &&
371 std::is_convertible<T2&&, T>::value,
373 /* implicit */ Future(Future<T2>&&);
376 typename std::enable_if<
377 !std::is_same<T, typename std::decay<T2>::type>::value &&
378 std::is_constructible<T, T2&&>::value &&
379 !std::is_convertible<T2&&, T>::value,
381 explicit Future(Future<T2>&&);
384 typename std::enable_if<
385 !std::is_same<T, typename std::decay<T2>::type>::value &&
386 std::is_constructible<T, T2&&>::value,
388 Future& operator=(Future<T2>&&);
392 using Base::hasException;
393 using Base::hasValue;
394 using Base::isActive;
398 using Base::setCallback_;
401 static Future<T> makeEmpty(); // equivalent to moved-from
404 Future& operator=(Future const&) = delete;
407 Future& operator=(Future&&) noexcept;
409 /// Call e->drive() repeatedly until the future is fulfilled. Examples
410 /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
411 /// reference to the Try of the value.
412 Try<T>& getTryVia(DrivableExecutor* e);
414 /// Call e->drive() repeatedly until the future is fulfilled. Examples
415 /// of DrivableExecutor include EventBase and ManualExecutor. Returns the
416 /// value (moved out), or throws the exception.
417 T getVia(DrivableExecutor* e);
419 /// Unwraps the case of a Future<Future<T>> instance, and returns a simple
420 /// Future<T> instance.
421 template <class F = T>
423 enable_if<isFuture<F>::value, Future<typename isFuture<T>::Inner>>::type
426 /// Returns an inactive Future which will call back on the other side of
427 /// executor (when it is activated).
429 /// NB remember that Futures activate when they destruct. This is good,
430 /// it means that this will work:
432 /// f.via(e).then(a).then(b);
434 /// a and b will execute in the same context (the far side of e), because
435 /// the Future (temporary variable) created by via(e) does not call back
436 /// until it destructs, which is after then(a) and then(b) have been wired
439 /// But this is still racy:
441 /// f = f.via(e).then(a);
443 // The ref-qualifier allows for `this` to be moved out so we
444 // don't get access-after-free situations in chaining.
445 // https://akrzemi1.wordpress.com/2014/06/02/ref-qualifiers/
446 inline Future<T> via(
448 int8_t priority = Executor::MID_PRI) &&;
450 /// This variant creates a new future, where the ref-qualifier && version
451 /// moves `this` out. This one is less efficient but avoids confusing users
452 /// when "return f.via(x);" fails.
453 inline Future<T> via(
455 int8_t priority = Executor::MID_PRI) &;
457 /** When this Future has completed, execute func which is a function that
467 Func shall return either another Future or a value.
469 A Future for the return type of func is returned.
471 Future<string> f2 = f1.then([](Try<T>&&) { return string("foo"); });
473 The Future given to the functor is ready, and the functor may call
474 value(), which may rethrow if this has captured an exception. If func
475 throws, the exception will be captured in the Future that is returned.
477 template <typename F, typename R = futures::detail::callableResult<T, F>>
478 typename R::Return then(F&& func) {
479 return this->template thenImplementation<F, R>(
480 std::forward<F>(func), typename R::Arg());
483 /// Variant where func is an member function
485 /// struct Worker { R doWork(Try<T>); }
488 /// Future<R> f2 = f1.then(&Worker::doWork, w);
490 /// This is just sugar for
492 /// f1.then(std::bind(&Worker::doWork, w));
493 template <typename R, typename Caller, typename... Args>
494 Future<typename isFuture<R>::Inner> then(
495 R (Caller::*func)(Args...),
498 /// Execute the callback via the given Executor. The executor doesn't stick.
502 /// f.via(x).then(b).then(c)
506 /// f.then(x, b).then(c)
508 /// In the former both b and c execute via x. In the latter, only b executes
509 /// via x, and c executes via the same executor (if any) that f had.
510 template <class Executor, class Arg, class... Args>
511 auto then(Executor* x, Arg&& arg, Args&&... args) {
512 auto oldX = this->getExecutor();
513 this->setExecutor(x);
514 return this->then(std::forward<Arg>(arg), std::forward<Args>(args)...)
518 /// Convenience method for ignoring the value and creating a Future<Unit>.
519 /// Exceptions still propagate.
520 /// This function is identical to .unit().
523 /// Convenience method for ignoring the value and creating a Future<Unit>.
524 /// Exceptions still propagate.
525 /// This function is identical to parameterless .then().
526 Future<Unit> unit() {
530 /// Set an error callback for this Future. The callback should take a single
531 /// argument of the type that you want to catch, and should return a value of
532 /// the same type as this Future, or a Future of that type (see overload
533 /// below). For instance,
537 /// throw std::runtime_error("oh no!");
540 /// .onError([] (std::runtime_error& e) {
541 /// LOG(INFO) << "std::runtime_error: " << e.what();
542 /// return -1; // or makeFuture<int>(-1)
545 typename std::enable_if<
546 !futures::detail::callableWith<F, exception_wrapper>::value &&
547 !futures::detail::callableWith<F, exception_wrapper&>::value &&
548 !futures::detail::Extract<F>::ReturnsFuture::value,
552 /// Overload of onError where the error callback returns a Future<T>
554 typename std::enable_if<
555 !futures::detail::callableWith<F, exception_wrapper>::value &&
556 !futures::detail::callableWith<F, exception_wrapper&>::value &&
557 futures::detail::Extract<F>::ReturnsFuture::value,
561 /// Overload of onError that takes exception_wrapper and returns Future<T>
563 typename std::enable_if<
564 futures::detail::callableWith<F, exception_wrapper>::value &&
565 futures::detail::Extract<F>::ReturnsFuture::value,
569 /// Overload of onError that takes exception_wrapper and returns T
571 typename std::enable_if<
572 futures::detail::callableWith<F, exception_wrapper>::value &&
573 !futures::detail::Extract<F>::ReturnsFuture::value,
577 /// func is like std::function<void()> and is executed unconditionally, and
578 /// the value/exception is passed through to the resulting Future.
579 /// func shouldn't throw, but if it does it will be captured and propagated,
580 /// and discard any value/exception that this Future has obtained.
582 Future<T> ensure(F&& func);
584 /// Like onError, but for timeouts. example:
586 /// Future<int> f = makeFuture<int>(42)
587 /// .delayed(long_time)
588 /// .onTimeout(short_time,
589 /// []() -> int{ return -1; });
593 /// Future<int> f = makeFuture<int>(42)
594 /// .delayed(long_time)
595 /// .onTimeout(short_time,
596 /// []() { return makeFuture<int>(some_exception); });
598 Future<T> onTimeout(Duration, F&& func, Timekeeper* = nullptr);
600 /// A Future's callback is executed when all three of these conditions have
601 /// become true: it has a value (set by the Promise), it has a callback (set
602 /// by then), and it is active (active by default).
604 /// Inactive Futures will activate upon destruction.
605 FOLLY_DEPRECATED("do not use") Future<T>& activate() & {
606 this->core_->activate();
609 FOLLY_DEPRECATED("do not use") Future<T>& deactivate() & {
610 this->core_->deactivate();
613 FOLLY_DEPRECATED("do not use") Future<T> activate() && {
614 this->core_->activate();
615 return std::move(*this);
617 FOLLY_DEPRECATED("do not use") Future<T> deactivate() && {
618 this->core_->deactivate();
619 return std::move(*this);
622 /// Throw TimedOut if this Future does not complete within the given
623 /// duration from now. The optional Timeekeeper is as with futures::sleep().
624 Future<T> within(Duration, Timekeeper* = nullptr);
626 /// Throw the given exception if this Future does not complete within the
627 /// given duration from now. The optional Timeekeeper is as with
628 /// futures::sleep().
630 Future<T> within(Duration, E exception, Timekeeper* = nullptr);
632 /// Delay the completion of this Future for at least this duration from
633 /// now. The optional Timekeeper is as with futures::sleep().
634 Future<T> delayed(Duration, Timekeeper* = nullptr);
636 /// Block until the future is fulfilled. Returns the value (moved out), or
637 /// throws the exception. The future must not already have a callback.
640 /// Block until the future is fulfilled, or until timed out. Returns the
641 /// value (moved out), or throws the exception (which might be a TimedOut
645 /// Block until this Future is complete. Returns a reference to this Future.
648 /// Overload of wait() for rvalue Futures
649 Future<T>&& wait() &&;
651 /// Block until this Future is complete or until the given Duration passes.
652 /// Returns a reference to this Future
653 Future<T>& wait(Duration) &;
655 /// Overload of wait(Duration) for rvalue Futures
656 Future<T>&& wait(Duration) &&;
658 /// Call e->drive() repeatedly until the future is fulfilled. Examples
659 /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
660 /// reference to this Future so that you can chain calls if desired.
661 /// value (moved out), or throws the exception.
662 Future<T>& waitVia(DrivableExecutor* e) &;
664 /// Overload of waitVia() for rvalue Futures
665 Future<T>&& waitVia(DrivableExecutor* e) &&;
667 /// If the value in this Future is equal to the given Future, when they have
668 /// both completed, the value of the resulting Future<bool> will be true. It
669 /// will be false otherwise (including when one or both Futures have an
671 Future<bool> willEqual(Future<T>&);
673 /// predicate behaves like std::function<bool(T const&)>
674 /// If the predicate does not obtain with the value, the result
675 /// is a folly::PredicateDoesNotObtain exception
677 Future<T> filter(F&& predicate);
679 /// Like reduce, but works on a Future<std::vector<T / Try<T>>>, for example
680 /// the result of collect or collectAll
681 template <class I, class F>
682 Future<I> reduce(I&& initial, F&& func);
684 /// Create a Future chain from a sequence of callbacks. i.e.
686 /// f.then(a).then(b).then(c)
688 /// where f is a Future<A> and the result of the chain is a Future<D>
691 /// f.thenMulti(a, b, c);
692 template <class Callback, class... Callbacks>
693 auto thenMulti(Callback&& fn, Callbacks&&... fns) {
694 // thenMulti with two callbacks is just then(a).thenMulti(b, ...)
695 return then(std::forward<Callback>(fn))
696 .thenMulti(std::forward<Callbacks>(fns)...);
699 template <class Callback>
700 auto thenMulti(Callback&& fn) {
701 // thenMulti with one callback is just a then
702 return then(std::forward<Callback>(fn));
705 /// Create a Future chain from a sequence of callbacks. i.e.
707 /// f.via(executor).then(a).then(b).then(c).via(oldExecutor)
709 /// where f is a Future<A> and the result of the chain is a Future<D>
712 /// f.thenMultiWithExecutor(executor, a, b, c);
713 template <class Callback, class... Callbacks>
714 auto thenMultiWithExecutor(Executor* x, Callback&& fn, Callbacks&&... fns) {
715 // thenMultiExecutor with two callbacks is
716 // via(x).then(a).thenMulti(b, ...).via(oldX)
717 auto oldX = this->getExecutor();
718 this->setExecutor(x);
719 return then(std::forward<Callback>(fn))
720 .thenMulti(std::forward<Callbacks>(fns)...)
724 template <class Callback>
725 auto thenMultiWithExecutor(Executor* x, Callback&& fn) {
726 // thenMulti with one callback is just a then with an executor
727 return then(x, std::forward<Callback>(fn));
730 // Convert this Future to a SemiFuture to safely export from a library
731 // without exposing a continuation interface
732 SemiFuture<T> semi() {
733 return SemiFuture<T>{std::move(*this)};
737 friend class Promise<T>;
739 friend class futures::detail::FutureBase;
743 friend class SemiFuture;
745 using Base::setExecutor;
746 using Base::throwIfInvalid;
747 using typename Base::corePtr;
749 explicit Future(corePtr obj) : Base(obj) {}
751 explicit Future(futures::detail::EmptyConstruct) noexcept
752 : Base(futures::detail::EmptyConstruct{}) {}
755 friend Future<T2> makeFuture(Try<T2>&&);
757 /// Repeat the given future (i.e., the computation it contains)
760 /// thunk behaves like std::function<Future<T2>(void)>
762 friend Future<Unit> times(int n, F&& thunk);
764 /// Carry out the computation contained in the given future if
765 /// the predicate holds.
767 /// thunk behaves like std::function<Future<T2>(void)>
769 friend Future<Unit> when(bool p, F&& thunk);
771 /// Carry out the computation contained in the given future if
772 /// while the predicate continues to hold.
774 /// thunk behaves like std::function<Future<T2>(void)>
776 /// predicate behaves like std::function<bool(void)>
777 template <class P, class F>
778 friend Future<Unit> whileDo(P&& predicate, F&& thunk);
783 #include <folly/futures/Future-inl.h>