English | π¨π³δΈζ
gnet is an event-driven networking framework that is fast and small. It makes direct epoll and kqueue syscalls rather than using the standard Go net package, and works in a similar manner as netty and libuv.
The goal of this project is to create a server framework for Go that performs on par with Redis and Haproxy for packet handling.
gnet sells itself as a high-performance, lightweight, non-blocking, event-driven networking framework written in pure Go which works on transport layer with TCP/UDP/Unix-Socket protocols, so it allows developers to implement their own protocols of application layer upon gnet for building diversified network applications, for instance, you get an HTTP Server or Web Framework if you implement HTTP protocol upon gnet while you have a Redis Server done with the implementation of Redis protocol upon gnet and so on.
gnet derives from the project: evio while having a much higher performance.
- High-performance event-loop under multi-threads/goroutines model
- Built-in load balancing algorithm: Round-Robin
- Built-in goroutine pool powered by the library ants
- Built-in memory pool with bytes powered by the library pool
- Concise APIs
- Efficient memory usage: Ring-Buffer
- Supporting multiple protocols: TCP, UDP, and Unix Sockets
- Supporting two event-notification mechanisms: epoll on Linux and kqueue on FreeBSD
- Supporting asynchronous write operation
- Flexible ticker event
- SO_REUSEPORT socket option
- Additional load-balancing algorithms: Random, Least-Connections, Consistent-hashing and so on
- New event-notification mechanism: IOCP on Windows platform
- TLS support
- Implementation of
gnetClient
gnet redesigns and implements a new built-in multiple-threads/goroutines model: γMultiple Reactorsγ which is also the default multiple-threads model of netty, Here's the schematic diagram:
and it works as the following sequence diagram:
You may ask me a question: what if my business logic in EventHandler.React contains some blocking code which leads to blocking in event-loop of gnet, what is the solution for this kind of situationοΌ
As you know, there is a most important tenet when writing code under gnet: you should never block the event-loop in the EventHandler.React, otherwise, it will lead to a low throughput in your gnet server, which is also the most important tenet in netty.
And the solution for that could be found in the subsequent multiple-threads/goroutines model of gnet: γMultiple Reactors with thread/goroutine poolγwhich pulls you out from the blocking mire, it will construct a worker-pool with fixed capacity and put those blocking jobs in EventHandler.React into the worker-pool to make the event-loop goroutines non-blocking.
The architecture diagram ofγMultiple Reactors with thread/goroutine poolγnetworking model architecture is in here:
and it works as the following sequence diagram:
gnet implements the networking model of γMultiple Reactors with thread/goroutine poolγby the aid of a high-performance goroutine pool called ants that allows you to manage and recycle a massive number of goroutines in your concurrent programs, the full features and usages in ants are documented here.
gnet integrates ants and provides the pool.NewWorkerPool method that you can invoke to instantiate a ants pool where you are able to put your blocking code logic in EventHandler.React and invoke the function of gnet.Conn.AsyncWrite to send out data asynchronously in worker pool after you finish the blocking process and get the output data, which makes the goroutine of event-loop non-blocking.
The details about integrating gnet with ants are shown here.
gnet utilizes Ring-Buffer to buffer network data and manage memories in networking.
gnet requires Go 1.9 or later.
go get -u github.com/panjf2000/gnetgnet is available as a Go module, with Go 1.11 Modules support (Go 1.11+), just simply import "github.com/panjf2000/gnet" in your source code and go [build|run|test] will download the necessary dependencies automatically.
The detailed documentation is located in here: docs of gnet, but let's pass through the brief instructions first.
It is easy to create a network server with gnet. All you have to do is just make your implementation of gnet.EventHandler interface and register your event-handler functions to it, then pass it to the gnet.Serve function along with the binding address(es). Each connection is represented as a gnet.Conn interface that is passed to various events to differentiate the clients. At any point you can close a client or shutdown the server by return a Close or Shutdown action from an event.
The simplest example to get you started playing with gnet would be the echo server. So here you are, a simplest echo server upon gnet that is listening on port 9000:
package main
import (
"log"
"github.com/panjf2000/gnet"
)
type echoServer struct {
*gnet.EventServer
}
func (es *echoServer) React(c gnet.Conn) (out []byte, action gnet.Action) {
out = c.Read()
c.ResetBuffer()
return
}
func main() {
echo := new(echoServer)
log.Fatal(gnet.Serve(echo, "tcp://:9000", gnet.WithMulticore(true)))
}As you can see, this example of echo server only sets up the EventHandler.React function where you commonly write your main business code and it will be invoked once the server receives input data from a client. The output data will be then sent back to that client by assigning the out variable and return it after your business code finish processing data(in this case, it just echo the data back).
package main
import (
"log"
"time"
"github.com/panjf2000/gnet"
"github.com/panjf2000/gnet/pool"
)
type echoServer struct {
*gnet.EventServer
pool *pool.WorkerPool
}
func (es *echoServer) React(c gnet.Conn) (out []byte, action gnet.Action) {
data := append([]byte{}, c.Read()...)
c.ResetBuffer()
// Use ants pool to unblock the event-loop.
_ = es.pool.Submit(func() {
time.Sleep(1 * time.Second)
c.AsyncWrite(data)
})
return
}
func main() {
p := pool.NewWorkerPool()
defer p.Release()
echo := &echoServer{pool: p}
log.Fatal(gnet.Serve(echo, "tcp://:9000", gnet.WithMulticore(true)))
}Like I said in the γMultiple Reactors + Goroutine-Pool Modelγsection, if there are blocking code in your business logic, then you ought to turn them into non-blocking code in any way, for instance you can wrap them into a goroutine, but it will result in a massive amount of goroutines if massive traffic is passing through your server so I would suggest you utilize a goroutine pool like ants to manage those goroutines and reduce the cost of system resources.
For more examples, check out here: examples of gnet.
Current supported I/O events in gnet:
EventHandler.OnInitCompleteis activated when the server is ready to accept new connections.EventHandler.OnOpenedis activated when a connection has opened.EventHandler.OnClosedis activated when a connection has closed.EventHandler.Reactis activated when the server receives new data from a connection. (usually it is where you write the code of business logic)EventHandler.Tickis activated immediately after the server starts and will fire again after a specified interval.EventHandler.PreWriteis activated just before any data is written to any client socket.
The EventHandler.Tick event fires ticks at a specified interval.
The first tick fires immediately after the Serving events and if you intend to set up a ticker event, remember to pass an option: gnet.WithTicker(true) to gnet.Serve.
events.Tick = func() (delay time.Duration, action Action){
log.Printf("tick")
delay = time.Second
return
}The gnet.Serve function can bind to UDP addresses.
- All incoming and outgoing packets will not be buffered but sent individually.
- The
EventHandler.OnOpenedandEventHandler.OnClosedevents are not available for UDP sockets, only theReactevent.
The gnet.WithMulticore(true) indicates whether the server will be effectively created with multi-cores, if so, then you must take care of synchronizing memory between all event callbacks, otherwise, it will run the server with a single thread. The number of threads in the server will be automatically assigned to the value of runtime.NumCPU().
The current built-in load balancing algorithm in gnet is Round-Robin.
Servers can utilize the SO_REUSEPORT option which allows multiple sockets on the same host to bind to the same port and the OS kernel takes care of the load balancing for you, it wakes one socket per accpet event coming to resolved the thundering herd.
Just use functional options to set up SO_REUSEPORT and you can enjoy this feature:
gnet.Serve(events, "tcp://:9000", gnet.WithMulticore(true), gnet.WithReusePort(true)))# Machine information
OS : Ubuntu 18.04/x86_64
CPU : 8 Virtual CPUs
Memory : 16.0 GiB
# G
9C2A
o version and configurations
Go Version : go1.12.9 linux/amd64
GOMAXPROCS=8# Machine information
OS : macOS Mojave 10.14.6/x86_64
CPU : 4 CPUs
Memory : 8.0 GiB
# Go version and configurations
Go Version : go version go1.12.9 darwin/amd64
GOMAXPROCS=4Source code in gnet is available under the MIT License.
Please read our Contributing Guidelines before opening a PR and thank you to all the developers who already made contributions to gnet!
- A Million WebSockets and Go
- Going Infinite, handling 1M websockets connections in Go
- gnet: δΈδΈͺθ½»ιηΊ§δΈι«ζ§θ½η Golang η½η»εΊ
Support us with a monthly donation and help us continue our activities.
Become a bronze sponsor with a monthly donation of $10 and get your logo on our README on Github.
Β Β
Β Β
Β Β