Name Date Size #Lines LOC

..--

cmake/H25-Apr-2025-6659

docs/H25-Apr-2025-1,1871,097

examples/H25-Apr-2025-726473

include/marl/H25-Apr-2025-4,6692,817

kokoro/H25-Apr-2025-1,272870

src/H25-Apr-2025-7,1355,025

tools/H25-Apr-2025-306237

.clang-formatH A D25-Apr-2025107 64

.gitignoreH A D25-Apr-202581 98

AUTHORSH A D25-Apr-2025405 109

Android.bpH A D25-Apr-20252 KiB7167

BUILD.bazelH A D25-Apr-20251.6 KiB6964

BUILD.gnH A D25-Apr-20253.1 KiB117108

CHANGES.mdH A D25-Apr-2025216 95

CMakeLists.txtH A D25-Apr-202515.1 KiB426371

CONTRIBUTING.mdH A D25-Apr-20251.1 KiB2820

LICENSEH A D25-Apr-202511.1 KiB202169

README.mdH A D25-Apr-20258.7 KiB235160

WORKSPACEH A D25-Apr-20251.3 KiB3228

go.modH A D25-Apr-202539 42

license-checker.cfgH A D25-Apr-2025668 2827

README.md

1# Marl
2
3Marl is a hybrid thread / fiber task scheduler written in C++ 11.
4
5## About
6
7Marl is a C++ 11 library that provides a fluent interface for running tasks across a number of threads.
8
9Marl uses a combination of fibers and threads to allow efficient execution of tasks that can block, while keeping a fixed number of hardware threads.
10
11Marl supports Windows, macOS, Linux, FreeBSD, Fuchsia, Emscripten, Android and iOS (arm, aarch64, loongarch64, mips64, ppc64, rv64, x86 and x64).
12
13Marl has no dependencies on other libraries (with an exception on googletest for building the optional unit tests).
14
15Example:
16
17```cpp
18#include "marl/defer.h"
19#include "marl/event.h"
20#include "marl/scheduler.h"
21#include "marl/waitgroup.h"
22
23#include <cstdio>
24
25int main() {
26  // Create a marl scheduler using all the logical processors available to the process.
27  // Bind this scheduler to the main thread so we can call marl::schedule()
28  marl::Scheduler scheduler(marl::Scheduler::Config::allCores());
29  scheduler.bind();
30  defer(scheduler.unbind());  // Automatically unbind before returning.
31
32  constexpr int numTasks = 10;
33
34  // Create an event that is manually reset.
35  marl::Event sayHello(marl::Event::Mode::Manual);
36
37  // Create a WaitGroup with an initial count of numTasks.
38  marl::WaitGroup saidHello(numTasks);
39
40  // Schedule some tasks to run asynchronously.
41  for (int i = 0; i < numTasks; i++) {
42    // Each task will run on one of the 4 worker threads.
43    marl::schedule([=] {  // All marl primitives are capture-by-value.
44      // Decrement the WaitGroup counter when the task has finished.
45      defer(saidHello.done());
46
47      printf("Task %d waiting to say hello...\n", i);
48
49      // Blocking in a task?
50      // The scheduler will find something else for this thread to do.
51      sayHello.wait();
52
53      printf("Hello from task %d!\n", i);
54    });
55  }
56
57  sayHello.signal();  // Unblock all the tasks.
58
59  saidHello.wait();  // Wait for all tasks to complete.
60
61  printf("All tasks said hello.\n");
62
63  // All tasks are guaranteed to complete before the scheduler is destructed.
64}
65```
66
67## Benchmarks
68
69Graphs of several microbenchmarks can be found [here](https://google.github.io/marl/benchmarks).
70
71## Building
72
73Marl contains many unit tests and examples that can be built using CMake.
74
75Unit tests require fetching the `googletest` external project, which can be done by typing the following in your terminal:
76
77```bash
78cd <path-to-marl>
79git submodule update --init
80```
81
82### Linux and macOS
83
84To build the unit tests and examples, type the following in your terminal:
85
86```bash
87cd <path-to-marl>
88mkdir build
89cd build
90cmake .. -DMARL_BUILD_EXAMPLES=1 -DMARL_BUILD_TESTS=1
91make
92```
93
94The resulting binaries will be found in `<path-to-marl>/build`
95
96### Emscripten
97
981. install and activate the emscripten sdk following [standard instructions for your platform](https://emscripten.org/docs/getting_started/downloads.html).
992. build an example from the examples folder using emscripten, say `hello_task`.
100```bash
101cd <path-to-marl>
102mkdir build
103cd build
104emcmake cmake .. -DMARL_BUILD_EXAMPLES=1
105make hello_task -j 8
106```
107NOTE: 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.
1083. Test the emscripten output.
109You can use the provided python script to create a local web server:
110```bash
111../run_webserver
112```
113In your browser, navigate to the example URL: [http://127.0.0.1:8080/hello_task.html](http://127.0.0.1:8080/hello_task.html).
114Voilà - you should see the log output appear on the web page.
115
116### Installing Marl (vcpkg)
117
118Alternatively, you can build and install Marl using [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
119
120```bash or powershell
121git clone https://github.com/Microsoft/vcpkg.git
122cd vcpkg
123./bootstrap-vcpkg.sh
124./vcpkg integrate install
125./vcpkg install marl
126```
127
128The 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](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
129
130### Windows
131
132Marl can be built using [Visual Studio 2019's CMake integration](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=vs-2019).
133
134### Using Marl in your CMake project
135
136You can build and link Marl using `add_subdirectory()` in your project's `CMakeLists.txt` file:
137
138```cmake
139set(MARL_DIR <path-to-marl>) # example <path-to-marl>: "${CMAKE_CURRENT_SOURCE_DIR}/third_party/marl"
140add_subdirectory(${MARL_DIR})
141```
142
143This will define the `marl` library target, which you can pass to `target_link_libraries()`:
144
145```cmake
146target_link_libraries(<target> marl) # replace <target> with the name of your project's target
147```
148
149You may also wish to specify your own paths to the third party libraries used by `marl`.
150You can do this by setting any of the following variables before the call to `add_subdirectory()`:
151
152```cmake
153set(MARL_THIRD_PARTY_DIR <third-party-root-directory>) # defaults to ${MARL_DIR}/third_party
154set(MARL_GOOGLETEST_DIR  <path-to-googletest>)         # defaults to ${MARL_THIRD_PARTY_DIR}/googletest
155add_subdirectory(${MARL_DIR})
156```
157
158### Usage Recommendations
159
160#### Capture marl synchronization primitives by value
161
162All marl synchronization primitives aside from `marl::ConditionVariable` should be lambda-captured by **value**:
163
164```c++
165marl::Event event;
166marl::schedule([=]{ // [=] Good, [&] Bad.
167  event.signal();
168})
169```
170
171Internally, 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.
172
173#### Create one instance of `marl::Scheduler`, use it for the lifetime of the process
174
175The `marl::Scheduler` constructor can be expensive as it may spawn a number of hardware threads. \
176Destructing the `marl::Scheduler` requires waiting on all tasks to complete.
177
178Multiple `marl::Scheduler`s may fight each other for hardware thread utilization.
179
180For these reasons, it is recommended to create a single `marl::Scheduler` for the lifetime of your process.
181
182For example:
183
184```c++
185int main() {
186  marl::Scheduler scheduler(marl::Scheduler::Config::allCores());
187  scheduler.bind();
188  defer(scheduler.unbind());
189
190  return do_program_stuff();
191}
192```
193
194#### Bind the scheduler to externally created threads
195
196In 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.
197
198`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()`.
199
200A typical way to pass the scheduler from one thread to another would be:
201
202```c++
203std::thread spawn_new_thread() {
204  // Grab the scheduler from the currently running thread.
205  marl::Scheduler* scheduler = marl::Scheduler::get();
206
207  // Spawn the new thread.
208  return std::thread([=] {
209    // Bind the scheduler to the new thread.
210    scheduler->bind();
211    defer(scheduler->unbind());
212
213    // You can now safely call `marl::schedule()`
214    run_thread_logic();
215  });
216}
217
218```
219
220Always remember to unbind the scheduler before terminating the thread. Forgetting to unbind will result in the `marl::Scheduler` destructor blocking indefinitely.
221
222#### Don't use externally blocking calls in marl tasks
223
224The `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.
225
226Calling 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()`](https://en.cppreference.com/w/cpp/thread/mutex/lock), [`std::condition_variable::wait()`](https://en.cppreference.com/w/cpp/thread/condition_variable/wait), [`accept()`](http://man7.org/linux/man-pages/man2/accept.2.html).
227
228Short 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.
229
230If you need to make a blocking call from a marl worker thread, you may wish to use [`marl::blocking_call()`](https://github.com/google/marl/blob/main/include/marl/blockingcall.h), which will spawn a new thread for performing the call, allowing the marl worker to continue processing other scheduled tasks.
231
232---
233
234Note: This is not an officially supported Google product
235