2 * Copyright 2015 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/SmallLocks.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.
78 /// This must be heap-constructed. There's probably a way to enforce that in
79 /// code but since this is just internal detail code and I don't know how
80 /// off-hand, I'm punting.
81 Core() : result_(), fsm_(State::Start), attached_(2) {}
83 explicit Core(Try<T>&& t)
84 : result_(std::move(t)),
85 fsm_(State::OnlyResult),
89 DCHECK(attached_ == 0);
93 Core(Core const&) = delete;
94 Core& operator=(Core const&) = delete;
96 // not movable (see comment in the implementation of Future::then)
97 Core(Core&&) noexcept = delete;
98 Core& operator=(Core&&) = delete;
100 /// May call from any thread
101 bool hasResult() const {
102 switch (fsm_.getState()) {
103 case State::OnlyResult:
114 /// May call from any thread
119 /// May call from any thread
124 throw FutureNotReady();
128 template <typename F>
129 class LambdaBufHelper {
131 explicit LambdaBufHelper(F&& func) : func_(std::forward<F>(func)) {}
132 void operator()(Try<T>&& t) {
133 SCOPE_EXIT { this->~LambdaBufHelper(); };
140 /// Call only from Future thread.
141 template <typename F>
142 void setCallback(F func) {
143 bool transitionToArmed = false;
144 auto setCallback_ = [&]{
145 context_ = RequestContext::saveContext();
147 // Move the lambda into the Core if it fits
148 if (sizeof(LambdaBufHelper<F>) <= lambdaBufSize) {
149 auto funcLoc = static_cast<LambdaBufHelper<F>*>((void*)lambdaBuf_);
150 new (funcLoc) LambdaBufHelper<F>(std::forward<F>(func));
151 callback_ = std::ref(*funcLoc);
153 callback_ = std::move(func);
159 FSM_UPDATE(fsm_, State::OnlyCallback, setCallback_);
162 case State::OnlyResult:
163 FSM_UPDATE(fsm_, State::Armed, setCallback_);
164 transitionToArmed = true;
167 case State::OnlyCallback:
170 throw std::logic_error("setCallback called twice");
173 // we could always call this, it is an optimization to only call it when
174 // it might be needed.
175 if (transitionToArmed) {
180 /// Call only from Promise thread
181 void setResult(Try<T>&& t) {
182 bool transitionToArmed = false;
183 auto setResult_ = [&]{ result_ = std::move(t); };
186 FSM_UPDATE(fsm_, State::OnlyResult, setResult_);
189 case State::OnlyCallback:
190 FSM_UPDATE(fsm_, State::Armed, setResult_);
191 transitionToArmed = true;
194 case State::OnlyResult:
197 throw std::logic_error("setResult called twice");
200 if (transitionToArmed) {
205 /// Called by a destructing Future (in the Future thread, by definition)
206 void detachFuture() {
211 /// Called by a destructing Promise (in the Promise thread, by definition)
212 void detachPromise() {
213 // detachPromise() and setResult() should never be called in parallel
214 // so we don't need to protect this.
215 if (UNLIKELY(!result_)) {
216 setResult(Try<T>(exception_wrapper(BrokenPromise())));
221 /// May call from any thread
223 active_.store(false, std::memory_order_release);
226 /// May call from any thread
228 active_.store(true, std::memory_order_release);
232 /// May call from any thread
233 bool isActive() { return active_.load(std::memory_order_acquire); }
235 /// Call only from Future thread
236 void setExecutor(Executor* x, int8_t priority = Executor::MID_PRI) {
237 if (!executorLock_.try_lock()) {
238 executorLock_.lock();
241 priority_ = priority;
242 executorLock_.unlock();
245 void setExecutorNoLock(Executor* x, int8_t priority = Executor::MID_PRI) {
247 priority_ = priority;
250 Executor* getExecutor() {
254 /// Call only from Future thread
255 void raise(exception_wrapper e) {
256 if (!interruptLock_.try_lock()) {
257 interruptLock_.lock();
259 if (!interrupt_ && !hasResult()) {
260 interrupt_ = folly::make_unique<exception_wrapper>(std::move(e));
261 if (interruptHandler_) {
262 interruptHandler_(*interrupt_);
265 interruptLock_.unlock();
268 std::function<void(exception_wrapper const&)> getInterruptHandler() {
269 if (!interruptHandlerSet_.load(std::memory_order_acquire)) {
272 if (!interruptLock_.try_lock()) {
273 interruptLock_.lock();
275 auto handler = interruptHandler_;
276 interruptLock_.unlock();
280 /// Call only from Promise thread
281 void setInterruptHandler(std::function<void(exception_wrapper const&)> fn) {
282 if (!interruptLock_.try_lock()) {
283 interruptLock_.lock();
289 setInterruptHandlerNoLock(std::move(fn));
292 interruptLock_.unlock();
295 void setInterruptHandlerNoLock(
296 std::function<void(exception_wrapper const&)> fn) {
297 interruptHandlerSet_.store(true, std::memory_order_relaxed);
298 interruptHandler_ = std::move(fn);
302 void maybeCallback() {
305 if (active_.load(std::memory_order_acquire)) {
306 FSM_UPDATE2(fsm_, State::Done, []{}, [this]{ this->doCallback(); });
316 Executor* x = executor_;
319 if (!executorLock_.try_lock()) {
320 executorLock_.lock();
323 priority = priority_;
324 executorLock_.unlock();
328 // keep Core alive until executor did its thing
331 if (LIKELY(x->getNumPriorities() == 1)) {
332 x->add([this]() mutable {
333 SCOPE_EXIT { detachOne(); };
334 RequestContext::setContext(context_);
335 callback_(std::move(*result_));
338 x->addWithPriority([this]() mutable {
339 SCOPE_EXIT { detachOne(); };
340 RequestContext::setContext(context_);
341 callback_(std::move(*result_));
345 --attached_; // Account for extra ++attached_ before try
346 RequestContext::setContext(context_);
347 result_ = Try<T>(exception_wrapper(std::current_exception()));
348 callback_(std::move(*result_));
351 RequestContext::setContext(context_);
352 callback_(std::move(*result_));
357 auto a = --attached_;
365 // lambdaBuf occupies exactly one cache line
366 static constexpr size_t lambdaBufSize = 8 * sizeof(void*);
367 char lambdaBuf_[lambdaBufSize];
368 // place result_ next to increase the likelihood that the value will be
369 // contained entirely in one cache line
370 folly::Optional<Try<T>> result_;
371 std::function<void(Try<T>&&)> callback_ {nullptr};
373 std::atomic<unsigned char> attached_;
374 std::atomic<bool> active_ {true};
375 std::atomic<bool> interruptHandlerSet_ {false};
376 folly::MicroSpinLock interruptLock_ {0};
377 folly::MicroSpinLock executorLock_ {0};
378 int8_t priority_ {-1};
379 Executor* executor_ {nullptr};
380 std::shared_ptr<RequestContext> context_ {nullptr};
381 std::unique_ptr<exception_wrapper> interrupt_ {};
382 std::function<void(exception_wrapper const&)> interruptHandler_ {nullptr};
385 template <typename... Ts>
386 struct CollectAllVariadicContext {
387 CollectAllVariadicContext() {}
388 template <typename T, size_t I>
389 inline void setPartialResult(Try<T>& t) {
390 std::get<I>(results) = std::move(t);
392 ~CollectAllVariadicContext() {
393 p.setValue(std::move(results));
395 Promise<std::tuple<Try<Ts>...>> p;
396 std::tuple<Try<Ts>...> results;
397 typedef Future<std::tuple<Try<Ts>...>> type;
400 template <typename... Ts>
401 struct CollectVariadicContext {
402 CollectVariadicContext() {}
403 template <typename T, size_t I>
404 inline void setPartialResult(Try<T>& t) {
405 if (t.hasException()) {
406 if (!threw.exchange(true)) {
407 p.setException(std::move(t.exception()));
410 std::get<I>(results) = std::move(t.value());
413 ~CollectVariadicContext() {
414 if (!threw.exchange(true)) {
415 p.setValue(std::move(results));
418 Promise<std::tuple<Ts...>> p;
419 std::tuple<Ts...> results;
420 std::atomic<bool> threw {false};
421 typedef Future<std::tuple<Ts...>> type;
424 template <template <typename ...> class T, typename... Ts>
425 void collectVariadicHelper(const std::shared_ptr<T<Ts...>>& ctx) {
429 template <template <typename ...> class T, typename... Ts,
430 typename THead, typename... TTail>
431 void collectVariadicHelper(const std::shared_ptr<T<Ts...>>& ctx,
432 THead&& head, TTail&&... tail) {
433 head.setCallback_([ctx](Try<typename THead::value_type>&& t) {
434 ctx->template setPartialResult<typename THead::value_type,
435 sizeof...(Ts) - sizeof...(TTail) - 1>(t);
437 // template tail-recursion
438 collectVariadicHelper(ctx, std::forward<TTail>(tail)...);