Gain

<a name="readme-top"></a>

<br /> <div align="center"> <a href="https://github.com/pawelgaczynski/gain"> <img src="images/gain.png" alt="Logo" width="495" height="327"> </a>

<h2 align="center">Gain</h2> <p align="center"> Gain is a high-performance io_uring networking framework written entirely in Go. <br /> <br /> <a href="https://github.com/pawelgaczynski/gain/issues">Report Bug</a> · <a href="https://github.com/pawelgaczynski/gain/issues">Request Feature</a> </p> </div> <details> <summary>Table of Contents</summary> <ol> <li> <a href="#about-the-project">About The Project</a> </li> <li> <a href="#getting-started">Getting Started</a> <ul> <li><a href="#prerequisites">Prerequisites</a></li> <li><a href="#installation">Installation</a></li> </ul> </li> <li><a href="#usage">Usage</a></li> <li><a href="#roadmap">Roadmap</a></li> <li><a href="#performance">Performance</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> <li><a href="#relevant-articles">Relevant Articles</a></li> </ol> </details> <br/>

About The Project

Gain is a high-performance networking framework written entirely in Go. It uses io_uring - a new asynchronous I/O API for Linux created by Jens Axboe from Facebook. Currently only Linux is supported.

WARNING: This is an alpha version so it is not yet stable enough to use in a production environment.

Articles about the project:

• Medium - Meet Gain - the New Fastest Go TCP Framework
• Medium - Writing High-performance TCP Applications Using the Gain Web Framework

<br/>

Getting Started

See examples:

• CLI server example
• TCP echo server example

<br/>

Prerequisites

Gain requires Go 1.20+

<br/>

Installation

1. Install the framework

   go get -u github.com/pawelgaczynski/gain@v0.4.0-alpha
   

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Roadmap

• [x] Go liburing port
• [x] Reactor architecture
• [x] Socket sharding architecture
• [x] Async workers and workers pool
• [x] Lock-free
• [ ] Protocols
  • [x] TCP
  • [x] UDP
  • [ ] Unix Domain Socket
• [ ] Load balancing
  • [x] Round robin
  • [x] Least connection
  • [x] Source IP hash
  • [ ] Support for custom implementations
• [ ] Support for read and write deadlines
• [ ] Further io_uring optimizations
• [x] More flexible connection buffer
• [x] Documentation
• [x] Support for kernels older than 5.15
• [ ] Support for Windows - IoRing (documentation)

See the open issues for a full list of proposed features (and known issues).

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Performance

AWS EC2 instance: m6i.xlarge <br/> vCPU: 4 <br/> RAM: 16GB <br/> OS: Ubuntu 22.04 LTS <br/> Kernel: 5.15.0-1026-aws <br/> Go: go1.19.3 linux/amd64 <br/> Number of connections: 512 <br/> Benchmark type: see TechEmpower Plaintext <br/>

<br/> <a href="https://github.com/pawelgaczynski/gain"> <img src="images/benchmark_result.png" alt="Logo" width="710" height="454"> </a> <br/> <br/>

Perfect locality

Run this script on the server machine before starting Gain. The first parameter is the name of network interface (e.g. eth0, ens5).

#!/bin/bash

systemctl stop irqbalance.service

export IRQS=($(grep $1 /proc/interrupts | awk '{print $1}' | tr -d :))
for i in ${!IRQS[@]}; do echo $i > /proc/irq/${IRQS[i]}/smp_affinity_list; done;

export TXQUEUES=($(ls -1qdv /sys/class/net/$1/queues/tx-*))
for i in ${!TXQUEUES[@]}; do printf '%x' $((2**i)) > ${TXQUEUES[i]}/xps_cpus; done;

To understand how it was achieved read an excellent article: Extreme HTTP Performance Tuning

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

<p align="right">(<a href="#readme-top">back to top</a>)</p>

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Contact

Paweł Gaczyński - LinkedIn

Project Link: https://github.com/pawelgaczynski/gain

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Relevant Articles

• Lord of the io_uring
• Ringing in a new asynchronous I/O API
• The rapid growth of io_uring
• An Introduction to the io_uring Asynchronous I/O Framework
• How io_uring and eBPF Will Revolutionize Programming in Linux
• Missing Manuals - io_uring worker pool
• IO_uring Continues Advancing In 2022 With New Features For Pushing Linux I/O
• Getting Hands on with io_uring using Go
• liburing Github

<p align="right">(<a href="#readme-top">back to top</a>)</p>