coroutine

C++ 20 Coroutine in Action.

Purpose of this library

• Help understanding of the C++ coroutine
• Provide meaningful design example with the feature

In that perspective, the library will be maintained as small as possible. Have fun with them. And try your own coroutines !

Developer Note

• Start with the GitHub Pages! You will visit the test/ and interface/ folder while reading the docs.
• This repository has some custom(and partial) implementation for the C++ Coroutine spec in the <coroutine/frame.h>

Architecture

This library is only for x64.

Tool Support

• Visual Studio 2017 or later
  • msvc (vc141, vc142)
• CMake
  • msvc
  • clang-cl: Works with VC++ headers. Requires static linking
  • clang: Linux
  • AppleClang: Mac

For Visual Studio users, please use 15.7.3 or later versions.
For clang users, I recommend Clang 6.0 or later versions.

Interfaces

To support multiple compilers, this library defines its own header, <coroutine/frame.h>. This might lead to conflict with existing library (libc++ and VC++).
If there is a collision(build issue), please make an issue in this repo so I can fix it.

// This header includes/overrides <experimental/coroutine>
#include <coroutine/frame.h>

Generator and async generator. Notice that the async generator is experimental. If you are curious with the concept, reference the kirkshoop's repo.

#include <coroutine/yield.hpp>  // enumerable<T> & sequence<T>

Utility types are in the following headers

#include <coroutine/return.h> // return type for resumable functions
#include <coroutine/concrt.h> // concurrency utilities

Go language style channel to deliver data between coroutines. It Supports awaitable read/write and select operation are possible.

But it is slightly different from that of the Go language because we don't have a built-in scheduler in C++. Furthermore Goroutine is quite different from the C++ coroutine. It may not a necessary feature since there are so much of the channel implementation, but I'm sure breakpointing this one will train you.

#include <coroutine/channel.hpp>  // channel<T> with Lockable

Awaitable socket operations using system API are also available. I used epoll, kqueue and Overlapped I/O of the Windows.

#include <coroutine/net.h>  // Awaitable I/O operations and some helpers

How To

Build

Please reference the build configurations.
Create an issue if you think another configuration is required.

• Azure Pipelines
  • Visual Studio 2017 (Visual Studio Solution File)
  • Visual Studio 2017 (CMake)
  • Ubuntu 16.04 + Clang 6.0
  • Mac OS + AppleClang
  • Windows + Clang-cl (LLVM 8)
• .travis.yml
  • Mac OS + AppleClang
  • Ubuntu 16.04 + Clang 7
  • iPhone OS : leetal/ios-cmake
  • Android NDK (SDK 24 - 27) + Clang 8
• appveyor.yml
  • Visual Studio 2017 (Visual Studio Solution File)
  • Windows + Clang-cl : LLVM chocolatey package
• Works on my machine :D
  • Visual Studio 2019
  • Windows Subsystem for Linux (Ubuntu 18.04 + Clang 7.1.0)
  • Clang-cl (LLVM 7.0.1, 8.0) + Ninja

Test

Exploring test(example) codes will be helpful. The library uses 2 tools for its test.

• Visual Studio Native Testing Tool
• CMake generated project with CTest

Import

Visual Studio Project

For Visual Studio users,
I recommend you to import(add reference) windows.vcxproj in modules.

CMake Project

Expect there is a higher CMake project which uses this library. For Android NDK, the minimum version of CMake is 3.14.

cmake_minimum_required(VERSION 3.8) # Android NDK requires 3.14

# ...
add_subdirectory(coroutine)

# ...
target_link_libraries(your_project
PUBLIC
    coroutine
)

Vcpkg

Requires ms-gsl package. If you are curious about the build configuration, reference the portfile.cmake.

Supporting triplets are ...

• x64-windows
• x64-linux
• x64-osx

License

This work is licensed under a Creative Commons Attribution 4.0 International License.