Repository files navigation

Cross-platform coroutine library in C++ .

License under theMIT LICENSE

Documents can be found athttps://libcopp.atframe.work , API references canbe found athttps://libcopp.atframe.work/doxygen/html/ .(Generated by sphinx and doxygen withdocs/sphinx anddocs/libcopp.doxyfile.in).

• Addusing value_type = int; intoT when usingcotask::task<T>.
• Renamestack_allocator_t tostack_allocator_type inT when usingcotask::task<T>.
• Renamecoroutine_t tocoroutine_type inT when usingcotask::task<T>.
• Renamelibcopp::util::* tocopp::util::.
• We are not allowed to uselibcopp::memory::intrusive_ptr<cotask::impl::task_impl> now, please usecotask::task<T>::ptr_type instead.

• Renamecotask::task::await intocotask::task::await_task
• Replacecotask::task<TCO_MACRO, TTASK_MACRO> withcotask::task<TCO_MACRO> , we don't allow to custom id allocator now.
• Replacecotask::core::standard_int_id_allocator<uint64_t> withcopp::util::uint64_id_allocator , we don't allow to custom id allocator now.
• Require gcc 4.8+, MSVC 15+(Visual Studio 2017)>)
• Requirecmake 3.12.0 or upper

• [required] GCC or Clang or MSVC or clang-cl support ISO C++ 11 and upper
• [required]cmake 3.16.0 and upper
• [optional]gtest 1.6.0 and upper (Better unit test supported)
• [optional] Boost.Test (Boost.Test supported)

• [required]ar, as, ld (binutils) orllvm
• [optional] if usinggtest , pthread is required.

• [required] masm (in MSVC)
• [optional] if usinggtest, pthread is required.

1. Clone and setupvcpkg (See more detail onhttps://github.com/Microsoft/vcpkg)

   git clone https://github.com/Microsoft/vcpkg.gitcd vcpkgPS> bootstrap-vcpkg.bootstrapLinux:~/$ ./bootstrap-vcpkg.sh

2. Install libcopp

   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 <usage-using with-cmake>` for cmake below.

1. Clone and make a build directory

   git clone --single-branch --depth=1 -b master https://github.com/owent/libcopp.gitmkdir libcopp/build&&cd libcopp/build

2. Run cmake command

   # cmake <libcopp dir> [options...]cmake .. -DPROJECT_ENABLE_UNITTEST=YES -DPROJECT_ENABLE_SAMPLE=YES

3. Make libcopp

   cmake --build. --config RelWithDebInfo# or make [options] when using Makefile

4. Runtest/sample/benchmark[optional]

   # Run test => Required: PROJECT_ENABLE_UNITTEST=YESctest -VV. -C RelWithDebInfo -L libcopp.unit_test# Run sample => Required: PROJECT_ENABLE_SAMPLE=YESctest -VV. -C RelWithDebInfo -L libcopp.sample# Run benchmark => Required: PROJECT_ENABLE_SAMPLE=YESctest -VV. -C RelWithDebInfo -L libcopp.benchmark

5. Install[optional]

   cmake --build. --config RelWithDebInfo --target install# or make install when using Makefile

6. Then just include and linklibcopp.*/libcotask.*, or see:ref:`using with cmake <usage-using with-cmake>` for cmake below.

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:

1. Usingset(Libcopp_ROOT <where to find libcopp/INSTALL_PREFIX>)
2. Just usingfind_package(Libcopp) to use libcopp module.
3. Example:(we assume the target name is stored in${CUSTOM_TARGET_NAME})

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:

if (MSVCAND VCPKG_TOOLCHAIN)    if(DEFINED ENV{VCPKG_DEFAULT_TRIPLET}ANDNOTDEFINED VCPKG_TARGET_TRIPLET)        set(VCPKG_TARGET_TRIPLET"$ENV{VCPKG_DEFAULT_TRIPLET}"CACHESTRING"")    endif()    if (VCPKG_TARGET_TRIPLETMATCHES"^.*windows-static$")        set(CMAKE_MSVC_RUNTIME_LIBRARY"MultiThreaded$<$<CONFIG:Debug>:Debug>"CACHESTRING"")    else ()        set(CMAKE_MSVC_RUNTIME_LIBRARY"MultiThreaded$<$<CONFIG:Debug>:Debug>DLL"CACHESTRING"")    endif ()endif ()

See more detail onhttps://github.com/Microsoft/vcpkg/tree/master/ports/libcopp .

Just include headers and linking library file of your platform to use libcopp.

LIBCOPP_PREFIX=<WHERE TO INSTALL libcopp># Example command for build sample with gcc 4.9 or upper on Linuxforsourcein 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 Linuxforsourcein 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.

# Example command for build sample with MSVC 1914 or upper on Windows & powershell(Debug Mode /MDd)foreach ($sourcein 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}

There serveral samples to usecopp::coroutine_context 、copp::coroutine_context_fiber andcotask::task :

1. Using coroutine context
2. Using coroutine task
3. Using coroutine task manager
4. Using stack pool
5. Usingtask::then ortask::await_task
6. Usingcopp::callable_promise of c++20 coroutine
7. Usingcopp::generator_future for c++20 coroutine
8. Custom error (timeout for example) when using c++20 coroutine
9. Let c++20 coroutine work withcotask::task
10. Using Windows fiber andSetUnhandledExceptionFilter on Windows withcotask::task
11. Using c++20 coroutine with channel receiver and sender
12. Using stackful coroutine task with channel receiver and sender

All sample codes can be found on:ref:`EXAMPLES <examples_doc_anchor>` andsample .

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.

Please see CI output for latest benchmark report. Click to visitGithub Actions .

Q: How to enable c++20 coroutine

If you can just use-std=c++20 -stdlib=libc++ clang 14 or above,-astd=c++20 for gcc 11 or above, and/std:c++latest for MSVC 1932 or above.

Q: Will libcopp handle exception?

Q: WhySetUnhandledExceptionFilter can not catch the unhandled exception in a coroutine?

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.

• owent

• mutouyun