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!

• 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 v3.0+

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

Tool Support

• CMake
  • msvc
  • clang-cl: Works with VC++ headers
  • clang: Linux
  • AppleClang: Mac

Known Issues

TBA

How To

Setup

Simply clone and initialize submodules recursively :)

git clone https://github.com/luncliff/coroutine
pushd coroutine
  git submodule update --init --recursive
popd

Test

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

Import

If you want some tool support, please let me know. I'm willing to learn about it.

CMake 3.12+

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

The library exports 3 targets.

• coroutine_portable
  • <coroutine/frame.h>
  • <coroutine/return.h>
  • <coroutine/channel.hpp>
• coroutine_system
  • requires: coroutine_portable
  • <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.12)

find_package(coroutine CONFIG REQUIRED)
# or add_subdirectory(coroutine) if you want to be simple

target_link_libraries(main
PUBLIC
    coroutine_portable
    coroutine_system
    coroutine_net
)

Developer Note

Interface

Portable

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. With the macro USE_EXPERIMENTAL_COROUTINE, you can enforce <experimental/coroutine> instead of <coroutine/frame.h>

// return/promise types for coroutine functions
#define USE_EXPERIMENTAL_COROUTINE 
#include <coroutine/return.h> 

Generator is named coro::enumerable here.

For now you can see various description for the concept in C++ conference talks in Youtube.
If you want better implementation or want to see another generators, visit the https://github.com/Quuxplusone/coro :D

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

Go language style channel to deliver data between coroutines. It Supports awaitable read/write and select operation are possible.
If you don't know the language, never worry. There was a talk in CppCon

• CppCon 2016: John Bandela "Channels - An alternative to callbacks and futures"

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 you may feel curiosity about it.

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

System

The library doesn't provides platform-neutral abstraction.

// #include <gsl/gsl>             // requires ms-gsl
// #include <coroutine/return.h>  // already used by the following headers
#include <coroutine/windows.h>
#include <coroutine/linux.h>
#include <coroutine/unix.h>
#include <coroutine/pthread.h>

Please reference test codes for their usage.

Network

Async I/O with awaitable types for socket operation and poll_net_tasks to multiplex control flow.

#include <coroutine/net.h>

Please reference test codes for its usage.

License

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