cross-platform coroutine library in c++
MIT License
.. _MIT LICENSE: https://github.com/owent/libcopp/blob/v2/LICENSE
.. _docs/libcopp.doxyfile.in
: https://github.com/owent/libcopp/blob/v2/docs/libcopp.doxyfile.in
.. _docs/sphinx
: https://github.com/owent/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++ .
.. image:: https://img.shields.io/github/forks/owent/libcopp?style=social .. image:: https://img.shields.io/github/stars/owent/libcopp?style=social
.. |release-badge| image:: https://img.shields.io/github/v/release/owent/libcopp :alt: Release :target: https://github.com/owent/libcopp/releases
.. |code-size-badge| image:: https://img.shields.io/github/languages/code-size/owent/libcopp :alt: Code size :target: https://github.com/owent/libcopp
.. |repo-size-badge| image:: https://img.shields.io/github/repo-size/owent/libcopp :alt: Repo size :target: https://github.com/owent/libcopp
.. |forks-badge| image:: https://img.shields.io/github/forks/owent/libcopp?style=social :alt: Forks :target: https://github.com/owent/libcopp
.. |stars-badge| image:: https://img.shields.io/github/stars/owent/libcopp?style=social :alt: Stars :target: https://github.com/owent/libcopp
.. |ci-badge| image:: https://github.com/owent/libcopp/actions/workflows/main.yml/badge.svg :alt: CI build status :target: https://github.com/owent/libcopp/actions/workflows/main.yml
.. |codecov-badge| image:: https://codecov.io/gh/owent/libcopp/branch/v2/graph/badge.svg :alt: Coveralls coverage :target: https://codecov.io/gh/owent/libcopp
.. |lgtm-badge| image:: https://img.shields.io/lgtm/grade/cpp/g/owent/libcopp.svg?logo=lgtm&logoWidth=18 :alt: Language grade: C/C++ :target: https://lgtm.com/projects/g/owent/libcopp/context:cpp
|release-badge| |code-size-badge| |repo-size-badge| |ci-badge| |codecov-badge| |lgtm-badge| |forks-badge| |stars-badge|
+---------------+--------------------+-----------------------+ | Target System | Toolchain | Note | +===============+====================+=======================+ | Linux | GCC | Static linking | +---------------+--------------------+-----------------------+ | Linux | GCC | Dynamic linking | +---------------+--------------------+-----------------------+ | Linux | GCC-latest | | +---------------+--------------------+-----------------------+ | Linux | GCC-latest | No Exception | +---------------+--------------------+-----------------------+ | Linux | GCC-latest | Thread Unsafe | +---------------+--------------------+-----------------------+ | Linux | GCC 4.8 | Legacy | +---------------+--------------------+-----------------------+ | Linux | Clang-latest | With libc++ | +---------------+--------------------+-----------------------+ | MinGW64 | GCC | Dynamic linking | +---------------+--------------------+-----------------------+ | Windows | Visual Studio 2019 | Static linking | +---------------+--------------------+-----------------------+ | Windows | Visual Studio 2019 | Dynamic linking | +---------------+--------------------+-----------------------+ | Windows | Visual Studio 2017 | Legacy,Static linking | +---------------+--------------------+-----------------------+ | macOS | AppleClang | With libc++ | +---------------+--------------------+-----------------------+
License under the MIT LICENSE
_
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
_).
using value_type = int;
into T
when using cotask::task<T>
.stack_allocator_t
to stack_allocator_type
in T
when using cotask::task<T>
.coroutine_t
to coroutine_type
in T
when using cotask::task<T>
.libcopp::util::*
to copp::util::
.libcopp::util::intrusive_ptr<cotask::impl::task_impl>
now, please use cotask::task<T>::ptr_type
instead.cotask::task::await
into cotask::task::await_task
cotask::task<TCO_MACRO, TTASK_MACRO>
with cotask::task<TCO_MACRO>
, we don't allow to custom id allocator now.cotask::core::standard_int_id_allocator<uint64_t>
with copp::util::uint64_id_allocator
, we don't allow to custom id allocator now.cmake
_ 3.12.0 or upper| libcopp use cmake
_ to generate makefile and switch build tools.
Prerequisites ^^^^^^^^^^^^^^^^
cmake
_ 3.16.0 and uppergtest
_ 1.6.0 and upper (Better unit test supported)Boost.Test
_ (Boost.Test supported)Unix ^^^^^^^^^^^^^^^^
ar, as, ld
(binutils
) or llvm
gtest
_ , pthread is required.Windows ^^^^^^^^^^^^^^^^
gtest
_, pthread is required.Install with vcpkg ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
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
See :ref:using with cmake <usage-using with-cmake>
for cmake below.
Custom Build ^^^^^^^^^^^^^^^^
Clone and make a build directory .. code-block:: shell
git clone --single-branch --depth=1 -b master https://github.com/owent/libcopp.git
mkdir libcopp/build && cd libcopp/build
Run cmake command .. code-block:: shell
# cmake <libcopp dir> [options...]
cmake .. -DPROJECT_ENABLE_UNITTEST=YES -DPROJECT_ENABLE_SAMPLE=YES
Make libcopp .. code-block:: shell
cmake --build . --config RelWithDebInfo # or make [options] when using Makefile
Run test/sample/benchmark
[optional]
.. code-block:: shell
# Run test => Required: PROJECT_ENABLE_UNITTEST=YES
ctest -VV . -C RelWithDebInfo -L libcopp.unit_test
# Run sample => Required: PROJECT_ENABLE_SAMPLE=YES
ctest -VV . -C RelWithDebInfo -L libcopp.sample
# Run benchmark => Required: PROJECT_ENABLE_SAMPLE=YES
ctest -VV . -C RelWithDebInfo -L libcopp.benchmark
Install [optional] .. code-block:: shell
cmake --build . --config RelWithDebInfo --target install # or make install when using Makefile
Then just include and link libcopp.*/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:
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
| 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_LOCK_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) <https://software.intel.com/en-us/node/695149>
_. |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
| LIBCOPP_MACRO_TLS_STACK_PROTECTOR=YES|NO | [default=NO] Users need set LIBCOPP_MACRO_TLS_STACK_PROTECTOR=ON when compiling with -fstack-protector
. |
| | Because it changes the default context switching logic. |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
| GTEST_ROOT=[path] | set gtest library install prefix path |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
| BOOST_ROOT=[path] | set Boost.Test library install prefix path |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
.. _usage-using with-cmake:
Using with cmake ^^^^^^^^^^^^^^^^
set(Libcopp_ROOT <where to find libcopp/INSTALL_PREFIX>)
find_package(Libcopp) <https://cmake.org/cmake/help/latest/command/find_package.html>
_ to use libcopp module.${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$<$<CONFIG:Debug>:Debug>" CACHE STRING "")
else ()
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>: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=<WHERE TO INSTALL libcopp>
# 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
:
task::then
or task::await_task
copp::callable_promise
of c++20 coroutinecopp::generator_future
for c++20 coroutinecotask::task
SetUnhandledExceptionFilter
on Windows with cotask::task
All sample codes can be found on :ref:EXAMPLES <examples_doc_anchor>
and sample <https://github.com/owent/libcopp/tree/v2/sample>
_ .
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 visit Github Actions <https://github.com/owent/libcopp/actions>
_ .
Q: How to enable c++20 coroutine
| ANS: Add /std:c++latest /await
for MSVC 1932 and below or -std=c++20 -fcoroutines-ts -stdlib=libc++
for clang 13 and below or -std=c++20 -fcoroutines
for gcc 10.
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?
| 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 <https://github.com/owent/libcopp/blob/v2/sample/sample_readme_11.cpp>
_ for details.
If you has any question, please create a issue and provide the information of your environments. For example:
msinfo32
) / Manjaro(Arch) Linux Linux 5.4.39-1-MANJAROcmake .. -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
cmake --build . -j
CC
、 CXX
、 AR
and etc.owent <https://github.com/owent>
_mutouyun <https://github.com/mutouyun>
_