github.com/pawelgaczynski/gain@v0.4.0-alpha.0.20230821120126-41f1e60a18da/README.md (about) 1 <a name="readme-top"></a> 2 3 <br /> 4 <div align="center"> 5 <a href="https://github.com/pawelgaczynski/gain"> 6 <img src="images/gain.png" alt="Logo" width="495" height="327"> 7 </a> 8 9 [![Apache 2.0 License][license-shield]][license-url] 10 [](https://pkg.go.dev/github.com/pawelgaczynski/gain) 11 [](https://goreportcard.com/report/github.com/pawelgaczynski/gain) 12 [](https://codecov.io/gh/pawelgaczynski/gain) 13 14 <h2 align="center">Gain</h2> 15 16 <p align="center"> 17 Gain is a high-performance io_uring networking framework written entirely in Go. 18 <br /> 19 <br /> 20 <a href="https://github.com/pawelgaczynski/gain/issues">Report Bug</a> 21 · 22 <a href="https://github.com/pawelgaczynski/gain/issues">Request Feature</a> 23 </p> 24 </div> 25 26 27 <details> 28 <summary>Table of Contents</summary> 29 <ol> 30 <li> 31 <a href="#about-the-project">About The Project</a> 32 </li> 33 <li> 34 <a href="#getting-started">Getting Started</a> 35 <ul> 36 <li><a href="#prerequisites">Prerequisites</a></li> 37 <li><a href="#installation">Installation</a></li> 38 </ul> 39 </li> 40 <li><a href="#usage">Usage</a></li> 41 <li><a href="#roadmap">Roadmap</a></li> 42 <li><a href="#performance">Performance</a></li> 43 <li><a href="#contributing">Contributing</a></li> 44 <li><a href="#license">License</a></li> 45 <li><a href="#contact">Contact</a></li> 46 <li><a href="#relevant-articles">Relevant Articles</a></li> 47 </ol> 48 </details> 49 50 <br/> 51 52 ## About The Project 53 54 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. 55 56 **WARNING: This is an alpha version so it is not yet stable enough to use in a production environment.** 57 58 Articles about the project: 59 60 * [Medium - Meet Gain - the New Fastest Go TCP Framework](https://medium.com/better-programming/gain-the-new-fastest-go-tcp-framework-40ec111d40e6) 61 * [Medium - Writing High-performance TCP Applications Using the Gain Web Framework](https://medium.com/better-programming/an-introduction-to-gain-part-1-writing-high-performance-tcp-application-df5f7253e54a) 62 63 <br/> 64 65 ## Getting Started 66 67 68 **See examples:** 69 70 * **[CLI server example](https://github.com/pawelgaczynski/gain/blob/main/examples/cli/main.go)** 71 * **[TCP echo server example](https://github.com/pawelgaczynski/gain/blob/main/examples/tcp_echo/main.go)** 72 73 <br/> 74 75 ### Prerequisites 76 77 Gain requires Go 1.20+ 78 79 <br/> 80 81 ### Installation 82 83 1. Install the framework 84 ```sh 85 go get -u github.com/pawelgaczynski/gain@v0.4.0-alpha 86 ``` 87 88 <p align="right">(<a href="#readme-top">back to top</a>)</p> 89 90 ## Roadmap 91 92 - [x] Go liburing port 93 - [x] Reactor architecture 94 - [x] Socket sharding architecture 95 - [x] Async workers and workers pool 96 - [x] Lock-free 97 - [ ] Protocols 98 - [x] TCP 99 - [x] UDP 100 - [ ] Unix Domain Socket 101 - [ ] Load balancing 102 - [x] Round robin 103 - [x] Least connection 104 - [x] Source IP hash 105 - [ ] Support for custom implementations 106 - [ ] Support for read and write deadlines 107 - [ ] Further io_uring optimizations 108 - [x] More flexible connection buffer 109 - [x] Documentation 110 - [x] Support for kernels older than 5.15 111 - [ ] Support for Windows - IoRing ([documentation](https://learn.microsoft.com/en-us/windows/win32/api/ioringapi/)) 112 113 See the [open issues](https://github.com/pawelgaczynski/gain/issues) for a full list of proposed features (and known issues). 114 115 <p align="right">(<a href="#readme-top">back to top</a>)</p> 116 117 118 119 ## Performance 120 121 AWS EC2 instance: m6i.xlarge 122 <br/> 123 vCPU: 4 124 <br/> 125 RAM: 16GB 126 <br/> 127 OS: Ubuntu 22.04 LTS 128 <br/> 129 Kernel: 5.15.0-1026-aws 130 <br/> 131 Go: go1.19.3 linux/amd64 132 <br/> 133 Number of connections: 512 134 <br/> 135 Benchmark type: [see TechEmpower Plaintext](https://github.com/TechEmpower/FrameworkBenchmarks/wiki/Project-Information-Framework-Tests-Overview#plaintext) 136 <br/> 137 138 <br/> 139 <a href="https://github.com/pawelgaczynski/gain"> 140 <img src="images/benchmark_result.png" alt="Logo" width="710" height="454"> 141 </a> 142 <br/> 143 <br/> 144 145 ### Perfect locality 146 147 Run this script on the server machine before starting Gain. The first parameter is the name of network interface (e.g. eth0, ens5). 148 149 ```sh 150 #!/bin/bash 151 152 systemctl stop irqbalance.service 153 154 export IRQS=($(grep $1 /proc/interrupts | awk '{print $1}' | tr -d :)) 155 for i in ${!IRQS[@]}; do echo $i > /proc/irq/${IRQS[i]}/smp_affinity_list; done; 156 157 export TXQUEUES=($(ls -1qdv /sys/class/net/$1/queues/tx-*)) 158 for i in ${!TXQUEUES[@]}; do printf '%x' $((2**i)) > ${TXQUEUES[i]}/xps_cpus; done; 159 160 ``` 161 162 To understand how it was achieved read an excellent article: [Extreme HTTP Performance Tuning](https://talawah.io/blog/extreme-http-performance-tuning-one-point-two-million/#_5-perfect-locality) 163 164 <p align="right">(<a href="#readme-top">back to top</a>)</p> 165 166 ## Contributing 167 168 Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. 169 170 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". 171 Don't forget to give the project a star! Thanks again! 172 173 1. Fork the Project 174 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) 175 3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`) 176 4. Push to the Branch (`git push origin feature/AmazingFeature`) 177 5. Open a Pull Request 178 179 <p align="right">(<a href="#readme-top">back to top</a>)</p> 180 181 ## License 182 183 Distributed under the Apache 2.0 License. See `LICENSE` for more information. 184 185 <p align="right">(<a href="#readme-top">back to top</a>)</p> 186 187 188 ## Contact 189 190 Paweł Gaczyński - [LinkedIn](http://linkedin.com/in/pawel-gaczynski) 191 192 Project Link: [https://github.com/pawelgaczynski/gain](https://github.com/pawelgaczynski/gain) 193 194 <p align="right">(<a href="#readme-top">back to top</a>)</p> 195 196 197 ## Relevant Articles 198 199 * [Lord of the io_uring](https://unixism.net/loti/what_is_io_uring.html) 200 * [Ringing in a new asynchronous I/O API](https://lwn.net/Articles/776703/) 201 * [The rapid growth of io_uring](https://lwn.net/Articles/810414/) 202 * [An Introduction to the io_uring Asynchronous I/O Framework](https://blogs.oracle.com/linux/post/an-introduction-to-the-io-uring-asynchronous-io-framework) 203 * [How io_uring and eBPF Will Revolutionize Programming in Linux](https://www.scylladb.com/2020/05/05/how-io_uring-and-ebpf-will-revolutionize-programming-in-linux/) 204 * [Missing Manuals - io_uring worker pool](https://blog.cloudflare.com/missing-manuals-io_uring-worker-pool/) 205 * [IO_uring Continues Advancing In 2022 With New Features For Pushing Linux I/O](https://www.phoronix.com/news/KR2022-IO_uring) 206 * [Getting Hands on with io_uring using Go](https://developers.mattermost.com/blog/hands-on-iouring-go/) 207 * [liburing Github](https://github.com/axboe/liburing) 208 209 <p align="right">(<a href="#readme-top">back to top</a>)</p> 210 211 212 [license-shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg 213 [license-url]: https://github.com/pawelgaczynski/gain/blob/main/LICENSE