2 * Copyright 2016 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.
24 #include <folly/Optional.h>
25 #include <folly/MicroSpinLock.h>
27 #include <folly/futures/Try.h>
28 #include <folly/futures/Promise.h>
29 #include <folly/futures/Future.h>
30 #include <folly/Executor.h>
31 #include <folly/futures/detail/FSM.h>
33 #include <folly/io/async/Request.h>
35 namespace folly { namespace detail {
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).
49 enum class State : uint8_t {
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.
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.
77 static_assert(!std::is_void<T>::value,
78 "void futures are not supported. Use Unit instead.");
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) {}
85 explicit Core(Try<T>&& t)
86 : result_(std::move(t)),
87 fsm_(State::OnlyResult),
91 DCHECK(attached_ == 0);
95 Core(Core const&) = delete;
96 Core& operator=(Core const&) = delete;
98 // not movable (see comment in the implementation of Future::then)
99 Core(Core&&) noexcept = delete;
100 Core& operator=(Core&&) = delete;
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
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);
122 /// May call from any thread
123 bool hasResult() const {
124 switch (fsm_.getState()) {
125 case State::OnlyResult:
136 /// May call from any thread
141 /// May call from any thread
146 throw FutureNotReady();
150 template <typename F>
151 class LambdaBufHelper {
153 template <typename FF>
154 explicit LambdaBufHelper(FF&& func) : func_(std::forward<FF>(func)) {}
155 void operator()(Try<T>&& t) {
156 SCOPE_EXIT { this->~LambdaBufHelper(); };
163 /// Call only from Future thread.
164 template <typename F>
165 void setCallback(F func) {
166 bool transitionToArmed = false;
167 auto setCallback_ = [&]{
168 context_ = RequestContext::saveContext();
170 // Move the lambda into the Core if it fits
171 if (sizeof(LambdaBufHelper<F>) <= lambdaBufSize) {
172 auto funcLoc = reinterpret_cast<LambdaBufHelper<F>*>(&lambdaBuf_);
173 new (funcLoc) LambdaBufHelper<F>(std::forward<F>(func));
174 callback_ = std::ref(*funcLoc);
176 callback_ = std::move(func);
182 FSM_UPDATE(fsm_, State::OnlyCallback, setCallback_);
185 case State::OnlyResult:
186 FSM_UPDATE(fsm_, State::Armed, setCallback_);
187 transitionToArmed = true;
190 case State::OnlyCallback:
193 throw std::logic_error("setCallback called twice");
196 // we could always call this, it is an optimization to only call it when
197 // it might be needed.
198 if (transitionToArmed) {
203 /// Call only from Promise thread
204 void setResult(Try<T>&& t) {
205 bool transitionToArmed = false;
206 auto setResult_ = [&]{ result_ = std::move(t); };
209 FSM_UPDATE(fsm_, State::OnlyResult, setResult_);
212 case State::OnlyCallback:
213 FSM_UPDATE(fsm_, State::Armed, setResult_);
214 transitionToArmed = true;
217 case State::OnlyResult:
220 throw std::logic_error("setResult called twice");
223 if (transitionToArmed) {
228 /// Called by a destructing Future (in the Future thread, by definition)
229 void detachFuture() {
234 /// Called by a destructing Promise (in the Promise thread, by definition)
235 void detachPromise() {
236 // detachPromise() and setResult() should never be called in parallel
237 // so we don't need to protect this.
238 if (UNLIKELY(!result_)) {
239 setResult(Try<T>(exception_wrapper(BrokenPromise(typeid(T).name()))));
244 /// May call from any thread
246 active_.store(false, std::memory_order_release);
249 /// May call from any thread
251 active_.store(true, std::memory_order_release);
255 /// May call from any thread
256 bool isActive() { return active_.load(std::memory_order_acquire); }
258 /// Call only from Future thread
259 void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
260 if (!executorLock_.try_lock()) {
261 executorLock_.lock();
264 priority_ = priority;
265 executorLock_.unlock();
268 void setExecutorNoLock(Executor* x, int8_t priority = Executor::MID_PRI) {
270 priority_ = priority;
273 Executor* getExecutor() {
277 /// Call only from Future thread
278 void raise(exception_wrapper e) {
279 if (!interruptLock_.try_lock()) {
280 interruptLock_.lock();
282 if (!interrupt_ && !hasResult()) {
283 interrupt_ = folly::make_unique<exception_wrapper>(std::move(e));
284 if (interruptHandler_) {
285 interruptHandler_(*interrupt_);
288 interruptLock_.unlock();
291 std::function<void(exception_wrapper const&)> getInterruptHandler() {
292 if (!interruptHandlerSet_.load(std::memory_order_acquire)) {
295 if (!interruptLock_.try_lock()) {
296 interruptLock_.lock();
298 auto handler = interruptHandler_;
299 interruptLock_.unlock();
303 /// Call only from Promise thread
304 void setInterruptHandler(std::function<void(exception_wrapper const&)> fn) {
305 if (!interruptLock_.try_lock()) {
306 interruptLock_.lock();
312 setInterruptHandlerNoLock(std::move(fn));
315 interruptLock_.unlock();
318 void setInterruptHandlerNoLock(
319 std::function<void(exception_wrapper const&)> fn) {
320 interruptHandlerSet_.store(true, std::memory_order_relaxed);
321 interruptHandler_ = std::move(fn);
325 void maybeCallback() {
328 if (active_.load(std::memory_order_acquire)) {
329 FSM_UPDATE2(fsm_, State::Done, []{}, [this]{ this->doCallback(); });
339 Executor* x = executor_;
342 if (!executorLock_.try_lock()) {
343 executorLock_.lock();
346 priority = priority_;
347 executorLock_.unlock();
350 // keep Core alive until callback did its thing
355 if (LIKELY(x->getNumPriorities() == 1)) {
356 x->add([this]() mutable {
357 SCOPE_EXIT { detachOne(); };
358 RequestContext::setContext(context_);
359 SCOPE_EXIT { callback_ = {}; };
360 callback_(std::move(*result_));
363 x->addWithPriority([this]() mutable {
364 SCOPE_EXIT { detachOne(); };
365 RequestContext::setContext(context_);
366 SCOPE_EXIT { callback_ = {}; };
367 callback_(std::move(*result_));
371 --attached_; // Account for extra ++attached_ before try
372 RequestContext::setContext(context_);
373 result_ = Try<T>(exception_wrapper(std::current_exception()));
374 SCOPE_EXIT { callback_ = {}; };
375 callback_(std::move(*result_));
378 SCOPE_EXIT { detachOne(); };
379 RequestContext::setContext(context_);
380 SCOPE_EXIT { callback_ = {}; };
381 callback_(std::move(*result_));
386 auto a = --attached_;
394 // Core should only be modified so that for size(T) == size(U),
395 // sizeof(Core<T>) == size(Core<U>).
396 // See Core::convert for details.
398 // lambdaBuf occupies exactly one cache line
399 static constexpr size_t lambdaBufSize = 8 * sizeof(void*);
400 typename std::aligned_storage<lambdaBufSize>::type lambdaBuf_;
401 // place result_ next to increase the likelihood that the value will be
402 // contained entirely in one cache line
403 folly::Optional<Try<T>> result_;
404 std::function<void(Try<T>&&)> callback_ {nullptr};
406 std::atomic<unsigned char> attached_;
407 std::atomic<bool> active_ {true};
408 std::atomic<bool> interruptHandlerSet_ {false};
409 folly::MicroSpinLock interruptLock_ {0};
410 folly::MicroSpinLock executorLock_ {0};
411 int8_t priority_ {-1};
412 Executor* executor_ {nullptr};
413 std::shared_ptr<RequestContext> context_ {nullptr};
414 std::unique_ptr<exception_wrapper> interrupt_ {};
415 std::function<void(exception_wrapper const&)> interruptHandler_ {nullptr};
418 template <typename... Ts>
419 struct CollectAllVariadicContext {
420 CollectAllVariadicContext() {}
421 template <typename T, size_t I>
422 inline void setPartialResult(Try<T>& t) {
423 std::get<I>(results) = std::move(t);
425 ~CollectAllVariadicContext() {
426 p.setValue(std::move(results));
428 Promise<std::tuple<Try<Ts>...>> p;
429 std::tuple<Try<Ts>...> results;
430 typedef Future<std::tuple<Try<Ts>...>> type;
433 template <typename... Ts>
434 struct CollectVariadicContext {
435 CollectVariadicContext() {}
436 template <typename T, size_t I>
437 inline void setPartialResult(Try<T>& t) {
438 if (t.hasException()) {
439 if (!threw.exchange(true)) {
440 p.setException(std::move(t.exception()));
443 std::get<I>(results) = std::move(t);
446 ~CollectVariadicContext() {
447 if (!threw.exchange(true)) {
448 p.setValue(unwrap(std::move(results)));
451 Promise<std::tuple<Ts...>> p;
452 std::tuple<folly::Try<Ts>...> results;
453 std::atomic<bool> threw {false};
454 typedef Future<std::tuple<Ts...>> type;
457 template <typename... Ts2>
458 static std::tuple<Ts...> unwrap(std::tuple<folly::Try<Ts>...>&& o,
460 static_assert(sizeof...(ts2) <
461 std::tuple_size<std::tuple<folly::Try<Ts>...>>::value,
462 "Non-templated unwrap should be used instead");
463 assert(std::get<sizeof...(ts2)>(o).hasValue());
465 return unwrap(std::move(o),
466 std::forward<Ts2>(ts2)...,
467 std::move(*std::get<sizeof...(ts2)>(o)));
470 static std::tuple<Ts...> unwrap(std::tuple<folly::Try<Ts>...>&& /* o */,
472 return std::tuple<Ts...>(std::forward<Ts>(ts)...);
476 template <template <typename...> class T, typename... Ts>
477 void collectVariadicHelper(const std::shared_ptr<T<Ts...>>& /* ctx */) {
481 template <template <typename ...> class T, typename... Ts,
482 typename THead, typename... TTail>
483 void collectVariadicHelper(const std::shared_ptr<T<Ts...>>& ctx,
484 THead&& head, TTail&&... tail) {
485 head.setCallback_([ctx](Try<typename THead::value_type>&& t) {
486 ctx->template setPartialResult<typename THead::value_type,
487 sizeof...(Ts) - sizeof...(TTail) - 1>(t);
489 // template tail-recursion
490 collectVariadicHelper(ctx, std::forward<TTail>(tail)...);