evnet

README

⚡ Introduction

Evnet is event-driven net framework with high performance deriving from gnet and evio. It supports epoll syscall in Linux. If it's useful to you, Please STAR it!

✨ Features

• Supporting an event-driven mechanism: epoll on Linux.
• Supporting multiple protocols/IPC mechanism: TCP, UDP and Unix Domain Socket.
• Efficient memory buffer and zero copy.
• Supporting multiple load-balancing algorithms: Round-Robin, Source-Addr-Hash and Least-Connections
• Implementation of gnet Client

🎬 Getting started

go get github.com/bruce2233/evnet

import "github.com/bruce2233/evnet"

type MyHandler struct {
	BuiltinEventHandler
}

func (mh MyHandler) OnConn(c Conn) error{
	p, err := c.Next(-1)
    if err!=nil{
        return evnet.ErrClose
    }
    c.AsyncWrite(p, func(c Conn){
        c.Close()
    })
}

//main.go
func main() {
	readHandler := MyHandler{BuiltinEventHandler{}}
	Run(readHandler, "tcp://127.0.0.1:9000")
}

BenchTest

# Machine information
        OS : Ubuntu 20.04/x86_64
       CPU : 8 CPU cores, Intel(R) Core(TM) i5-8265U CPU @ 1.60GHz
    Memory : 4.0 GiB
  Platform : VMware Workstation 16.2.3

# Go version and settings
Go Version : go1.18.3 linux/amd64
GOMAXPROCS : 8

The average performance of evnet in the condition of 12 threads and 1000 connections is 103% more than standard net/http package.

| Thread Stats | Avg    | Stdev  | Max     | +/- Stdev |
| ------------ | ------ | ------ | ------- | --------- |
| Latency      | 7.94ms | 8.90ms | 84.67ms | 85.92%    |
| Req/Sec      | 13.60k | 4.41k  | 32.25k  | 68.19%    |
1622016 requests in 10.09s, 199.55MB read

Requests/sec: 160690.88
Transfer/sec:     19.77MB

pprof analysis

go tool pprof -http=:9999 cpu.pprof

Documentation

Overview

Copyright (c) 2022 Bruce Zhang

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• Variables
• func AcceptSocket(fd int) (int, net.Addr, error)
• func Run(eventHandler EventHandler, protoAddr string, optList ...SetOption)
• type BuiltinEventHandler
  • func (builtinEventHandler BuiltinEventHandler) OnBoot(mr *MainReactor) error
  • func (builtinEventHandler BuiltinEventHandler) OnClose(c Conn) error
  • func (builtinEventHandler BuiltinEventHandler) OnConn(c Conn) error
  • func (builtinEventHandler BuiltinEventHandler) OnOpen(c Conn) error
  • func (builtinEventHandler BuiltinEventHandler) OnShutdown(mr *MainReactor) error
  • func (builtinEventHandler BuiltinEventHandler) OnTraffic(c Conn) error
• type Conn
  • func NewConn(fd int, la net.Addr, ra net.Addr) (Conn, error)
• type EventHandler
• type Listener
• type MainReactor
  • func (mr *MainReactor) Init(proto, addr string) error
  • func (mainReactor *MainReactor) Listen(proto, addr string) (fd int, netAddr net.Addr, err error)
  • func (mainReactor *MainReactor) Loop()
  • func (mr *MainReactor) SetEventHandler(eh EventHandler)
• type OptionArg
• type PollAttachment
• type Poller
  • func OpenPoller() (poller *Poller, err error)
  • func (poller *Poller) AddPollRead(pafd int) error
  • func (p *Poller) Delete(fd int) error
  • func (p *Poller) ModRead(fd int) error
  • func (p *Poller) ModReadWrite(fd int) error
  • func (poller *Poller) Polling() []unix.EpollEvent
• type SetOption
  • func WithLogLevel(logLevel log.Level) SetOption
  • func WithLogPath(logPath string) SetOption
• type SubReactor
  • func (sr *SubReactor) Loop() error
  • func (sr *SubReactor) Polling(callback func(fd int, events uint32) error)
• type Writer

Constants

const (
	ErrEvents = unix.EPOLLERR | unix.EPOLLHUP | unix.EPOLLRDHUP
	// OutEvents combines EPOLLOUT event and some exceptional events.
	OutEvents = ErrEvents | unix.EPOLLOUT
	// InEvents combines EPOLLIN/EPOLLPRI events and some exceptional events.
	InEvents = ErrEvents | unix.EPOLLIN | unix.EPOLLPRI
)

const (
	PollEventsCap = 128
)

Variables

var (
	//close the connection
	ErrClose = errors.New("Close")
	//shutdown the reactor
	ErrShutdown = errors.New("Shutdown")
	//peer close the connection before writting completely
	ErrClosedWhenWritting = errors.New("Closed when writting")
)

var SubReactorsNum = 10

Functions

func AcceptSocket

func AcceptSocket(fd int) (int, net.Addr, error)

func Run

func Run(eventHandler EventHandler, protoAddr string, optList ...SetOption)

Types

type BuiltinEventHandler

type BuiltinEventHandler struct {
}

func (BuiltinEventHandler) OnBoot

func (builtinEventHandler BuiltinEventHandler) OnBoot(mr *MainReactor) error

func (BuiltinEventHandler) OnClose

func (builtinEventHandler BuiltinEventHandler) OnClose(c Conn) error

func (BuiltinEventHandler) OnConn

func (builtinEventHandler BuiltinEventHandler) OnConn(c Conn) error

func (BuiltinEventHandler) OnOpen

func (builtinEventHandler BuiltinEventHandler) OnOpen(c Conn) error

func (BuiltinEventHandler) OnShutdown

func (builtinEventHandler BuiltinEventHandler) OnShutdown(mr *MainReactor) error

func (BuiltinEventHandler) OnTraffic

func (builtinEventHandler BuiltinEventHandler) OnTraffic(c Conn) error

type Conn

type Conn interface {
	//working
	io.Reader
	Writer
	Socket

	Next(n int) ([]byte, error)

	// LocalAddr is the connection's local socket address.
	LocalAddr() (addr net.Addr)

	// RemoteAddr is the connection's remote peer address.
	RemoteAddr() (addr net.Addr)

	SetContext(ctx interface{})

	Context() interface{}

	Close() error
}

func NewConn

func NewConn(fd int, la net.Addr, ra net.Addr) (Conn, error)

type EventHandler

type EventHandler interface {
	//working
	OnConn(c Conn) error
	OnClose(c Conn) error
	OnTraffic(c Conn) error
	OnOpen(c Conn) error
	OnShutdown(mr *MainReactor) error
	OnBoot(mr *MainReactor) error
}

type Listener

type Listener struct {
	Fd int
	// contains filtered or unexported fields
}

type MainReactor

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

func (*MainReactor) Init

func (mr *MainReactor) Init(proto, addr string) error

Create poller and listener for mainReactor

func (*MainReactor) Listen

func (mainReactor *MainReactor) Listen(proto, addr string) (fd int, netAddr net.Addr, err error)

The proto paramater MUST be "tcp" The addr parameter

func (*MainReactor) Loop

func (mainReactor *MainReactor) Loop()

func (*MainReactor) SetEventHandler

func (mr *MainReactor) SetEventHandler(eh EventHandler)

type OptionArg

type OptionArg struct {
	LogPath  string
	LogLevel log.Level
}

type PollAttachment

type PollAttachment struct {
	Fd    int
	Event unix.EpollEvent
}

type Poller

type Poller struct {
	Fd int
}

func OpenPoller

func OpenPoller() (poller *Poller, err error)

create a new poller

func (*Poller) AddPollRead

func (poller *Poller) AddPollRead(pafd int) error

func (*Poller) Delete

func (p *Poller) Delete(fd int) error

Delete removes the given file-descriptor from the poller.

func (*Poller) ModRead

func (p *Poller) ModRead(fd int) error

ModRead renews the given file-descriptor with readable event in the poller.

func (*Poller) ModReadWrite

func (p *Poller) ModReadWrite(fd int) error

func (*Poller) Polling

func (poller *Poller) Polling() []unix.EpollEvent

block

type SetOption

type SetOption func(optArg *OptionArg)

func WithLogLevel

func WithLogLevel(logLevel log.Level) SetOption

func WithLogPath

func WithLogPath(logPath string) SetOption

type SubReactor

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

func (*SubReactor) Loop

func (sr *SubReactor) Loop() error

func (*SubReactor) Polling

func (sr *SubReactor) Polling(callback func(fd int, events uint32) error)

type Writer

type Writer interface {
	io.Writer

	AsyncWrite([]byte, func(Conn) error) error
}