libcopp icon indicating copy to clipboard operation
libcopp copied to clipboard

Published 20 hours ago • verified publisher icon owent
→

Metadata

cross-platform coroutine library in c++

libcopp

.. _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|

CI Job Matrix

+---------------+--------------------+-----------------------+ | 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

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.3.X-1.4.X to 2.X

  • Add using value_type = int; into T when using cotask::task<T>.
  • Rename stack_allocator_t to stack_allocator_type in T when using cotask::task<T>.
  • Rename coroutine_t to coroutine_type in T when using cotask::task<T>.
  • Rename libcopp::util::* to copp::util::.
  • We are not allowed to use libcopp::util::intrusive_ptr<cotask::impl::task_impl> now, please use cotask::task<T>::ptr_type instead.

UPGRADE FROM 1.2.X to 1.3.X-1.4.X

  • Rename cotask::task::await into cotask::task::await_task
  • Replace cotask::task<TCO_MACRO, TTASK_MACRO> with cotask::task<TCO_MACRO> , we don't allow to custom id allocator now.
  • Replace cotask::core::standard_int_id_allocator<uint64_t> with copp::util::uint64_id_allocator , we don't allow to custom id allocator now.
  • Require gcc 4.8+, MSVC 15+(Visual Studio 2017)>)
  • 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.16.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 <usage-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/owent/libcopp.git 
 mkdir libcopp/build && cd libcopp/build

  2. Run cmake command .. code-block:: shell

     # cmake <libcopp dir> [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
 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

  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 <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_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>_. | +------------------------------------------+------------------------------------------------------------------------------------------------------------------------------+ | 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 <where to find libcopp/INSTALL_PREFIX>)
  2. Just using find_package(Libcopp) <https://cmake.org/cmake/help/latest/command/find_package.html>_ 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$<$<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 :

  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::callable_promise of c++20 coroutine
  7. Using copp::generator_future for c++20 coroutine
  8. Custom error (timeout for example) when using c++20 coroutine
  9. Let c++20 coroutine work with cotask::task
  10. Using Windows fiber and 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>_ .

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 Github Actions <https://github.com/owent/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. If you are using clang 14 or above, just use -std=c++20 -stdlib=libc++.Or if you are using MSVC 1932 or above, just use /std:c++latest.

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.

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/owent>_

THANKS TO

  • mutouyun <https://github.com/mutouyun>_

← Metadata

808
Stars
105
Forks
Watchers

Owner

verified publisher icon owent

Metadata

cross-platform coroutine library in c++

Back