evio

by tidwall

tidwall / evio

Fast event-loop networking for Go

4.4K Stars 344 Forks Last release: Not found MIT License 135 Commits 9 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

evio
Build Status GoDoc

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

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.

echo benchmarkhttp benchmarkredis 1 benchmarkredis 8 benchmark

Contact

Josh Baker @tidwall

License

evio
source code is available under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.