folly/wangle/Later.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 "folly/wangle/Executor.h"
  20 #include "folly/wangle/Future.h"
  21 #include "folly/Optional.h"
  22
  23 namespace folly { namespace wangle {
  24
  25 template <typename T> struct isLaterOrFuture;
  26 template <typename T> struct isLater;
  27
  28 /*
  29  * Since wangle primitives (promise/future) are not thread safe, it is difficult
  30  * to build complex asynchronous workflows. A Later allows you to build such a
  31  * workflow before actually launching it so that continuations can be set in a
  32  * threadsafe manner.
  33  *
  34  * The interface to add additional work is the same as future: a then() method
  35  * that takes a function that can return either a type T, a Future<T>, or a
  36  * Later<T>
  37  *
  38  * Thread transitions are done by using executors and calling the via() method.
  39  *
  40  * Here is an example of a workflow:
  41  *
  42  * Later<ClientRequest> later(std::move(request));
  43  *
  44  * auto future = later.
  45  *   .via(cpuExecutor)
  46  *   .then([=](Try<ClientRequest>&& t) { return doCpuWork(t.value()); })
  47  *   .via(diskExecutor)
  48  *   .then([=](Try<CpuResponse>&& t) { return doDiskWork(t.value()); })
  49  *   .via(serverExecutor)
  50  *   .then([=]Try<DiskResponse>&& t) { return sendClientResponse(t.value()); })
  51  *   .launch();
  52  *
  53  * Although this workflow traverses many threads, we are able to string
  54  * continuations together in a threadsafe manner.
  55  *
  56  * Laters can also be used to wrap preexisting asynchronous modules that were
  57  * not built with wangle in mind. You can create a Later with a function that
  58  * takes a callback as input. The function will not actually be called until
  59  * launch(), allowing you to string then() statements on top of the callback.
  60  */
  61 template <class T>
  62 class Later {
  63  public:
  64   typedef T value_type;
  65
  66   /*
  67    * This default constructor is used to build an asynchronous workflow that
  68    * takes no input.
  69    */
  70   template <class U = void,
  71             class = typename std::enable_if<std::is_void<U>::value>::type,
  72             class = typename std::enable_if<std::is_same<T, U>::value>::type>
  73   Later();
  74
  75   /*
  76    * This constructor is used to build an asynchronous workflow that takes a
  77    * value as input, and that value is passed in.
  78    */
  79   template <class U,
  80             class = typename std::enable_if<!std::is_void<U>::value>::type,
  81             class = typename std::enable_if<std::is_same<T, U>::value>::type>
  82   explicit Later(U&& input);
  83
  84   /*
  85    * This constructor is used to wrap a pre-existing cob-style asynchronous api
  86    * so that it can be used in wangle in a threadsafe manner. wangle provides
  87    * the callback to this pre-existing api, and this callback will fulfill a
  88    * promise so as to incorporate this api into the workflow.
  89    *
  90    * Example usage:
  91    *
  92    * // This adds two ints asynchronously. cob is called in another thread.
  93    * void addAsync(int a, int b, std::function<void(int&&)>&& cob);
  94    *
  95    * Later<int> asyncWrapper([=](std::function<void(int&&)>&& fn) {
  96    *   addAsync(1, 2, std::move(fn));
  97    * });
  98    */
  99   template <class U,
 100             class = typename std::enable_if<!std::is_void<U>::value>::type,
 101             class = typename std::enable_if<std::is_same<T, U>::value>::type>
 102   explicit Later(std::function<void(std::function<void(U&&)>&&)>&& fn);
 103
 104   /*
 105    * then() adds additional work to the end of the workflow. If the lambda
 106    * provided to then() returns a future, that future must be fulfilled in the
 107    * same thread of the last set executor (either at constructor or from a call
 108    * to via()).
 109    */
 110   template <class F>
 111   typename std::enable_if<
 112     !isLaterOrFuture<typename std::result_of<F(Try<T>&&)>::type>::value,
 113     Later<typename std::result_of<F(Try<T>&&)>::type> >::type
 114   then(F&& fn);
 115
 116   template <class F>
 117   typename std::enable_if<
 118     isFuture<typename std::result_of<F(Try<T>&&)>::type>::value,
 119     Later<typename std::result_of<F(Try<T>&&)>::type::value_type> >::type
 120   then(F&& fn);
 121
 122   /*
 123    * If the function passed to then() returns a Later<T>, calls to then() will
 124    * be chained to the new Later before launching the new Later.
 125    *
 126    * This can be used to build asynchronous modules that can be called from a
 127    * user thread and completed in a callback thread. Callbacks can be set up
 128    * ahead of time without thread safety issues.
 129    *
 130    * Using the Later(std::function<void(std::function<void(T&&)>)>&& fn)
 131    * constructor, you can wrap existing asynchronous modules with a Later and
 132    * can chain it to wangle asynchronous workflows via this call.
 133    */
 134   template <class F>
 135   typename std::enable_if<
 136     isLater<typename std::result_of<F(Try<T>&&)>::type>::value,
 137     Later<typename std::result_of<F(Try<T>&&)>::type::value_type> >::type
 138   then(F&& fn);
 139
 140   /*
 141    * Resets the executor - all then() calls made after the call to via() will be
 142    * made in the new executor. The Executor must outlive.
 143    */
 144   Later<T> via(Executor* executor);
 145
 146   /*
 147    * Starts the workflow. The function provided in the constructor will be
 148    * called in the executor provided in the constructor. Subsequent then()
 149    * calls will be made, potentially changing threads if a via() call is made.
 150    * The future returned will be fulfilled in the last executor.
 151    *
 152    * Thread safety issues of Futures still apply. If you want to wait on the
 153    * Future, it must be done in the thread that will fulfil it. If you do not
 154    * plan to use the result of the Future, use fireAndForget()
 155    */
 156   Future<T> launch();
 157
 158   /*
 159    * Same as launch, only no Future is returned. This guarantees thread safe
 160    * cleanup of the internal Futures, even if the Later completes in a different
 161    * thread than the thread that calls fireAndForget().
 162    */
 163   void fireAndForget();
 164
 165  private:
 166   Promise<void> starter_;
 167   folly::Optional<Future<T>> future_;
 168
 169   struct hide { };
 170
 171   explicit Later(Promise<void>&& starter);
 172
 173   template <class U>
 174   friend class Later;
 175 };
 176
 177 }}
 178
 179 #include "Later-inl.h"