evio

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

Serve

evio.Conn

Close

Shutdown

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

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

Serving

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

UDP

The

Serve

• 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

runtime.NumProcs()

Load balancing

The

events.LoadBalance

events.NumLoops

• 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

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