{"id":19168425,"url":"https://github.com/bloomberg/quantum","last_synced_at":"2025-04-13T04:59:52.871Z","repository":{"id":33920566,"uuid":"140625429","full_name":"bloomberg/quantum","owner":"bloomberg","description":"Powerful multi-threaded coroutine dispatcher and parallel execution engine","archived":false,"fork":false,"pushed_at":"2024-08-23T19:06:07.000Z","size":2769,"stargazers_count":590,"open_issues_count":9,"forks_count":100,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-13T04:59:46.695Z","etag":null,"topics":["boost","coroutines","cpp","multi-threading","parallel"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-11T20:40:04.000Z","updated_at":"2025-04-01T20:27:52.000Z","dependencies_parsed_at":"2024-11-09T09:42:47.509Z","dependency_job_id":"117fc43a-857d-40dc-b281-3a360137a0a1","html_url":"https://github.com/bloomberg/quantum","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fquantum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fquantum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fquantum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Fquantum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/quantum/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665756,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boost","coroutines","cpp","multi-threading","parallel"],"created_at":"2024-11-09T09:42:37.882Z","updated_at":"2025-04-13T04:59:52.852Z","avatar_url":"https://github.com/bloomberg.png","language":"C++","readme":"# Quantum Library : A scalable C++ coroutine framework\n[![Build status](https://travis-ci.com/bloomberg/quantum.svg?branch=master)](https://travis-ci.org/bloomberg/quantum) \n\n**Quantum** is a full-featured and powerful C++ framework build on top of the [Boost coroutine](https://www.boost.org/doc/libs/1_65_0/libs/coroutine2/doc/html/index.html) library. The framework allows users to dispatch units of work (a.k.a. _tasks_) as coroutines and execute them concurrently using the 'reactor' pattern.\n\n### Features\n\n* **NEW** Added support for simpler V2 coroutine API which returns computed values [directly](https://github.com/bloomberg/quantum/wiki/4.-Quick-reference-guide).\n* Header-only library and interface-based design.\n* Full integration with Boost asymmetric coroutine library.\n* Highly parallelized coroutine framework for CPU-bound workloads.\n* Support for long-running or blocking IO tasks.\n* Allows explicit and implicit cooperative yielding between coroutines.\n* Task continuations and coroutine chaining for serializing work execution.\n* Synchronous and asynchronous dispatching using futures and promises similar to STL.\n* Support for _streaming futures_ which allows faster processing of large data sets.\n* Support for _future references_.\n* Cascading execution output during task continuations (a.k.a. _past_ futures).\n* Task prioritization.\n* Internal error handling and exception forwarding.\n* Ability to write lock-free code by synchronizing coroutines on dedicated queues.\n* Coroutine-friendly mutexes and condition variables for locking critical code paths or synchronizing access to external objects.\n* Fast pre-allocated memory pools for internal objects and coroutines.\n* Parallel `forEach` and `mapReduce` functions.\n* Various stats API.\n* `Sequencer` class allowing strict FIFO ordering of tasks based on sequence ids.\n\n### Sample code\n**Quantum** is very simple and easy to use:\n```c++\nusing namespace Bloomberg::quantum;\n\n// Define a coroutine\nint getDummyValue(CoroContextPtr\u003cint\u003e ctx)\n{\n    int value;\n    ...           //do some work\n    ctx-\u003eyield(); //be nice and let other coroutines run (optional cooperation)\n    ...           //do more work and calculate 'value'\n    return ctx-\u003eset(value);\n}\n\n// Create a dispatcher\nDispatcher dispatcher;\n\n// Dispatch a work item to do some work and return a value\nint result = dispatcher.post(getDummyValue)-\u003eget();\n```\n\nChaining tasks can also be straightforward. In this example we produce various types in a sequence.\n```c++\nusing namespace Bloomberg::quantum;\n\n// Create a dispatcher\nDispatcher dispatcher;\n\nauto ctx = dispatcher.postFirst([](CoroContextPtr\u003cint\u003e ctx)-\u003eint {\n    return ctx-\u003eset(55); //Set the 1st value\n})-\u003ethen([](CoroContextPtr\u003cdouble\u003e ctx)-\u003eint {\n    // Get the first value and add something to it\n    return ctx-\u003eset(ctx-\u003egetPrev\u003cint\u003e() + 22.33); //Set the 2nd value\n})-\u003ethen([](CoroContextPtr\u003cstd::string\u003e ctx)-\u003eint {\n    return ctx-\u003eset(\"Hello world!\"); //Set the 3rd value\n})-\u003efinally([](CoroContextPtr\u003cstd::list\u003cint\u003e\u003e ctx)-\u003eint {\n    return ctx-\u003eset(std::list\u003cint\u003e{1,2,3}); //Set 4th value\n})-\u003eend();\n\nint i = ctx-\u003egetAt\u003cint\u003e(0); //This will throw 'FutureAlreadyRetrievedException'\n                            //since future was already read in the 2nd coroutine\ndouble d = ctx-\u003egetAt\u003cdouble\u003e(1); //returns 77.33\nstd::string s = ctx-\u003egetAt\u003cstd::string\u003e(2); //returns \"Hello world!\";\nstd::list\u003cint\u003e\u0026 listRef = ctx-\u003egetRefAt\u003cstd::list\u003cint\u003e\u003e(3); //get list reference\nstd::list\u003cint\u003e\u0026 listRef2 = ctx-\u003egetRef(); //get another list reference.\n                                          //The 'At' overload is optional for last chain future\nstd::list\u003cint\u003e listValue = ctx-\u003eget(); //get list value\n```\nChaining with the **new** V2 api:\n```c++\nusing namespace Bloomberg::quantum;\n\n// Create a dispatcher\nDispatcher dispatcher;\n\nauto ctx = dispatcher.postFirst([](VoidContextPtr ctx)-\u003eint {\n    return 55; //Set the 1st value\n})-\u003ethen([](VoidContextPtr ctx)-\u003edouble {\n    // Get the first value and add something to it\n    return ctx-\u003egetPrev\u003cint\u003e() + 22.33; //Set the 2nd value\n})-\u003ethen([](VoidContextPtr ctx)-\u003estd::string {\n    return \"Hello world!\"; //Set the 3rd value\n})-\u003efinally([](VoidContextPtr ctx)-\u003estd::list\u003cint\u003e {\n    return {1,2,3}; //Set 4th value\n})-\u003eend();\n```\n\n### Building and installing\n**Quantum** is a header-only library and as such no targets need to be built. To install simply run:\n```shell\n\u003e cmake -Bbuild \u003coptions\u003e .\n\u003e cd build\n\u003e make install\n```\n\n### CMake options\nVarious **CMake** options can be used to configure the output:\n* `QUANTUM_BUILD_DOC`        : Build Doxygen documentation. Default `OFF`.\n* `QUANTUM_ENABLE_DOT`       : Enable generation of DOT viewer files. Default `OFF`.\n* `QUANTUM_VERBOSE_MAKEFILE` : Enable verbose cmake output. Default `ON`.\n* `QUANTUM_ENABLE_TESTS`     : Builds the `tests` target. Default `OFF`.\n* `QUANTUM_BOOST_STATIC_LIBS`: Link with Boost static libraries. Default `ON`.\n* `QUANTUM_BOOST_USE_MULTITHREADED` : Use Boost multi-threaded libraries. Default `ON`.\n* `QUANTUM_USE_DEFAULT_ALLOCATOR` : Use default system supplied allocator instead of Quantum's. Default `OFF`.\n* `QUANTUM_ALLOCATE_POOL_FROM_HEAP` : Pre-allocates object pools from heap instead of the application stack. Default `OFF`.\n* `QUANTUM_BOOST_USE_SEGMENTED_STACKS` : Use Boost segmented stacks for coroutines. Default `OFF`.\n* `QUANTUM_BOOST_USE_PROTECTED_STACKS` : Use Boost protected stacks for coroutines (slow!). Default `OFF`.\n* `QUANTUM_BOOST_USE_FIXEDSIZE_STACKS` : Use Boost fixed size stacks for coroutines. Default `OFF`.\n* `QUANTUM_INSTALL_ROOT`     : Specify custom install path.\n                               Default is `/usr/local/include` for Linux or `c:/Program Files` for Windows.\n* `QUANTUM_PKGCONFIG_DIR`    : Specify custom install path for the `quantum.pc` file. Default is `${QUANTUM_INSTALL_ROOT}/share/pkgconfig`.\n                               To specify a relative path from `QUANTUM_INSTALL_ROOT`, omit leading `/`. \n* `QUANTUM_EXPORT_PKGCONFIG` : Generate `quantum.pc` file. Default `ON`.\n* `QUANTUM_CMAKE_CONFIG_DIR` : Specify a different install directory for the project's config, target and version files. Default is `${QUANTUM_INSTALL_ROOT}/share/cmake`.\n* `QUANTUM_EXPORT_CMAKE_CONFIG` : Generate CMake config, target and version files. Default `ON`.\n* `BOOST_ROOT`               : Specify a different Boost install directory.\n* `GTEST_ROOT`               : Specify a different GTest install directory.\n\nNote: options must be preceded with `-D` when passed as arguments to CMake.\n\n### Running tests\nRun the following from the top directory:\n```shell\n\u003e cmake -Bbuild -DQUANTUM_ENABLE_TESTS=ON \u003coptions\u003e .\n\u003e cd build\n\u003e make quantum_test \u0026\u0026 ctest\n```\n\n### Using\nTo use the library simply include `\u003cquantum/quantum.h\u003e` in your application. Also, the following libraries must be included in the link:\n* `boost_context`\n* `pthread`\n\n**Quantum** library is fully is compatible with `C++11`, `C++14` and `C++17` language features. See compiler options below for more details.\n\n### Compiler options\nThe following compiler options can be set when building your application:\n* `__QUANTUM_PRINT_DEBUG` : Prints debug and error information to `stdout` and `stderr` respectively.\n* `__QUANTUM_USE_DEFAULT_ALLOCATOR` : Disable pool allocation for internal objects (other than coroutine stacks) and\nuse default system allocators instead.\n* `__QUANTUM_ALLOCATE_POOL_FROM_HEAP` : Pre-allocates object pools from heap instead of the application stack (default).\nThis affects internal object allocations other than coroutines. Coroutine pools are always heap-allocated due to their size.\n* `__QUANTUM_BOOST_USE_SEGMENTED_STACKS` : Uses boost segmented stack for on-demand coroutine stack growth. Note that\n**Boost.Context** library must be built with property `segmented-stacks=on` and applying `BOOST_USE_UCONTEXT` and\n`BOOST_USE_SEGMENTED_STACKS` at b2/bjam command line.\n* `__QUANTUM_BOOST_USE_PROTECTED_STACKS` : Uses boost protected stack for runtime bound-checking. When using this option,\ncoroutine creation (but not runtime efficiency) becomes more expensive.\n* `__QUANTUM_BOOST_USE_FIXEDSIZE_STACKS` : Uses boost fixed size stack. This defaults to system default allocator.\n                                        \n### Application-wide settings\nVarious application-wide settings can be configured via `ThreadTraits`, `AllocatorTraits` and `StackTraits`.\n\n### Documentation\nPlease see the [wiki](https://github.com/bloomberg/quantum/wiki) page for a detailed overview of this library, use-case scenarios and examples.\n\nFor class description visit the [API reference](https://bloomberg.github.io/quantum) page.\n","funding_links":[],"categories":["Concurrency"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fquantum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Fquantum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Fquantum/lists"}