{"id":15048058,"url":"https://github.com/volt-software/ichor","last_synced_at":"2025-04-04T12:06:30.055Z","repository":{"id":50610812,"uuid":"240087660","full_name":"volt-software/Ichor","owner":"volt-software","description":"C++20 Microservice Bootstrapping Framework","archived":false,"fork":false,"pushed_at":"2025-01-12T21:28:39.000Z","size":3027,"stargazers_count":215,"open_issues_count":0,"forks_count":13,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-28T11:06:53.931Z","etag":null,"topics":["beast","boost","boost-beast","cmake","coroutine","coroutines","cpp20","cpp20-library","dependency-injection","event-loops","realtime","thread-confinement","thread-safety","threads"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/volt-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["volt-software"]}},"created_at":"2020-02-12T18:41:26.000Z","updated_at":"2025-03-27T15:29:26.000Z","dependencies_parsed_at":"2023-10-04T05:34:00.320Z","dependency_job_id":"efa07afb-ebe4-447a-8fcd-78a8124184de","html_url":"https://github.com/volt-software/Ichor","commit_stats":{"total_commits":340,"total_committers":2,"mean_commits":170.0,"dds":0.00588235294117645,"last_synced_commit":"a8d988481c6b6069d7f27f7d333d24031e548917"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volt-software%2FIchor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volt-software%2FIchor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volt-software%2FIchor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volt-software%2FIchor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/volt-software","download_url":"https://codeload.github.com/volt-software/Ichor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174407,"owners_count":20896076,"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":["beast","boost","boost-beast","cmake","coroutine","coroutines","cpp20","cpp20-library","dependency-injection","event-loops","realtime","thread-confinement","thread-safety","threads"],"created_at":"2024-09-24T21:07:32.861Z","updated_at":"2025-04-04T12:06:30.035Z","avatar_url":"https://github.com/volt-software.png","language":"C++","readme":"![CI](https://github.com/volt-software/Ichor/actions/workflows/cmake.yml/badge.svg)\n[![codecov](https://codecov.io/gh/volt-software/Ichor/branch/main/graph/badge.svg?token=ATIZ63PTFJ)](https://codecov.io/gh/volt-software/Ichor)\n\n# What is this?\n\nIchor, [Greek Mythos for ethereal fluid that is the blood of the gods/immortals](https://en.wikipedia.org/wiki/Ichor), is a C++ framework/middleware for microservices. Ichor allows re-usable services and components to be used in multiple microservices, greatly supporting the workflow for large teams. It also supports reasoning in multithreaded environments, reducing the chances for data races.\n\nTL;DR: Node.js-style event loops with coroutines and dependency injection, except it's C++.\n\nIchor borrows from the concept of [Fearless Concurrency](https://doc.rust-lang.org/book/ch16-00-concurrency.html) and offers thread confinement.\n\n### Boost supports event loops, dependency injection, networking, can do all of that, and more. Any reason i'd want to use your lib instead?\n\nExcellent question! Please see [this page](./docs/04-WhyUseIchor.md) to get a more in-depth answer.\n\n### Thread confinement? Fearless Concurrency?\n\nMultithreading is hard. There exist plenty of methods trying to make it easier, ranging from the [actor framework](https://github.com/actor-framework/actor-framework), [static analysis a la rust](https://doc.rust-lang.org/book/ch16-00-concurrency.html), [software transaction memory](https://en.wikipedia.org/wiki/Software_transactional_memory) and traditional manual lock-wrangling.\n\nThread confinement is one such approach. Instead of having to protect resources, Ichor attempts to make it well-defined on which thread an instance of a C++ class runs and pushes you to only access and modify memory from that thread. Thereby removing the need to think about atomics/mutexes, unless you use threads not managed by, or otherwise trying to circumvent, Ichor.\nIn which case, you're on your own.\n\n### Dependency Injection?\n\nTo support software lifecycles measured in decades, engineers try to encapsulate functionality. Using the [Dependency Injection](./docs/02-DependencyInjection.md) approach allows engineers to insulate updates to parts of the code.\n\nThere exist many Dependency Injection libraries for C++ already, but where those usually only provide Dependency Injection, Ichor also provides service lifecycle management and thread confinement. If a dependency goes away at runtime, e.g. a network client, then all the services depending on it will be cleaned up at that moment. \n\n## Quickstart\n\nThe [minimal example](examples/minimal_example/main.cpp) requires a main function, which initiates at least one event loop, a framework logger and one service and quitting the program gracefully using ctrl+c.\n\nThe [realtime example](examples/realtime_example/main.cpp) shows a trivial program running with realtime priorities and shows some usage of Ichor priorities.\n\nMore examples can be found in the [examples directory](examples).\n\n## Supported OSes\n* Linux (including aarch64 and musl-based distros like alpine linux)\n* Windows\n* Partial support for OSX Monterey (using `brew install llvm`, ASAN in combination with boost beast may result in false positives)\n\n## Supported Compilers\n* Gcc 11.3 or newer (see [this gcc bug](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95137) for why)\n* Clang 14 or newer\n* MSVC 17.4+ (though some workarounds for [some](https://developercommunity.visualstudio.com/t/C2039:-promise_type:-is-not-a-member-o/10505491) [compiler](https://developercommunity.visualstudio.com/t/c20-Friend-definition-of-class-with-re/10197302) [bugs](https://developercommunity.visualstudio.com/t/certain-coroutines-cause-error-C7587:-/10311276?q=%22task+runner%22+gulp+duration\u0026sort=newest) are used)\n\n## Currently Unsupported\n* Baremetal, might change if someone puts in the effort to modify Ichor to work with freestanding implementations of C++20\n* Far out future plans for any RTOS that supports C++20 such as VxWorks Wind River, FreeRTOS\n\n## Building\n\nFor build instructions and required dependencies, please see [GettingStarted](docs/01-GettingStarted.md).\n\n## Documentation\n\nDocumentation can be found in the [docs directory](docs).\n\n### Current design focuses\n\n* code as configuration, as much as possible bundled in one place\n* As much type-safety as possible, prefer compile errors over run-time errors.\n* Well-defined and managed multi-threading to prevent data races and similar issues\n    * Use of an event loop\n    * Where multi-threading is desired, provide easy to use abstractions to prevent issues\n* Performance-oriented design in all-parts of the framework / making it easy to get high performance and low latency\n* Fully utilise OOP, RAII and C++20 Concepts to steer users to using the framework correctly\n* Implement business logic in the least amount of code possible \n* Less error-prone code and better time to market \n\n### Supported features\n\nThe framework provides several core features and optional services behind cmake feature flags:\n* Coroutine-based event loop\n* Event-based message passing\n* Dependency Injection\n* Service lifecycle management (sort of like OSGi-lite services)\n* data race free communication between event loops on multiple threads\n\nOptional services:\n* Websocket service through Boost.BEAST\n* HTTP/HTTPS client and server services through Boost.BEAST\n* Spdlog logging service\n* TCP communication service\n* JSON serialization services examples\n* Timer service\n* Redis service\n* Etcd v2 service\n\n# Roadmap\n\n* EDF scheduling / WCET measurements\n* Look into Etcd v3 HTTP API\n* Pubsub interfaces\n    * Kafka? Pulsar? Ecal?\n* Shell Commands / REPL\n* Tracing interface\n    * Opentracing? Jaeger?\n* \"Remote\" services, where services are either in a different thread or a different machine\n* Code generator to reduce boilerplate\n* ...\n\n# Benchmarks\n\nSee [benchmarks directory](benchmarks)\n\n# Support\n\nFeel free to make issues/pull requests, and I'm sometimes online on Discord: https://discord.gg/r9BtesB\n\nBusiness inquiries can be sent to michael AT volt-software.nl\n\n# FAQ\n\n### I want to have a non-voluntary pre-emption scheduler\n\nBy default, Ichor uses a mutex when inserting/extracting events from its queue. Because non-voluntary user-space scheduling requires lock-free data-structures, this is not possible.\n\n### Is it possible to have a completely stack-based allocation while using C++?\n\nIchor used to have full support for the polymorphic allocators, but as not all compilers support it yet (looking at you libc++) as well as having a negative impact on developer ergonomy, it has been removed.\nInstead, Ichor now recommends usage with [mimalloc](https://github.com/microsoft/mimalloc): \n\n\u003e it does not suffer from blowup, has bounded worst-case allocation times (wcat), bounded space overhead (~0.2% meta-data, with low internal fragmentation), and has no internal points of contention using only atomic operations.\n\n### FreeRTOS? VxWorks Wind River? Baremetal?\n\nWhat is necessary to implement before using Ichor on these platforms:\n* Ichor [STL](include/ichor/stl) functionality, namely the RealtimeMutex and ConditionVariable.\n* Compiler support for C++20 may not be adequate yet.\n* Time / effort.\n\nThe same goes for Wind River. Freestanding implementations might be necessary for Baremetal support, but that would stray rather far from my expertise.\n\n### Why re-implement parts of the STL?\n\nTo add support for `-fno-rtti` while providing the functionality of `std::any` and realtime mutexes (at least on linux).\n\nThe real-time extensions to mutexes (PTHREAD_MUTEX_ADAPTIVE_NP/PTHREAD_PRIO_INHERIT/PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP) are either not a standard extension or not exposed by the standard library equivalents.\n\n# License\n\nIchor is licensed under the MIT license.\n","funding_links":["https://github.com/sponsors/volt-software"],"categories":["Asynchronous Event Loop"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolt-software%2Fichor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolt-software%2Fichor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolt-software%2Fichor/lists"}