evio

README

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/tidwall/evio

This will retrieve the library.

Usage

Starting a server is easy with evio. Just set up your events and pass them to the Serve 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/tidwall/evio"

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

Here the only event being used is Data, 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:

• Serving fires when the server is ready to accept new connections.
• Opened fires when a connection has opened.
• Closed fires when a connection has closed.
• Detach fires when a connection has been detached using the Detach return action.
• Data fires when the server receives new data from a connection.
• Tick 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.Serve(events, "tcp://192.168.0.10:5000", "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 are not buffered and sent individually.
• The Opened and Closed events are not availble for UDP sockets, only the Data 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.

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.Serve(events, "tcp://0.0.0.0:1234?reuseport=true"))

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
$ go run examples/redis-server/main.go
$ go run examples/echo-server/main.go

Performance

Benchmarks

These benchmarks were run on an ec2 c4.xlarge instance in single-threaded mode (GOMAXPROC=1) over Ipv4 localhost. Check out benchmarks for more info.

Contact

Josh Baker @tidwall

License

evio source code is available under the MIT License.

Documentation

Index

• func Serve(events Events, addr ...string) error
• type Action
• type Conn
• type Events
• type InputStream
  • func (is *InputStream) Begin(packet []byte) (data []byte)
  • func (is *InputStream) End(data []byte)
• type LoadBalance
• 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 Data event for this connection.
	Wake()
}

Conn is an evio connection.

type Events

type Events struct {
	// NumLoops sets the number of loops to use for the server. Setting this
	// to a value greater than 1 will effectively make the server
	// multithreaded for multi-core machines. Which means you must take care
	// with synchonizing memory between all event callbacks. Setting to 0 or 1
	// will run the server single-threaded. Setting to -1 will automatically
	// assign this value equal to runtime.NumProcs().
	NumLoops int
	// LoadBalance 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 works when NumLoops is set.
	LoadBalance LoadBalance
	// Serving fires when the server can accept connections. The server
	// parameter has information and various utilities.
	Serving func(server Server) (action Action)
	// Opened 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.
	Opened func(c Conn) (out []byte, opts Options, action Action)
	// Closed fires when a connection has closed.
	// The err parameter is the last known connection error.
	Closed func(c Conn, 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(c Conn, rwc io.ReadWriteCloser) (action Action)
	// PreWrite fires just before any data is written to any client socket.
	PreWrite func()
	// 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(c Conn, in []byte) (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 InputStream

type InputStream struct {
	// contains filtered or unexported fields
}

InputStream is a helper type for managing input streams from inside the Data event.

func (*InputStream) Begin

func (is *InputStream) Begin(packet []byte) (data []byte)

Begin accepts a new packet and returns a working sequence of unprocessed bytes.

func (*InputStream) End

func (is *InputStream) End(data []byte)

End shifts the stream to match the unprocessed data.

type LoadBalance

type LoadBalance int

LoadBalance sets the load balancing method.

const (
	// Random requests that connections are randomly distributed.
	Random LoadBalance = iota
	// RoundRobin requests that connections are distributed to a loop in a
	// round-robin fashion.
	RoundRobin
	// LeastConnections assigns the next accepted connection to the loop with
	// the least number of active connections.
	LeastConnections
)

type Options

type Options struct {
	// TCPKeepAlive (SO_KEEPALIVE) socket option.
	TCPKeepAlive time.Duration
	// ReuseInputBuffer will forces the connection to share and reuse the
	// same input packet buffer with all other connections that also use
	// this option.
	// Default value is false, which means that all input data which is
	// passed to the Data event will be a uniquely copied []byte slice.
	ReuseInputBuffer bool
}

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.