gnet

README

[中文]

gnet is an Event-Loop 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 libuv and libevent.

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, nonblocking network library 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 a 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.

gent derives from project evio while having higher performance.

Features

• High-performance Event-Loop under multi-threads/goroutines model
• Built-in load balancing algorithm: Round-Robin
• Concise APIs
• Efficient memory usage: Ring-Buffer
• Supporting multiple protocols: TCP, UDP, and Unix Sockets
• Supporting two event-notification mechanisms: epoll in Linux and kqueue in FreeBSD
• Supporting asynchronous write operation
• Allowing multiple network binding on the same Event-Loop
• Flexible ticker event
• SO_REUSEPORT socket option

Key Designs

Multiple-Threads/Goroutines Model

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:

The subsequent multiple-threads/goroutines model of gnet: 『Multiple Reactors with thread/goroutine pool』is under development and about to be delivered soon, the architecture diagram of new model is in here:

and it works as the following sequence diagram:

Communication Mechanism

gnet builds its 『Multiple Reactors』Model under Goroutines in Golang, one Reactor per Goroutine, so there is a critical requirement handling extremely large amounts of messages between Goroutines in this networking model of gnet, which means gnet needs a efficient communication mechanism between Goroutines. I choose a tricky solution of Disruptor(Ring-Buffer) which provides a higher performance of messages dispatching in networking, instead of the recommended pattern: CSP(Channel) under Golang-Best-Practices.

That is why I finally settle on go-disruptor: the Golang port of the LMAX Disruptor(a high performance inter-thread messaging library).

Auto-scaling Ring Buffer

gnet leverages Ring-Buffer to cache TCP streams and manage memory cache in networking.

Getting Started

Installation

$ go get -u github.com/panjf2000/gnet

Usage

It is easy to create a network server with gnet. All you have to do is just register your events to gnet.Events and pass it to the gnet.Serve function along with the binding address(es). Each connections is represented as an gnet.Conn object 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 litsening on port 9000:

package main

import (
	"log"

	"github.com/panjf2000/gnet"
	"github.com/panjf2000/gnet/ringbuffer"
)

func main() {
	var events gnet.Events
	events.Multicore = true
	events.React = func(c gnet.Conn, inBuf *ringbuffer.RingBuffer) (out []byte, action gnet.Action) {
		top, tail := inBuf.PreReadAll()
		out = append(top, tail...)
		inBuf.Reset()
		return
	}
	log.Fatal(gnet.Serve(events, "tcp://:9000"))
}

As you can see, this example of echo server only sets up the 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).

I/O Events

Current supported I/O events in gnet:

• OnInitComplete is activated when the server is ready to accept new connections.
• OnOpened is activated when a connection has opened.
• OnClosed is activated when a connection has closed.
• OnDetached is activated when a connection has been detached using the Detach return action.
• React is activated when the server receives new data from a connection.
• Tick is activated immediately after the server starts and will fire again after a specified interval.
• PreWrite is activated just before any data is written to any client socket.

Multiple addresses

// Binding both TCP and Unix-Socket to one gnet server.
gnet.Serve(events, "tcp://:9000", "unix://socket")

Ticker

The Tick event fires ticks at a specified interval. The first tick fires immediately after the Serving events.

events.Tick = func() (delay time.Duration, action Action){
	log.Printf("tick")
	delay = time.Second
	return
}

UDP

The Serve function can bind to UDP addresses.

• All incoming and outgoing packets will not be buffered but sent individually.
• The OnOpened and OnClosed events are not availble for UDP sockets, only the React event.

Multi-threads

The Events.Multicore indicates whether the server will be effectively created with multi-cores, if so, then you must take care with synchonizing memory between all event callbacks, otherwise, it will run the server with single thread. The number of threads in the server will be automatically assigned to the value of runtime.NumCPU().

Load balancing

The current built-in load balancing algorithm in gnet is Round-Robin.

SO_REUSEPORT

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 provide reuseport=true to an address and you can enjoy this feature:

gnet.Serve(events, "tcp://:9000?reuseport=true"))

Performance

On Linux (epoll)

Test Environment

Go Version : go1.12.9 linux/amd64
        OS : Ubuntu 18.04/x86_64
       CPU : 8 Virtual CPUs
    Memory : 16.0 GiB

Echo Server

HTTP Server

On FreeBSD (kqueue)

Test Environment

Go Version : go version go1.12.9 darwin/amd64
        OS : macOS Mojave 10.14.6/x86_64
       CPU : 4 CPUs
    Memory : 8.0 GiB

Echo Server

HTTP Server

License

Source code in gnet is available under the MIT License.

Thanks

• evio
• go-disruptor

TODO

gnet is still under active development so the code and documentation will continue to be updated, if you are interested in gnet, please feel free to make your code contributions to it, also if you like gnet, give it a star ~~

Documentation

Index

• func Serve(events Events, addr ...string) error
• type Action
• type Conn
• type Events
• type Options
• type Server

Functions

func Serve

func Serve(events Events, addr ...string) error

Serve starts handling events for the specified addresses.

Addresses should use a scheme prefix and be formatted like `tcp://192.168.0.10:9851` or `unix://socket`. Valid network schemes:

tcp   - bind to both IPv4 and IPv6
tcp4  - IPv4
tcp6  - IPv6
udp   - bind to both IPv4 and IPv6
udp4  - IPv4
udp6  - IPv6
unix  - Unix Domain Socket

The "tcp" network scheme is assumed when one is not specified.

Types

type Action

type Action int

Action is an action that occurs after the completion of an event.

const (
	// None indicates that no action should occur following an event.
	None Action = iota
	// Detach detaches a connection. Not available for UDP connections.
	Detach
	// Close closes the connection.
	Close
	// Shutdown shutdowns the server.
	Shutdown
)

type Conn

type Conn interface {
	// Context returns a user-defined context.
	Context() interface{}
	// SetContext sets a user-defined context.
	SetContext(interface{})
	// AddrIndex is the index of server address that was passed to the Serve call.
	AddrIndex() int
	// LocalAddr is the connection's local socket address.
	LocalAddr() net.Addr
	// RemoteAddr is the connection's remote peer address.
	RemoteAddr() net.Addr
	// Wake triggers a React event for this connection.
	Wake()
}

Conn is an gnet connection.

type Events

type Events struct {
	// Multicore indicates whether the server will be effectively created with multi-cores, if so,
	// then you must take care with synchonizing memory between all event callbacks, otherwise,
	// it will run the server with single thread. The number of threads in the server will be automatically
	// assigned to the value of runtime.NumCPU().
	Multicore bool
	// OnInitComplete fires when the server can accept connections. The server
	// parameter has information and various utilities.
	OnInitComplete func(server Server) (action Action)
	// OnOpened fires when a new connection has opened.
	// The info parameter has information about the connection such as
	// it's local and remote address.
	// Use the out return value to write data to the connection.
	// The opts return value is used to set connection options.
	OnOpened func(c Conn) (out []byte, opts Options, action Action)
	// OnClosed fires when a connection has closed.
	// The err parameter is the last known connection error.
	OnClosed func(c Conn, err error) (action Action)
	// OnDetached fires when a connection has been previously detached.
	// Once detached it's up to the receiver of this event to manage the
	// state of the connection. The OnClosed event will not be called for
	// this connection.
	// The conn parameter is a ReadWriteCloser that represents the
	// underlying socket connection. It can be freely used in goroutines
	// and should be closed when it's no longer needed.
	OnDetached func(c Conn, rwc io.ReadWriteCloser) (action Action)
	// PreWrite fires just before any data is written to any client socket.
	PreWrite func()
	// React fires when a connection sends the server data.
	// The in parameter is the incoming data.
	// Use the out return value to write data to the connection.
	React func(c Conn, inBuf *ringbuffer.RingBuffer) (out []byte, action Action)
	// Tick fires immediately after the server starts and will fire again
	// following the duration specified by the delay return value.
	Tick func() (delay time.Duration, action Action)
}

Events represents the server events for the Serve call. Each event has an Action return value that is used manage the state of the connection and server.

type Options

type Options struct {
	// TCPKeepAlive (SO_KEEPALIVE) socket option.
	TCPKeepAlive time.Duration
}

Options are set when the client opens.

type Server

type Server struct {
	// The addrs parameter is an array of listening addresses that align
	// with the addr strings passed to the Serve function.
	Addrs []net.Addr
	// NumLoops is the number of loops that the server is using.
	NumLoops int
}

Server represents a server context which provides information about the running server and has control functions for managing state.