https://github.com/andydunstall/puddle

Minimal asynchronous C++ networking library
https://github.com/andydunstall/puddle

Last synced: 28 days ago
JSON representation

Minimal asynchronous C++ networking library

• Host: GitHub
• URL: https://github.com/andydunstall/puddle
• Owner: andydunstall
• Created: 2023-05-28T17:48:25.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-03-03T07:08:22.000Z (11 months ago)
• Last Synced: 2024-10-28T20:10:32.511Z (3 months ago)
• Language: C++
• Homepage:
• Size: 119 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Puddle

> Note Puddle is just a toy project to play with Boost fibers and `io_uring`.

Puddle is a minimal asynchronous C++ networking library built with

[Boost fibers](https://publish.obsidian.md/andydunstall/public/Boost+Fibers)

and `io_uring`.

Puddle is based on the [helio](https://github.com/romange/helio), though

Puddle only supports a single OS thread and is much more basic.

## Usage

Puddle provides asynchronous networking on a single OS thread using Boost

fibers.

To create a TCP server with Puddle, you must implement `puddle::Listener` which

accepts connections. The `Listener::Connection(std::unique_ptr conn)`

method is called when a new connection is accepted.

Each connection is run in its own fiber and can use the passed `puddle::Socket`

to read and write to the socket. When reads and writes block, the fiber will

be descheduled so another fiber can run on the same thread.

See [`examples/echo`](examples/echo/main.cc) for an example.

## Scheduling

Each connection has its own fiber. When the connection 'blocks' by making

a socket request, the request will be added to the `io_uring` submission queue

and the fiber will be descheduled so another fiber can run.

Puddle implements a custom fiber scheduling algorithm which used round-robin

scheduling, similar to the default algorithm. Though when there are no fibers

ready to run, it will submit the queued requests to `io_uring` and wait for

a completion event. For each completion event, it will mark the fiber blocked

on that event as ready to run so the fiber will be scheduled.

## Building

Puddle is built with [Bazel](https://bazel.build/).

Build the library with `bazel build //puddle:puddle` which will build both

`bazel-bin/puddle/libpuddle.a` and `bazel-bin/puddle/libpuddle.so`.

You can also run the echo server example with `bazel run //examples/echo`.