Repository files navigation

evio is an event loop networking framework that is fast and small. It makes directepoll andkqueue syscalls rather than using the standard Gonet package, and works in a similar manner aslibuv andlibevent.

The goal of this project is to create a server framework for Go that performs on par withRedis andHaproxy for packet handling. It was built to be the foundation forTile38 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.

• Fast single-threaded ormultithreaded event loop
• Built-inload balancing options
• Simple API
• Low memory usage
• Supports tcp,udp, and unix sockets
• Allowsmultiple network binding on the same event loop
• Flexibleticker event
• Fallback for non-epoll/kqueue operating systems by simulating events with thenet package
• SO_REUSEPORT socket option

To start using evio, install Go and rungo get:

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

This will retrieve the library.

Starting a server is easy withevio. Just set up your events and pass them to theServe function along with the binding address(es). Each connections is represented as anevio.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 aClose orShutdown action from an event.

Example echo server that binds to port 5000:

package mainimport"github.com/tidwall/evio"funcmain() {varevents evio.Eventsevents.Data=func(c evio.Conn,in []byte) (out []byte,action evio.Action) {out=inreturn}iferr:=evio.Serve(events,"tcp://localhost:5000");err!=nil {panic(err.Error())}}

Here the only event being used isData, 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

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 theDetach 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.

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

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

TheTick event fires ticks at a specified interval.The first tick fires immediately after theServing events.

events.Tick=func() (delay time.Duration,actionAction){log.Printf("tick")delay=time.Secondreturn}

TheServe function can bind to UDP addresses.

• All incoming and outgoing packets are not buffered and sent individually.
• TheOpened andClosed events are not availble for UDP sockets, only theData event.

Theevents.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 toruntime.NumProcs().

Theevents.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 whenevents.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.

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

Just providereuseport=true to an address:

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

Please check out theexamples subdirectory for a simplifiedredis clone, anecho server, and a very basichttp 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

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

Josh Baker@tidwall

evio source code is available under the MITLicense.