gnet

package module
v0.0.0-...-9677cda Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 22, 2021 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var CRLFByte = byte('\n')

CRLFByte represents a byte of CRLF.

Functions

func Serve 

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

Serve starts handling events for the specified address.

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

func Stop 

func Stop(ctx context.Context, protoAddr string) error

Stop gracefully shuts down the server without interrupting any active event-loops, it waits indefinitely for connections and event-loops to be closed and then shuts down.

Types

type Action 

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 

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 

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

Decode ...

func (*BuiltInFrameCodec) Encode 

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

Encode ...

func (*BuiltInFrameCodec) Encodev 

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

Encode ...

type Conn 

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)

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

	// ResetBuffer resets the buffers, which means all data in inbound ring-buffer and event-loop-buffer will be evicted.
	ResetBuffer()

	// ReadN reads bytes with the given length from inbound ring-buffer and event-loop-buffer without moving
	// "read" pointer, which means it will not evict the data from buffers until the ShiftN method is called,
	// it reads data from the inbound ring-buffer and event-loop-buffer and returns both bytes and the size of it.
	// If the length of the available data is less than the given "n", ReadN will return all available data, so you
	// should make use of the variable "size" returned by it to be aware of the exact length of the returned data.
	ReadN(n int) (size int, buf []byte)

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

	// BufferLength returns the length of available data in the internal buffers.
	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) error

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

	// AsyncWritev writes data_vec to client/connection asynchronously, usually you would call it in individual goroutines
	// instead of the event-loop goroutines.
	AsyncWritev(wb WrappedBuffer) error

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

	// Close closes the current connection.
	Close() error
}

Conn is a interface of gnet connection.

type DecoderConfig 

type DecoderConfig struct {
	// ByteOrder is the ByteOrder of the length field.
	ByteOrder binary.ByteOrder
	// LengthFieldOffset is the offset of the length field
	LengthFieldOffset int
	// LengthFieldLength is the length of the length field
	LengthFieldLength int
	// LengthAdjustment is the compensation value to add to the value of the length field
	LengthAdjustment int
	// InitialBytesToStrip is the number of first bytes to strip out from the decoded frame
	InitialBytesToStrip int
}

DecoderConfig config for decoder.

type DelimiterBasedFrameCodec 

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

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

func NewDelimiterBasedFrameCodec 

func NewDelimiterBasedFrameCodec(delimiter byte) *DelimiterBasedFrameCodec

NewDelimiterBasedFrameCodec instantiates and returns a codec with a specific delimiter.

func (*DelimiterBasedFrameCodec) Decode 

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

Decode ...

func (*DelimiterBasedFrameCodec) Encode 

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

Encode ...

func (*DelimiterBasedFrameCodec) Encodev 

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

Encodev ...

type EncoderConfig 

type EncoderConfig struct {
	// ByteOrder is the ByteOrder of the length field.
	ByteOrder binary.ByteOrder
	// LengthFieldLength is the length of the length field.
	LengthFieldLength int
	// LengthAdjustment is the compensation value to add to the value of the length field
	LengthAdjustment int
	// LengthIncludesLengthFieldLength is true, the length of the prepended length field is added to the value of
	// the prepended length field
	LengthIncludesLengthFieldLength bool
}

EncoderConfig config for encoder.

type EventHandler 

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

	// OnShutdown fires when the server is being shut down, it is called right after
	// all event-loops and connections are closed.
	OnShutdown(server Server)

	// OnOpened fires when a new connection has been opened.
	// The parameter:c has information about the connection such as it's local and remote address.
	// Parameter:out is the return value which is going to be sent back to the client.
	// It is generally not recommended to send large amounts of data back to the client in OnOpened.
	//
	// Note that the bytes returned by OnOpened will be sent back to client without being encoded.
	OnOpened(c Conn) (out []byte, action Action)

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

	// PreWrite fires just before a packet is written to the peer socket, this event function is usually where
	// you put some code of logging/counting/reporting or any fore operations before writing data to client.
	PreWrite(c Conn)

	// AfterWrite fires right after a packet is written to the peer socket, this event function is usually where
	// you put the []byte's back to your memory pool.
	AfterWrite(c Conn, b []byte)

	// AfterWrite fires right after a packet is written to the peer socket, this event function is usually where
	// you put the [][]byte's back to your memory pool.
	AfterWritev(c Conn, b [][]byte)

	// React fires when a connection sends the server data.
	// Call c.Read() or c.ReadN(n) within the parameter:c to read incoming data from client.
	// Parameter:out is the return value which is going to be sent back to the client.
	React(packet []byte, 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 

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) AfterWrite 

func (es *EventServer) AfterWrite(c Conn, b []byte)

AfterWrite fires right after a packet is written to the peer socket, this event function is usually where you put the []byte's back to your memory pool.

func (*EventServer) AfterWritev 

func (es *EventServer) AfterWritev(c Conn, b [][]byte)

AfterWrite fires right after a packet is written to the peer socket, this event function is usually where you put the []byte's back to your memory pool.

func (*EventServer) OnClosed 

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

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

func (*EventServer) OnInitComplete 

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

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

func (*EventServer) OnOpened 

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

OnOpened fires when a new connection has been opened. The parameter:c has information about the connection such as it's local and remote address. Parameter:out is the return value which is going to be sent back to the client.

func (*EventServer) OnShutdown 

func (es *EventServer) OnShutdown(svr Server)

OnShutdown fires when the server is being shut down, it is called right after all event-loops and connections are closed.

func (*EventServer) PreWrite 

func (es *EventServer) PreWrite(c Conn)

PreWrite fires just before a packet is written to the peer socket, this event function is usually where you put some code of logging/counting/reporting or any fore operations before writing data to client.

func (*EventServer) React 

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

React fires when a connection sends the server data. Call c.Read() or c.ReadN(n) within the parameter:c to read incoming data from client. Parameter:out is the return value which is going to be sent back to the client.

func (*EventServer) Tick 

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 

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

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

func NewFixedLengthFrameCodec 

func NewFixedLengthFrameCodec(frameLength int) *FixedLengthFrameCodec

NewFixedLengthFrameCodec instantiates and returns a codec with fixed length.

func (*FixedLengthFrameCodec) Decode 

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

Decode ...

func (*FixedLengthFrameCodec) Encode 

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

Encode ...

func (*FixedLengthFrameCodec) Encodev 

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

Encodev ...

type ICodec 

type ICodec interface {
	// Encode encodes frames upon server responses into TCP stream.
	Encode(c Conn, buf []byte) ([]byte, error)
	// Encodev encodes frames upon server responses into TCP stream.
	Encodev(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 LengthFieldBasedFrameCodec 

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.

func NewLengthFieldBasedFrameCodec 

func NewLengthFieldBasedFrameCodec(ec EncoderConfig, dc 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 

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

Decode ...

func (*LengthFieldBasedFrameCodec) Encode 

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

Encode ...

func (*LengthFieldBasedFrameCodec) Encodev 

func (cc *LengthFieldBasedFrameCodec) Encodev(c Conn, data_vec [][]byte) (out []byte, err error)

Encodev ...

type LineBasedFrameCodec 

type LineBasedFrameCodec struct{}

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

func (*LineBasedFrameCodec) Decode 

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

Decode ...

func (*LineBasedFrameCodec) Encode 

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

Encode ...

func (*LineBasedFrameCodec) Encodev 

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

Encodev ...

type LoadBalancing 

type LoadBalancing int

LoadBalancing represents the the type of load-balancing algorithm. 

const (
	// RoundRobin assigns the next accepted connection to the event-loop by polling event-loop list.
	RoundRobin LoadBalancing = iota

	// LeastConnections assigns the next accepted connection to the event-loop that is
	// serving the least number of active connections at the current time.
	LeastConnections

	// SourceAddrHash assignes the next accepted connection to the event-loop by hashing the remote address.
	SourceAddrHash
)

type Option 

type Option func(opts *Options)

Option is a function that will set up option.

func WithCodec 

func WithCodec(codec ICodec) Option

WithCodec sets up a codec to handle TCP stream.

func WithLoadBalancing 

func WithLoadBalancing(lb LoadBalancing) Option

WithLoadBalancing sets up the load-balancing algorithm in gnet server.

func WithLockOSThread 

func WithLockOSThread(lockOSThread bool) Option

WithLockOSThread sets up LockOSThread mode for I/O event-loops.

func WithLogLevel 

func WithLogLevel(lvl zapcore.Level) Option

WithLogLevel is an option to set up the logging level.

func WithLogPath 

func WithLogPath(fileName string) Option

WithLogPath is an option to set up the local path of log file.

func WithLogger 

func WithLogger(logger logging.Logger) Option

WithLogger sets up a customized logger.

func WithMulticore 

func WithMulticore(multicore bool) Option

WithMulticore sets up multi-cores in gnet server.

func WithNumEventLoop 

func WithNumEventLoop(numEventLoop int) Option

WithNumEventLoop sets up NumEventLoop in gnet server.

func WithOptions 

func WithOptions(options Options) Option

WithOptions sets up all options.

func WithReadBufferCap 

func WithReadBufferCap(readBufferCap int) Option

WithReadBufferCap sets up ReadBufferCap for reading bytes.

func WithReusePort 

func WithReusePort(reusePort bool) Option

WithReusePort sets up SO_REUSEPORT socket option.

func WithSocketRecvBuffer 

func WithSocketRecvBuffer(recvBuf int) Option

WithSocketRecvBuffer sets the maximum socket receive buffer in bytes.

func WithSocketSendBuffer 

func WithSocketSendBuffer(sendBuf int) Option

WithSocketSendBuffer sets the maximum socket send buffer in bytes.

func WithTCPKeepAlive 

func WithTCPKeepAlive(tcpKeepAlive time.Duration) Option

WithTCPKeepAlive sets up the SO_KEEPALIVE socket option with duration.

func WithTCPNoDelay 

func WithTCPNoDelay(tcpNoDelay TCPSocketOpt) Option

WithTCPNoDelay enable/disable the TCP_NODELAY socket option.

func WithTicker 

func WithTicker(ticker bool) Option

WithTicker indicates that a ticker is set.

type Options 

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 logical CPUs usable by the current process.
	Multicore bool

	// LockOSThread is used to determine whether each I/O event-loop is associated to an OS thread, it is useful when you
	// need some kind of mechanisms like thread local storage, or invoke certain C libraries (such as graphics lib: GLib)
	// that require thread-level manipulation via cgo, or want all I/O event-loops to actually run in parallel for a
	// potential higher performance.
	LockOSThread bool

	// ReadBufferCap is the maximum number of bytes that can be read from the client when the readable event comes.
	// The default value is 64KB, it can be reduced to avoid starving subsequent client connections.
	//
	// Note that ReadBufferCap will be always converted to the least power of two integer value greater than
	// or equal to its real amount.
	ReadBufferCap int

	// LB represents the load-balancing algorithm used when assigning new connections.
	LB LoadBalancing

	// NumEventLoop is set up to start the given number of event-loop goroutine.
	// Note: Setting up NumEventLoop will override Multicore.
	NumEventLoop int

	// 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 sets up a duration for (SO_KEEPALIVE) socket option.
	TCPKeepAlive time.Duration

	// TCPNoDelay controls whether the operating system should delay
	// packet transmission in hopes of sending fewer packets (Nagle's algorithm).
	//
	// The default is true (no delay), meaning that data is sent
	// as soon as possible after a Write.
	TCPNoDelay TCPSocketOpt

	// SocketRecvBuffer sets the maximum socket receive buffer in bytes.
	SocketRecvBuffer int

	// SocketSendBuffer sets the maximum socket send buffer in bytes.
	SocketSendBuffer int

	// ICodec encodes and decodes TCP stream.
	Codec ICodec

	// LogPath the local path where logs will be written, this is the easiest way to set up client logs,
	// the client instantiates a default uber-go/zap logger with this given log path, you are also allowed to employ
	// you own logger during the client lifetime by implementing the following log.Logger interface.
	//
	// Note that this option can be overridden by the option Logger.
	LogPath string

	// LogLevel indicates the logging level inside client, it should be used along with LogPath.
	LogLevel zapcore.Level

	// Logger is the customized logger for logging info, if it is not set,
	// then gnet will use the default logger powered by go.uber.org/zap.
	Logger logging.Logger
}

Options are set when the client opens.

type Server 

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 logical CPUs usable by the current process.
	Multicore bool

	// The Addr parameter is the listening address that align
	// with the addr string passed to the Serve function.
	Addr net.Addr

	// NumEventLoop is the number of event-loops that the server is using.
	NumEventLoop int

	// ReusePort indicates whether SO_REUSEPORT is enable.
	ReusePort bool

	// TCPKeepAlive (SO_KEEPALIVE) socket option.
	TCPKeepAlive time.Duration
	// contains filtered or unexported fields
}

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

func (Server) CountConnections 

func (s Server) CountConnections() (count int)

CountConnections counts the number of currently active connections and returns it.

func (Server) DupFd 

func (s Server) DupFd() (dupFD int, err error)

DupFd returns a copy of the underlying file descriptor of listener. It is the caller's responsibility to close dupFD when finished. Closing listener does not affect dupFD, and closing dupFD does not affect listener.

type TCPSocketOpt 

type TCPSocketOpt int

TCPSocketOpt is the type of TCP socket options. 

const (
	TCPNoDelay TCPSocketOpt = iota
	TCPDelay
)

Available TCP socket options.

type WrappedBuffer 

type WrappedBuffer struct {
	Bufs [][]byte
	Ctx  interface{}
}

Source Files

View all Source files

Directories

Path Synopsis
io
netpoll
queue
Package queue delivers an implementation of lock-free concurrent queue based on the algorithm presented by Maged M. Michael and Michael L. Scot.
 Package queue delivers an implementation of lock-free concurrent queue based on the algorithm presented by Maged M. Michael and Michael L. Scot.
socket
Package socket provides functions that return fd and net.Addr based on given the protocol and address with a SO_REUSEPORT option set to the socket.
 Package socket provides functions that return fd and net.Addr based on given the protocol and address with a SO_REUSEPORT option set to the socket.
Package logging provides logging functionality for gnet server, it sets up a default logger (powered by go.uber.org/zap) which is about to be used by gnet server, it also allows users to replace the default logger with their customized logger by just implementing the `Logger` interface and assign it to the functional option `Options.Logger`, pass it to `gnet.Serve` method.
 Package logging provides logging functionality for gnet server, it sets up a default logger (powered by go.uber.org/zap) which is about to be used by gnet server, it also allows users to replace the default logger with their customized logger by just implementing the `Logger` interface and assign it to the functional option `Options.Logger`, pass it to `gnet.Serve` method.
pool
bytebuffer
goroutine
ringbuffer

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.