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 &&
63 !isSemiFuture<typename std::decay<T2>::type>::value>::type>
64 /* implicit */ FutureBase(T2&& val);
66 template <class T2 = T>
67 /* implicit */ FutureBase(
68 typename std::enable_if<std::is_same<Unit, T2>::value>::type*);
72 typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
74 explicit FutureBase(in_place_t, Args&&... args);
76 FutureBase(FutureBase<T> const&) = delete;
77 FutureBase(SemiFuture<T>&&) noexcept;
78 FutureBase(Future<T>&&) noexcept;
81 FutureBase(Future<T> const&) = delete;
82 FutureBase(SemiFuture<T> const&) = delete;
86 /// Returns a reference to the result, with a reference category and const-
87 /// qualification equivalent to the reference category and const-qualification
90 /// If moved-from, throws NoState.
92 /// If !isReady(), throws FutureNotReady.
94 /// If an exception has been captured, throws that exception.
96 T const& value() const&;
98 T const&& value() const&&;
100 /** True when the result (or exception) is ready. */
101 bool isReady() const;
103 /// sugar for getTry().hasValue()
106 /// sugar for getTry().hasException()
109 /// If the promise has been fulfilled, return an Optional with the Try<T>.
110 /// Otherwise return an empty Optional.
111 /// Note that this moves the Try<T> out.
112 Optional<Try<T>> poll();
114 /// This is not the method you're looking for.
116 /// This needs to be public because it's used by make* and when*, and it's
117 /// not worth listing all those and their fancy template signatures as
118 /// friends. But it's not for public consumption.
120 void setCallback_(F&& func);
123 return core_->isActive();
127 void raise(E&& exception) {
128 raise(make_exception_wrapper<typename std::remove_reference<E>::type>(
129 std::forward<E>(exception)));
132 /// Raise an interrupt. If the promise holder has an interrupt
133 /// handler it will be called and potentially stop asynchronous work from
134 /// being done. This is advisory only - a promise holder may not set an
135 /// interrupt handler, or may do anything including ignore. But, if you know
136 /// your future supports this the most likely result is stopping or
137 /// preventing the asynchronous operation (if in time), and the promise
138 /// holder setting an exception on the future. (That may happen
139 /// asynchronously, of course.)
140 void raise(exception_wrapper interrupt);
143 raise(FutureCancellation());
147 friend class Promise<T>;
149 friend class SemiFuture;
153 using corePtr = futures::detail::Core<T>*;
155 // shared core state object
158 explicit FutureBase(corePtr obj) : core_(obj) {}
160 explicit FutureBase(futures::detail::EmptyConstruct) noexcept;
164 void throwIfInvalid() const;
166 template <class FutureType>
167 void assign(FutureType&) noexcept;
169 Executor* getExecutor() {
170 return core_->getExecutor();
173 void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
174 core_->setExecutor(x, priority);
177 // Variant: returns a value
178 // e.g. f.then([](Try<T> t){ return t.value(); });
179 template <typename F, typename R, bool isTry, typename... Args>
180 typename std::enable_if<!R::ReturnsFuture::value, typename R::Return>::type
181 thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
183 // Variant: returns a Future
184 // e.g. f.then([](Try<T> t){ return makeFuture<T>(t); });
185 template <typename F, typename R, bool isTry, typename... Args>
186 typename std::enable_if<R::ReturnsFuture::value, typename R::Return>::type
187 thenImplementation(F&& func, futures::detail::argResult<isTry, F, Args...>);
189 } // namespace detail
190 } // namespace futures
193 class SemiFuture : private futures::detail::FutureBase<T> {
195 using Base = futures::detail::FutureBase<T>;
196 using DeferredExecutor = futures::detail::DeferredExecutor;
199 static SemiFuture<T> makeEmpty(); // equivalent to moved-from
201 // Export public interface of FutureBase
202 // FutureBase is inherited privately to avoid subclasses being cast to
203 // a FutureBase pointer
204 using typename Base::value_type;
206 /// Construct a Future from a value (perfect forwarding)
209 typename = typename std::enable_if<
210 !isFuture<typename std::decay<T2>::type>::value &&
211 !isSemiFuture<typename std::decay<T2>::type>::value>::type>
212 /* implicit */ SemiFuture(T2&& val) : Base(std::forward<T2>(val)) {}
214 template <class T2 = T>
215 /* implicit */ SemiFuture(
216 typename std::enable_if<std::is_same<Unit, T2>::value>::type* p = nullptr)
221 typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
223 explicit SemiFuture(in_place_t, Args&&... args)
224 : Base(in_place, std::forward<Args>(args)...) {}
226 SemiFuture(SemiFuture<T> const&) = delete;
228 SemiFuture(SemiFuture<T>&&) noexcept;
229 // safe move-constructabilty from Future
230 /* implicit */ SemiFuture(Future<T>&&) noexcept;
233 using Base::hasException;
234 using Base::hasValue;
235 using Base::isActive;
239 using Base::setCallback_;
242 SemiFuture& operator=(SemiFuture const&) = delete;
243 SemiFuture& operator=(SemiFuture&&) noexcept;
244 SemiFuture& operator=(Future<T>&&) noexcept;
246 /// Block until the future is fulfilled. Returns the value (moved out), or
247 /// throws the exception. The future must not already have a callback.
250 /// Block until the future is fulfilled, or until timed out. Returns the
251 /// value (moved out), or throws the exception (which might be a TimedOut
253 T get(Duration dur) &&;
255 /// Block until the future is fulfilled, or until timed out. Returns the
256 /// Try of the value (moved out).
259 /// Block until this Future is complete. Returns a reference to this Future.
260 SemiFuture<T>& wait() &;
262 /// Overload of wait() for rvalue Futures
263 SemiFuture<T>&& wait() &&;
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) &;
269 /// Overload of wait(Duration) for rvalue Futures
270 SemiFuture<T>&& wait(Duration) &&;
272 /// Returns an inactive Future which will call back on the other side of
273 /// executor (when it is activated).
275 /// NB remember that Futures activate when they destruct. This is good,
276 /// it means that this will work:
278 /// f.via(e).then(a).then(b);
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
285 /// But this is still racy:
287 /// f = f.via(e).then(a);
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(
294 int8_t priority = Executor::MID_PRI) &&;
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.
305 template <typename F>
306 SemiFuture<typename futures::detail::callableResult<T, F>::Return::value_type>
309 // Public as for setCallback_
310 // Ensure that a boostable executor performs work to chain deferred work
315 friend class Promise<T>;
317 friend class futures::detail::FutureBase;
319 friend class SemiFuture;
321 using typename Base::corePtr;
322 using Base::setExecutor;
323 using Base::throwIfInvalid;
326 friend SemiFuture<T2> makeSemiFuture(Try<T2>&&);
328 explicit SemiFuture(corePtr obj) : Base(obj) {}
330 explicit SemiFuture(futures::detail::EmptyConstruct) noexcept
331 : Base(futures::detail::EmptyConstruct{}) {}
335 class Future : private futures::detail::FutureBase<T> {
337 using Base = futures::detail::FutureBase<T>;
340 // Export public interface of FutureBase
341 // FutureBase is inherited privately to avoid subclasses being cast to
342 // a FutureBase pointer
343 using typename Base::value_type;
345 /// Construct a Future from a value (perfect forwarding)
348 typename = typename std::enable_if<
349 !isFuture<typename std::decay<T2>::type>::value &&
350 !isSemiFuture<typename std::decay<T2>::type>::value>::type>
351 /* implicit */ Future(T2&& val) : Base(std::forward<T2>(val)) {}
353 template <class T2 = T>
354 /* implicit */ Future(
355 typename std::enable_if<std::is_same<Unit, T2>::value>::type* p = nullptr)
360 typename std::enable_if<std::is_constructible<T, Args&&...>::value, int>::
362 explicit Future(in_place_t, Args&&... args)
363 : Base(in_place, std::forward<Args>(args)...) {}
365 Future(Future<T> const&) = delete;
367 Future(Future<T>&&) noexcept;
372 typename std::enable_if<
373 !std::is_same<T, typename std::decay<T2>::type>::value &&
374 std::is_constructible<T, T2&&>::value &&
375 std::is_convertible<T2&&, T>::value,
377 /* implicit */ Future(Future<T2>&&);
380 typename std::enable_if<
381 !std::is_same<T, typename std::decay<T2>::type>::value &&
382 std::is_constructible<T, T2&&>::value &&
383 !std::is_convertible<T2&&, T>::value,
385 explicit Future(Future<T2>&&);
388 typename std::enable_if<
389 !std::is_same<T, typename std::decay<T2>::type>::value &&
390 std::is_constructible<T, T2&&>::value,
392 Future& operator=(Future<T2>&&);
395 using Base::hasException;
396 using Base::hasValue;
397 using Base::isActive;
401 using Base::setCallback_;
404 static Future<T> makeEmpty(); // equivalent to moved-from
407 Future& operator=(Future const&) = delete;
410 Future& operator=(Future&&) noexcept;
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);
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);
422 /// Unwraps the case of a Future<Future<T>> instance, and returns a simple
423 /// Future<T> instance.
424 template <class F = T>
426 enable_if<isFuture<F>::value, Future<typename isFuture<T>::Inner>>::type
429 /// Returns an inactive Future which will call back on the other side of
430 /// executor (when it is activated).
432 /// NB remember that Futures activate when they destruct. This is good,
433 /// it means that this will work:
435 /// f.via(e).then(a).then(b);
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
442 /// But this is still racy:
444 /// f = f.via(e).then(a);
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(
451 int8_t priority = Executor::MID_PRI) &&;
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(
458 int8_t priority = Executor::MID_PRI) &;
460 /** When this Future has completed, execute func which is a function that
470 Func shall return either another Future or a value.
472 A Future for the return type of func is returned.
474 Future<string> f2 = f1.then([](Try<T>&&) { return string("foo"); });
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.
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());
486 /// Variant where func is an member function
488 /// struct Worker { R doWork(Try<T>); }
491 /// Future<R> f2 = f1.then(&Worker::doWork, w);
493 /// This is just sugar for
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...),
501 /// Execute the callback via the given Executor. The executor doesn't stick.
505 /// f.via(x).then(b).then(c)
509 /// f.then(x, b).then(c)
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)...)
521 /// Convenience method for ignoring the value and creating a Future<Unit>.
522 /// Exceptions still propagate.
523 /// This function is identical to .unit().
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() {
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,
540 /// throw std::runtime_error("oh no!");
543 /// .onError([] (std::runtime_error& e) {
544 /// LOG(INFO) << "std::runtime_error: " << e.what();
545 /// return -1; // or makeFuture<int>(-1)
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,
555 /// Overload of onError where the error callback returns a Future<T>
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,
564 /// Overload of onError that takes exception_wrapper and returns Future<T>
566 typename std::enable_if<
567 futures::detail::callableWith<F, exception_wrapper>::value &&
568 futures::detail::Extract<F>::ReturnsFuture::value,
572 /// Overload of onError that takes exception_wrapper and returns T
574 typename std::enable_if<
575 futures::detail::callableWith<F, exception_wrapper>::value &&
576 !futures::detail::Extract<F>::ReturnsFuture::value,
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.
585 Future<T> ensure(F&& func);
587 /// Like onError, but for timeouts. example:
589 /// Future<int> f = makeFuture<int>(42)
590 /// .delayed(long_time)
591 /// .onTimeout(short_time,
592 /// []() -> int{ return -1; });
596 /// Future<int> f = makeFuture<int>(42)
597 /// .delayed(long_time)
598 /// .onTimeout(short_time,
599 /// []() { return makeFuture<int>(some_exception); });
601 Future<T> onTimeout(Duration, F&& func, Timekeeper* = nullptr);
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).
607 /// Inactive Futures will activate upon destruction.
608 FOLLY_DEPRECATED("do not use") Future<T>& activate() & {
609 this->core_->activate();
612 FOLLY_DEPRECATED("do not use") Future<T>& deactivate() & {
613 this->core_->deactivate();
616 FOLLY_DEPRECATED("do not use") Future<T> activate() && {
617 this->core_->activate();
618 return std::move(*this);
620 FOLLY_DEPRECATED("do not use") Future<T> deactivate() && {
621 this->core_->deactivate();
622 return std::move(*this);
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);
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().
633 Future<T> within(Duration, E exception, Timekeeper* = nullptr);
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);
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.
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
648 /** A reference to the Try of the value */
651 /// Block until this Future is complete. Returns a reference to this Future.
654 /// Overload of wait() for rvalue Futures
655 Future<T>&& wait() &&;
657 /// Block until this Future is complete or until the given Duration passes.
658 /// Returns a reference to this Future
659 Future<T>& wait(Duration) &;
661 /// Overload of wait(Duration) for rvalue Futures
662 Future<T>&& wait(Duration) &&;
664 /// Call e->drive() repeatedly until the future is fulfilled. Examples
665 /// of DrivableExecutor include EventBase and ManualExecutor. Returns a
666 /// reference to this Future so that you can chain calls if desired.
667 /// value (moved out), or throws the exception.
668 Future<T>& waitVia(DrivableExecutor* e) &;
670 /// Overload of waitVia() for rvalue Futures
671 Future<T>&& waitVia(DrivableExecutor* e) &&;
673 /// If the value in this Future is equal to the given Future, when they have
674 /// both completed, the value of the resulting Future<bool> will be true. It
675 /// will be false otherwise (including when one or both Futures have an
677 Future<bool> willEqual(Future<T>&);
679 /// predicate behaves like std::function<bool(T const&)>
680 /// If the predicate does not obtain with the value, the result
681 /// is a folly::PredicateDoesNotObtain exception
683 Future<T> filter(F&& predicate);
685 /// Like reduce, but works on a Future<std::vector<T / Try<T>>>, for example
686 /// the result of collect or collectAll
687 template <class I, class F>
688 Future<I> reduce(I&& initial, F&& func);
690 /// Create a Future chain from a sequence of callbacks. i.e.
692 /// f.then(a).then(b).then(c)
694 /// where f is a Future<A> and the result of the chain is a Future<D>
697 /// f.thenMulti(a, b, c);
698 template <class Callback, class... Callbacks>
699 auto thenMulti(Callback&& fn, Callbacks&&... fns) {
700 // thenMulti with two callbacks is just then(a).thenMulti(b, ...)
701 return then(std::forward<Callback>(fn))
702 .thenMulti(std::forward<Callbacks>(fns)...);
705 template <class Callback>
706 auto thenMulti(Callback&& fn) {
707 // thenMulti with one callback is just a then
708 return then(std::forward<Callback>(fn));
711 /// Create a Future chain from a sequence of callbacks. i.e.
713 /// f.via(executor).then(a).then(b).then(c).via(oldExecutor)
715 /// where f is a Future<A> and the result of the chain is a Future<D>
718 /// f.thenMultiWithExecutor(executor, a, b, c);
719 template <class Callback, class... Callbacks>
720 auto thenMultiWithExecutor(Executor* x, Callback&& fn, Callbacks&&... fns) {
721 // thenMultiExecutor with two callbacks is
722 // via(x).then(a).thenMulti(b, ...).via(oldX)
723 auto oldX = this->getExecutor();
724 this->setExecutor(x);
725 return then(std::forward<Callback>(fn))
726 .thenMulti(std::forward<Callbacks>(fns)...)
730 template <class Callback>
731 auto thenMultiWithExecutor(Executor* x, Callback&& fn) {
732 // thenMulti with one callback is just a then with an executor
733 return then(x, std::forward<Callback>(fn));
736 // Convert this Future to a SemiFuture to safely export from a library
737 // without exposing a continuation interface
738 SemiFuture<T> semi() {
739 return SemiFuture<T>{std::move(*this)};
743 friend class Promise<T>;
745 friend class futures::detail::FutureBase;
749 friend class SemiFuture;
751 using Base::setExecutor;
752 using Base::throwIfInvalid;
753 using typename Base::corePtr;
755 explicit Future(corePtr obj) : Base(obj) {}
757 explicit Future(futures::detail::EmptyConstruct) noexcept
758 : Base(futures::detail::EmptyConstruct{}) {}
761 friend Future<T2> makeFuture(Try<T2>&&);
763 /// Repeat the given future (i.e., the computation it contains)
766 /// thunk behaves like std::function<Future<T2>(void)>
768 friend Future<Unit> times(int n, F&& thunk);
770 /// Carry out the computation contained in the given future if
771 /// the predicate holds.
773 /// thunk behaves like std::function<Future<T2>(void)>
775 friend Future<Unit> when(bool p, F&& thunk);
777 /// Carry out the computation contained in the given future if
778 /// while the predicate continues to hold.
780 /// thunk behaves like std::function<Future<T2>(void)>
782 /// predicate behaves like std::function<bool(void)>
783 template <class P, class F>
784 friend Future<Unit> whileDo(P&& predicate, F&& thunk);
789 #include <folly/futures/Future-inl.h>