/ / 32 min read

Presenting Gnet

Hello World! We present you, gnet!
type: announcementdomain: presentation

gnet

📖 Introduction

gnet is an event-driven networking framework that is fast and lightweight. 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, which makes gnet achieve a much higher performance than Go net.

gnet is not designed to displace the standard Go net package, but to create a networking server framework for Go that performs on par with Redis and Haproxy for networking packets 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 protocols and Unix Domain Socket , so it allows developers to implement their own protocols(HTTP, RPC, WebSocket, Redis, etc.) 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 and more features.

🚀 Features

  • High-performance event-loop under networking model of multiple threads/goroutines
  • Built-in goroutine pool powered by the library ants
  • Built-in memory pool with bytes powered by the library bytebufferpool
  • Lock-free during the entire runtime
  • Concise and easy-to-use APIs
  • Efficient, reusable and scalable memory buffer: Ring-Buffer
  • Supporting multiple protocols/IPC mechanism: TCP, UDP and Unix Domain Socket
  • Supporting multiple load-balancing algorithms: Round-Robin, Source-Addr-Hash and Least-Connections
  • Supporting two event-driven mechanisms: epoll on Linux and kqueue on FreeBSD/DragonFly/Darwin
  • Supporting asynchronous write operation
  • Flexible ticker event
  • SO_REUSEPORT socket option
  • Built-in multiple codecs to encode/decode network frames into/from TCP stream: LineBasedFrameCodec, DelimiterBasedFrameCodec, FixedLengthFrameCodec and LengthFieldBasedFrameCodec, referencing netty codec, also supporting customized codecs
  • Supporting Windows platform with event-driven mechanism of IOCP Go stdlib: net
  • Implementation of gnet Client

💡 Key Designs

Networking Model of Multiple Threads/Goroutines

Multiple Reactors

gnet redesigns and implements a new built-in networking model of multiple threads/goroutines: 『multiple reactors』 which is also the default networking model of multiple threads in netty, Here's the schematic diagram:

multi_reactor

and it works as the following sequence diagram:

reactor

Multiple Reactors + Goroutine Pool

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 goroutine in the EventHandler.React, which is also the most important tenet in netty, otherwise, it will result in a low throughput in your gnet server.

And the solution to that could be found in the subsequent networking model of multiple threads/goroutines in 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 networking model:『multiple reactors with thread/goroutine pool』dissolves the blocking jobs by introducing a goroutine pool, as shown below:

multi_reactor_thread_pool

and it works as the following sequence diagram:

multi-reactors

gnet implements the networking model:『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.goroutine.Default() method that you can call to instantiate a ants pool where you are able to put your blocking code logic and call the function gnet.Conn.AsyncWrite([]byte) to send out data asynchronously 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.

Reusable and auto-scaling Ring Buffer

There are two ring-buffers inside gnet: inbound buffer and outbound buffer to buffer and manage inbound/outbound network data, ring-buffer inside gnet is designed and tuned to reuse memory and be auto-scaling on demand.

The purpose of implementing inbound and outbound ring-buffers in gnet is to transfer the logic of buffering and managing network data based on application protocol upon TCP stream from business server to framework and unify the network data buffer, which minimizes the complexity of business code so that developers are able to concentrate on business logic instead of the underlying implementation.

🎉 Getting Started

Prerequisites

gnet requires Go 1.9 or later.

Installation

go get -u github.com/panjf2000/gnet

gnet 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.

Usage Examples

The detailed documentation is located 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 to 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 connection or shutdown the server by return a Close or Shutdown action from an event function.

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:

Echo server without blocking logic

Old version(<=v1.0.0-rc.4) 
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)))
}
package main


import (
    "log"


    "github.com/panjf2000/gnet"
)


type echoServer struct {
    *gnet.EventServer
}


func (es *echoServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    out = frame
    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 called once the server receives input data from a client. What you should know is that the input parameter: frame is a complete packet which has been decoded by the codec, as a general rule, you should implement the gnet codec interface as the business codec to packet and unpacket TCP stream, but if you don't, your gnet server is going to work with the default codec under the acquiescence, which means all data inculding latest data and previous data in buffer will be stored in the input parameter: frame when EventHandler.React is being triggered. The output data will be then encoded and sent back to that client by assigning the out variable and returning it after your business code finish processing data(in this case, it just echo the data back).

Echo server with blocking logic

Old version(<=v1.0.0-rc.4) 
package main


import (
    "log"
    "time"


    "github.com/panjf2000/gnet"
    "github.com/panjf2000/gnet/pool/goroutine"
)


type echoServer struct {
    *gnet.EventServer
    pool *goroutine.Pool
}


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 := goroutine.Default()
    defer p.Release()
    
    echo := &echoServer{pool: p}
    log.Fatal(gnet.Serve(echo, "tcp://:9000", gnet.WithMulticore(true)))
}
package main


import (
    "log"
    "time"


    "github.com/panjf2000/gnet"
    "github.com/panjf2000/gnet/pool/goroutine"
)


type echoServer struct {
    *gnet.EventServer
    pool *goroutine.Pool
}


func (es *echoServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    data := append([]byte{}, frame...)


    // Use ants pool to unblock the event-loop.
    _ = es.pool.Submit(func() {
        time.Sleep(1 * time.Second)
        c.AsyncWrite(data)
    })


    return
}


func main() {
    p := goroutine.Default()
    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』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.

All gnet examples:

TCP Echo Server 
package main


import (
    "flag"
    "fmt"
    "log"


    "github.com/panjf2000/gnet"
)


type echoServer struct {
    *gnet.EventServer
}


func (es *echoServer) OnInitComplete(srv gnet.Server) (action gnet.Action) {
    log.Printf("Echo server is listening on %s (multi-cores: %t, loops: %d)\n",
        srv.Addr.String(), srv.Multicore, srv.NumEventLoop)
    return
}


func (es *echoServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    // Echo synchronously.
    out = frame
    return


    /*
        // Echo asynchronously.
        data := append([]byte{}, frame...)
        go func() {
            time.Sleep(time.Second)
            c.AsyncWrite(data)
        }()
        return
    */
}


func main() {
    var port int
    var multicore, reuseport bool


    // Example command: go run echo.go --port 9000 --multicore=true --reuseport=true
    flag.IntVar(&port, "port", 9000, "--port 9000")
    flag.BoolVar(&multicore, "multicore", false, "--multicore true")
    flag.BoolVar(&reuseport, "reuseport", false, "--reuseport true")
    flag.Parse()
    echo := new(echoServer)
    log.Fatal(gnet.Serve(echo, fmt.Sprintf("tcp://:%d", port), gnet.WithMulticore(multicore), gnet.WithReusePort(reuseport)))
}
UDP Echo Server 
package main


import (
    "flag"
    "fmt"
    "log"


    "github.com/panjf2000/gnet"
)


type echoServer struct {
    *gnet.EventServer
}


func (es *echoServer) OnInitComplete(srv gnet.Server) (action gnet.Action) {
    log.Printf("UDP Echo server is listening on %s (multi-cores: %t, loops: %d)\n",
        srv.Addr.String(), srv.Multicore, srv.NumEventLoop)
    return
}


func (es *echoServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    // Echo synchronously.
    out = frame
    return


    /*
        // Echo asynchronously.
        data := append([]byte{}, frame...)
        go func() {
            time.Sleep(time.Second)
            c.SendTo(data)
        }()
        return
    */
}


func main() {
    var port int
    var multicore, reuseport bool


    // Example command: go run echo.go --port 9000 --multicore=true --reuseport=true
    flag.IntVar(&port, "port", 9000, "--port 9000")
    flag.BoolVar(&multicore, "multicore", false, "--multicore true")
    flag.BoolVar(&reuseport, "reuseport", false, "--reuseport true")
    flag.Parse()
    echo := new(echoServer)
    log.Fatal(gnet.Serve(echo, fmt.Sprintf("udp://:%d", port), gnet.WithMulticore(multicore), gnet.WithReusePort(reuseport)))
}
UDS Echo Server 
package main


import (
    "flag"
    "fmt"
    "log"


    "github.com/panjf2000/gnet"
)


type echoServer struct {
    *gnet.EventServer
}


func (es *echoServer) OnInitComplete(srv gnet.Server) (action gnet.Action) {
    log.Printf("Echo server is listening on %s (multi-cores: %t, loops: %d)\n",
        srv.Addr.String(), srv.Multicore, srv.NumEventLoop)
    return
}


func (es *echoServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    // Echo synchronously.
    out = frame
    return


    /*
        // Echo asynchronously.
        data := append([]byte{}, frame...)
        go func() {
            time.Sleep(time.Second)
            c.AsyncWrite(data)
        }()
        return
    */
}


func main() {
    var addr string
    var multicore bool


    // Example command: go run echo.go --sock echo.sock --multicore=true
    flag.StringVar(&addr, "sock", "echo.sock", "--port 9000")
    flag.BoolVar(&multicore, "multicore", false, "--multicore true")
    flag.Parse()


    echo := new(echoServer)
    log.Fatal(gnet.Serve(echo, fmt.Sprintf("unix://%s", addr), gnet.WithMulticore(multicore)))
}
HTTP Server 
package main


import (
    "flag"
    "fmt"
    "log"
    "strconv"
    "strings"
    "time"
    "unsafe"


    "github.com/panjf2000/gnet"
)


var res string


type request struct {
    proto, method string
    path, query   string
    head, body    string
    remoteAddr    string
}


type httpServer struct {
    *gnet.EventServer
}


var (
    errMsg      = "Internal Server Error"
    errMsgBytes = []byte(errMsg)
)


type httpCodec struct {
    req request
}


func (hc *httpCodec) Encode(c gnet.Conn, buf []byte) (out []byte, err error) {
    if c.Context() == nil {
        return buf, nil
    }
    return appendResp(out, "500 Error", "", errMsg+"\n"), nil
}


func (hc *httpCodec) Decode(c gnet.Conn) (out []byte, err error) {
    buf := c.Read()
    c.ResetBuffer()


    // process the pipeline
    var leftover []byte
pipeline:
    leftover, err = parseReq(buf, &hc.req)
    // bad thing happened
    if err != nil {
        c.SetContext(err)
        return nil, err
    } else if len(leftover) == len(buf) {
        // request not ready, yet
        return
    }
    out = appendHandle(out, res)
    buf = leftover
    goto pipeline
}


func (hs *httpServer) OnInitComplete(srv gnet.Server) (action gnet.Action) {
    log.Printf("HTTP server is listening on %s (multi-cores: %t, loops: %d)\n",
        srv.Addr.String(), srv.Multicore, srv.NumEventLoop)
    return
}


func (hs *httpServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    if c.Context() != nil {
        // bad thing happened
        out = errMsgBytes
        action = gnet.Close
        return
    }
    // handle the request
    out = frame
    return
}


func main() {
    var port int
    var multicore bool


    // Example command: go run http.go --port 8080 --multicore=true
    flag.IntVar(&port, "port", 8080, "server port")
    flag.BoolVar(&multicore, "multicore", true, "multicore")
    flag.Parse()


    res = "Hello World!\r\n"


    http := new(httpServer)
    hc := new(httpCodec)


    // Start serving!
    log.Fatal(gnet.Serve(http, fmt.Sprintf("tcp://:%d", port), gnet.WithMulticore(multicore), gnet.WithCodec(hc)))
}


// appendHandle handles the incoming request and appends the response to
// the provided bytes, which is then returned to the caller.
func appendHandle(b []byte, res string) []byte {
    return appendResp(b, "200 OK", "", res)
}


// appendResp will append a valid http response to the provide bytes.
// The status param should be the code plus text such as "200 OK".
// The head parameter should be a series of lines ending with "\r\n" or empty.
func appendResp(b []byte, status, head, body string) []byte {
    b = append(b, "HTTP/1.1"...)
    b = append(b, ' ')
    b = append(b, status...)
    b = append(b, '\r', '\n')
    b = append(b, "Server: gnet\r\n"...)
    b = append(b, "Date: "...)
    b = time.Now().AppendFormat(b, "Mon, 02 Jan 2006 15:04:05 GMT")
    b = append(b, '\r', '\n')
    if len(body) > 0 {
        b = append(b, "Content-Length: "...)
        b = strconv.AppendInt(b, int64(len(body)), 10)
        b = append(b, '\r', '\n')
    }
    b = append(b, head...)
    b = append(b, '\r', '\n')
    if len(body) > 0 {
        b = append(b, body...)
    }
    return b
}


func b2s(b []byte) string {
    return *(*string)(unsafe.Pointer(&b))
}


// parseReq is a very simple http request parser. This operation
// waits for the entire payload to be buffered before returning a
// valid request.
func parseReq(data []byte, req *request) (leftover []byte, err error) {
    sdata := b2s(data)
    var i, s int
    var head string
    var clen int
    q := -1
    // method, path, proto line
    for ; i < len(sdata); i++ {
        if sdata[i] == ' ' {
            req.method = sdata[s:i]
            for i, s = i+1, i+1; i < len(sdata); i++ {
                if sdata[i] == '?' && q == -1 {
                    q = i - s
                } else if sdata[i] == ' ' {
                    if q != -1 {
                        req.path = sdata[s:q]
                        req.query = req.path[q+1 : i]
                    } else {
                        req.path = sdata[s:i]
                    }
                    for i, s = i+1, i+1; i < len(sdata); i++ {
                        if sdata[i] == '\n' && sdata[i-1] == '\r' {
                            req.proto = sdata[s:i]
                            i, s = i+1, i+1
                            break
                        }
                    }
                    break
                }
            }
            break
        }
    }
    if req.proto == "" {
        return data, fmt.Errorf("malformed request")
    }
    head = sdata[:s]
    for ; i < len(sdata); i++ {
        if i > 1 && sdata[i] == '\n' && sdata[i-1] == '\r' {
            line := sdata[s : i-1]
            s = i + 1
            if line == "" {
                req.head = sdata[len(head)+2 : i+1]
                i++
                if clen > 0 {
                    if len(sdata[i:]) < clen {
                        break
                    }
                    req.body = sdata[i : i+clen]
                    i += clen
                }
                return data[i:], nil
            }
            if strings.HasPrefix(line, "Content-Length:") {
                n, err := strconv.ParseInt(strings.TrimSpace(line[len("Content-Length:"):]), 10, 64)
                if err == nil {
                    clen = int(n)
                }
            }
        }
    }
    // not enough data
    return data, nil
}
Push Server 
package main


import (
    "flag"
    "fmt"
    "log"
    "sync"
    "time"


    "github.com/panjf2000/gnet"
)


type pushServer struct {
    *gnet.EventServer
    tick             time.Duration
    connectedSockets sync.Map
}


func (ps *pushServer) OnInitComplete(srv gnet.Server) (action gnet.Action) {
    log.Printf("Push server is listening on %s (multi-cores: %t, loops: %d), "+
        "pushing data every %s ...\n", srv.Addr.String(), srv.Multicore, srv.NumEventLoop, ps.tick.String())
    return
}


func (ps *pushServer) OnOpened(c gnet.Conn) (out []byte, action gnet.Action) {
    log.Printf("Socket with addr: %s has been opened...\n", c.RemoteAddr().String())
    ps.connectedSockets.Store(c.RemoteAddr().String(), c)
    return
}


func (ps *pushServer) OnClosed(c gnet.Conn, err error) (action gnet.Action) {
    log.Printf("Socket with addr: %s is closing...\n", c.RemoteAddr().String())
    ps.connectedSockets.Delete(c.RemoteAddr().String())
    return
}


func (ps *pushServer) Tick() (delay time.Duration, action gnet.Action) {
    log.Println("It's time to push data to clients!!!")
    ps.connectedSockets.Range(func(key, value interface{}) bool {
        addr := key.(string)
        c := value.(gnet.Conn)
        c.AsyncWrite([]byte(fmt.Sprintf("heart beating to %s\n", addr)))
        return true
    })
    delay = ps.tick
    return
}


func (ps *pushServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    out = frame
    return
}


func main() {
    var port int
    var multicore bool
    var interval time.Duration
    var ticker bool


    // Example command: go run push.go --port 9000 --tick 1s --multicore=true
    flag.IntVar(&port, "port", 9000, "server port")
    flag.BoolVar(&multicore, "multicore", true, "multicore")
    flag.DurationVar(&interval, "tick", 0, "pushing tick")
    flag.Parse()
    if interval > 0 {
        ticker = true
    }
    push := &pushServer{tick: interval}
    log.Fatal(gnet.Serve(push, fmt.Sprintf("tcp://:%d", port), gnet.WithMulticore(multicore), gnet.WithTicker(ticker)))
}
Codec Client/Server

Client:

// Reference https://github.com/smallnest/goframe/blob/master/_examples/goclient/client.go


package main


import (
    "encoding/binary"
    "fmt"
    "net"


    "github.com/smallnest/goframe"
)


func main() {
    conn, err := net.Dial("tcp", "127.0.0.1:9000")
    if err != nil {
        panic(err)
    }
    defer conn.Close()


    encoderConfig := goframe.EncoderConfig{
        ByteOrder:                       binary.BigEndian,
        LengthFieldLength:               4,
        LengthAdjustment:                0,
        LengthIncludesLengthFieldLength: false,
    }


    decoderConfig := goframe.DecoderConfig{
        ByteOrder:           binary.BigEndian,
        LengthFieldOffset:   0,
        LengthFieldLength:   4,
        LengthAdjustment:    0,
        InitialBytesToStrip: 4,
    }


    fc := goframe.NewLengthFieldBasedFrameConn(encoderConfig, decoderConfig, conn)
    err = fc.WriteFrame([]byte("hello"))
    if err != nil {
        panic(err)
    }
    err = fc.WriteFrame([]byte("world"))
    if err != nil {
        panic(err)
    }


    buf, err := fc.ReadFrame()
    if err != nil {
        panic(err)
    }
    fmt.Println("received: ", string(buf))
    buf, err = fc.ReadFrame()
    if err != nil {
        panic(err)
    }
    fmt.Println("received: ", string(buf))
}

Server:

package main


import (
    "encoding/binary"
    "flag"
    "fmt"
    "log"
    "time"


    "github.com/panjf2000/gnet"
    "github.com/panjf2000/gnet/pool/goroutine"
)


type codecServer struct {
    *gnet.EventServer
    addr       string
    multicore  bool
    async      bool
    codec      gnet.ICodec
    workerPool *goroutine.Pool
}


func (cs *codecServer) OnInitComplete(srv gnet.Server) (action gnet.Action) {
    log.Printf("Test codec server is listening on %s (multi-cores: %t, loops: %d)\n",
        srv.Addr.String(), srv.Multicore, srv.NumEventLoop)
    return
}


func (cs *codecServer) React(frame []byte, c gnet.Conn) (out []byte, action gnet.Action) {
    if cs.async {
        data := append([]byte{}, frame...)
        _ = cs.workerPool.Submit(func() {
            c.AsyncWrite(data)
        })
        return
    }
    out = frame
    return
}


func testCodecServe(addr string, multicore, async bool, codec gnet.ICodec) {
    var err error
    if codec == nil {
        encoderConfig := gnet.EncoderConfig{
            ByteOrder:                       binary.BigEndian,
            LengthFieldLength:               4,
            LengthAdjustment:                0,
            LengthIncludesLengthFieldLength: false,
        }
        decoderConfig := gnet.DecoderConfig{
            ByteOrder:           binary.BigEndian,
            LengthFieldOffset:   0,
            LengthFieldLength:   4,
            LengthAdjustment:    0,
            InitialBytesToStrip: 4,
        }
        codec = gnet.NewLengthFieldBasedFrameCodec(encoderConfig, decoderConfig)
    }
    cs := &codecServer{addr: addr, multicore: multicore, async: async, codec: codec, workerPool: goroutine.Default()}
    err = gnet.Serve(cs, addr, gnet.WithMulticore(multicore), gnet.WithTCPKeepAlive(time.Minute*5), gnet.WithCodec(codec))
    if err != nil {
        panic(err)
    }
}


func main() {
    var port int
    var multicore bool


    // Example command: go run server.go --port 9000 --multicore=true
    flag.IntVar(&port, "port", 9000, "server port")
    flag.BoolVar(&multicore, "multicore", true, "multicore")
    flag.Parse()
    addr := fmt.Sprintf("tcp://:%d", port)
    testCodecServe(addr, multicore, false, nil)
}
Custom Codec Demo with Client/Server

protocol intro:

// CustomLengthFieldProtocol : custom protocol
// custom protocol header contains Version, ActionType and DataLength fields
// its payload is Data field
type CustomLengthFieldProtocol struct {
    Version    uint16
    ActionType uint16
    DataLength uint32
    Data       []byte
}




// Encode ...
func (cc *CustomLengthFieldProtocol) Encode(c gnet.Conn, buf []byte) ([]byte, error) {
    result := make([]byte, 0)


    buffer := bytes.NewBuffer(result)


    // take out the param that `React()` event saved.
    item := c.Context().(CustomLengthFieldProtocol)




    if err := binary.Write(buffer, binary.BigEndian, item.Version); err != nil {
        s := fmt.Sprintf("Pack version error , %v", err)
        return nil, errors.New(s)
    }


    if err := binary.Write(buffer, binary.BigEndian, item.ActionType); err != nil {
        s := fmt.Sprintf("Pack type error , %v", err)
        return nil, errors.New(s)
    }
    dataLen := uint32(len(buf))
    if err := binary.Write(buffer, binary.BigEndian, dataLen); err != nil {
        s := fmt.Sprintf("Pack datalength error , %v", err)
        return nil, errors.New(s)
    }
    if dataLen > 0 {
        if err := binary.Write(buffer, binary.BigEndian, buf); err != nil {
            s := fmt.Sprintf("Pack data error , %v", err)
            return nil, errors.New(s)
        }
    }


    return buffer.Bytes(), nil
}


// Decode ...
func (cc *CustomLengthFieldProtocol) Decode(c gnet.Conn) ([]byte, error) {
    // parse header
    headerLen := DefaultHeadLength // uint16+uint16+uint32
    if size, header := c.ReadN(headerLen); size == headerLen {
        byteBuffer := bytes.NewBuffer(header)
        var pbVersion, actionType uint16
        var dataLength uint32
        binary.Read(byteBuffer, binary.BigEndian, &pbVersion)
        binary.Read(byteBuffer, binary.BigEndian, &actionType)
        binary.Read(byteBuffer, binary.BigEndian, &dataLength)
        // to check the protocol version and actionType,
        // reset buffer if the version or actionType is not correct
        if pbVersion != DefaultProtocolVersion || isCorrectAction(actionType) == false {
            c.ResetBuffer()
            log.Println("not normal protocol:", pbVersion, DefaultProtocolVersion, actionType, dataLength)
            return nil, errors.New("not normal protocol")
        }
        // parse payload
        dataLen := int(dataLength) // max int32 can contain 210MB payload
        protocolLen := headerLen + dataLen
        if dataSize, data := c.ReadN(protocolLen); dataSize == protocolLen {
            c.ShiftN(protocolLen)
            // log.Println("parse success:", data, dataSize)


            // return the payload of the data
            return data[headerLen:], nil
        }
        // log.Println("not enough payload data:", dataLen, protocolLen, dataSize)
        return nil, errors.New("not enough payload data")


    }
    // log.Println("not enough header data:", size)
    return nil, errors.New("not enough header data")
}

Client/Server: Check out the source code.

For more details, check out here: all examples of gnet.

I/O Events

Current supported I/O events in gnet:

  • EventHandler.OnInitComplete fires when the server has been initialized and ready to accept new connections.
  • EventHandler.OnOpened fires once a connection has been opened.
  • EventHandler.OnClosed fires after a connection has been closed.
  • EventHandler.React fires when the server receives inbound data from a socket/connection. (usually it is where you write the code of business logic)
  • EventHandler.Tick fires right after the server starts and then fires every specified interval.
  • EventHandler.PreWrite fires just before any data has been written to client.

poll_opt mode

By default, gnet utilizes the standard package golang.org/x/sys/unix to implement pollers with epoll or kqueue, where a HASH MAP of fd->conn is introduced to help retrieve connections by file descriptors returned from pollers, but now the user can run go build with build tags poll_opt, like this: go build -tags=poll_opt, and gnet then switch to the optimized implementations of pollers that invoke the system calls of epoll or kqueue directly and add file descriptors to the interest list along with storing the corresponding connection pointers into epoll_data or kevent, in which case gnet can get rid of the HASH MAP of fd->conn and regain each connection pointer by the conversion of void* pointer in the I/O event-looping. In theory, it ought to achieve a higher performance with this optimization.

See #230 for code details.

Ticker

The EventHandler.Tick event fires ticks at a specified interval. The first tick fires right after the gnet server starts up and if you intend to set up a ticker event, don't forget 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
}

UDP

gnet supports UDP protocol so the gnet.Serve method can bind to UDP addresses.

  • All incoming and outgoing packets will not be buffered but read and sent directly, which means all functions of gnet.Conn that manipulate the internal buffers are not available; users should use the frame []byte from the gnet.React(frame []byte, c gnet.Conn) as the UDP packet instead calling functions of gnet.Conn, like c.Read(), c.ResetBuffer(), c.BufferLength() and so on, to process data.
  • The EventHandler.OnOpened and EventHandler.OnClosed events are not available for UDP sockets, only the React event.
  • The UDP equivalents of AsyncWrite([]byte) in TCP is SendTo([]byte).

Unix Domain Socket

gnet also supports UDS(Unix Domain Socket), just pass the UDS addresses like "unix://xxx" to the gnet.Serve method and you could play with it.

It is nothing different from making use of TCP when doing stuff with UDS, so the gnet UDS servers are able to leverage all event functions which are available under TCP protocol.

Multi-threads

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().

Load Balancing

gnet currently supports three load balancing algorithms: Round-Robin, Source-Addr-Hash and Least-Connections, you are able to decide which algorithm to use by passing the functional option LB (RoundRobin/LeastConnections/SourceAddrHash) to gnet.Serve.

If the load balancing algorithm is not specified explicitly, gnet will use Round-Robin by default.

SO_REUSEPORT

gnet server is able to 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 connect event coming to resolved the thundering herd.

By default, gnet is not going to be haunted by the thundering herd under its networking model:『multiple reactors』which gets only one main reactor to listen on "address:port" and accept new sockets. So this SO_REUSEPORT option is trivial in gnet but note that it will fall back to the old networking model of evio when you enable the SO_REUSEPORT option.

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)))

Multiple built-in codecs for TCP stream

There are multiple built-in codecs in gnet which allow you to encode/decode frames into/from TCP stream.

So far gnet has four kinds of built-in codecs: LineBasedFrameCodec, DelimiterBasedFrameCodec, FixedLengthFrameCodec and LengthFieldBasedFrameCodec, which generally meets most scenarios, but still gnet allows users to customize their own codecs in their gnet servers by implementing the interface gnet.ICodec and replacing the default codec in gnet with customized codec via functional options.

Here is an example with codec, showing you how to leverage codec to encode/decode network frames into/from TCP stream.

📊 Performance

Benchmarks on TechEmpower

# Hardware Environment
CPU: 28 HT Cores Intel(R) Xeon(R) Gold 5120 CPU @ 2.20GHz
Mem: 32GB RAM
OS : Ubuntu 18.04.3 4.15.0-88-generic #88-Ubuntu
Net: Switched 10-gigabit ethernet
Go : go1.14.x linux/amd64

All languages

This is the top 50 on the framework ranking of all programming languages consists of a total of 422 frameworks from all over the world where gnet is the runner-up.

Golang

This is the full framework ranking of Go and gnet tops all the other frameworks, which makes gnet the fastest networking framework in Go.

To see the full ranking list, visit TechEmpower Plaintext Benchmark.

Contrasts to the similar networking libraries

On Linux (epoll)

Test Environment

# Machine information
        OS : Ubuntu 20.04/x86_64
       CPU : 8 CPU cores, AMD EPYC 7K62 48-Core Processor
    Memory : 16.0 GiB


# Go version and settings
Go Version : go1.16.5 linux/amd64
GOMAXPROCS : 8


# Benchmark parameters
TCP connections : 500/1000/5000/10000
Packet size     : 512/1024/2048/4096/8192/16384/32768/65536 bytes
Test duration   : 15s

Echo benchmark

On MacOS (kqueue)

Test Environment

# Machine information
        OS : MacOS Big Sur/x86_64
       CPU : 6 CPU cores, Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
    Memory : 16.0 GiB


# Go version and settings
Go Version : go1.16.5 darwin/amd64
GOMAXPROCS : 12


# Benchmark parameters
TCP connections : 300/400/500/600/700
Packet size     : 512/1024/2048/4096/8192 bytes
Test duration   : 15s

Echo benchmark

️🚨 License

Source code in gnet is available under the MIT License.

👏 Contributors

Please read the Contributing Guidelines before opening a PR and thank you to all the developers who already made contributions to gnet!

🙏 Acknowledgments

⚓ Relevant Articles

🎡 User cases

The following companies/organizations use gnet as the underlying network service in production.

          

If your projects are also using gnet, feel free to open a pull request refreshing this list of user cases.

💰 Backers

Support us with a monthly donation and help us continue our activities.

💎 Sponsors

Become a bronze sponsor with a monthly donation of $10 and get your logo on our README on Github.

☕️ Buy me a coffee

Please be sure to leave your name, Github account or other social media accounts when you donate by the following means so that I can add it to the list of donors as a token of my appreciation.

💴 Patrons

Patrick Othmer  Jimmy  ChenZhen  Mai Yang  王开帅  Unger Alejandro  Swaggadan Weng Wei

💵 Paid Support

If you need a tailored version of gnet and want the author to help develop it, or bug fix/fast resolution/consultation which takes a lot of effort, you can request paid support here.

🔑 JetBrains OS licenses

gnet had been being developed with GoLand IDE under the free JetBrains Open Source license(s) granted by JetBrains s.r.o., hence I would like to express my thanks here.

🔋 Sponsorship

This project is supported by:

Like What You See?

Follow @_andy_pan
Get real-time updates!
Star panjf2000/gnet
Star the repo to support us.