{"id":13434838,"url":"https://github.com/alibaba/async_simple","last_synced_at":"2025-05-14T02:04:46.456Z","repository":{"id":36959810,"uuid":"460260102","full_name":"alibaba/async_simple","owner":"alibaba","description":"Simple, light-weight and easy-to-use asynchronous components ","archived":false,"fork":false,"pushed_at":"2025-04-28T02:51:16.000Z","size":8384,"stargazers_count":1897,"open_issues_count":22,"forks_count":272,"subscribers_count":35,"default_branch":"main","last_synced_at":"2025-04-28T03:30:33.992Z","etag":null,"topics":["asynchronous","coroutines","cpp20","cpp20-modules","modules"],"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/alibaba.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","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,"zenodo":null}},"created_at":"2022-02-17T02:57:14.000Z","updated_at":"2025-04-28T02:51:20.000Z","dependencies_parsed_at":"2022-07-14T07:10:29.983Z","dependency_job_id":"63abb141-5d5b-4145-8a74-efcb2a956bdf","html_url":"https://github.com/alibaba/async_simple","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fasync_simple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fasync_simple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fasync_simple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alibaba%2Fasync_simple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alibaba","download_url":"https://codeload.github.com/alibaba/async_simple/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052668,"owners_count":22006716,"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":["asynchronous","coroutines","cpp20","cpp20-modules","modules"],"created_at":"2024-07-31T03:00:24.748Z","updated_at":"2025-05-14T02:04:46.407Z","avatar_url":"https://github.com/alibaba.png","language":"C++","funding_links":[],"categories":["HarmonyOS","C++","网络"],"sub_categories":["Windows Manager"],"readme":"\u003cp align=\"center\"\u003e\n\u003ch1 align=\"center\"\u003easync_simple\u003c/h1\u003e\n\u003ch6 align=\"center\"\u003eA Simple, Light-Weight Asynchronous C++ Framework\u003c/h6\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"license\" src=\"https://img.shields.io/github/license/alibaba/async_simple?style=flat-square\"\u003e\n\u003cimg alt=\"language\" src=\"https://img.shields.io/github/languages/top/alibaba/async_simple?style=flat-square\"\u003e\n\u003cimg alt=\"feature\" src=\"https://img.shields.io/badge/c++20-Coroutines-orange?style=flat-square\"\u003e\n\u003cimg alt=\"last commit\" src=\"https://img.shields.io/github/last-commit/alibaba/async_simple?style=flat-square\"\u003e\n\u003c/p\u003e\n\nEnglish | [中文](./README_CN.md)\n\nasync_simple is a library offering simple, light-weight and easy-to-use\ncomponents to write asynchronous code. The components offered include Lazy\n(based on C++20 stackless coroutine), Uthread (based on stackful coroutine)\nand the traditional Future/Promise.\n\n# Quick Experience\n\nWe can try async_simple online in [compiler-explorer](compiler-explorer.com): https://compiler-explorer.com/z/Tdaesqsqj . Note that `Uthread` cannot be use in compiler-explorer since it requires installation.\n\n# Get Started\n\nOur documents are hosted by GitHub Pages, [go to Get Started](https://alibaba.github.io/async_simple/docs.en/GetStarted.html).\n\nAfter installing and reading [Lazy](./docs/docs.en/Lazy.md) to get familiar with API, here is a [demo](./docs/docs.en/GetStarted.md) use Lazy to count char in a file.\n\n# Install async_simple\n\n## By Vcpkg\n\nvcpkg is a [cross-platform package manager](https://vcpkg.io/en/getting-started).\n\n```\n./vcpkg install async-simple\n```\n\n## By Cmake\n\n```\ngit clone -b main --single-branch --depth 1 https://github.com/alibaba/async_simple.git\ncd async_simple\nmkdir build\ncd build\ncmake .. -DASYNC_SIMPLE_ENABLE_TESTS=OFF -DASYNC_SIMPLE_BUILD_DEMO_EXAMPLE=OFF -DASYNC_SIMPLE_ENABLE_ASAN=OFF\ncmake --build .\ncmake --install . # --prefix ./user_defined_install_path\n```\n\n# Import async_simple\n\nAfter install async_simple, you can import it to your project.\n\n## By cmake find_package\n\nPlease add those cmake code:\n\n```cmake\nfind_package(async_simple REQUIRED)\ntarget_link_libraries(\u003cyour-target-name\u003e PRIVATE async_simple::async_simple) # dynamic_link\n                                 # async_simple::async_simple_header_only\n                                 # async_simple::async_simple_static\n```\n`\u003cyour-target-name\u003e` is the target name which want to use async_simple\n\n## Manually\n\nasync_simple is almost header-only. So you can just pass the include path of the install position to your compiler.\n\nBut the uthread part of async_simple is not head-only. If you want to use uthread, You need link it manually. The library file is in the install path.\n\n# Compiler Requirement\n\nRequired Compiler: clang (\u003e= 10.0.0) or gcc (\u003e= 10.3) or Apple-clang (\u003e= 14)\n\nNote that we need to add the `-Wno-maybe-uninitialized` option when we use gcc 12 due to a false positive diagnostic message by gcc 12\n\nIf you're using `async_simple::Generator`, there may be some compiler bugs in clang15. We suggest to use clang17 or higher for that.\n\nIf you meet any problem about MSVC Compiler Error C4737. Try to add the /EHa option to fix the problem.\n\n# Develop async_simple\n\nThe build of async_simple requires libaio, googletest and cmake.  Both libaio and googletest\nare optional. (Testing before using is highly suggested.) By default, async_simple would try\nto clone the googletest from git to make sure the version used is correct. But in case the\nusers have problems with networks, users can try to install the gtest libraries by the following instructions and use the CMake variables ('GMOCK_INCLUDE_DIR', 'GTEST_LIBRARIES', 'GMOCK_INCLUDE_DIR', 'GMOCK_LIBRARIES') to specify the location.\n\n## Using apt (Ubuntu and Debian)\n\n```bash\n# Install libaio\nsudo apt install libaio-dev -y\n# Install cmake\nsudo apt install cmake -y\n# Install bazel See: https://bazel.build/install/ubuntu\n```\n- Use `apt` to install gtest and gmock\n```bash\nsudo apt install -y libgtest-dev libgmock-dev\n```\n\n- [Try to build gtest and gmock from source](#Build-Dependencies-From-Source)\n```bash\n# Install gtest\nsudo apt install libgtest-dev -y\nsudo apt install cmake -y\ncd /usr/src/googletest/gtest\nsudo mkdir build \u0026\u0026 cd build\nsudo cmake .. \u0026\u0026 sudo make install\ncd .. \u0026\u0026 sudo rm -rf build\ncd /usr/src/googletest/gmock\nsudo mkdir build \u0026\u0026 cd build\nsudo cmake .. \u0026\u0026 sudo make install\ncd .. \u0026\u0026 sudo rm -rf build\n\n# Install bazel See: https://bazel.build/install/ubuntu\n```\n\n## Using yum (CentOS and Fedora)\n```bash\n# Install libaio\nsudo yum install libaio-devel -y\n```\n- Use `yum` to install gtest, gmock\n```\nsudo yum install gtest-devel gmock-devel\n```\n- [Try to build gtest and gmock from source](#Build-Dependencies-From-Source)\n\n## Using Pacman (Arch)\n```bash\n# Optional\nsudo pacman -S libaio\n# Use cmake to build project\nsudo pacman -S cmake gtest\n# Use bazel to build project\nsudo pacman -S bazel\n```\n\n\n## Using Homebrew (macOS)\n\n```bash\n# Use cmake to build project\nbrew install cmake\nbrew install googletest\n# Use bazel to build project\nbrew install bazel\n```\n\n\n## Windows\n```powershell\n# Install cmake\nwinget install cmake\n# Install google-test\n# TODO\n# Install bazel See: https://bazel.build/install/windows\n```\n\n## Build Dependencies From Source\n\n```\n# libaio (optional)\n# you can skip this if you install libaio from packages\ngit clone https://pagure.io/libaio.git\ncd libaio\nsudo make install\n# gmock and gtest\ngit clone git@github.com:google/googletest.git -b v1.8.x\ncd googletest\nmkdir build \u0026\u0026 cd build\ncmake .. \u0026\u0026 sudo make install\n```\n\n\n## Demo example dependency\n\nDemo example depends on standalone asio(https://github.com/chriskohlhoff/asio/tree/master/asio), the commit id:f70f65ae54351c209c3a24704624144bfe8e70a3\n\n# Build\n\n## cmake\n```bash\n$ mkdir build \u0026\u0026 cd build\n# Specify [-DASYNC_SIMPLE_ENABLE_TESTS=OFF] to skip tests.\n# Specify [-DASYNC_SIMPLE_BUILD_DEMO_EXAMPLE=OFF] to skip build demo example.\n# Specify [-DASYNC_SIMPLE_DISABLE_AIO=ON] to skip the build libaio\nCXX=clang++ CC=clang cmake ../ -DCMAKE_BUILD_TYPE=[Release|Debug] [-DASYNC_SIMPLE_ENABLE_TESTS=OFF] [-DASYNC_SIMPLE_BUILD_DEMO_EXAMPLE=OFF] [-DASYNC_SIMPLE_DISABLE_AIO=ON] [-DGMOCK_INCLUDE_DIR=\u003cpath-to-headers of gtest\u003e -DGTEST_INCLUDE_DIR=\u003cpath-to-headers of mock\u003e -DGTEST_LIBRARIES=\u003cpath-to-library-of-gtest\u003e  -DGMOCK_LIBRARIES=\u003cpath-to-library-of-gmock\u003e ]\n# for gcc, use CXX=g++ CC=gcc\nmake -j4\nmake test # optional\nmake install # sudo if required\n```\n\nConan is also supported. You can install async_simple to conan local cache.\n```\nmkdir build \u0026\u0026 cd build\nconan create ..\n```\n\n## bazel\n```bash\n# Specify [--define=ASYNC_SIMPLE_DISABLE_AIO=true] to skip the build libaio\n# Example bazel build --define=ASYNC_SIMPLE_DISABLE_AIO=true ...\nbazel build ...                      # compile all target\nbazel build ...:all                  # compile all target\nbazel build ...:*                    # compile all target\nbazel build -- ... -benchmarks/...   # compile all target except those beneath `benchmarks`\nbazel test ...                       # compile and execute tests\n# Specify compile a target\n# Format: bazel [build|test|run] [directory name]:[binary name]\n# Example\nbazel build :async_simple           # only compile libasync_simple\nbazel run benchmarks:benchmarking   # compile and run benchmark\nbazel test async_simple/coro/test:async_simple_coro_test\n# Use clang toolchain\nbazel build --action_env=CXX=clang++ --action_env=CC=clang ...\n# Add compile option\nbazel build --copt='-O0' --copt='-ggdb' ...\n# Extracts compile_commands.json\n# If you want to specify additional flags for targets, please refer to:\n# https://github.com/hedronvision/bazel-compile-commands-extractor\nbazel run @hedron_compile_commands//:refresh_all\n```\n- See [this](https://bazel.build/run/build) to get more information\n- ` ...` Indicates recursively scan all targets, recognized as `../..` in `oh-my-zsh`, can be replaced by other `shell` or `bash -c 'commond'` to run, such as `bash -c 'bazel build' ...` or use `bazel build ...:all`\n- Use `async_simple` as a dependency, see also [bazel support](bazel/support/README.md)\n\n# Docker Compile Environment\n```\ngit clone https://github.com/alibaba/async_simple.git\ncd async_simple/docker/(ubuntu|centos7|rockylinux)\ndocker build . --no-cache -t async_simple:1.0\ndocker run -it --name async_simple async_simple:1.0 /bin/bash\n```\n\n# Performance\n\nWe also give a [Quantitative Analysis Report](docs/docs.en/QuantitativeAnalysisReportOfCoroutinePerformance.md) of\nLazy (based on C++20 stackless coroutine) and Uthread (based on stackful coroutine).\n\n# C++20 Modules Support\n\nWe have **experimental** support for C++20 Modules in `modules/async_simple.cppm`.\nWe can build the `async_simple` module by `xmake` and `cmake`.\nWe can find the related usage in `CountChar`, `ReadFiles`, `LazyTest.cpp` and `FutureTest.cpp`.\n\nWe need clang (\u003e= d18806e6733 or simply clang 16) to build the `async_simple` module.\nIt is only tested for libstdc++10.3. Due to the current support status for C++20, it won't be a surprise if the compilation fails in higher versions of STL.\n\nWe can build the `async_simple` module with xmake (\u003e= 0eccc6e) using the commands:\n\n```\nxmake\n```\n\nWe can build the `async_simple` module with cmake (\u003e= d18806e673 or cmake 3.26 and up) using the following commands:\n\n```\nmkdir build_modules \u0026\u0026 cd build_modules\nCC=clang CXX=clang++ cmake .. -DCMAKE_BUILD_TYPE=Release -DASYNC_SIMPLE_BUILD_MODULES=ON -GNinja\nninja\n```\n\nIf std module is available, we can define `-DSTD_MODULE_AVAILABLE=ON` when configuring cmake to use std modules provided by vendors.\n\n**Note** that the `async_simple` module in the main branch is actually a named module's wrapper for headers for compatibility. We can find the practical usage of C++20 Modules in https://github.com/alibaba/async_simple/tree/CXX20Modules, which contains the support for xmake and cmake as well.\n\n# Questions\n\nFor questions, we suggest to read [docs](./docs/docs.en), [issues](https://github.com/alibaba/async_simple/issues)\nand [discussions](https://github.com/alibaba/async_simple/discussions) first.\nIf there is no satisfying answer, you could file an [issues](https://github.com/alibaba/async_simple/issues)\nor start a thread in [discussions](https://github.com/alibaba/async_simple/discussions).\nSpecifically, for defect report or feature enhancement, it'd be better to file an [issues](https://github.com/alibaba/async_simple/issues). And for how-to-use questions, it'd be better to start a thread in [discussions](https://github.com/alibaba/async_simple/discussions).\n\n# How to Contribute\n1. Read the [How to fix issue](./docs/docs.en/HowToFixIssue.md) document firstly.\n2. Run tests and `git-clang-format HEAD^` locally for the change. Note that the  version of clang-format in CI is clang-format 14. So that it is possible your local\nformat result is inconsistency with the format result in the CI. In the case, you need to install the new clang-format or adopt the suggested change by hand. In case the format result is not good, it is OK to accept the PR temporarily and file an issue for the clang-formt.\n3. Create a PR, fill in the PR template.\n4. Choose one or more reviewers from contributors: (e.g., ChuanqiXu9, RainMark, foreverhy, qicosmos).\n5. Get approved and merged.\n\n# License\n\nasync_simple is distributed under the Apache License (Version 2.0)\nThis product contains various third-party components under other open source licenses.\nSee the NOTICE file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fasync_simple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falibaba%2Fasync_simple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falibaba%2Fasync_simple/lists"}