cloudwego/netpoll: a non-blocking I/O framework for Go RPC servers

The goroutine-per-connection cost netpoll was written to remove

Go's net package exposes blocking I/O. A server written on top of it reads as a loop that accepts a connection and hands it to a goroutine, which is why RPC frameworks built on net end up with one goroutine per connection. The netpoll README states the problem plainly: RPC is heavy on processing logic, so it cannot handle I/O serially, and a large number of goroutines under high concurrency wastes context switching.

The second problem the README names is connection liveness. net.Conn has no API to check whether a connection is still alive, so an RPC connection pool has no cheap way to tell a usable connection from a dead one, and the README describes the result as a large number of failed connections sitting in the pool. Netpoll exposes IsActive for exactly that check.

The audience is therefore narrow and specific: people building RPC clients and servers in Go, not people building generic TCP daemons. The README says netpoll was developed by ByteDance and that the RPC framework Kitex and the HTTP framework Hertz are built on it. If you are writing a Redis proxy or a load balancer, the README explicitly points at evio and gnet as the projects aimed at those cases.

EventLoop, LinkBuffer and the nocopy path through a connection

The architecture follows the reactor shape the README attributes to evio and Netty. The repository's top-level files map onto it: eventloop.go defines the event loop, poll.go and poll_default.go handle the polling layer, net_listener.go and net_dialer.go cover the accept and dial sides, and connection.go plus connection_impl.go define the connection abstraction. The platform split is visible in netpoll_unix.go and netpoll_windows.go.

On the data path, LinkBuffer is the piece that matters. The README calls it a nocopy API for streaming reading and writing, and it is implemented in nocopy_linkbuffer.go, with separate nocopy_linkbuffer_race.go and nocopy_linkbuffer_norace.go variants and a nocopy_readwriter.go wrapper. The build-tag split means the buffer behaves differently under the race detector, which is a deliberate trade of throughput for diagnosability.

Around the buffer sit two supporting packages the README lists as features: gopool for goroutine pooling and mcache for memory reuse, both imported from github.com/bytedance/gopkg. Note that go.mod also requires github.com/cloudwego/gopkg, so a single netpoll dependency pulls two gopkg modules plus golang.org/x/sys into your module graph.

Transport support is TCP and Unix Domain Socket. The README lists Linux and macOS as supported operating systems and Windows under Unsupported. There is a connection_reuse_linux.go file, so some connection-reuse behaviour is Linux-only.

Installing netpoll and writing a first server

The README does not print install commands. It links to a Getting Started guide at docs/guide/guide_en.md and to a separate netpoll-examples repository, and those are where the project says to look for working code. What the repository does pin down is the module path and the Go version. The go.mod file at the top level of the repository reads in full:

module github.com/cloudwego/netpoll

go 1.20

require (
	github.com/bytedance/gopkg v0.1.1
	github.com/cloudwego/gopkg v0.1.4
	golang.org/x/sys v0.30.0
)

That gives you the import path, the minimum Go toolchain, and the three modules you inherit. There is no install command to copy, so the fetch step is whatever your own module workflow is against that path.

The README describes the two halves of the API in one line each: Dialer supports building clients, EventLoop supports building a server. The repository layout backs that up, with net_dialer.go and eventloop.go as the entry points. A server is therefore an EventLoop with a registered OnRequest handler, and the handler receives a connection and a buffer rather than a net.Conn and an io.Reader.

The connection abstraction is the part to read before writing code. connection.go and connection_impl.go define it, and connection_onevent.go shows the event callbacks. Because the README describes IsActive as a supported check, the intended shape of a client-side pool is to call it before handing a connection to a request. The README does not document reconnection, backoff or pool eviction, so those are yours to write.

For a runnable starting point, the README's own pointer is the netpoll-examples repository. It is the only example source the README names, and it is separate from this repository.

What netpoll does not do, and where it is the wrong choice

Windows is unsupported. The README lists it under Unsupported, and netpoll_windows.go exists at the top level, so the build story on that platform is worth checking yourself rather than assuming.

The bigger limitation is scope. The README says netpoll is recommended to replace net in some RPC scenarios, not all of them. It is an I/O and connection layer. It does not give you a protocol, serialization, service discovery, or a code generator. Kitex is the project that adds those on top. If what you actually want is an RPC framework, adopting netpoll directly means writing the layer Kitex already wrote.

There is also a debugging trade. The one-goroutine-per-connection model is easy to reason about because a stack trace points at the connection. An event loop inverts that: state lives in the loop and in connection objects, and the nocopy buffer means data you hand out is shared rather than copied. The repository ships nocopy_linkbuffer_race.go and a docs/reference/explain.md file whose title in the README reference list is Why DATA RACE, which tells you the maintainers consider race behaviour worth a dedicated document. Read it before you write handlers that retain buffers.

Finally, the README's performance section does not print numbers. It points at the netpoll-benchmark project and at the Kitex and Hertz benchmark repositories. Any figure you have seen quoted elsewhere is not in this README.

netpoll against gnet, evio and the standard net package

The README names its own comparison set, which makes this easy to state without guessing. evio and gnet are described as focusing on scenarios like Redis and HAProxy, and the README's complaint about the open source landscape is that Go network libraries focused on RPC were missing. Netpoll draws inspiration from evio and Netty but targets RPC instead of proxy or cache protocols.

The practical difference is the API shape and what comes with it. A proxy framework optimises for moving bytes between two sockets and rarely needs a connection-liveness check or a client-side dialer abstraction. Netpoll ships Dialer for building clients and IsActive for checking a connection, both of which exist because an RPC connection pool needs them. The README frames the whole project around that gap.

Against the standard net package the difference is the concurrency model, not the feature list. net gives you blocking calls and a goroutine per connection; netpoll gives you an event loop and a nocopy buffer. The README's own wording is that netpoll is recommended to replace net in some RPC scenarios, which is a narrower claim than replacing it everywhere.

Against Kitex there is no contest, because they are different layers. Kitex is the RPC framework built on netpoll. If you want a framework, use Kitex; if you are building the framework, netpoll is the substrate.

Maintenance, licence and the upgrade surface

The repository is not archived, and the last push was on 2026-08-06. The most recent release in the list is v0.7.5, also dated 2026-08-06, with v0.7.4 on the same day and v0.7.3 on 2026-06-10. Two releases on one day suggests a quick follow-up fix rather than a planned cadence, so read the release notes for both before pinning either.

The version is still 0.x, which is the honest signal about API stability. The repository has no v1 branch and no compatibility promise in the README. Treat every minor bump as a potential source change and read the release notes rather than trusting Go module resolution to keep you safe.

The dependency surface is small but not zero. go.mod requires github.com/bytedance/gopkg v0.1.1, github.com/cloudwego/gopkg v0.1.4 and golang.org/x/sys v0.30.0. Those are the modules you inherit, and golang.org/x/sys is the one that ties you to supported operating systems.

The licence is Apache-2.0. The repository carries both LICENSE and NOTICE files, and a .licenserc.yaml at the top level. Apache-2.0 includes an explicit patent grant and requires that NOTICE contents be preserved when you redistribute. That is a description of the licence text, not legal advice; if you are redistributing netpoll inside a product, have your own counsel read the NOTICE file.

Editorial conclusion

Adopt netpoll when you are writing a Go RPC server or client and the standard net package's goroutine-per-connection cost is the thing you are trying to remove. Skip it if you need Windows, if you want a ready-made protocol server, or if you are not comfortable owning the framing and lifecycle code yourself. Before committing, read docs/guide/guide_en.md and docs/reference/design_en.md, check the eventloop.go and connection.go interfaces against the version you will pin in go.mod, and confirm the last release date against your own dependency policy.

Frequently asked questions

Official sources

1. cloudwego/netpoll on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases