coroutine

C++ 20 Coroutines in Action

Purpose of this library

• Help understanding of the C++ Coroutines
• 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!

If you are looking for another materials, visit the MattPD's collection!

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++ Coroutines 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
  • 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. Or you can navigate the

#include <coroutine/yield.hpp>      // enumerable<T>
#include <coroutine/sequence.hpp>   // sequence<T> has an optimization issue

Utility types are in the following headers

#include <coroutine/return.h>   // return type for coroutine functions
#include <coroutine/event.h>    // Awaitable event type over System API
#include <coroutine/thread.h>   // Working with the thread API

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++ Coroutines. 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
• CTest for CMake users

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.