gnet v2

Supported Transport Protocols

• TCP
• UDP
• Unix Domain Socket

Core Features

• High-performance event-driven looping: Based on a multi-threaded/goroutine networking model.
• Built-in goroutine pool: Powered by the ants library.
• Lock-free runtime: Designed for high concurrency without lock contention.
• Memory Management: Uses efficient, reusable, and elastic buffers (Elastic-Ring-Buffer, Linked-List-Buffer, and Elastic-Mixed-Buffer).
• Load Balancing: Supports Round-Robin, Source-Addr-Hash, and Least-Connections algorithms.
• I/O Support: Supports Edge-triggered I/O.
• Client Support: Includes a built-in gnet client.
• Platform Support: Runs on Linux, macOS, Windows, and *BSD (Darwin, DragonFlyBSD, FreeBSD, NetBSD, OpenBSD).

gnet is a high-performance, lightweight, event-driven networking framework implemented in pure Go. It is built from scratch using epoll and kqueue to provide lower memory consumption and higher performance compared to the standard Go net package.

Key Characteristics:

• Non-blocking: Designed for high-concurrency, non-blocking I/O.
• Transport Layer Focus: It provides core transport layer capabilities (TCP, UDP, and Unix Domain Socket) rather than being an all-in-one application framework.
• Application Layer Implementation: Developers use gnet to implement their own application-level protocols such as HTTP, RPC, Redis, or WebSocket.
• Different Paradigm: Unlike the standard net package, gnet follows an event-driven model similar to libuv or netty. It is not a direct replacement for net but an alternative for performance-sensitive services.

gnet is an ultra-fast, lightweight, event-driven networking framework built from scratch using epoll and kqueue.

Key Differences:

• Philosophy: Unlike the standard Go net package, gnet is non-blocking and event-driven. It is designed for performance-critical services where low memory consumption and high throughput are required.
• Scope: gnet is not a comprehensive replacement for net. It provides a concise set of core APIs for the transport layer (TCP, UDP, and Unix Domain Sockets), allowing developers to implement their own application-layer protocols (like HTTP, RPC, or Redis) on top of it.
• Model: It uses a multi-threaded/goroutine looping model and is lock-free during runtime.

To use the legacy version (v1) of gnet, use the following command:

go get -u github.com/panjf2000/gnet

To use the current version (v2) of gnet, add it to your Go module using the following command. Ensure you are using Go 1.20 or higher as per the minimum requirements.

go get -u github.com/panjf2000/gnet/v2

The EventHandler interface defines the lifecycle callbacks for network events. You can implement all methods or embed gnet.BuiltinEventEngine to only implement the ones you need.

Key methods:

• OnBoot(eng Engine): Called when the engine is ready.
• OnOpen(c Conn): Called when a new connection is opened. Returns out []byte to send immediately and an Action (e.g., gnet.Close).
• OnClose(c Conn, err error): Called when a connection closes.
• OnTraffic(c Conn): Called when data is received. Use the Conn object to read data.
• OnTick(): Called periodically based on the duration returned.
• OnShutdown(eng Engine): Called when the engine shuts down.

To start a networking server, use gnet.Run for a single address or gnet.Rotate for multiple addresses. You must provide an EventHandler to handle network events.

Addresses must use a scheme prefix:

• tcp, tcp4, tcp6 (default is tcp)
• udp, udp4, udp6
• unix (Unix Domain Socket)

Example address format: tcp://127.0.0.1:9851 or unix:///tmp/gnet.sock.

package main

import "github.com/panjf2000/gnet/v2"

type ec struct {
	gnet.BuiltinEventEngine
}

func main() {
	err := gnet.Run(&ec{}, "tcp://:9851")
	if err != nil {
		panic(err)
	}
}

Use NewClient to create a new Client instance. You must provide an EventHandler to handle network events and can optionally provide Option arguments to configure the client (e.g., buffer sizes, logging, or TCP settings).

NewClient(eh EventHandler, opts ...Option) (*Client, error)

// Example initialization
cli, err := gnet.NewClient(myEventHandler, gnet.WithReadBufferCap(1024))
if err != nil {
	panic(err)
}