evio

evio 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. It was built to be the foundation for Tile38 and a future L7 proxy for Go.

从原项目复制了代码，做了大量的重构和修复工作，今后会成为这个项目的主要维护者。

Please note: Evio should not be considered as a drop-in replacement for the standard Go net or net/http packages.

Features

• Fast single-threaded or multithreaded event loop
• Built-in load balancing options
• Simple API
• Low memory usage
• Supports tcp, udp, and unix sockets
• Allows multiple network binding on the same event loop
• Flexible ticker event
• Fallback for non-epoll/kqueue operating systems by simulating events with the net package
• SO_REUSEPORT socket option

Getting Started

Installing

To start using evio, install Go and run go get:

$ go get -u github.com/gnuos/evio

This will retrieve the library.

Usage

这个库暴露出的API如下:

type Engine interface {
    Start()
    Stop()
    Serve() error
    Ready() chan bool
    Clear()
    HasErr() bool
    Errors() iter.Seq[error]
}

详细用法可以参考 example_test.go 文件里的代码

Starting a server is easy with evio. Just set up your events and pass them to the NewEngine function along with the binding address(es). Each connections is represented as an evio.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.

Example echo server that binds to port 5000:

package main

import "github.com/gnuos/evio"

func main() {
	var events evio.Events
	events.OnData = func(c evio.Conn, in []byte) (out []byte, action evio.Action) {
		out = in
		return
	}

    addresses := []string{"tcp://localhost:5000"}
    engine, err := evio.NewEngine(events, addresses...)
	if err != nil {
		panic(err.Error())
	}

    engine.Serve()

    // or run in background
    // engine.Start()
    // <- engine.Ready()
    //
    // defer func() {
    //     serv.Stop()
    //     serv.Clear()
    // }()

    // Do other things
}

Here the only event being used is OnData, which fires when the server receives input data from a client. The exact same input data is then passed through the output return value, which is then sent back to the client.

Connect to the echo server:

$ telnet localhost 5000

Events

The event type has a bunch of handy events:

• OnServing fires when the server is ready to accept new connections.
• OnOpened fires when a connection has opened.
• OnClosed fires when a connection has closed.
• OnDetach fires when a connection has been detached using the Detach return action.
• OnData fires when the server receives new data from a connection.
• OnTick fires immediately after the server starts and will fire again after a specified interval.

Multiple addresses

A server can bind to multiple addresses and share the same event loop.

evio.NewEngine(events, "tcp://:5000", "unix://socket")

Ticker

The OnTick event fires ticks at a specified interval. The first tick fires immediately after the OnServing events.

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

UDP

The NewEngine function can bind to UDP addresses.

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

Multithreaded

The events.NumLoops options sets the number of loops to use for the server. A value greater than 1 will effectively make the server multithreaded for multi-core machines. Which means you must take care when synchonizing memory between event callbacks. Setting to 0 or 1 will run the server as single-threaded. Setting to -1 will automatically assign this value equal to runtime.NumProcs().

Load balancing

The events.LoadBalance options sets the load balancing method. Load balancing is always a best effort to attempt to distribute the incoming connections between multiple loops. This option is only available when events.NumLoops is set.

• Random requests that connections are randomly distributed.
• RoundRobin requests that connections are distributed to a loop in a round-robin fashion.
• LeastConnections assigns the next accepted connection to the loop with the least number of active connections.

Collect connections

The events.ConnDeadline options sets the count of timeout seconds which accepted connection is inactive. This options use 15 as a default value. These accpted connections will be clean automatically.

SO_REUSEPORT

Servers can utilize the SO_REUSEPORT option which allows multiple sockets on the same host to bind to the same port.

Just provide reuseport=true to an address:

evio.NewEngine(events, "tcp://0.0.0.0:1234?reuseport=true"))

Contact

Josh Baker @tidwall

Kevin email

License

evio source code is available under the MIT License.