# libcopp **Repository Path**: shun_dev/libcopp ## Basic Information - **Project Name**: libcopp - **Description**: cross-platform coroutine library in c++ - **Primary Language**: C++ - **License**: BSL-1.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2021-12-11 - **Last Updated**: 2024-06-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README libcopp ============ .. _MIT LICENSE: https://github.com/owt5008137/libcopp/blob/v2/LICENSE .. _`docs/libcopp.doxyfile.in`: https://github.com/owt5008137/libcopp/blob/v2/docs/libcopp.doxyfile.in .. _`docs/sphinx`: https://github.com/owt5008137/libcopp/blob/v2/docs/sphinx .. _cmake: https://cmake.org/ .. _binutils: http://www.gnu.org/software/binutils/ .. _llvm: http://llvm.org/ .. _gtest: https://github.com/google/googletest .. _Boost.Test: (http://www.boost.org/doc/libs/release/libs/test .. _vcpkg: https://github.com/Microsoft/vcpkg Cross-platform coroutine library in C++ . +-------------------+------------------------------------+---------------------------------+-------------------------+-------------------------+ | | Linux+OSX(Clang+GCC) | Windows(VC+MinGW) | Coveralls | Dev branch | +===================+====================================+=================================+=========================+=========================+ | Build & Unit Test | |linux-ci| | |windows-ci| | |coverage-ci| | |github-action-ci| | +-------------------+------------------------------------+---------------------------------+-------------------------+-------------------------+ | Compilers | linux-gcc-4.8 | MSVC 14(Visual Studio 2015) | | | +-------------------+------------------------------------+---------------------------------+-------------------------+-------------------------+ | | linux-gcc-10 | MSVC 15(Visual Studio 2017) | | | +-------------------+------------------------------------+---------------------------------+-------------------------+-------------------------+ | | macos-apple-clang-9 | MSVC 16(Visual Studio 2019) | | | +-------------------+------------------------------------+---------------------------------+-------------------------+-------------------------+ | | macos-apple-clang-12 | MinGW64-gcc | | | +-------------------+------------------------------------+---------------------------------+-------------------------+-------------------------+ .. image:: https://img.shields.io/github/v/release/owt5008137/libcopp .. image:: https://img.shields.io/github/languages/code-size/owt5008137/libcopp .. image:: https://img.shields.io/github/repo-size/owt5008137/libcopp .. image:: https://img.shields.io/github/forks/owt5008137/libcopp?style=social .. image:: https://img.shields.io/github/stars/owt5008137/libcopp?style=social |lgtm-quality| .. |linux-ci| image:: https://travis-ci.com/owt5008137/libcopp.svg?branch=v2 :alt: Travis build status :target: https://travis-ci.com/github/owt5008137/libcopp .. |windows-ci| image:: https://ci.appveyor.com/api/projects/status/7w6dfnpeahfmgaqj/branch/v2?svg=true :alt: AppVeyor build status :target: https://ci.appveyor.com/project/owt5008137/libcopp .. |coverage-ci| image:: https://coveralls.io/repos/github/owt5008137/libcopp/badge.svg?branch=v2 :alt: Coveralls coverage :target: https://coveralls.io/github/owt5008137/libcopp?branch=v2 .. |github-action-ci| image:: https://github.com/owt5008137/libcopp/workflows/Linux%20Building/badge.svg :alt: Coveralls coverage :target: https://github.com/owt5008137/libcopp/actions .. |lgtm-quality| image:: https://img.shields.io/lgtm/grade/cpp/g/owt5008137/libcopp.svg?logo=lgtm&logoWidth=18 :alt: Language grade: C/C++ :target: https://lgtm.com/projects/g/owt5008137/libcopp/context:cpp LICENSE ------------ License under the `MIT LICENSE`_ Document ------------ Documents can be found at https://libcopp.atframe.work , API references canbe found at https://libcopp.atframe.work/doxygen/html/ .(Generated by sphinx and doxygen with `docs/sphinx`_ and `docs/libcopp.doxyfile.in`_). UPGRADE FROM 1.2.X ------------------------ + Rename ``cotask::task::await`` into ``cotask::task::await_task`` + Replace ``cotask::task`` with ``cotask::task`` , we don't allow to custom id allocator now. + Replace ``cotask::core::standard_int_id_allocator`` with ``copp::util::uint64_id_allocator`` , we don't allow to custom id allocator now. + Require gcc 4.7+, MSVC 14+(Visual Studio 2015)>) + Require `cmake`_ 3.12.0 or upper INSTALL ------------ | libcopp use `cmake`_ to generate makefile and switch build tools. Prerequisites ^^^^^^^^^^^^^^^^ * **[required]** GCC or Clang or MSVC or clang-cl support ISO C++ 11 and upper * **[required]** `cmake`_ 3.12.0 and upper * **[optional]** `gtest`_ 1.6.0 and upper (Better unit test supported) * **[optional]** `Boost.Test`_ (Boost.Test supported) Unix ^^^^^^^^^^^^^^^^ * **[required]** ``ar, as, ld`` (`binutils`_) or `llvm`_ * **[optional]** if using `gtest`_ , pthread is required. Windows ^^^^^^^^^^^^^^^^ * **[required]** masm (in MSVC) * **[optional]** if using `gtest`_, pthread is required. Install with vcpkg ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Clone and setup `vcpkg`_ (See more detail on https://github.com/Microsoft/vcpkg) .. code-block:: shell git clone https://github.com/Microsoft/vcpkg.git cd vcpkg PS> bootstrap-vcpkg.bootstrap Linux:~/$ ./bootstrap-vcpkg.sh 2. Install libcopp .. code-block:: shell PS> .\vcpkg install libcopp [--triplet x64-windows-static/x64-windows/x64-windows-static-md and etc...] Linux:~/$ ./vcpkg install libcopp 3. See :ref:`using with cmake ` for cmake below. Custom Build ^^^^^^^^^^^^^^^^ 1. Clone and make a build directory .. code-block:: shell git clone --single-branch --depth=1 -b master https://github.com/owt5008137/libcopp.git mkdir libcopp/build && cd libcopp/build 2. Run cmake command .. code-block:: shell # cmake [options...] cmake .. -DPROJECT_ENABLE_UNITTEST=YES -DPROJECT_ENABLE_SAMPLE=YES 3. Make libcopp .. code-block:: shell cmake --build . --config RelWithDebInfo # or make [options] when using Makefile 4. Run ``test/sample/benchmark`` *[optional]* .. code-block:: shell # Run test => Required: PROJECT_ENABLE_UNITTEST=YES cmake --build . --config RelWithDebInfo --target run_test # or make run_test when using Makefile # Run sample => Required: PROJECT_ENABLE_SAMPLE=YES cmake --build . --config RelWithDebInfo --target run_sample # or make run_sample when using Makefile # Run benchmark => Required: PROJECT_ENABLE_SAMPLE=YES cmake --build . --config RelWithDebInfo --target benchmark # or make benchmark when using Makefile 5. Install *[optional]* .. code-block:: shell cmake --build . --config RelWithDebInfo --target install # or make install when using Makefile 6. Then just include and link ``libcopp.*/libcotask.*``, or see :ref:`using with cmake ` for cmake below. CMake Options ---------------- Options can be cmake options. such as set compile toolchains, source directory or options of libcopp that control build actions. libcopp options are listed below: +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | Option | Description | +==========================================+==============================================================================================================================+ | BUILD_SHARED_LIBS=YES|NO | [default=NO] Build dynamic library. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | LIBCOPP_ENABLE_SEGMENTED_STACKS=YES|NO | [default=NO] Enable split stack supported context.(it's only availabe in linux and gcc 4.7.0 or upper) | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | LIBCOPP_ENABLE_VALGRIND=YES|NO | [default=YES] Enable valgrind supported context. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | PROJECT_ENABLE_UNITTEST=YES|NO | [default=NO] Build unit test. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | PROJECT_ENABLE_SAMPLE=YES|NO | [default=NO] Build samples. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | LIBCOPP_DISABLE_THIS_MT=YES|NO | [default=NO] Disable multi-thread support for ``copp::this_coroutine`` and ``cotask::this_task``. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | LIBCOPP_DISABLE_ATOMIC_LOCK=YES|NO | [default=NO] Disable multi-thread support. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | LIBCOTASK_ENABLE=YES|NO | [default=YES] Enable build libcotask. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | LIBCOPP_FCONTEXT_USE_TSX=YES|NO | [default=YES] Enable `Intel Transactional Synchronisation Extensions (TSX) `_. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | GTEST_ROOT=[path] | set gtest library install prefix path | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | BOOST_ROOT=[path] | set Boost.Test library install prefix path | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ USAGE ------------ .. _usage-using with-cmake: Using with cmake ^^^^^^^^^^^^^^^^ 1. Using ``set(Libcopp_ROOT )`` 2. Just using `find_package(Libcopp) `_ to use libcopp module. 3. Example:(we assume the target name is stored in ``${CUSTOM_TARGET_NAME}``) .. code-block:: cmake find_package(Libcopp CONFIG REQUIRED) target_link_libraries(${CUSTOM_TARGET_NAME} libcopp::cotask) # Or just using copp by target_link_libraries(${CUSTOM_TARGET_NAME} libcopp::copp) If using MSVC and vcpkg, CRT must match the triplet of vcpkg, these codes below may be helpful: .. code-block:: cmake if (MSVC AND VCPKG_TOOLCHAIN) if(DEFINED ENV{VCPKG_DEFAULT_TRIPLET} AND NOT DEFINED VCPKG_TARGET_TRIPLET) set(VCPKG_TARGET_TRIPLET "$ENV{VCPKG_DEFAULT_TRIPLET}" CACHE STRING "") endif() if (VCPKG_TARGET_TRIPLET MATCHES "^.*windows-static$") set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$:Debug>" CACHE STRING "") else () set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$:Debug>DLL" CACHE STRING "") endif () endif () See more detail on https://github.com/Microsoft/vcpkg/tree/master/ports/libcopp . Directly use headers and libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Just include headers and linking library file of your platform to use libcopp. .. code-block:: shell LIBCOPP_PREFIX= # Example command for build sample with gcc 4.9 or upper on Linux for source in sample_readme_*.cpp; do g++ -std=c++14 -O2 -g -ggdb -Wall -Werror -fPIC -rdynamic -fdiagnostics-color=auto -Wno-unused-local-typedefs \ -I$LIBCOPP_PREFIX/include -L$LIBCOPP_PREFIX/lib64 -lcopp -lcotask $source -o $source.exe; done # Example command for build sample with clang 3.9 or upper and libc++ on Linux for source in sample_readme_*.cpp; do clang++ -std=c++17 -stdlib=libc++ -O2 -g -ggdb -Wall -Werror -fPIC -rdynamic \ -I$LIBCOPP_PREFIX/include -L$LIBCOPP_PREFIX/lib64 -lcopp -lcotask -lc++ -lc++abi \ $source -o $source.exe; done # AppleClang on macOS just like those scripts upper. # If you are using MinGW on Windows, it's better to add -static-libstdc++ -static-libgcc to # use static linking and other scripts are just like those on Linux. .. code-block:: shell # Example command for build sample with MSVC 1914 or upper on Windows & powershell(Debug Mode /MDd) foreach ($source in Get-ChildItem -File -Name .\sample_readme_*.cpp) { cl /nologo /MP /W4 /wd"4100" /wd"4125" /EHsc /std:c++17 /Zc:__cplusplus /O2 /MDd /I$LIBCOPP_PREFIX/include $LIBCOPP_PREFIX/lib64/copp.lib $LIBCOPP_PREFIX/lib64/cotask.lib $source } Get Start & Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There serveral samples to use ``copp::coroutine_context`` 、 ``copp::coroutine_context_fiber`` and ``cotask::task`` : 1. Using coroutine context 2. Using coroutine task 3. Using coroutine task manager 4. Using stack pool 5. Using ``task::then`` or ``task::await_task`` 6. Using ``copp::future::future_t`` and prepare for c++20 coroutine 7. Using c++20 coroutine 8. Using c++20 coroutine with custom generator 9. Custom error (timeout for example) when polling c++20 coroutine task or generator 10. Let c++20 coroutine work with ``cotask::task`` 11. Using Windows fiber and ``SetUnhandledExceptionFilter`` on Windows with ``cotask::task`` All sample codes can be found on :ref:`EXAMPLES ` and `sample `_ . NOTICE ------------ Split stack support: if in Linux and user gcc 4.7.0 or upper, add ``-DLIBCOPP_ENABLE_SEGMENTED_STACKS=YES`` to use split stack supported context. It's recommanded to use stack pool instead of gcc splited stack. BENCHMARK ------------ Please see CI output for latest benchmark report. Click to visit `benchmark on Linux and macOS `_ and `benchmark on Windows `_ . `benchmark on Linux,macOS and Windows of dev branch `_ can be found on `Github Actions `_ . FAQ ------------ Q: How to enable c++20 coroutine | ANS: Add ``/std:c++latest /await`` for MSVC or ``-std=c++20 -fcoroutines-ts -stdlib=libc++`` for clang or ``-std=c++20 -fcoroutines`` for gcc. Q: Will libcopp handle exception? | ANS: When using c++11 or above, libcopp will catch all unhandled exception and rethrow it after coroutine resumed. Q: Why ``SetUnhandledExceptionFilter`` can not catch the unhandled exception in a coroutine? | ANS: ``SetUnhandledExceptionFilter`` only works with **Windows Fiber**, please see `sample/sample_readme_11.cpp `_ for details. FEEDBACK ------------ If you has any question, please create a issue and provide the information of your environments. For example: + **OS**: Windows 10 Pro 19041 *(This can be see after running ``msinfo32``)* / Manjaro(Arch) Linux Linux 5.4.39-1-MANJARO + **Compiler**: Visual Studio 2019 C++ 16.5.5 with VS 2019 C++ v14.25 or MSVC 1925/ gcc 9.3.0 + **CMake Commands**: ``cmake .. -G "Visual Studio 16 2019" -A x64 -DLIBCOPP_FCONTEXT_USE_TSX=ON -DPROJECT_ENABLE_UNITTEST=ON -DPROJECT_ENABLE_SAMPLE=ON-DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=%cd%/install-prefix`` / ``cmake .. -G Ninja -DLIBCOPP_FCONTEXT_USE_TSX=ON -DPROJECT_ENABLE_UNITTEST=ON -DPROJECT_ENABLE_SAMPLE=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/opt/libcopp`` + **Compile Commands**: ``cmake --build . -j`` + **Related Environment Variables**: Please provide all the environment variables which will change the cmake toolchain, ``CC`` 、 ``CXX`` 、 ``AR`` and etc. CONSTRIBUTORS ------------------------ + `owent `_ THANKS TO ------------ + `mutouyun `_