search

CarterLi / liburing4cpp

Modern C++ binding for liburing (io_uring) that features C++ coroutines support
MIT License
284 stars 20 forks source link

readme

liburing4cpp

Modern C++ binding for liburing that uses C++20 Coroutines ( but still compiles for clang at C++17 mode with -fcoroutines-ts )

Originally named liburing-http-demo ( this project was originally started for demo )

Requirements

Requires the latest kernel ( currently 5.8 ). Since io_uring is in active development, we will drop old kernel support when every new linux kernel version is released ( before the next LTS version is released, maybe ).

Tested: Ubuntu 5.9.0-050900rc6daily20200923-generic #202009222208 SMP Wed Sep 23 02:24:13 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux with clang version 10.0.0-4ubuntu1

First glance

#include <liburing/io_service.hpp>

using namespace std::literals;

int main() {
    // You first need an io_service instance
    uio::io_service service;

    // In order to `co_await`, you must be in a coroutine.
    // We use IIFE here for simplification
    auto work = [&] () -> uio::task<> {
        // Use Linux syscalls just as what you did before (except a little changes)
        const auto str = "Hello world\n"sv;
        co_await service.write(STDOUT_FILENO, str.data(), str.size(), 0);
    }();

    // At last, you need a loop to dispatch finished IO events
    // It's usually called Event Loop (https://en.wikipedia.org/wiki/Event_loop)
    service.run(work);
}

Benchmarks

demo/bench

service.yield:        5436209973
plain IORING_OP_NOP:  5268565967
this_thread::yield:   4750992301
pause:                  41557653

About 3% overhead

demo/echo_server

with rust_echo_bench: https://github.com/haraldh/rust_echo_bench unit: request/sec

Also see benchmarks for different opcodes

command: cargo run --release

LANG USE_LINK USE_SPLICE USE_POLL operations 1st 2nd 3rd mid rate
C - - 0 RECV-SEND 114461 116797 112112 114461 100.00%
C - - 1 POLL-RECV-SEND 109037 114893 117629 114893 100.38%
C++ 0 0 0 RECV-SEND 117519 121139 120239 120239 105.05%
C++ 0 1 0 SPLICE-SPLICE 90577 91912 92301 91912 80.30%
C++ 1 1 0 SPLICE-SPLICE 93440 92619 94201 93440 81.63%
C++ 0 0 1 POLL-RECV-SEND 107454 111525 111210 111210 97.16%
C++ 0 1 1 POLL-SPLICE-SPLICE 89469 90663 89315 89469 78.17%
C++ 1 1 1 POLL-SPLICE-SPLICE 87628 89099 88708 89099 77.84%

Project Structure

task.hpp

An awaitable class for C++2a coroutine functions. Originally modified from gor_task.h

NOTE: task is not lazily executed, which is easy to use of course, but also can be easily misused. The simplest code to crash your memory is:

{
    char c;
    service.read(STDIN_FILENO, &c, sizeof (c), 0);
}

The task instance returned by service.read is destructed, but the kernel task itself is NOT canceled. The memory of variable c will be written sometime. In this case, out-of-scope stack memory access will happen.

io_service.hpp

Main liburing binding. Also provides some helper functions for working with posix interfaces easier.

demo

Some examples

file_server.cpp

A simple http file server that returns file's content requested by clients

link_cp.cpp

A cp command inspired by original liburing link-cp demo

http_client.cpp

A simple http client that sends GET http request

threading.cpp

A simple async_invoke implementation

test.cpp

Various simple tests

bench.cpp

Benchmarks

echo_server.cpp

Echo server, features IOSQE_IO_LINK and IOSQE_FIXED_FILE

See also https://github.com/frevib/io_uring-echo-server#benchmarks for benchmarking

Build

This library is header only. It provides some demos, as well as some tests.

Dependencies

This library has to be linked against liburing, and requires a recent version of GCC or Clang. For best results, please use GCC 10.3 (or later), or Clang 10.0.0 (or later)

[Optional] This library can be built with either libc++ or libstdc++. If you want to use libc++, you can install it with

sudo apt install clang libc++-dev libc++abi-dev`

Building Demos & Tests

In order to build the demos, clone the repository and then run CMake in the project's root directory:

git clone https://github.com/CarterLi/liburing4cpp.git
cd liburing4cpp
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Optionally, you may also use CMake Presets instead (requires CMake version 3.19 or above)

git clone https://github.com/CarterLi/liburing4cpp.git
cd liburing4cpp
cmake --preset=Release
cmake --build --preset=Release

Binares are placed in the build/ directory. You can then run tests via ctest:

ctest --test-dir build

Using this library with CMake

When using CMake, you can automatically include this library as a dependency of your project by using the FetchContent interface:

include(FetchContent)
FetchContent_Declare(
    liburing4cpp
    GIT_REPOSITORY https://github.com/CarterLi/liburing4cpp.git
    GIT_TAG        async
)
FetchContent_MakeAvailable(liburing4cpp)

Then, just use target_link_libraries, which will ensure that liburing4cpp/include is added to the list of includes for whatever target you're building.

target_link_libraries(
    <your target>
    <PUBLIC|PRIVATE|INTERFACE>
    liburing4cpp)

License

MIT