async_simple

A Simple, Light-Weight Asynchronous C++ Framework

English | 中文

The async_simple is a library offering simple, light-weight and easy-to-use components to write asynchronous codes. The components offered include the Lazy (based on C++20 stackless coroutine), the Uthread (based on stackful coroutine) and the traditional Future/Promise.

Install Dependencies

The build of async_simple need libaio, googletest and cmake. Both libaio and googletest are optional. (Testing before using is highly suggested.)

Using apt (ubuntu and debian's)

# Install libaio
sudo apt install libaio-dev -y
# Install cmake
sudo apt install cmake -y
# Install bazel See: https://bazel.build/install/ubuntu

using apt to install gtest, gmock

sudo apt install -y libgtest-dev libgmock-dev

Try to build gtest and gmock from source

# Install gtest
sudo apt install libgtest-dev -y
sudo apt install cmake -y
cd /usr/src/googletest/gtest
sudo mkdir build && cd build
sudo cmake .. && sudo make install
cd .. && sudo rm -rf build
cd /usr/src/googletest/gmock
sudo mkdir build && cd build
sudo cmake .. && sudo make install
cd .. && sudo rm -rf build

# Install bazel See: https://bazel.build/install/ubuntu

Using yum (CentOS and Fedora)

# Install libaio
sudo yum install libaio-devel -y

Using yum to install gtest, gmock

sudo yum install gtest-devel gmock-devel

Try to build gtest and gmock from source

Using Pacman (Arch)

# Optional
sudo pacman -S libaio
# Use cmake to build project
sudo pacman -S cmake gtest
# Use bazel to build project
sudo pacman -S bazel

Using Homebrew (macOS)

# Use cmake to build project
brew install cmake
brew install googletest
# Use bazel to build project
brew install bazel

Windows

# Install cmake
winget install cmake
# Install google-test
# TODO
# Install bazel See: https://bazel.build/install/windows

Build Dependencies From Source

# libaio (optional)
# you can skip this if you install libaio from packages
git clone https://pagure.io/libaio.git
cd libaio
sudo make install
# gmock and gtest
git clone git@github.com:google/googletest.git -b v1.8.x
cd googletest
mkdir build && cd build
cmake .. && sudo make install

Compiler Requirement

Required Compiler: clang (>= 10.0.0) or gcc (>= 10.3) or Apple-clang (>= 14)

Note that we need to add -Wno-maybe-uninitialized option when we use gcc12 due to a false positive diagnostic message by gcc12

If you meet any problem about MSVC Compiler Error C4737. Try to add option /EHa to fix the problem.

Demo example dependency

Demo example depends on standalone asio(https://github.com/chriskohlhoff/asio/tree/master/asio), the commit id:f70f65ae54351c209c3a24704624144bfe8e70a3

Build

cmake

$ mkdir build && cd build
# Specify [-DASYNC_SIMPLE_ENABLE_TESTS=OFF] to skip tests.
# Specify [-DASYNC_SIMPLE_BUILD_DEMO_EXAMPLE=OFF] to skip build demo example.
# Specify [-DASYNC_SIMPLE_DISABLE_AIO=ON] to skip the build libaio
CXX=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]
# for gcc, use CXX=g++ CC=gcc
make -j4
make test # optional
make install # sudo if required

Conan is also supported. You can install async_simple to conan local cache.

mkdir build && cd build
conan create ..

bazel

# Specify [--define=ASYNC_SIMPLE_DISABLE_AIO=true] to skip the build libaio
# Example bazel build --define=ASYNC_SIMPLE_DISABLE_AIO=true ...
bazel build ...                      # compile all target
bazel build ...:all                  # compile all target
bazel build ...:*                    # compile all target
bazel build -- ... -benchmarks/...   # compile all target except those beneath `benchmarks`
bazel test ...                       # compile and execute tests
# Specify compile a target
# Format: bazel [build|test|run] [directory name]:[binary name]
# Example
bazel build :async_simple           # only compile libasync_simple
bazel run benchmarks:benchmarking   # compile and run benchmark
bazel test async_simple/coro/test:async_simple_coro_test
# Use clang toolchain
bazel build --action_env=CXX=clang++ --action_env=CC=clang ...
# Add compile option 
bazel build --copt='-O0' --copt='-ggdb' ...

See this get more infomation
... 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

Docker Compile Environment

# for centos-7
git clone https://github.com/alibaba/async_simple.git
cd async_simple/docker/centos7
docker build . --no-cache -t async_simple:1.0 --network host
docker run -it --name test-async-simple async_simple:1.0 /bin/bash
// Has entered centos bash shell
mkdir build && cd build
cmake3 .. -DCMAKE_BUILD_TYPE=Release

# for ubuntu 22.04
git clone https://github.com/alibaba/async_simple.git
cd async_simple/docker/ubuntu
docker build . --no-cache -t async_simple:1.0 --network host
docker run -it --name test-async-simple async_simple:1.0 /bin/bash
// Has entered ubuntu bash shell
mkdir build && cd build
# use clang for compile
CXX=clang++-13 CC=clang-13 cmake .. -DCMAKE_BUILD_TYPE=Release
# use g++ for compile
CXX=g++-11 CC=gcc-11 cmake .. -DCMAKE_BUILD_TYPE=Release

Get Started

After installing and reading Lazy to get familiar with API, here is a demo use Lazy to count char in a file.

Performance

We also give a Quantitative Analysis Report Of the Lazy (based on C++20 stackless coroutine) and the Uthread (based on stackful coroutine).

Questions

For questions, we suggest to read docs, issues and discussions first. If there is no satisfying answer, you could file an issues or start a thread in discussions. Specifically, for defect report or feature enhancement, it'd be better to file an issues. And for how-to-use questions, it'd be better to start a thread in discussions.

How to Contribute

Read the How to fix issue document firstly.
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 format 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.
Create a PR, fill in the PR template.
Choose one or more reviewers from contributors: (e.g., ChuanqiXu9, RainMark, foreverhy, qicosmos).
Get approved and merged.

Contact us

Please scan the following QR code of DingTalk to contact us.

Performance Monitoring

We could monitor the performance change history in: https://alibaba.github.io/async_simple/benchmark-monitoring/index.html.

License

async_simple is distributed under the Apache License (Version 2.0) This product contains various third-party components under other open source licenses. See the NOTICE file for more information.

allegrofb/async_simple