• Home
Name Date Size #Lines LOC

..--

docs/03-May-2024-1,3121,225

examples/03-May-2024-411245

include/marl/03-May-2024-3,0011,785

kokoro/03-May-2024-301230

src/03-May-2024-5,2113,618

tools/03-May-2024-307238

.clang-formatD03-May-2024195 109

.gitignoreD03-May-202456 66

.gitmodulesD03-May-2024229 76

AUTHORSD03-May-2024405 109

Android.bpD03-May-20241.4 KiB4745

BUILD.bazelD03-May-20241.4 KiB5653

BUILD.gnD03-May-20241.9 KiB7768

CMakeLists.txtD03-May-20248.7 KiB268230

CONTRIBUTING.mdD03-May-20241.1 KiB2820

LICENSED03-May-202411.1 KiB202169

README.mdD03-May-20243.7 KiB12785

WORKSPACED03-May-2024663 1917

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, Fuchsia and Android (arm, aarch64, mips64, ppc64 (ELFv2), 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 the 4 hardware threads.
27  // Bind this scheduler to the main thread so we can call marl::schedule()
28  marl::Scheduler scheduler;
29  scheduler.bind();
30  scheduler.setWorkerThreadCount(4);
31  defer(scheduler.unbind());  // Automatically unbind before returning.
32
33  constexpr int numTasks = 10;
34
35  // Create an event that is manually reset.
36  marl::Event sayHellow(marl::Event::Mode::Manual);
37
38  // Create a WaitGroup with an initial count of numTasks.
39  marl::WaitGroup saidHellow(numTasks);
40
41  // Schedule some tasks to run asynchronously.
42  for (int i = 0; i < numTasks; i++) {
43    // Each task will run on one of the 4 worker threads.
44    marl::schedule([=] {  // All marl primitives are capture-by-value.
45      // Decrement the WaitGroup counter when the task has finished.
46      defer(saidHellow.done());
47
48      printf("Task %d waiting to say hello...\n", i);
49
50      // Blocking in a task?
51      // The scheduler will find something else for this thread to do.
52      sayHellow.wait();
53
54      printf("Hello from task %d!\n", i);
55    });
56  }
57
58  sayHellow.signal();  // Unblock all the tasks.
59
60  saidHellow.wait();  // Wait for all tasks to complete.
61
62  printf("All tasks said hello.\n");
63
64  // All tasks are guaranteed to complete before the scheduler is destructed.
65}
66```
67
68## Building
69
70Marl contains many unit tests and examples that can be built using CMake.
71
72Unit tests require fetching the `googletest` external project, which can be done by typing the following in your terminal:
73
74```bash
75cd <path-to-marl>
76git submodule update --init
77```
78
79### Linux and macOS
80
81To build the unit tests and examples, type the following in your terminal:
82
83```bash
84cd <path-to-marl>
85mkdir build
86cd build
87cmake .. -DMARL_BUILD_EXAMPLES=1 -DMARL_BUILD_TESTS=1
88make
89```
90
91The resulting binaries will be found in `<path-to-marl>/build`
92
93### Windows
94
95Marl 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).
96
97### Using Marl in your CMake project
98
99You can build and link Marl using `add_subdirectory()` in your project's `CMakeLists.txt` file:
100```cmake
101set(MARL_DIR <path-to-marl>) # example <path-to-marl>: "${CMAKE_CURRENT_SOURCE_DIR}/third_party/marl"
102add_subdirectory(${MARL_DIR})
103```
104
105This will define the `marl` library target, which you can pass to `target_link_libraries()`:
106
107```cmake
108target_link_libraries(<target> marl) # replace <target> with the name of your project's target
109```
110
111You may also wish to specify your own paths to the third party libraries used by `marl`.
112You can do this by setting any of the following variables before the call to `add_subdirectory()`:
113
114```cmake
115set(MARL_THIRD_PARTY_DIR <third-party-root-directory>) # defaults to ${MARL_DIR}/third_party
116set(MARL_GOOGLETEST_DIR  <path-to-googletest>)         # defaults to ${MARL_THIRD_PARTY_DIR}/googletest
117add_subdirectory(${MARL_DIR})
118```
119
120## Benchmarks
121
122Graphs of several microbenchmarks can be found [here](https://google.github.io/marl/benchmarks).
123
124---
125
126Note: This is not an officially supported Google product
127