react-native-macos

<section class="dex_guide"><h1 class="dex_title">folly::fibers</h1><section class="dex_document"><h1></h1>folly::fibers is an async C++ framework, which uses fibers for parallelism.<h2 id="overview">Overview <a href="#overview" class="headerLink">#</a></h2> Fibers (or coroutines) are lightweight application threads. Multiple fibers can be running on top of a single system thread. Unlike system threads, all the context switching between fibers is happening explicitly. Because of this every such context switch is very fast (~200 million of fiber context switches can be made per second on a single CPU core). folly::fibers implements a task manager (FiberManager), which executes scheduled tasks on fibers. It also provides some fiber-compatible synchronization primitives. <h2 id="basic-example">Basic example <a href="#basic-example" class="headerLink">#</a></h2> <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">... folly::EventBase evb; auto& fiberManager = folly::fibers::getFiberManager(evb); folly::fibers::Baton baton; fiberManager.addTask([&]() { std::cout << "Task 1: start" << std::endl; baton.wait(); std::cout << "Task 1: after baton.wait()" << std::endl; }); fiberManager.addTask([&]() { std::cout << "Task 2: start" << std::endl; baton.post(); std::cout << "Task 2: after baton.post()" << std::endl; }); evb.loop(); ...</pre></div> This would print: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">Task 1: start Task 2: start Task 2: after baton.post() Task 1: after baton.wait()</pre></div> It's very important to note that both tasks in this example were executed on the same system thread. Task 1 was suspended by <tt>baton.wait()</tt> call. Task 2 then started and called <tt>baton.post()</tt>, resuming Task 1. <h2 id="features">Features <a href="#features" class="headerLink">#</a></h2> <ul> <li>Fibers creation and scheduling is performed by FiberManager</li> <li>Integration with any event-management system (e.g. EventBase)</li> <li>Low-level synchronization primitives (Baton) as well as higher-level primitives built on top of them (await, collectN, mutexes, ... )</li> <li>Synchronization primitives have timeout support</li> <li>Built-in mechanisms for fiber stack-overflow detection</li> <li>Optional fiber-local data (i.e. equivalent of thread locals)</li> </ul> <h2 id="non-features">Non-features <a href="#non-features" class="headerLink">#</a></h2> <ul> <li>Individual fibers scheduling can't be directly controlled by application</li> <li>FiberManager is not thread-safe (we recommend to keep one FiberManager per thread). Application is responsible for managing its own threads and distributing load between them</li> <li>We don't support automatic stack size adjustments. Each fiber has a stack of fixed size.</li> </ul> <h2 id="why-would-i-not-want-to">Why would I not want to use fibers ? <a href="#why-would-i-not-want-to" class="headerLink">#</a></h2> The only real downside to using fibers is the need to keep a pre-allocated stack for every fiber being run. That either makes you application use a lot of memory (if you have many concurrent tasks and each of them uses large stacks) or creates a risk of stack overflow bugs (if you try to reduce the stack size). We believe these problems can be addressed (and we provide some tooling for that), as fibers library is used in many critical applications at Facebook (mcrouter, TAO, Service Router). However, it's important to be aware of the risks and be ready to deal with stack issues if you decide to use fibers library in your application. <h2 id="what-are-the-alternative">What are the alternatives ? <a href="#what-are-the-alternative" class="headerLink">#</a></h2> <ul> <li><a href="https://github.com/facebook/folly/blob/master/folly/futures/" target="_blank">Futures</a> library works great for asynchronous high-level application code. Yet code written using fibers library is generally much simpler and much more efficient (you are not paying the penalty of heap allocation).</li> <li>You can always keep writing your asynchronous code using traditional callback approach. Such code quickly becomes hard to manage and is error-prone. Even though callback approach seems to allow you writing the most efficient code, inefficiency still comes from heap allocations (<tt>std::function</tt>s used for callbacks, context objects to be passed between callbacks etc.)</li> </ul></section><section class="dex_document"><h1>Quick guide</h1>Let's take a look at this basic example: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">... folly::EventBase evb; auto& fiberManager = folly::fibers::getFiberManager(evb); folly::fibers::Baton baton; fiberManager.addTask([&]() { std::cout << "Task: start" << std::endl; baton.wait(); std::cout << "Task: after baton.wait()" << std::endl; }); evb.loop(); baton.post(); std::cout << "Baton posted" << std::endl; evb.loop(); ...</pre></div> This would print: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">Task: start Baton posted Task: after baton.wait()</pre></div> What makes fiber-task different from any other task run on e.g. an <tt>folly::EventBase</tt> is the ability to suspend such task, without blocking the system thread. So how do you suspend a fiber-task ? <h3 id="fibers-baton">fibers::Baton <a href="#fibers-baton" class="headerLink">#</a></h3> <tt>fibers::Baton</tt> is the core synchronization primitive which is used to suspend a fiber-task and notify when the task may be resumed. <tt>fibers::Baton</tt> supports two basic operations: <tt>wait()</tt> and <tt>post()</tt>. Calling <tt>wait()</tt> on a Baton will suspend current fiber-task until <tt>post()</tt> is called on the same Baton. Please refer to <a href="https://github.com/facebook/folly/blob/master/folly/fibers/Baton.h" target="_blank">Baton</a> for more detailed documentation. <div class="remarkup-note">NOTE: <tt>fibers::Baton</tt> is the only native synchronization primitive of folly::fibers library. All other synchronization primitives provided by folly::fibers are built on top of <tt>fibers::Baton</tt>.</div> <h3 id="integrating-with-other-a">Integrating with other asynchronous APIs (callbacks) <a href="#integrating-with-other-a" class="headerLink">#</a></h3> Let's say we have some existing library which provides a classic callback-style asynchronous API. <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">void asyncCall(Request request, folly::Function<void(Response)> cb);</pre></div> If we use folly::fibers we can just make an async call from a fiber-task and wait until callback is run: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... Response response; fibers::Baton baton; asyncCall(request, [&](Response r) mutable { response = std::move(r); baton.post(); }); baton.wait(); // Now response holds response returned by the async call ... }</pre></div> Using <tt>fibers::Baton</tt> directly is generally error-prone. To make the task above simpler, folly::fibers provide <tt>fibers::await</tt> function. With <tt>fibers::await</tt>, the code above transforms into: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... auto response = fibers::await([&](fibers::Promise<Response> promise) { asyncCall(request, [promise = std::move(promise)](Response r) mutable { promise.setValue(std::move(r)); }); }); // Now response holds response returned by the async call ... }</pre></div> Callback passed to <tt>fibers::await</tt> is executed immediately and then fiber-task is suspended until <tt>fibers::Promise</tt> is fulfilled. When <tt>fibers::Promise</tt> is fulfilled with a value or exception, fiber-task will be resumed and 'fibers::await' returns that value (or throws an exception, if exception was used to fulfill the <tt>Promise</tt>). <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... try { auto response = fibers::await([&](fibers::Promise<Response> promise) { asyncCall(request, [promise = std::move(promise)](Response r) mutable { promise.setException(std::runtime_error("Await will re-throw me")); }); }); assert(false); // We should never get here } catch (const std::exception& e) { assert(e.what() == "Await will re-throw me"); } ... }</pre></div> If <tt>fibers::Promise</tt> is not fulfilled, <tt>fibers::await</tt> will throw a <tt>std::logic_error</tt>. <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... try { auto response = fibers::await([&](fibers::Promise<Response> promise) { // We forget about the promise }); assert(false); // We should never get here } catch (const std::logic_error& e) { ... } ... }</pre></div> Please refer to <a href="https://github.com/facebook/folly/blob/master/folly/fibers/Promise.h" target="_blank">await</a> for more detailed documentation. <div class="remarkup-note">NOTE: most of your code written with folly::fibers, won't be using <tt>fibers::Baton</tt> or <tt>fibers::await</tt>. These primitives should only be used to integrate with other asynchronous API which are not fibers-compatible.</div> <h3 id="integrating-with-other-a-1">Integrating with other asynchronous APIs (folly::Future) <a href="#integrating-with-other-a-1" class="headerLink">#</a></h3> Let's say we have some existing library which provides a Future-based asynchronous API. <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">folly::Future<Response> asyncCallFuture(Request request);</pre></div> The good news are, <tt>folly::Future</tt> is already fibers-compatible. You can simply write: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... auto response = asyncCallFuture(request).get(); // Now response holds response returned by the async call ... }</pre></div> Calling <tt>get()</tt> on a <tt>folly::Future</tt> object will only suspend the calling fiber-task. It won't block the system thread, letting it process other tasks. <h2 id="writing-code-with-folly">Writing code with folly::fibers <a href="#writing-code-with-folly" class="headerLink">#</a></h2> <h3 id="building-fibers-compatib">Building fibers-compatible API <a href="#building-fibers-compatib" class="headerLink">#</a></h3> Following the explanations above we may wrap an existing asynchronous API in a function: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">Response fiberCall(Request request) { return fibers::await([&](fibers::Promise<Response> promise) { asyncCall(request, [promise = std::move(promise)](Response r) mutable { promise.setValue(std::move(r)); }); }); }</pre></div> We can then call it from a fiber-task: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... auto response = fiberCall(request); ... });</pre></div> But what happens if we just call <tt>fiberCall</tt> not from within a fiber-task, but directly from a system thread ? Here another important feature of <tt>fibers::Baton</tt> (and thus all other folly::fibers synchronization primitives built on top of it) comes into play. Calling <tt>wait()</tt> on a <tt>fibers::Baton</tt> within a system thread context just blocks the thread until <tt>post()</tt> is called on the same <tt>folly::Baton</tt>. What this means is that you no longer need to write separate code for synchronous and asynchronous APIs. If you use only folly::fibers synchronization primitives for all blocking calls inside of your synchronous function, it automatically becomes asynchronous when run inside a fiber-task. <h3 id="passing-by-reference">Passing by reference <a href="#passing-by-reference" class="headerLink">#</a></h3> Classic asynchronous APIs (same applies to folly::Future-based APIs) generally rely on copying/moving-in input arguments and often require you to copy/move in some context variables into the callback. E.g.: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">... Context context; asyncCall(request, [request, context](Response response) mutable { doSomething(request, response, context); }); ...</pre></div> Fibers-compatible APIs look more like synchronous APIs, so you can actually pass input arguments by reference and you don't have to think about passing context at all. E.g. <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... Context context; auto response = fiberCall(request); doSomething(request, response, context); ... });</pre></div> Same logic applies to <tt>fibers::await</tt>. Since <tt>fibers::await</tt> call blocks until promise is fulfilled, it's safe to pass everything by reference. <h3 id="limited-stack-space">Limited stack space <a href="#limited-stack-space" class="headerLink">#</a></h3> So should you just run all the code inside a fiber-task ? No exactly. Similarly to system threads, every fiber-task has some stack space assigned to it. Stack usage goes up with the number of nested function calls and objects allocated on the stack. folly::fibers implementation only supports fiber-tasks with fixed stack size. If you want to have many fiber-tasks running concurrently - you need to reduce the amount of stack assigned to each fiber-task, otherwise you may run out of memory. <div class="remarkup-important">IMPORTANT: If a fiber-task runs out of stack space (e.g. calls a function which does a lot of stack allocations) you program will fail.</div> However if you know that some function never suspends a fiber-task, you can use <tt>fibers::runInMainContext</tt> to safely call it from a fiber-task, without any risk of running out of stack space of the fiber-task. <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">Result useALotOfStack() { char buffer[1024*1024]; ... } ... fiberManager.addTask([]() { ... auto result = fibers::runInMainContext([&]() { return useALotOfStack(); }); ... }); ...</pre></div> <tt>fibers::runInMainContext</tt> will switch to the stack of the system thread (main context), run the functor passed to it and then switch back to the fiber-task stack. <div class="remarkup-important">IMPORTANT: Make sure you don't do any blocking calls on main context though. It will suspend the whole system thread, not just the fiber-task which was running.</div> Remember that it's fine to use <tt>fibers::runInMainContext</tt> in general purpose functions (those which may be called both from fiber-task and non from fiber-task). When called in non-fiber-task context <tt>fibers::runInMainContext</tt> would simply execute passed functor right away. <div class="remarkup-note">NOTE: Besides <tt>fibers::runInMainContext</tt> some other functions in folly::fibers are also executing some of the passed functors on the main context. E.g. functor passes to <tt>fibers::await</tt> is executed on main context, finally-functor passed to <tt>FiberManager::addTaskFinally</tt> is also executed on main context etc. Relying on this can help you avoid extra <tt>fibers::runInMainContext</tt> calls (and avoid extra context switches).</div> <h3 id="using-locks">Using locks <a href="#using-locks" class="headerLink">#</a></h3> Consider the following example: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">... folly::EventBase evb; auto& fiberManager = folly::fibers::getFiberManager(evb); std::mutex lock; folly::fibers::Baton baton; fiberManager.addTask([&]() { std::lock_guard<std::mutex> lg(lock); baton.wait(); }); fiberManager.addTask([&]() { std::lock_guard<std::mutex> lg(lock); }); evb.loop(); // We won't get here :( baton.post(); ...</pre></div> First fiber-task will grab a lock and then suspend waiting on a <tt>fibers::Baton</tt>. Then second fiber-task will be run and it will try to grab a lock. Unlike system threads, fiber-task can be only suspended explicitly, so the whole system thread will be blocked waiting on the lock, and we end up with a dead-lock. There're generally two ways we can solve this problem. Ideally we would re-design the program to never not hold any locks when fiber-task is suspended. However if we are absolutely sure we need that lock - folly::fibers library provides some fiber-task-aware lock implementations (e.g. <a href="https://github.com/facebook/folly/blob/master/folly/fibers/TimedMutex.h" target="_blank">TimedMutex</a>).</section><section class="dex_document"><h1>APIs</h1><h2 id="fibers-baton">fibers::Baton <a href="#fibers-baton" class="headerLink">#</a></h2> All of the features of folly::fibers library are actually built on top a single synchronization primitive called Baton. <tt>fibers::Baton</tt> is a fiber-specific version of <tt>folly::Baton</tt>. It only supports two basic operations: <tt>wait()</tt> and <tt>post()</tt>. Whenever <tt>wait()</tt> is called on the Baton, the current thread or fiber-task is suspended, until <tt>post()</tt> is called on the same Baton. <tt>wait()</tt> does not suspend the thread or fiber-task if <tt>post()</tt> was already called on the Baton. Please refer to <a href="https://github.com/facebook/folly/blob/master/folly/fibers/Baton.h" target="_blank">Baton</a> for more detailed documentation. Baton is thread-safe, so <tt>wait()</tt> and <tt>post()</tt> can be (and should be :) ) called from different threads or fiber-tasks. <div class="remarkup-note">NOTE: Because Baton transparently works both on threads and fiber-tasks, any synchronization primitive built using it would have the same property. This means that any library with a synchronous API, which uses only <tt>fibers::Baton</tt> for synchronization, becomes asynchronous when used in fiber context.</div> <h3 id="timed-wait">timed_wait() <a href="#timed-wait" class="headerLink">#</a></h3> <tt>fibers::Baton</tt> also supports wait with timeout. <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([=]() { auto baton = std::make_shared<folly::fibers::Baton>(); auto result = std::make_shared<Result>(); fiberManager.addTask([=]() { *result = sendRequest(...); baton->post(); }); bool success = baton.timed_wait(std::chrono::milliseconds{10}); if (success) { // request successful ... } else { // handle timeout ... } });</pre></div> <div class="remarkup-important">IMPORTANT: unlike <tt>wait()</tt> when using <tt>timed_wait()</tt> API it's generally not safe to pass <tt>fibers::Baton</tt> by reference. You have to make sure that task, which fulfills the Baton is either cancelled in case of timeout, or have shared ownership for the Baton.</div> <h2 id="task-creation">Task creation <a href="#task-creation" class="headerLink">#</a></h2> <h3 id="addtask-addtaskremote">addTask() / addTaskRemote() <a href="#addtask-addtaskremote" class="headerLink">#</a></h3> As you could see from previous examples, the easiest way to create a new fiber-task is to call <tt>addTask()</tt>: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([]() { ... });</pre></div> It is important to remember that <tt>addTask()</tt> is not thread-safe. I.e. it can only be safely called from the the thread, which is running the <tt>folly::FiberManager</tt> loop. If you need to create a fiber-task from a different thread, you have to use <tt>addTaskRemote()</tt>: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">folly::EventBase evb; auto& fiberManager = folly::fibers::getFiberManager(evb); std::thread t([&]() { fiberManager.addTaskRemote([]() { ... }); }); evb.loopForever();</pre></div> <h3 id="addtaskfinally">addTaskFinally() <a href="#addtaskfinally" class="headerLink">#</a></h3> <tt>addTaskFinally()</tt> is useful when you need to run some code on the main context in the end of a fiber-task. <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTaskFinally( [=]() { ... return result; }, [=](Result&& result) { callUserCallbacks(std::move(result), ...) } );</pre></div> Of course you could achieve the same by calling <tt>fibers::runInMainContext()</tt>, but <tt>addTaskFinally()</tt> reduces the number of fiber context switches: <div class="remarkup-code-block" data-code-lang="php"><pre class="remarkup-code">fiberManager.addTask([=]() { ... folly::fibers::runInMainContext([&]() { // Switched to main context callUserCallbacks(<span class="nc" data