commit | e4e86cff05b2eb36abc345cb3eac5c63d83e3f34 | [log] [tgz] |
---|---|---|
author | Ben Clayton <bclayton@google.com> | Thu Jun 01 10:59:09 2023 +0100 |
committer | Ben Clayton <bclayton@google.com> | Thu Jun 01 10:59:09 2023 +0100 |
tree | ab2cae36d8d422c97a945c1d5f33b2201d6f5bd1 | |
parent | 21b336ccb273c0331477ae7626440f8160b2a4bb [diff] |
Squashed 'third_party/marl/' changes from 9c689c9a8..a089b4aaf a089b4aaf Update tools/bench to handle new Google Benchmark output b98f00446 Use @platforms instead of @bazel_tools a192264a8 Update google benchmark to v1.8.0 4be5115d8 Implement move assignment operator as move ctor already exists f05db401e Core is cheap to copy, pass by reference can hurt performance 40ce132cc Cache workers in variable to speedup access eb2780637 Encapsulate OS stuff in Thread::Impl d2bae7442 Use = default ctor/dtor bodies instead of {} e5ffc9907 remove unnecessary html canvas in example 38743a45a exclude example files from license check 3c9b819ec added license header 47d4a52ac updated copyright year 7b1f567b8 emscripten support: updated readme d5f5f80f8 proper emscripten support - tested on the examples 60d60c682 [build] make it build under emscripten - untested and most likely incorrect runtime behavior. 99646b3c3 Fix Android host build git-subtree-dir: third_party/marl git-subtree-split: a089b4aaf803963f63b1961b4093f76d6db32cdd Change-Id: I51765bc251cd0e5f9af88951bc209e1b48f39067
Marl is a hybrid thread / fiber task scheduler written in C++ 11.
Marl is a C++ 11 library that provides a fluent interface for running tasks across a number of threads.
Marl uses a combination of fibers and threads to allow efficient execution of tasks that can block, while keeping a fixed number of hardware threads.
Marl supports Windows, macOS, Linux, FreeBSD, Fuchsia, Emscripten, Android and iOS (arm, aarch64, loongarch64, mips64, ppc64, rv64, x86 and x64).
Marl has no dependencies on other libraries (with an exception on googletest for building the optional unit tests).
Example:
#include "marl/defer.h" #include "marl/event.h" #include "marl/scheduler.h" #include "marl/waitgroup.h" #include <cstdio> int main() { // Create a marl scheduler using all the logical processors available to the process. // Bind this scheduler to the main thread so we can call marl::schedule() marl::Scheduler scheduler(marl::Scheduler::Config::allCores()); scheduler.bind(); defer(scheduler.unbind()); // Automatically unbind before returning. constexpr int numTasks = 10; // Create an event that is manually reset. marl::Event sayHello(marl::Event::Mode::Manual); // Create a WaitGroup with an initial count of numTasks. marl::WaitGroup saidHello(numTasks); // Schedule some tasks to run asynchronously. for (int i = 0; i < numTasks; i++) { // Each task will run on one of the 4 worker threads. marl::schedule([=] { // All marl primitives are capture-by-value. // Decrement the WaitGroup counter when the task has finished. defer(saidHello.done()); printf("Task %d waiting to say hello...\n", i); // Blocking in a task? // The scheduler will find something else for this thread to do. sayHello.wait(); printf("Hello from task %d!\n", i); }); } sayHello.signal(); // Unblock all the tasks. saidHello.wait(); // Wait for all tasks to complete. printf("All tasks said hello.\n"); // All tasks are guaranteed to complete before the scheduler is destructed. }
Graphs of several microbenchmarks can be found here.
Marl contains many unit tests and examples that can be built using CMake.
Unit tests require fetching the googletest
external project, which can be done by typing the following in your terminal:
cd <path-to-marl> git submodule update --init
To build the unit tests and examples, type the following in your terminal:
cd <path-to-marl> mkdir build cd build cmake .. -DMARL_BUILD_EXAMPLES=1 -DMARL_BUILD_TESTS=1 make
The resulting binaries will be found in <path-to-marl>/build
hello_task
.cd <path-to-marl> mkdir build cd build emcmake cmake .. -DMARL_BUILD_EXAMPLES=1 make hello_task -j 8
NOTE: you want to change the value of the linker flag sPTHREAD_POOL_SIZE
that must be at least as large as the number of threads used by your application. 3. Test the emscripten output. You can use the provided python script to create a local web server:
../run_webserver
In your browser, navigate to the example URL: http://127.0.0.1:8080/hello_task.html.
VoilĂ - you should see the log output appear on the web page.
Alternatively, you can build and install Marl using vcpkg dependency manager:
git clone https://github.com/Microsoft/vcpkg.git cd vcpkg ./bootstrap-vcpkg.sh ./vcpkg integrate install ./vcpkg install marl
The Marl port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.
Marl can be built using Visual Studio 2019's CMake integration.
You can build and link Marl using add_subdirectory()
in your project's CMakeLists.txt
file:
set(MARL_DIR <path-to-marl>) # example <path-to-marl>: "${CMAKE_CURRENT_SOURCE_DIR}/third_party/marl" add_subdirectory(${MARL_DIR})
This will define the marl
library target, which you can pass to target_link_libraries()
:
target_link_libraries(<target> marl) # replace <target> with the name of your project's target
You may also wish to specify your own paths to the third party libraries used by marl
. You can do this by setting any of the following variables before the call to add_subdirectory()
:
set(MARL_THIRD_PARTY_DIR <third-party-root-directory>) # defaults to ${MARL_DIR}/third_party set(MARL_GOOGLETEST_DIR <path-to-googletest>) # defaults to ${MARL_THIRD_PARTY_DIR}/googletest add_subdirectory(${MARL_DIR})
All marl synchronization primitives aside from marl::ConditionVariable
should be lambda-captured by value:
marl::Event event; marl::schedule([=]{ // [=] Good, [&] Bad. event.signal(); })
Internally, these primitives hold a shared pointer to the primitive state. By capturing by value we avoid common issues where the primitive may be destructed before the last reference is used.
marl::Scheduler
, use it for the lifetime of the processThe marl::Scheduler
constructor can be expensive as it may spawn a number of hardware threads.
Destructing the marl::Scheduler
requires waiting on all tasks to complete.
Multiple marl::Scheduler
s may fight each other for hardware thread utilization.
For these reasons, it is recommended to create a single marl::Scheduler
for the lifetime of your process.
For example:
int main() { marl::Scheduler scheduler(marl::Scheduler::Config::allCores()); scheduler.bind(); defer(scheduler.unbind()); return do_program_stuff(); }
In order to call marl::schedule()
the scheduler must be bound to the calling thread. Failure to bind the scheduler to the thread before calling marl::schedule()
will result in undefined behavior.
marl::Scheduler
may be simultaneously bound to any number of threads, and the scheduler can be retrieved from a bound thread with marl::Scheduler::get()
.
A typical way to pass the scheduler from one thread to another would be:
std::thread spawn_new_thread() { // Grab the scheduler from the currently running thread. marl::Scheduler* scheduler = marl::Scheduler::get(); // Spawn the new thread. return std::thread([=] { // Bind the scheduler to the new thread. scheduler->bind(); defer(scheduler->unbind()); // You can now safely call `marl::schedule()` run_thread_logic(); }); }
Always remember to unbind the scheduler before terminating the thread. Forgetting to unbind will result in the marl::Scheduler
destructor blocking indefinitely.
The marl::Scheduler
internally holds a number of worker threads which will execute the scheduled tasks. If a marl task becomes blocked on a marl synchronization primitive, marl can yield from the blocked task and continue execution of other scheduled tasks.
Calling a non-marl blocking function on a marl worker thread will prevent that worker thread from being able to switch to execute other tasks until the blocking function has returned. Examples of these non-marl blocking functions include: std::mutex::lock()
, std::condition_variable::wait()
, accept()
.
Short blocking calls are acceptable, such as a mutex lock to access a data structure. However be careful that you do not use a marl blocking call with a std::mutex
lock held - the marl task may yield with the lock held, and block other tasks from re-locking the mutex. This sort of situation may end up with a deadlock.
If you need to make a blocking call from a marl worker thread, you may wish to use marl::blocking_call()
, which will spawn a new thread for performing the call, allowing the marl worker to continue processing other scheduled tasks.
Note: This is not an officially supported Google product