Categorygithub.com/cloudwego/netpoll
modulepackage
0.6.5
Repository: https://github.com/cloudwego/netpoll.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
21
Dependents
42
Files
4.4k SLOC

# README

CloudWeGo-Netpoll

中文

Release WebSite License Go Report Card OpenIssue ClosedIssue Stars Forks

Introduction

Netpoll is a high-performance non-blocking I/O networking framework, which focused on RPC scenarios, developed by ByteDance.

RPC is usually heavy on processing logic and therefore cannot handle I/O serially. But Go's standard library net is designed for blocking I/O APIs, so that the RPC framework can only follow the One Conn One Goroutine design. It will waste a lot of cost for context switching, due to a large number of goroutines under high concurrency. Besides, net.Conn has no API to check Alive, so it is difficult to make an efficient connection pool for RPC framework, because there may be a large number of failed connections in the pool.

On the other hand, the open source community currently lacks Go network libraries that focus on RPC scenarios. Similar repositories such as: evio, gnet, etc., are all focus on scenarios like Redis, HAProxy.

But now, Netpoll was born and solved the above problems. It draws inspiration from the design of evio and netty, has excellent Performance, and is more suitable for microservice architecture. Also Netpoll provides a number of Features, and it is recommended to replace net in some RPC scenarios.

We developed the RPC framework Kitex and HTTP framework Hertz based on Netpoll, both with industry-leading performance.

Examples show how to build RPC client and server using Netpoll.

For more information, please refer to Document.

Features

  • Already

    • LinkBuffer provides nocopy API for streaming reading and writing
    • gopool provides high-performance goroutine pool
    • mcache provides efficient memory reuse
    • IsActive supports checking whether the connection is alive
    • Dialer supports building clients
    • EventLoop supports building a server
    • TCP, Unix Domain Socket
    • Linux, macOS (operating system)

  • Future

  • Unsupported

    • Windows (operating system)

Performance

Benchmark should meet the requirements of industrial use. In the RPC scenario, concurrency and timeout are necessary support items.

We provide the netpoll-benchmark project to track and compare the performance of Netpoll and other frameworks under different conditions for reference.

More benchmarks reference kitex-benchmark and hertz-benchmark.

Reference

# Packages

No description provided by the author

# Functions

Configure the internal behaviors of netpoll.
ConvertListener converts net.Listener to Listener.
CreateListener return a new Listener.
DialConnection is a default implementation of Dialer.
DialTCP acts like Dial for TCP networks.
DialUnix acts like Dial for Unix networks.
DisableGopool will remove gopool(the goroutine pool used to run OnRequest), which means that OnRequest will be run via `go OnRequest(...)`.
EpollCreate implements epoll_create1.
EpollCtl implements epoll_ctl.
EpollWait implements epoll_wait.
wrap Errno, implement xerrors.Wrapper.
GetSysFdPairs creates and returns the fds of a pair of sockets.
Initialize the pollers actively.
NewDialer only support TCP and unix socket now.
NewEventLoop .
NewFDConnection create a Connection initialed by any fd It's useful for write unit test for functions have args with the type of netpoll.Connection The typical usage like: rfd, wfd := netpoll.GetSysFdPairs() rconn, _ = netpoll.NewFDConnection(rfd) wconn, _ = netpoll.NewFDConnection(wfd).
NewIOReader convert Reader to io.Reader.
NewIOReadWriter convert ReadWriter to io.ReadWriter.
NewIOWriter convert Writer to io.Writer.
NewLinkBuffer size defines the initial capacity, but there is no readable data.
NewReader convert io.Reader to nocopy Reader.
NewReadWriter convert io.ReadWriter to nocopy ReadWriter.
NewWriter convert io.Writer to nocopy Writer.
ResolveTCPAddr returns an address of TCP end point.
ResolveUnixAddr returns an address of Unix domain socket end point.
just support ipv4.
SetLoadBalance sets the load balancing method.
SetLoggerOutput sets the logger output target.
SetNumLoops is used to set the number of pollers, generally do not need to actively set.
SetRunner set the runner function for every OnRequest/OnConnect callback Deprecated: use Configure instead.
WithIdleTimeout sets the idle timeout of connections.
WithOnConnect registers the OnConnect method to EventLoop.
WithOnDisconnect registers the OnDisconnect method to EventLoop.
WithOnPrepare registers the OnPrepare method to EventLoop.
WithReadTimeout sets the read timeout of connections.
WithWriteTimeout sets the write timeout of connections.

# Constants

BinaryInplaceThreshold marks the minimum value of the nocopy slice length, which is the threshold to use copy to minimize overhead.
No description provided by the author
Concurrent connection access error.
The connection closed when in use.
TODO: no-deadline support in future.
Dial timeout.
Same as io.EOF.
No description provided by the author
Read I/O buffer timeout, calling by Connection.Reader.
The calling function not support.
Write I/O buffer timeout, calling by Connection.Writer.
No description provided by the author
PollDetach is used to remove the FDOperator from poll.
PollR2RW is used to monitor writable for FDOperator, which is only called when the socket write buffer is full.
PollReadable is used to monitor whether the FDOperator registered by listener and connection is readable or closed.
PollRW2R is used to remove the writable monitor of FDOperator, generally used with PollR2RW.
PollWritable is used to monitor whether the FDOperator created by the dialer is writable or closed.
Random requests that connections are randomly distributed.
RoundRobin requests that connections are distributed to a Poll in a round-robin fashion.
No description provided by the author
No description provided by the author

# Variables

LinkBufferCap that can be modified marks the minimum value of each node of LinkBuffer.

# Structs

Config expose some tuning parameters to control the internal behaviors of netpoll.
FDOperator is a collection of operations on file descriptors.
Feature expose some new features maybe promoted as a default behavior but not yet.
Option .
TCPAddr represents the address of a TCP end point.
TCPConnection implements Connection.
UnixAddr represents the address of a Unix domain socket end point.
UnixConnection implements Connection.
UnsafeLinkBuffer implements ReadWriter.

# Interfaces

Conn extends net.Conn, but supports getting the conn's fd.
Connection supports reading and writing simultaneously, but does not support simultaneous reading or writing by multiple goroutines.
Dialer extends net.Dialer's API, just for interface compatibility.
A EventLoop is a network server.
Listener extends net.Listener, but supports getting the listener's fd.
Poll monitors fd(file descriptor), calls the FDOperator to perform specific actions, and shields underlying differences.
Reader is a collection of operations for nocopy reads.
ReadWriter is a combination of Reader and Writer.
Writer is a collection of operations for nocopy writes.

# Type aliases

CloseCallback will be called after the connection is closed.
No description provided by the author
LoadBalance sets the load balancing method.
OnConnect is called once connection created.
OnDisconnect is called once connection is going to be closed.
OnPrepare is used to inject custom preparation at connection initialization, which is optional but important in some scenarios.
OnRequest defines the function for handling connection.
PollEvent defines the operation of poll.Control.