futures: fix behaviour when executors don't exec callback
[folly.git] / folly / futures / detail / Core.h
1 /*
2  * Copyright 2016 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 <atomic>
20 #include <mutex>
21 #include <stdexcept>
22 #include <vector>
23
24 #include <folly/Executor.h>
25 #include <folly/Function.h>
26 #include <folly/MicroSpinLock.h>
27 #include <folly/Optional.h>
28 #include <folly/futures/Future.h>
29 #include <folly/futures/Promise.h>
30 #include <folly/Try.h>
31 #include <folly/futures/detail/FSM.h>
32
33 #include <folly/io/async/Request.h>
34
35 namespace folly { namespace detail {
36
37 /*
38         OnlyCallback
39        /            \
40   Start              Armed - Done
41        \            /
42          OnlyResult
43
44 This state machine is fairly self-explanatory. The most important bit is
45 that the callback is only executed on the transition from Armed to Done,
46 and that transition can happen immediately after transitioning from Only*
47 to Armed, if it is active (the usual case).
48 */
49 enum class State : uint8_t {
50   Start,
51   OnlyResult,
52   OnlyCallback,
53   Armed,
54   Done,
55 };
56
57 /// The shared state object for Future and Promise.
58 /// Some methods must only be called by either the Future thread or the
59 /// Promise thread. The Future thread is the thread that currently "owns" the
60 /// Future and its callback-related operations, and the Promise thread is
61 /// likewise the thread that currently "owns" the Promise and its
62 /// result-related operations. Also, Futures own interruption, Promises own
63 /// interrupt handlers. Unfortunately, there are things that users can do to
64 /// break this, and we can't detect that. However if they follow move
65 /// semantics religiously wrt threading, they should be ok.
66 ///
67 /// It's worth pointing out that Futures and/or Promises can and usually will
68 /// migrate between threads, though this usually happens within the API code.
69 /// For example, an async operation will probably make a Promise, grab its
70 /// Future, then move the Promise into another thread that will eventually
71 /// fulfill it. With executors and via, this gets slightly more complicated at
72 /// first blush, but it's the same principle. In general, as long as the user
73 /// doesn't access a Future or Promise object from more than one thread at a
74 /// time there won't be any problems.
75 template<typename T>
76 class Core final {
77   static_assert(!std::is_void<T>::value,
78                 "void futures are not supported. Use Unit instead.");
79  public:
80   /// This must be heap-constructed. There's probably a way to enforce that in
81   /// code but since this is just internal detail code and I don't know how
82   /// off-hand, I'm punting.
83   Core() : result_(), fsm_(State::Start), attached_(2) {}
84
85   explicit Core(Try<T>&& t)
86     : result_(std::move(t)),
87       fsm_(State::OnlyResult),
88       attached_(1) {}
89
90   ~Core() {
91     DCHECK(attached_ == 0);
92   }
93
94   // not copyable
95   Core(Core const&) = delete;
96   Core& operator=(Core const&) = delete;
97
98   // not movable (see comment in the implementation of Future::then)
99   Core(Core&&) noexcept = delete;
100   Core& operator=(Core&&) = delete;
101
102   // Core is assumed to be convertible only if the type is convertible
103   // and the size is the same. This is a compromise for the complexity
104   // of having to make Core truly have a conversion constructor which
105   // would cause various other problems.
106   // If we made Core move constructible then we would need to update the
107   // Promise and Future with the location of the new Core. This is complex
108   // and may be inefficient.
109   // Core should only be modified so that for size(T) == size(U),
110   // sizeof(Core<T>) == size(Core<U>).
111   // This assumption is used as a proxy to make sure that
112   // the members of Core<T> and Core<U> line up so that we can use a
113   // reinterpret cast.
114   template <
115       class U,
116       typename = typename std::enable_if<std::is_convertible<U, T>::value &&
117                                          sizeof(U) == sizeof(T)>::type>
118   static Core<T>* convert(Core<U>* from) {
119     return reinterpret_cast<Core<T>*>(from);
120   }
121
122   /// May call from any thread
123   bool hasResult() const {
124     switch (fsm_.getState()) {
125       case State::OnlyResult:
126       case State::Armed:
127       case State::Done:
128         assert(!!result_);
129         return true;
130
131       default:
132         return false;
133     }
134   }
135
136   /// May call from any thread
137   bool ready() const {
138     return hasResult();
139   }
140
141   /// May call from any thread
142   Try<T>& getTry() {
143     if (ready()) {
144       return *result_;
145     } else {
146       throw FutureNotReady();
147     }
148   }
149
150   /// Call only from Future thread.
151   template <typename F>
152   void setCallback(F&& func) {
153     bool transitionToArmed = false;
154     auto setCallback_ = [&]{
155       context_ = RequestContext::saveContext();
156       callback_ = std::forward<F>(func);
157     };
158
159     FSM_START(fsm_)
160       case State::Start:
161         FSM_UPDATE(fsm_, State::OnlyCallback, setCallback_);
162         break;
163
164       case State::OnlyResult:
165         FSM_UPDATE(fsm_, State::Armed, setCallback_);
166         transitionToArmed = true;
167         break;
168
169       case State::OnlyCallback:
170       case State::Armed:
171       case State::Done:
172         throw std::logic_error("setCallback called twice");
173     FSM_END
174
175     // we could always call this, it is an optimization to only call it when
176     // it might be needed.
177     if (transitionToArmed) {
178       maybeCallback();
179     }
180   }
181
182   /// Call only from Promise thread
183   void setResult(Try<T>&& t) {
184     bool transitionToArmed = false;
185     auto setResult_ = [&]{ result_ = std::move(t); };
186     FSM_START(fsm_)
187       case State::Start:
188         FSM_UPDATE(fsm_, State::OnlyResult, setResult_);
189         break;
190
191       case State::OnlyCallback:
192         FSM_UPDATE(fsm_, State::Armed, setResult_);
193         transitionToArmed = true;
194         break;
195
196       case State::OnlyResult:
197       case State::Armed:
198       case State::Done:
199         throw std::logic_error("setResult called twice");
200     FSM_END
201
202     if (transitionToArmed) {
203       maybeCallback();
204     }
205   }
206
207   /// Called by a destructing Future (in the Future thread, by definition)
208   void detachFuture() {
209     activate();
210     detachOne();
211   }
212
213   /// Called by a destructing Promise (in the Promise thread, by definition)
214   void detachPromise() {
215     // detachPromise() and setResult() should never be called in parallel
216     // so we don't need to protect this.
217     if (UNLIKELY(!result_)) {
218       setResult(Try<T>(exception_wrapper(BrokenPromise(typeid(T).name()))));
219     }
220     detachOne();
221   }
222
223   /// May call from any thread
224   void deactivate() {
225     active_.store(false, std::memory_order_release);
226   }
227
228   /// May call from any thread
229   void activate() {
230     active_.store(true, std::memory_order_release);
231     maybeCallback();
232   }
233
234   /// May call from any thread
235   bool isActive() { return active_.load(std::memory_order_acquire); }
236
237   /// Call only from Future thread
238   void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
239     if (!executorLock_.try_lock()) {
240       executorLock_.lock();
241     }
242     executor_ = x;
243     priority_ = priority;
244     executorLock_.unlock();
245   }
246
247   void setExecutorNoLock(Executor* x, int8_t priority = Executor::MID_PRI) {
248     executor_ = x;
249     priority_ = priority;
250   }
251
252   Executor* getExecutor() {
253     return executor_;
254   }
255
256   /// Call only from Future thread
257   void raise(exception_wrapper e) {
258     if (!interruptLock_.try_lock()) {
259       interruptLock_.lock();
260     }
261     if (!interrupt_ && !hasResult()) {
262       interrupt_ = folly::make_unique<exception_wrapper>(std::move(e));
263       if (interruptHandler_) {
264         interruptHandler_(*interrupt_);
265       }
266     }
267     interruptLock_.unlock();
268   }
269
270   std::function<void(exception_wrapper const&)> getInterruptHandler() {
271     if (!interruptHandlerSet_.load(std::memory_order_acquire)) {
272       return nullptr;
273     }
274     if (!interruptLock_.try_lock()) {
275       interruptLock_.lock();
276     }
277     auto handler = interruptHandler_;
278     interruptLock_.unlock();
279     return handler;
280   }
281
282   /// Call only from Promise thread
283   void setInterruptHandler(std::function<void(exception_wrapper const&)> fn) {
284     if (!interruptLock_.try_lock()) {
285       interruptLock_.lock();
286     }
287     if (!hasResult()) {
288       if (interrupt_) {
289         fn(*interrupt_);
290       } else {
291         setInterruptHandlerNoLock(std::move(fn));
292       }
293     }
294     interruptLock_.unlock();
295   }
296
297   void setInterruptHandlerNoLock(
298       std::function<void(exception_wrapper const&)> fn) {
299     interruptHandlerSet_.store(true, std::memory_order_relaxed);
300     interruptHandler_ = std::move(fn);
301   }
302
303  private:
304   class CountedReference {
305    public:
306     ~CountedReference() {
307       if (core_) {
308         core_->detachOne();
309         core_ = nullptr;
310       }
311     }
312
313     explicit CountedReference(Core* core) noexcept : core_(core) {
314       // do not construct a CountedReference from nullptr!
315       DCHECK(core);
316
317       ++core_->attached_;
318     }
319
320     // CountedReference must be copy-constructable as long as
321     // folly::Executor::add takes a std::function
322     CountedReference(CountedReference const& o) noexcept : core_(o.core_) {
323       if (core_) {
324         ++core_->attached_;
325       }
326     }
327
328     CountedReference& operator=(CountedReference const& o) noexcept {
329       ~CountedReference();
330       new (this) CountedReference(o);
331       return *this;
332     }
333
334     CountedReference(CountedReference&& o) noexcept {
335       std::swap(core_, o.core_);
336     }
337
338     CountedReference& operator=(CountedReference&& o) noexcept {
339       ~CountedReference();
340       new (this) CountedReference(std::move(o));
341       return *this;
342     }
343
344     Core* getCore() const noexcept {
345       return core_;
346     }
347
348    private:
349     Core* core_{nullptr};
350   };
351
352   void maybeCallback() {
353     FSM_START(fsm_)
354       case State::Armed:
355         if (active_.load(std::memory_order_acquire)) {
356           FSM_UPDATE2(fsm_, State::Done, []{}, [this]{ this->doCallback(); });
357         }
358         FSM_BREAK
359
360       default:
361         FSM_BREAK
362     FSM_END
363   }
364
365   void doCallback() {
366     Executor* x = executor_;
367     int8_t priority;
368     if (x) {
369       if (!executorLock_.try_lock()) {
370         executorLock_.lock();
371       }
372       x = executor_;
373       priority = priority_;
374       executorLock_.unlock();
375     }
376
377     if (x) {
378       try {
379         if (LIKELY(x->getNumPriorities() == 1)) {
380           x->add([core_ref = CountedReference(this)]() mutable {
381             auto cr = std::move(core_ref);
382             Core* const core = cr.getCore();
383             RequestContextScopeGuard rctx(core->context_);
384             SCOPE_EXIT { core->callback_ = {}; };
385             core->callback_(std::move(*core->result_));
386           });
387         } else {
388           x->addWithPriority([core_ref = CountedReference(this)]() mutable {
389             auto cr = std::move(core_ref);
390             Core* const core = cr.getCore();
391             RequestContextScopeGuard rctx(core->context_);
392             SCOPE_EXIT { core->callback_ = {}; };
393             core->callback_(std::move(*core->result_));
394           }, priority);
395         }
396       } catch (...) {
397         CountedReference core_ref(this);
398         RequestContextScopeGuard rctx(context_);
399         result_ = Try<T>(exception_wrapper(std::current_exception()));
400         SCOPE_EXIT { callback_ = {}; };
401         callback_(std::move(*result_));
402       }
403     } else {
404       CountedReference core_ref(this);
405       RequestContextScopeGuard rctx(context_);
406       SCOPE_EXIT { callback_ = {}; };
407       callback_(std::move(*result_));
408     }
409   }
410
411   void detachOne() {
412     auto a = attached_--;
413     assert(a >= 1);
414     if (a == 1) {
415       delete this;
416     }
417   }
418
419   // Core should only be modified so that for size(T) == size(U),
420   // sizeof(Core<T>) == size(Core<U>).
421   // See Core::convert for details.
422
423   folly::Function<void(Try<T>&&)> callback_;
424   // place result_ next to increase the likelihood that the value will be
425   // contained entirely in one cache line
426   folly::Optional<Try<T>> result_;
427   FSM<State> fsm_;
428   std::atomic<unsigned char> attached_;
429   std::atomic<bool> active_ {true};
430   std::atomic<bool> interruptHandlerSet_ {false};
431   folly::MicroSpinLock interruptLock_ {0};
432   folly::MicroSpinLock executorLock_ {0};
433   int8_t priority_ {-1};
434   Executor* executor_ {nullptr};
435   std::shared_ptr<RequestContext> context_ {nullptr};
436   std::unique_ptr<exception_wrapper> interrupt_ {};
437   std::function<void(exception_wrapper const&)> interruptHandler_ {nullptr};
438 };
439
440 template <typename... Ts>
441 struct CollectAllVariadicContext {
442   CollectAllVariadicContext() {}
443   template <typename T, size_t I>
444   inline void setPartialResult(Try<T>& t) {
445     std::get<I>(results) = std::move(t);
446   }
447   ~CollectAllVariadicContext() {
448     p.setValue(std::move(results));
449   }
450   Promise<std::tuple<Try<Ts>...>> p;
451   std::tuple<Try<Ts>...> results;
452   typedef Future<std::tuple<Try<Ts>...>> type;
453 };
454
455 template <typename... Ts>
456 struct CollectVariadicContext {
457   CollectVariadicContext() {}
458   template <typename T, size_t I>
459   inline void setPartialResult(Try<T>& t) {
460     if (t.hasException()) {
461        if (!threw.exchange(true)) {
462          p.setException(std::move(t.exception()));
463        }
464      } else if (!threw) {
465        std::get<I>(results) = std::move(t);
466      }
467   }
468   ~CollectVariadicContext() {
469     if (!threw.exchange(true)) {
470       p.setValue(unwrap(std::move(results)));
471     }
472   }
473   Promise<std::tuple<Ts...>> p;
474   std::tuple<folly::Try<Ts>...> results;
475   std::atomic<bool> threw {false};
476   typedef Future<std::tuple<Ts...>> type;
477
478  private:
479   template <typename... Ts2>
480   static std::tuple<Ts...> unwrap(std::tuple<folly::Try<Ts>...>&& o,
481                                   Ts2&&... ts2) {
482     static_assert(sizeof...(ts2) <
483                   std::tuple_size<std::tuple<folly::Try<Ts>...>>::value,
484                   "Non-templated unwrap should be used instead");
485     assert(std::get<sizeof...(ts2)>(o).hasValue());
486
487     return unwrap(std::move(o),
488                   std::forward<Ts2>(ts2)...,
489                   std::move(*std::get<sizeof...(ts2)>(o)));
490   }
491
492   static std::tuple<Ts...> unwrap(std::tuple<folly::Try<Ts>...>&& /* o */,
493                                   Ts&&... ts) {
494     return std::tuple<Ts...>(std::forward<Ts>(ts)...);
495   }
496 };
497
498 template <template <typename...> class T, typename... Ts>
499 void collectVariadicHelper(const std::shared_ptr<T<Ts...>>& /* ctx */) {
500   // base case
501 }
502
503 template <template <typename ...> class T, typename... Ts,
504           typename THead, typename... TTail>
505 void collectVariadicHelper(const std::shared_ptr<T<Ts...>>& ctx,
506                            THead&& head, TTail&&... tail) {
507   head.setCallback_([ctx](Try<typename THead::value_type>&& t) {
508     ctx->template setPartialResult<typename THead::value_type,
509                                    sizeof...(Ts) - sizeof...(TTail) - 1>(t);
510   });
511   // template tail-recursion
512   collectVariadicHelper(ctx, std::forward<TTail>(tail)...);
513 }
514
515 }} // folly::detail