folly/wangle/Future.h

   1 /*
   2  * Copyright 2014 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
  25 #include "folly/MoveWrapper.h"
  26 #include "Promise.h"
  27 #include "Try.h"
  28
  29 namespace folly { namespace wangle {
  30
  31 template <typename T> struct isFuture;
  32
  33 template <class T>
  34 class Future {
  35  public:
  36   typedef T value_type;
  37
  38   // not copyable
  39   Future(Future const&) = delete;
  40   Future& operator=(Future const&) = delete;
  41
  42   // movable
  43   Future(Future&&);
  44   Future& operator=(Future&&);
  45
  46   ~Future();
  47
  48   /** Return the reference to result. Should not be called if !isReady().
  49     Will rethrow the exception if an exception has been
  50     captured.
  51
  52     This function is not thread safe - the returned Future can only
  53     be executed from the thread that the executor runs it in.
  54     See below for a thread safe version
  55     */
  56   typename std::add_lvalue_reference<T>::type
  57   value();
  58   typename std::add_lvalue_reference<const T>::type
  59   value() const;
  60
  61   template <typename Executor>
  62   Future<T> executeWithSameThread(Executor* executor);
  63
  64   /**
  65      Thread-safe version of executeWith
  66
  67      Since an executor would likely start executing the Future chain
  68      right away, it would be a race condition to call:
  69      Future.executeWith(...).then(...), as there would be race
  70      condition between the then and the running Future.
  71      Instead, you may pass in a Promise so that we can set up
  72      the rest of the chain in advance, without any racey
  73      modifications of the continuation
  74    */
  75   template <typename Executor>
  76   void executeWith(Executor* executor, Promise<T>&& cont_promise);
  77
  78   /** True when the result (or exception) is ready.  value() will not block
  79       when this returns true. */
  80   bool isReady() const;
  81
  82   Try<T>& valueTry();
  83
  84   /** When this Future has completed, execute func which is a function that
  85     takes a Try<T>&&. A Future for the return type of func is
  86     returned. e.g.
  87
  88     Future<string> f2 = f1.then([](Try<T>&&) { return string("foo"); });
  89
  90     The functor given may call value() without blocking, which may rethrow if
  91     this has captured an exception. If func throws, the exception will be
  92     captured in the Future that is returned.
  93     */
  94   /* n3428 has then(scheduler&, F&&), we might want to reorganize to use
  95      similar API. or maybe not */
  96   template <class F>
  97   typename std::enable_if<
  98     !isFuture<typename std::result_of<F(Try<T>&&)>::type>::value,
  99     Future<typename std::result_of<F(Try<T>&&)>::type> >::type
 100   then(F&& func);
 101
 102   template <class F>
 103   typename std::enable_if<
 104     isFuture<typename std::result_of<F(Try<T>&&)>::type>::value,
 105     Future<typename std::result_of<F(Try<T>&&)>::type::value_type> >::type
 106   then(F&& func);
 107
 108   /** Use this method on the Future when we don't really care about the
 109     returned value and want to convert the Future<T> to a Future<void>
 110     Convenience function
 111     */
 112   Future<void> then();
 113
 114   template <class F>
 115   void setContinuation(F&& func);
 116
 117  private:
 118   /* Eventually this may not be a shared_ptr, but something similar without
 119      expensive thread-safety. */
 120   typedef detail::FutureObject<T>* objPtr;
 121
 122   // shared state object
 123   objPtr obj_;
 124
 125   explicit
 126   Future(objPtr obj) : obj_(obj) {}
 127
 128   void throwIfInvalid() const;
 129
 130   friend class Promise<T>;
 131 };
 132
 133 /** Make a completed Future by moving in a value. e.g.
 134   auto f = makeFuture(string("foo"));
 135 */
 136 template <class T>
 137 Future<typename std::decay<T>::type> makeFuture(T&& t);
 138
 139 /** Make a completed void Future. */
 140 Future<void> makeFuture();
 141
 142 /** Make a completed Future by executing a function. If the function throws
 143   we capture the exception, otherwise we capture the result. */
 144 template <class F>
 145 auto makeFutureTry(
 146   F&& func,
 147   typename std::enable_if<
 148     !std::is_reference<F>::value, bool>::type sdf = false)
 149   -> Future<decltype(func())>;
 150
 151 template <class F>
 152 auto makeFutureTry(
 153   F const& func)
 154   -> Future<decltype(func())>;
 155
 156 /** Make a completed (error) Future from an exception_ptr. Because the type
 157 can't be inferred you have to give it, e.g.
 158
 159 auto f = makeFuture<string>(std::current_exception());
 160 */
 161 template <class T>
 162 Future<T> makeFuture(std::exception_ptr const& e);
 163
 164 /** Make a Future from an exception type E that can be passed to
 165   std::make_exception_ptr(). */
 166 template <class T, class E>
 167 typename std::enable_if<std::is_base_of<std::exception, E>::value, Future<T>>::type
 168 makeFuture(E const& e);
 169
 170 /** When all the input Futures complete, the returned Future will complete.
 171   Errors do not cause early termination; this Future will always succeed
 172   after all its Futures have finished (whether successfully or with an
 173   error).
 174
 175   The Futures are moved in, so your copies are invalid. If you need to
 176   chain further from these Futures, use the variant with an output iterator.
 177
 178   This function is thread-safe for Futures running on different threads.
 179
 180   The return type for Future<T> input is a Future<vector<Try<T>>>
 181   */
 182 template <class InputIterator>
 183 Future<std::vector<Try<
 184   typename std::iterator_traits<InputIterator>::value_type::value_type>>>
 185 whenAll(InputIterator first, InputIterator last);
 186
 187 /** This version takes a varying number of Futures instead of an iterator.
 188   The return type for (Future<T1>, Future<T2>, ...) input
 189   is a Future<tuple<Try<T1>, Try<T2>, ...>>.
 190   */
 191 template <typename... Fs>
 192 typename detail::VariadicContext<typename Fs::value_type...>::type
 193 whenAll(Fs&... fs);
 194
 195 /** The result is a pair of the index of the first Future to complete and
 196   the Try. If multiple Futures complete at the same time (or are already
 197   complete when passed in), the "winner" is chosen non-deterministically.
 198
 199   This function is thread-safe for Futures running on different threads.
 200   */
 201 template <class InputIterator>
 202 Future<std::pair<
 203   size_t,
 204   Try<typename std::iterator_traits<InputIterator>::value_type::value_type>>>
 205 whenAny(InputIterator first, InputIterator last);
 206
 207 /** when n Futures have completed, the Future completes with a vector of
 208   the index and Try of those n Futures (the indices refer to the original
 209   order, but the result vector will be in an arbitrary order)
 210
 211   Not thread safe.
 212   */
 213 template <class InputIterator>
 214 Future<std::vector<std::pair<
 215   size_t,
 216   Try<typename std::iterator_traits<InputIterator>::value_type::value_type>>>>
 217 whenN(InputIterator first, InputIterator last, size_t n);
 218
 219 }} // folly::wangle
 220
 221 #include "Future-inl.h"
 222
 223 /*
 224
 225 TODO
 226
 227 I haven't included a Future<T&> specialization because I don't forsee us
 228 using it, however it is not difficult to add when needed. Refer to
 229 Future<void> for guidance. std::Future and boost::Future code would also be
 230 instructive.
 231
 232 I think that this might be a good candidate for folly, once it has baked for
 233 awhile.
 234
 235 */