gnet: github.com/panjf2000/gnet Index | Files | Directories

package gnet

import "github.com/panjf2000/gnet"

gnet is an event-driven 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 netty and libuv.

The goal of this project is to create a server framework for Go that performs on par with Redis and Haproxy for packet handling.

gnet sells itself as a high-performance, lightweight, non-blocking, event-driven networking framework written in pure Go which works on transport layer with TCP/UDP/Unix-Socket protocols, so it allows developers to implement their own protocols of application layer upon gnet for building diversified network applications, for instance, you get an HTTP Server or Web Framework if you implement HTTP protocol upon gnet while you have a Redis Server done with the implementation of Redis protocol upon gnet and so on.

Echo server built upon gnet is shown below:

package main

import (
	"log"

	"github.com/panjf2000/gnet"
)

type echoServer struct {
	*gnet.EventServer
}

func (es *echoServer) React(c gnet.Conn) (out []byte, action gnet.Action) {
	out = c.Read()
	c.ResetBuffer()
	return
}

func main() {
	echo := new(echoServer)
	log.Fatal(gnet.Serve(echo, "tcp://:9000", gnet.WithMulticore(true)))
}

Index

Package Files

acceptor_unix.go codec.go connection_unix.go doc.go errors.go eventloop_group.go eventloop_unix.go gnet.go listener.go listener_unix.go loop_linux.go options.go reactor_linux.go server_unix.go

Variables

var (

    // ErrInvalidFixedLength invalid fixed length.
    ErrInvalidFixedLength = errors.New("invalid fixed length of bytes")
    // ErrUnexpectedEOF no enough data to read.
    ErrUnexpectedEOF = errors.New("there is no enough data")
    // ErrDelimiterNotFound no such a delimiter.
    ErrDelimiterNotFound = errors.New("there is no such a delimiter")
    // ErrCRLFNotFound CRLF not found.
    ErrCRLFNotFound = errors.New("there is no CRLF")
    // ErrUnsupportedLength unsupported lengthFieldLength.
    ErrUnsupportedLength = errors.New("unsupported lengthFieldLength. (expected: 1, 2, 3, 4, or 8)")
    // ErrTooLessLength adjusted frame length is less than zero.
    ErrTooLessLength = errors.New("adjusted frame length is less than zero")
)
var CRLFByte = byte('\n')

CRLFByte represents a byte of CRLF.

func Serve Uses

func Serve(eventHandler EventHandler, addr string, opts ...Option) error

Serve starts handling events for the specified addresses.

Addresses should use a scheme prefix and be formatted like `tcp://192.168.0.10:9851` or `unix://socket`. Valid network schemes:

tcp   - bind to both IPv4 and IPv6
tcp4  - IPv4
tcp6  - IPv6
udp   - bind to both IPv4 and IPv6
udp4  - IPv4
udp6  - IPv6
unix  - Unix Domain Socket

The "tcp" network scheme is assumed when one is not specified.

type Action Uses

type Action int

Action is an action that occurs after the completion of an event.

const (
    // None indicates that no action should occur following an event.
    None Action = iota

    // Close closes the connection.
    Close

    // Shutdown shutdowns the server.
    Shutdown
)

type BuiltInFrameCodec Uses

type BuiltInFrameCodec struct {
}

BuiltInFrameCodec is the built-in codec which will be assigned to gnet server when customized codec is not set up.

func (*BuiltInFrameCodec) Decode Uses

func (cc *BuiltInFrameCodec) Decode(c Conn) ([]byte, error)

Decode ...

func (*BuiltInFrameCodec) Encode Uses

func (cc *BuiltInFrameCodec) Encode(c Conn, buf []byte) ([]byte, error)

Encode ...

type Conn Uses

type Conn interface {
    // Context returns a user-defined context.
    Context() (ctx interface{})

    // SetContext sets a user-defined context.
    SetContext(ctx interface{})

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

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

    // ReadFromUDP reads data for UDP socket.
    ReadFromUDP() (buf []byte)

    // ReadFrame returns either a frame from TCP stream based on codec or nil when there isn't a complete frame yet.
    ReadFrame() (buf []byte)

    // Read reads all data from inbound ring-buffer without moving "read" pointer, which means
    // it does not evict the data from ring-buffer actually and those data will present in ring-buffer until the
    // ResetBuffer method is invoked.
    Read() (buf []byte)

    // ResetBuffer resets the inbound ring-buffer, which means all data in the inbound ring-buffer has been evicted.
    ResetBuffer()

    // ShiftN shifts "read" pointer in buffer with the given length.
    ShiftN(n int) (size int)

    // ReadN reads bytes with the given length from inbound ring-buffer and event-loop-buffer, it would move
    // "read" pointer, which means it will evict the data from buffer and it can't be revoked (put back to buffer),
    // it reads data from the inbound ring-buffer and event-loop-buffer when the length of the available data is equal
    // to the given "n", otherwise, it will not read any data from the inbound ring-buffer. So you should use this
    // function only if you know exactly the length of subsequent TCP stream based on the protocol, like the
    // Content-Length attribute in an HTTP request which indicates you how much data you should read from inbound ring-buffer.
    ReadN(n int) (size int, buf []byte)

    // BufferLength returns the length of available data in the inbound ring-buffer.
    BufferLength() (size int)

    // SendTo writes data for UDP sockets, it allows you to send data back to UDP socket in individual goroutines.
    SendTo(buf []byte)

    // AsyncWrite writes data to client/connection asynchronously, usually you would invoke it in individual goroutines
    // instead of the event-loop goroutines.
    AsyncWrite(buf []byte)

    // Wake triggers a React event for this connection.
    Wake()
}

Conn is a interface of gnet connection.

type DecoderConfig Uses

type DecoderConfig = goframe.DecoderConfig

DecoderConfig config for decoder.

type DelimiterBasedFrameCodec Uses

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

DelimiterBasedFrameCodec encodes/decodes specific-delimiter-separated frames into/from TCP stream.

func NewDelimiterBasedFrameCodec Uses

func NewDelimiterBasedFrameCodec(delimiter byte) *DelimiterBasedFrameCodec

NewDelimiterBasedFrameCodec instantiates and returns a codec with a specific delimiter.

func (*DelimiterBasedFrameCodec) Decode Uses

func (cc *DelimiterBasedFrameCodec) Decode(c Conn) ([]byte, error)

Decode ...

func (*DelimiterBasedFrameCodec) Encode Uses

func (cc *DelimiterBasedFrameCodec) Encode(c Conn, buf []byte) ([]byte, error)

Encode ...

type EncoderConfig Uses

type EncoderConfig = goframe.EncoderConfig

EncoderConfig config for encoder.

type EventHandler Uses

type EventHandler interface {
    // OnInitComplete fires when the server is ready for accepting connections.
    // The server parameter has information and various utilities.
    OnInitComplete(server Server) (action Action)

    // OnOpened fires when a new connection has been opened.
    // The info parameter has information about the connection such as
    // it's local and remote address.
    // Use the out return value to write data to the connection.
    OnOpened(c Conn) (out []byte, action Action)

    // OnClosed fires when a connection has been closed.
    // The err parameter is the last known connection error.
    OnClosed(c Conn, err error) (action Action)

    // PreWrite fires just before any data is written to any client socket.
    PreWrite()

    // React fires when a connection sends the server data.
    // Invoke c.Read() or c.ReadN(n) within the parameter c to read incoming data from client/connection.
    // Use the out return value to write data to the client/connection.
    React(c Conn) (out []byte, action Action)

    // Tick fires immediately after the server starts and will fire again
    // following the duration specified by the delay return value.
    Tick() (delay time.Duration, action Action)
}

EventHandler represents the server events' callbacks for the Serve call. Each event has an Action return value that is used manage the state of the connection and server.

type EventServer Uses

type EventServer struct {
}

EventServer is a built-in implementation of EventHandler which sets up each method with a default implementation, you can compose it with your own implementation of EventHandler when you don't want to implement all methods in EventHandler.

func (*EventServer) OnClosed Uses

func (es *EventServer) OnClosed(c Conn, err error) (action Action)

OnClosed fires when a connection has been closed. The err parameter is the last known connection error.

func (*EventServer) OnInitComplete Uses

func (es *EventServer) OnInitComplete(svr Server) (action Action)

OnInitComplete fires when the server is ready for accepting connections. The server parameter has information and various utilities.

func (*EventServer) OnOpened Uses

func (es *EventServer) OnOpened(c Conn) (out []byte, action Action)

OnOpened fires when a new connection has been opened. The info parameter has information about the connection such as it's local and remote address. Use the out return value to write data to the connection.

func (*EventServer) PreWrite Uses

func (es *EventServer) PreWrite()

PreWrite fires just before any data is written to any client socket.

func (*EventServer) React Uses

func (es *EventServer) React(c Conn) (out []byte, action Action)

React fires when a connection sends the server data. Invoke c.Read() or c.ReadN(n) within the parameter c to read incoming data from client/connection. Use the out return value to write data to the client/connection.

func (*EventServer) Tick Uses

func (es *EventServer) Tick() (delay time.Duration, action Action)

Tick fires immediately after the server starts and will fire again following the duration specified by the delay return value.

type FixedLengthFrameCodec Uses

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

FixedLengthFrameCodec encodes/decodes fixed-length-separated frames into/from TCP stream.

func NewFixedLengthFrameCodec Uses

func NewFixedLengthFrameCodec(frameLength int) *FixedLengthFrameCodec

NewFixedLengthFrameCodec instantiates and returns a codec with fixed length.

func (*FixedLengthFrameCodec) Decode Uses

func (cc *FixedLengthFrameCodec) Decode(c Conn) ([]byte, error)

Decode ...

func (*FixedLengthFrameCodec) Encode Uses

func (cc *FixedLengthFrameCodec) Encode(c Conn, buf []byte) ([]byte, error)

Encode ...

type ICodec Uses

type ICodec interface {
    // Encode encodes frames upon server responses into TCP stream.
    Encode(c Conn, buf []byte) ([]byte, error)
    // Decode decodes frames from TCP stream via specific implementation.
    Decode(c Conn) ([]byte, error)
}

ICodec is the interface of gnet codec.

type IEventLoopGroup Uses

type IEventLoopGroup interface {
    // contains filtered or unexported methods
}

IEventLoopGroup represents a set of event-loops.

type LengthFieldBasedFrameCodec Uses

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

LengthFieldBasedFrameCodec is the refactoring from https://github.com/smallnest/goframe/blob/master/length_field_based_frameconn.go, licensed by Apache License 2.0. It encodes/decodes frames into/from TCP stream with value of the length field in the message. Original implementation: https://github.com/netty/netty/blob/4.1/codec/src/main/java/io/netty/handler/codec/LengthFieldBasedFrameDecoder.java

func NewLengthFieldBasedFrameCodec Uses

func NewLengthFieldBasedFrameCodec(encoderConfig EncoderConfig, decoderConfig DecoderConfig) *LengthFieldBasedFrameCodec

NewLengthFieldBasedFrameCodec instantiates and returns a codec based on the length field. It is the go implementation of netty LengthFieldBasedFrameecoder and LengthFieldPrepender. you can see javadoc of them to learn more details.

func (*LengthFieldBasedFrameCodec) Decode Uses

func (cc *LengthFieldBasedFrameCodec) Decode(c Conn) ([]byte, error)

Decode ...

func (*LengthFieldBasedFrameCodec) Encode Uses

func (cc *LengthFieldBasedFrameCodec) Encode(c Conn, buf []byte) (out []byte, err error)

Encode ...

type LineBasedFrameCodec Uses

type LineBasedFrameCodec struct {
}

LineBasedFrameCodec encodes/decodes line-separated frames into/from TCP stream.

func (*LineBasedFrameCodec) Decode Uses

func (cc *LineBasedFrameCodec) Decode(c Conn) ([]byte, error)

Decode ...

func (*LineBasedFrameCodec) Encode Uses

func (cc *LineBasedFrameCodec) Encode(c Conn, buf []byte) ([]byte, error)

Encode ...

type Option Uses

type Option func(opts *Options)

Option is a function that will set up option.

func WithCodec Uses

func WithCodec(codec ICodec) Option

WithCodec sets up a codec to handle TCP stream.

func WithMulticore Uses

func WithMulticore(multicore bool) Option

WithMulticore sets up multi-cores with gnet.

func WithOptions Uses

func WithOptions(options Options) Option

WithOptions sets up all options.

func WithReusePort Uses

func WithReusePort(reusePort bool) Option

WithReusePort sets up SO_REUSEPORT socket option.

func WithTCPKeepAlive Uses

func WithTCPKeepAlive(tcpKeepAlive time.Duration) Option

WithTCPKeepAlive sets up SO_KEEPALIVE socket option.

func WithTicker Uses

func WithTicker(ticker bool) Option

WithTicker indicates that a ticker is set.

type Options Uses

type Options struct {
    // Multicore indicates whether the server will be effectively created with multi-cores, if so,
    // then you must take care with synchronizing memory between all event callbacks, otherwise,
    // it will run the server with single thread. The number of threads in the server will be automatically
    // assigned to the value of runtime.NumCPU().
    Multicore bool

    // ReusePort indicates whether to set up the SO_REUSEPORT socket option.
    ReusePort bool

    // Ticker indicates whether the ticker has been set up.
    Ticker bool

    // TCPKeepAlive (SO_KEEPALIVE) socket option.
    TCPKeepAlive time.Duration

    // ICodec encodes and decodes TCP stream.
    Codec ICodec
}

Options are set when the client opens.

type Server Uses

type Server struct {
    // Multicore indicates whether the server will be effectively created with multi-cores, if so,
    // then you must take care of synchronizing the shared data between all event callbacks, otherwise,
    // it will run the server with single thread. The number of threads in the server will be automatically
    // assigned to the value of runtime.NumCPU().
    Multicore bool

    // The Addr parameter is an array of listening addresses that align
    // with the addr strings passed to the Serve function.
    Addr net.Addr

    // NumLoops is the number of loops that the server is using.
    NumLoops int

    // ReUsePort indicates whether SO_REUSEPORT is enable.
    ReUsePort bool

    // TCPKeepAlive (SO_KEEPALIVE) socket option.
    TCPKeepAlive time.Duration
}

Server represents a server context which provides information about the running server and has control functions for managing state.

Directories

PathSynopsis
internal
internal/netpoll
netpoll
pool
pool/bytes
pool/goroutine
pool/ringbuffer
ringbuffer

Package gnet imports 17 packages (graph) and is imported by 1 packages. Updated 2019-12-12. Refresh now. Tools for package owners.