evio/README.md

Event Networking for Go

evio is an event driven networking framework that is fast and small. It makes direct epoll and kqueue syscalls rather than the standard Go net package. It 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, but without having to interop with Cgo. My hope is to use this as a foundation for Tile38 and a future L7 proxy for Go.

Features

• Very fast single-threaded event loop design
• Simple API. Only one entrypoint and eight events
• Low memory usage
• Supports tcp4, tcp6, and unix sockets
• Allows multiple network binding on the same event loop
• Has a flexible ticker event
• Support for non-epoll/kqueue operating systems by simulating events with the net package.

Getting Started

Installing

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

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

This will retrieve the library.

Usage

Calling Serve will start the event loop:

// 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
//  unix  - Unix Domain Socket
//
// The "tcp" network scheme is assumed when one is not specified.
func Serve(events Events, addr ...string) error

The Events type is defined as:

// 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 Events struct {
	// Serving fires when the server can accept connections.
	// The wake parameter is a goroutine-safe function that triggers
	// a Data event (with a nil `in` parameter) for the specified id.
	// The addrs parameter is an array of listening addresses that align
	// with the addr strings passed to the Serve function.
	Serving func(wake func(id int) bool, addrs []net.Addr) (action Action)
	// Opened fires when a new connection has opened.
	// The addr parameter is the connection's local and remote addresses.
	// Use the out return value to write data to the connection.
	// The opts return value is used to set connection options.
	Opened func(id int, addr Addr) (out []byte, opts Options, action Action)
	// Opened fires when a connection has closed.
	// The err parameter is the last known connection error, usually nil.
	Closed func(id int, err error) (action Action)
	// Detached 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 Closed 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.
	Detached func(id int, rwc io.ReadWriteCloser) (action Action)
	// Data 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.
	Data func(id int, in []byte) (out []byte, action Action)
	// Prewrite fires prior to every write attempt.
	// The amount parameter is the number of bytes that will be attempted
	// to be written to the connection.
	Prewrite func(id int, amount int) (action Action)
	// Postwrite fires immediately after every write attempt.
	// The amount parameter is the number of bytes that was written to the
	// connection.
	// The remaining parameter is the number of bytes that still remain in
	// the buffer scheduled to be written.
	Postwrite func(id int, amount, remaining int) (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)
}

• All events are executed in the same thread as the Serve call.
• The wake function is there to wake up the event loop from a background goroutine. This is useful for when you need to perform a long-running operation that must send data back to a client after the operation is completed, but without blocking the server. A call to wake fires a Data event providing an opening to write data to the client. The in param of the Data event is nil for wakeups.
• Data, Opened, Closed, Prewrite, and Postwrite events have an id param which is a unique number assigned to the client socket.
• in represents an input network packet from a client, and out is output data sent to the client.
• The Action return value allows for closing or detaching a connection, or shutting down the server.

Example - Simple echo server

package main

import "github.com/tidwall/evio"

func main() {
	var events evio.Events
	events.Data = func(id int, in []byte) (out []byte, action evio.Action) {
		out = in
		return
	}
	if err := evio.Serve(events, "tcp://localhost:5000"); err != nil {
		println(err.Error())
	}
}

Connect to the server:

$ telnet localhost 5000

Multiple addresses

You can bind to multiple address and share the same event loop.

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

More examples

Please check out the examples subdirectory for a simplified redis clone, an echo server, and a very basic http server.

To run an example:

$ go run examples/http-server/main.go

Performance

The benchmarks below use pipelining which allows for combining multiple Redis commands into a single packet.

Real Redis

$ redis-server

redis-benchmark -p 6379 -t ping,set,get -q -P 32
PING_INLINE: 869565.19 requests per second
PING_BULK: 1694915.25 requests per second
SET: 917431.19 requests per second
GET: 1265822.75 requests per second

Redis clone (evio)

$ go run examples/redis-server/main.go

redis-benchmark -p 6380 -t ping,set,get -q -P 32
PING_INLINE: 2380952.50 requests per second
PING_BULK: 2380952.50 requests per second
SET: 2325581.25 requests per second
GET: 2222222.25 requests per second

Running on a MacBook Pro 15" 2.8 GHz Intel Core i7 using Go 1.7

Contact

Josh Baker @tidwall

License

evio source code is available under the MIT License.