{"id":25430441,"url":"https://github.com/longhao-li/onion","last_synced_at":"2025-05-14T12:19:40.198Z","repository":{"id":277285606,"uuid":"922474359","full_name":"longhao-li/onion","owner":"longhao-li","description":"A lightweight and easy to use async IO library implemented with C++20 coroutine.","archived":false,"fork":false,"pushed_at":"2025-02-13T05:04:44.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-13T06:20:32.771Z","etag":null,"topics":["async","cpp","cpp-coroutines","cpp23","io-uring","iocp","socket-io"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/longhao-li.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2025-01-26T10:09:47.000Z","updated_at":"2025-02-13T05:04:47.000Z","dependencies_parsed_at":"2025-02-13T06:20:35.963Z","dependency_job_id":"63897b1e-ba40-4b60-8cbe-56db29bf475d","html_url":"https://github.com/longhao-li/onion","commit_stats":null,"previous_names":["longhao-li/onion"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longhao-li%2Fonion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longhao-li%2Fonion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longhao-li%2Fonion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longhao-li%2Fonion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/longhao-li","download_url":"https://codeload.github.com/longhao-li/onion/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239228287,"owners_count":19603585,"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":["async","cpp","cpp-coroutines","cpp23","io-uring","iocp","socket-io"],"created_at":"2025-02-17T03:28:19.902Z","updated_at":"2025-02-17T03:28:20.722Z","avatar_url":"https://github.com/longhao-li.png","language":"C++","readme":"# onion\n\n`onion` is a easy-to-use and high-performance general purpose asynchronous IO framework using C++20 coroutine, which aims to provide a flexible and efficient way to handle asynchronous file IO, network communications and more.\n\n## Getting Started\n\n### Build Requirement\n\n- CMake \u003e= 3.20\n- For Linux:\n    - Any distribution with kernel version \u003e= 5.12.\n    - GCC \u003e= 12 or clang \u003e= 18\n    - System liburing package. For Debian-based distributions, this is usually the liburing-dev package.\n- For Windows:\n    - Windows Vista, Windows Server 2008 or later version\n    - `onion` supports building with both MSVC and clang on Windows. Visual Studio 2022 is required to build with MSVC, and clang \u003e= 18 is required to build with clang.\n\n### Build Options\n\nUse `-DONION_BUILD_SHARED_LIBS=ON` to build `onion` as shared library. Please notice that `BUILD_SHARED_LIBS` option does not affect `onion`.\n\nUse `-DONION_BUILD_TESTS=ON` to build unit tests. Unit tests requires [doctest](https://github.com/doctest/doctest). The build script will automatically fetch [doctest](https://github.com/doctest/doctest) from GitHub if it is not found on the system.\n\nUse `-DONION_BUILD_EXAMPLES=ON` to build examples. Please notice that the examples requires GCC version \u003e= 14 for `std::print` support.\n\nSee [CMakeLists.txt](./CMakeLists.txt) for other build options.\n\n### Basic Usage\n\n`onion::Task\u003cT\u003e` is used for general-purpose coroutine. Coroutines should always return `onion::Task\u003cT\u003e`. to support async operations. Here is a minimal example:\n\n```cpp\n#include \"onion/io_context.hpp\"\n\n#include \u003cformat\u003e\n#include \u003cprint\u003e\n\nusing namespace onion;\n\nauto hello() noexcept -\u003e Task\u003c\u003e {\n    std::println(\"Hello, world!\");\n    co_return;\n}\n\nauto greetings(std::string name) noexcept -\u003e Task\u003cstd::string\u003e {\n    co_return std::format(\"Greetings, {}!\", name);\n}\n\nauto main() -\u003e int  {\n    // Coroutines need a context to be scheduled.\n    // IoContext works as a static thread pool. Number of threads will be determined by std::thread::hardware_concurrency().\n    IoContext ctx;\n\n    // Schedule work to I don't know which thread.\n    ctx.schedule(hello());\n    ctx.schedule(greetings(\"world\"));\n\n    // Dispatch hello() to all worker threads.\n    ctx.dispatch(hello);\n\n    // Block and wait. Usually, this method could be considered as a noreturn function.\n    ctx.start();\n}\n```\n\nIf you want to generate new task to run concurrently with current task, please consider using `onion::schedule`:\n\n```cpp\nauto foo() -\u003e Task\u003c\u003e {\n    // do something.\n}\n\nauto bar() -\u003e Task\u003c\u003e {\n    // schedule never suspends current coroutine and there is no mutex lock operation.\n    co_await schedule(foo());\n}\n```\n\nYou might also use `ctx.schedule(foo())` to do the same thing, but `IoContext::schedule` requires mutex operations, but `onion::schedule` does not.\n\nOne example is the [TCP echo server](./examples/tcp_echo/main.cpp). The acceptor schedules a server coroutine for each incoming connection.\n\n### Asynchronous IO\n\nFor async TCP IO operations, please see [TCP echo server](./examples/tcp_echo/main.cpp) for details. Asynchronous UDP and file are still in-progress.\n\n## License\n\nBSD 3-Clause License. See [LICENSE](./LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flonghao-li%2Fonion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flonghao-li%2Fonion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flonghao-li%2Fonion/lists"}