nbio

README

NBIO - NON-BLOCKING IO

Contents

• NBIO - NON-BLOCKING IO
  • Contents
  • Features
  • Installation
  • Quick Start
  • API Examples
    • New Gopher For Server-Side
    • New Gopher For Client-Side
    • Start Gopher
    • Custom Other Config For Gopher
    • SetDeadline/SetReadDeadline/SetWriteDeadline
    • Bind User Session With Conn
    • Writev / Batch Write
    • Handle New Connection
    • Handle Disconnected
    • Handle Data
    • Handle Memory Allocation/Free For Reading
    • Handle Memory Free For Writing
    • Handle Conn Before Read
    • Handle Conn After Read
    • Handle Conn Before Write
  • Echo Examples
  • TLS Examples
  • HTTP Examples
  • HTTPS Examples
  • Websocket Examples
  • Websocket TLS Examples
  • Websocket 1M Connections Examples
  • Use With Other STD Based Frameworkds
  • More Examples

Features

• linux: epoll
• macos(bsd): kqueue
• windows: golang std net
• nbio.Conn implements a non-blocking net.Conn(except windows)
• writev supported
• least dependency
• TLS supported
• HTTP/HTTPS 1.x
• Websocket, Passes the Autobahn Test Suite
• HTTP 2.0

Installation

1. Get and install nbio

$ go get -u github.com/Lcfling/nbio

1. Import in your code:

import "github.com/Lcfling/nbio"

Quick Start

• start a server

import "github.com/Lcfling/nbio"

g := nbio.NewGopher(nbio.Config{
    Network: "tcp",
    Addrs:   []string{"localhost:8888"},
})

// echo
g.OnData(func(c *nbio.Conn, data []byte) {
    c.Write(append([]byte{}, data...))
})

err := g.Start()
if err != nil {
    panic(err)
}
// ...

• start a client

import "github.com/Lcfling/nbio"

g := nbio.NewGopher(nbio.Config{})

g.OnData(func(c *nbio.Conn, data []byte) {
    // ...
})

err := g.Start()
if err != nil {
    fmt.Printf("Start failed: %v\n", err)
}
defer g.Stop()

c, err := nbio.Dial("tcp", addr)
if err != nil {
    fmt.Printf("Dial failed: %v\n", err)
}
g.AddConn(c)

buf := make([]byte, 1024)
c.Write(buf)
// ...

API Examples

New Gopher For Server-Side

g := nbio.NewGopher(nbio.Config{
    Network: "tcp",
    Addrs:   []string{"localhost:8888"},
})

New Gopher For Client-Side

g := nbio.NewGopher(nbio.Config{})

Start Gopher

err := g.Start()
if err != nil {
    fmt.Printf("Start failed: %v\n", err)
}
defer g.Stop()

Custom Other Config For Gopher

conf := nbio.Config struct {
    // Name describes your gopher name for logging, it's set to "NB" by default
    Name: "NB",

    // MaxLoad represents the max online num, it's set to 10k by default
    MaxLoad: 1024 * 10, 

    // NPoller represents poller goroutine num, it's set to runtime.NumCPU() by default
    NPoller: runtime.NumCPU(),

    // ReadBufferSize represents buffer size for reading, it's set to 16k by default
    ReadBufferSize: 1024 * 16,

    // MaxWriteBufferSize represents max write buffer size for Conn, it's set to 1m by default.
    // if the connection's Send-Q is full and the data cached by nbio is 
    // more than MaxWriteBufferSize, the connection would be closed by nbio.
    MaxWriteBufferSize uint32

    // LockListener represents listener's goroutine to lock thread or not, it's set to false by default.
	LockListener bool

    // LockPoller represents poller's goroutine to lock thread or not.
    LockPoller bool
}

SetDeadline/SetReadDeadline/SetWriteDeadline

var c *nbio.Conn = ...
c.SetDeadline(time.Now().Add(time.Second * 10))
c.SetReadDeadline(time.Now().Add(time.Second * 10))
c.SetWriteDeadline(time.Now().Add(time.Second * 10))

Bind User Session With Conn

var c *nbio.Conn = ...
var session *YourSessionType = ... 
c.SetSession(session)

var c *nbio.Conn = ...
session := c.Session().(*YourSessionType)

Writev / Batch Write

var c *nbio.Conn = ...
var data [][]byte = ...
c.Writev(data)

Handle New Connection

g.OnOpen(func(c *Conn) {
    // ...
    c.SetReadDeadline(time.Now().Add(time.Second*30))
})

Handle Disconnected

g.OnClose(func(c *Conn) {
    // clear sessions from user layer
})

Handle Data

g.OnData(func(c *Conn, data []byte) {
    // decode data
    // ...
})

Handle Memory Allocation/Free For Reading

import "sync"

var memPool = sync.Pool{
    New: func() interface{} {
        return make([]byte, yourSize)
    },
}

g.OnReadBufferAlloc(func(c *Conn) []byte {
    return memPool.Get().([]byte)
})
g.OnReadBufferFree(func(c *Conn, b []byte) {
    memPool.Put(b)
})

Handle Memory Free For Writing

g.OnWriteBufferFree(func(c *Conn, b []byte) {
    // ...
})

Handle Conn Before Read

// BeforeRead registers callback before syscall.Read
// the handler would be called only on windows
g.OnData(func(c *Conn, data []byte) {
    c.SetReadDeadline(time.Now().Add(time.Second*30))
})

Handle Conn After Read

// AfterRead registers callback after syscall.Read
// the handler would be called only on *nix
g.BeforeRead(func(c *Conn) {
    c.SetReadDeadline(time.Now().Add(time.Second*30))
})

Handle Conn Before Write

g.OnData(func(c *Conn, data []byte) {
    c.SetWriteDeadline(time.Now().Add(time.Second*5))
})

Echo Examples

• echo-server
• echo-client

TLS Examples

• tls-server
• tls-client

HTTP Examples

• http-server
• http-client

HTTPS Examples

• http-tls_server
• visit: https://localhost:8888/echo

Websocket Examples

• websocket-server
• websocket-client

Websocket TLS Examples

• websocket-tls-server
• websocket-tls-client

Websocket 1M Connections Examples

• websocket-1m-connections-server
• websocket-1m-connections-client

Use With Other STD Based Frameworkds

• gin-http-and-websocket-server
• echo-http-and-websocket-server

More Examples

• nbio-examples

Documentation

Index

• Constants
• Variables
• type Config
• type Conn
  • func Dial(network string, address string) (*Conn, error)
  • func DialTimeout(network string, address string, timeout time.Duration) (*Conn, error)
  • func NBConn(conn net.Conn) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) CloseWithError(err error) error
  • func (c *Conn) Execute(f func())
  • func (c *Conn) ExecuteLen() int
  • func (c *Conn) Hash() int
  • func (c *Conn) IsClosed() (bool, error)
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Lock()
  • func (c *Conn) MustExecute(f func())
  • func (c *Conn) OnData(h func(conn *Conn, data []byte))
  • func (c *Conn) Read(b []byte) (int, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) Sendfile(f *os.File, remain int64) (int64, error)
  • func (c *Conn) Session() interface{}
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetKeepAlive(keepalive bool) error
  • func (c *Conn) SetKeepAlivePeriod(d time.Duration) error
  • func (c *Conn) SetLinger(onoff int32, linger int32) error
  • func (c *Conn) SetNoDelay(nodelay bool) error
  • func (c *Conn) SetReadBuffer(bytes int) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetSession(session interface{})
  • func (c *Conn) SetWriteBuffer(bytes int) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Unlock()
  • func (c *Conn) Write(b []byte) (int, error)
  • func (c *Conn) Writev(in [][]byte) (int, error)
• type Gopher
  • func NewGopher(conf Config) *Gopher
  • func (g *Gopher) AddConn(conn net.Conn) (*Conn, error)
  • func (g *Gopher) After(timeout time.Duration) <-chan time.Time
  • func (g *Gopher) AfterFunc(timeout time.Duration, f func()) *Timer
  • func (g *Gopher) AfterRead(h func(c *Conn))
  • func (g *Gopher) BeforeRead(h func(c *Conn))
  • func (g *Gopher) BeforeWrite(h func(c *Conn))
  • func (g *Gopher) OnClose(h func(c *Conn, err error))
  • func (g *Gopher) OnData(h func(c *Conn, data []byte))
  • func (g *Gopher) OnOpen(h func(c *Conn))
  • func (g *Gopher) OnRead(h func(c *Conn))
  • func (g *Gopher) OnReadBufferAlloc(h func(c *Conn) []byte)
  • func (g *Gopher) OnReadBufferFree(h func(c *Conn, b []byte))
  • func (g *Gopher) OnStop(h func())
  • func (g *Gopher) OnWriteBufferRelease(h func(c *Conn, b []byte))
  • func (g *Gopher) PollerBuffer(c *Conn) []byte
  • func (g *Gopher) Start() error
  • func (g *Gopher) Stop()
• type Timer
  • func (it Timer) Reset(timeout time.Duration)
  • func (it Timer) Stop()

Constants

const (
	// DefaultReadBufferSize .
	DefaultReadBufferSize = 1024 * 32

	// DefaultMaxWriteBufferSize .
	DefaultMaxWriteBufferSize = 1024 * 1024

	// DefaultMaxReadTimesPerEventLoop .
	DefaultMaxReadTimesPerEventLoop = 3

	// DefaultMinConnCacheSize .
	DefaultMinConnCacheSize = 1024 * 2
)

const (
	// EPOLLLT .
	EPOLLLT = 0

	// EPOLLET .
	EPOLLET = 0x80000000
)

Variables

var (
	// MaxOpenFiles .
	MaxOpenFiles = 1024 * 1024
)

Types

type Config

type Config struct {
	// Name describes your gopher name for logging, it's set to "NB" by default.
	Name string

	// Network is the listening protocol, used with Addrs toghter.
	// tcp* supported only by now, there's no plan for other protocol such as udp,
	// because it's too easy to write udp server/client.
	Network string

	// Addrs is the listening addr list for a nbio server.
	// if it is empty, no listener created, then the Gopher is used for client by default.
	Addrs []string

	// NPoller represents poller goroutine num, it's set to runtime.NumCPU() by default.
	NPoller int

	// NListener represents poller goroutine num, it's set to runtime.NumCPU() by default.
	NListener int

	// Backlog represents backlog arg for syscall.Listen
	Backlog int

	// ReadBufferSize represents buffer size for reading, it's set to 16k by default.
	ReadBufferSize int

	// MinConnCacheSize represents application layer's Conn write cache buffer size when the kernel sendQ is full
	MinConnCacheSize int

	// MaxWriteBufferSize represents max write buffer size for Conn, it's set to 1m by default.
	// if the connection's Send-Q is full and the data cached by nbio is
	// more than MaxWriteBufferSize, the connection would be closed by nbio.
	MaxWriteBufferSize int

	// MaxReadTimesPerEventLoop represents max read times in one poller loop for one fd
	MaxReadTimesPerEventLoop int

	// LockListener represents listener's goroutine to lock thread or not, it's set to false by default.
	LockListener bool

	// LockPoller represents poller's goroutine to lock thread or not, it's set to false by default.
	LockPoller bool

	// EpollMod sets the epoll mod, EPOLLLT by default.
	EpollMod int
}

Config Of Gopher.

type Conn

type Conn struct {
	ReadBuffer []byte

	DataHandler func(c *Conn, data []byte)
	// contains filtered or unexported fields
}

Conn implements net.Conn.

func Dial

func Dial(network string, address string) (*Conn, error)

Dial wraps net.Dial.

func DialTimeout

func DialTimeout(network string, address string, timeout time.Duration) (*Conn, error)

DialTimeout wraps net.DialTimeout.

func NBConn

func NBConn(conn net.Conn) (*Conn, error)

NBConn converts net.Conn to *Conn.

func (*Conn) Close

func (c *Conn) Close() error

Close implements Close.

func (*Conn) CloseWithError

func (c *Conn) CloseWithError(err error) error

CloseWithError .

func (*Conn) Execute

func (c *Conn) Execute(f func())

Execute .

func (*Conn) ExecuteLen

func (c *Conn) ExecuteLen() int

ExecuteLen .

func (*Conn) Hash

func (c *Conn) Hash() int

Hash returns a hash code.

func (*Conn) IsClosed

func (c *Conn) IsClosed() (bool, error)

IsClosed .

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr implements LocalAddr.

func (*Conn) Lock

func (c *Conn) Lock()

Lock .

func (*Conn) MustExecute

func (c *Conn) MustExecute(f func())

MustExecute .

func (*Conn) OnData

func (c *Conn) OnData(h func(conn *Conn, data []byte))

OnData registers callback for data.

func (*Conn) Read

func (c *Conn) Read(b []byte) (int, error)

Read implements Read.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr implements RemoteAddr.

func (*Conn) Sendfile

func (c *Conn) Sendfile(f *os.File, remain int64) (int64, error)

Sendfile .

func (*Conn) Session

func (c *Conn) Session() interface{}

Session returns user session.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline implements SetDeadline.

func (*Conn) SetKeepAlive

func (c *Conn) SetKeepAlive(keepalive bool) error

SetKeepAlive implements SetKeepAlive.

func (*Conn) SetKeepAlivePeriod

func (c *Conn) SetKeepAlivePeriod(d time.Duration) error

SetKeepAlivePeriod implements SetKeepAlivePeriod.

func (*Conn) SetLinger

func (c *Conn) SetLinger(onoff int32, linger int32) error

SetLinger implements SetLinger.

func (*Conn) SetNoDelay

func (c *Conn) SetNoDelay(nodelay bool) error

SetNoDelay implements SetNoDelay.

func (*Conn) SetReadBuffer

func (c *Conn) SetReadBuffer(bytes int) error

SetReadBuffer implements SetReadBuffer.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline implements SetReadDeadline.

func (*Conn) SetSession

func (c *Conn) SetSession(session interface{})

SetSession sets user session.

func (*Conn) SetWriteBuffer

func (c *Conn) SetWriteBuffer(bytes int) error

SetWriteBuffer implements SetWriteBuffer.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline implements SetWriteDeadline.

func (*Conn) Unlock

func (c *Conn) Unlock()

Unlock .

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

Write implements Write.

func (*Conn) Writev

func (c *Conn) Writev(in [][]byte) (int, error)

Writev implements Writev.

type Gopher

type Gopher struct {
	sync.WaitGroup

	Name string

	Execute func(f func())
	// contains filtered or unexported fields
}

Gopher is a manager of poller.

func NewGopher

func NewGopher(conf Config) *Gopher

NewGopher is a factory impl.

func (*Gopher) AddConn

func (g *Gopher) AddConn(conn net.Conn) (*Conn, error)

AddConn adds conn to a poller.

func (*Gopher) After

func (g *Gopher) After(timeout time.Duration) <-chan time.Time

After used as time.After.

func (*Gopher) AfterFunc

func (g *Gopher) AfterFunc(timeout time.Duration, f func()) *Timer

AfterFunc used as time.AfterFunc.

func (*Gopher) AfterRead

func (g *Gopher) AfterRead(h func(c *Conn))

AfterRead registers callback after syscall.Read the handler would be called on *nix.

func (*Gopher) BeforeRead

func (g *Gopher) BeforeRead(h func(c *Conn))

BeforeRead registers callback before syscall.Read the handler would be called on windows.

func (*Gopher) BeforeWrite

func (g *Gopher) BeforeWrite(h func(c *Conn))

BeforeWrite registers callback befor syscall.Write and syscall.Writev the handler would be called on windows.

func (*Gopher) OnClose

func (g *Gopher) OnClose(h func(c *Conn, err error))

OnClose registers callback for disconnected.

func (*Gopher) OnData

func (g *Gopher) OnData(h func(c *Conn, data []byte))

OnData registers callback for data.

func (*Gopher) OnOpen

func (g *Gopher) OnOpen(h func(c *Conn))

OnOpen registers callback for new connection.

func (*Gopher) OnRead

func (g *Gopher) OnRead(h func(c *Conn))

OnRead registers callback for reading event.

func (*Gopher) OnReadBufferAlloc

func (g *Gopher) OnReadBufferAlloc(h func(c *Conn) []byte)

OnReadBufferAlloc registers callback for memory allocating.

func (*Gopher) OnReadBufferFree

func (g *Gopher) OnReadBufferFree(h func(c *Conn, b []byte))

OnReadBufferFree registers callback for memory release.

func (*Gopher) OnStop

func (g *Gopher) OnStop(h func())

OnStop registers callback before Gopher is stopped.

func (*Gopher) OnWriteBufferRelease

func (g *Gopher) OnWriteBufferRelease(h func(c *Conn, b []byte))

OnWriteBufferRelease registers callback for write buffer memory release.

func (*Gopher) PollerBuffer

func (g *Gopher) PollerBuffer(c *Conn) []byte

PollerBuffer returns Poller's buffer by Conn, can be used on linux/bsd.

func (*Gopher) Start

func (g *Gopher) Start() error

Start init and start pollers.

func (*Gopher) Stop

func (g *Gopher) Stop()

Stop pollers.

type Timer

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

Timer type for export.

func (Timer) Reset

func (it Timer) Reset(timeout time.Duration)

reset timer.

func (Timer) Stop

func (it Timer) Stop()

cancel timer.