owt5008137 / Libcopp
Labels
Projects that are alternatives of or similar to Libcopp
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
intocotask::task::await_task
- Replace
cotask::task<TCO_MACRO, TTASK_MACRO>
withcotask::task<TCO_MACRO>
, we don't allow to custom id allocator now. - Replace
cotask::core::standard_int_id_allocator<uint64_t>
withcopp::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
) orllvm
-
[optional] if using
gtest
_ , pthread is required.
Windows ^^^^^^^^^^^^^^^^
- [required] masm (in MSVC)
-
[optional] if using
gtest
_, pthread is required.
Install with vcpkg ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
Clone and setup
vcpkg
_ (See more detail on https://github.com/Microsoft/vcpkg) .. code-block:: shellgit 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/owt5008137/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 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
-
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.
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) <https://software.intel.com/en-us/node/695149>
_. |
+------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+
| 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 ^^^^^^^^^^^^^^^^
- Using
set(Libcopp_ROOT <where to find libcopp/INSTALL_PREFIX>)
- Just using
find_package(Libcopp) <https://cmake.org/cmake/help/latest/command/find_package.html>
_ to use libcopp module. - 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$<$<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
:
- Using coroutine context
- Using coroutine task
- Using coroutine task manager
- Using stack pool
- Using
task::then
ortask::await_task
- Using
copp::future::future_t
and prepare for c++20 coroutine - Using c++20 coroutine
- Using c++20 coroutine with custom generator
- Custom error (timeout for example) when polling c++20 coroutine task or generator
- Let c++20 coroutine work with
cotask::task
- Using Windows fiber and
SetUnhandledExceptionFilter
on Windows withcotask::task
All sample codes can be found on :ref:EXAMPLES <examples_doc_anchor>
and sample <https://github.com/owt5008137/libcopp/tree/v2/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 <https://travis-ci.com/github/owt5008137/libcopp>
_ and benchmark on Windows <https://ci.appveyor.com/project/owt5008137/libcopp>
_ . benchmark on Linux,macOS and Windows of dev branch <https://github.com/owt5008137/libcopp/actions>
_ can be found on Github Actions <https://github.com/owt5008137/libcopp/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 <https://github.com/owt5008137/libcopp/blob/v2/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 <https://github.com/owt5008137>
_
THANKS TO
-
mutouyun <https://github.com/mutouyun>
_