ReadMe.md

coroutine

C++ 20 Coroutines in Action

Purpose of this repository

• 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's 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 in the <coroutine/frame.h>.
  It can be activated with macro USE_PORTABLE_COROUTINE_HANDLE

Pre-requisite

• Microsoft GSL v2.0.0 or later

The installation of this library will install it together. All other required modules for build/test will be placed in external/.

Build Configuration

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.

Interface

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>

Utility types are in the following headers

#include <coroutine/return.h>   // return type for coroutine functions

Generator is named coro::enumerable here. For now you can see various description for the concept in C++ conference talks in Youtube, or some resources in the MattPD's collection. If you are curious with the concept, reference the kirkshoop's repo. If you want better implementation, visit the https://github.com/Quuxplusone/coro

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

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

How To

Setup

Simply clone and initialize submodules recursively :)

git submodule update --init --recursive

Build

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

• Azure Pipelines
  • Visual Studio 2017 / 2019 (CMake)
  • Ubuntu 16.04 + Clang 8
  • Mac OS X + AppleClang 11
  • Windows + Clang-cl (LLVM 8.0.1)
• .travis.yml
  • Mac OS X + AppleClang
  • Ubuntu 16.04 + Clang 7
• appveyor.yml
  • Visual Studio 2017 / 2019
  • VC++ & Clang-cl : LLVM chocolatey package
• Works on my machine :D
  • Windows Subsystem for Linux (Ubuntu 18.04 + Clang 7.1.0)
  • Clang-cl (LLVM 8.0.1) + Ninja

Test

Exploring test(example) codes will be helpful. The library uses CTest for its test. AppVeyor & Travis CI build shows the execution of them.

Import

CMake

Expect there is a higher CMake project which uses this library.

The library export 3 targets.

• coroutine_portable
  • <coroutine/frame.h>
  • <coroutine/return.h>
  • <coroutine/channel.hpp>
• coroutine_system
  • <coroutine/windows.h>
  • <coroutine/linux.h>
  • <coroutine/unix.h>
  • <coroutine/pthread.h>
• coroutine_net
  • requires: coroutine_system
  • <coroutine/net.h>

cmake_minimum_required(VERSION 3.8)
# ...
add_subdirectory(coroutine)
# ...
target_link_libraries(main
PUBLIC
    coroutine_portable  # header-only
    coroutine_system
    coroutine_net
)

License

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