Categorygithub.com/machworklab/netpoll
modulepackage
0.0.1
Repository: https://github.com/machworklab/netpoll.git
Documentation: pkg.go.dev

# README

netpoll

see https://pkg.go.dev/github.com/mailru/easygo/netpoll for details

Overview 

Package netpoll provides a portable interface for network I/O event notification facility.

Its API is intended for monitoring multiple file descriptors to see if I/O is possible on any of them. It supports edge-triggered and level-triggered interfaces.

To get more info you could look at operating system API documentation of particular netpoll implementations:

  • epoll on linux;
  • kqueue on bsd;

The Handle function creates netpoll.Desc for further use in Poller's methods:

desc, err := netpoll.Handle(conn, netpoll.EventRead | netpoll.EventEdgeTriggered)
if err != nil {
	// handle error
}

The Poller describes os-dependent network poller:

poller, err := netpoll.New(nil)
if err != nil {
	// handle error
}

// Get netpoll descriptor with EventRead|EventEdgeTriggered.
desc := netpoll.Must(netpoll.HandleRead(conn))

poller.Start(desc, func(ev netpoll.Event) {
	if ev&netpoll.EventReadHup != 0 {
		poller.Stop(desc)
		conn.Close()
		return
	}

	_, err := ioutil.ReadAll(conn)
	if err != nil {
		// handle error
	}
})

Currently, Poller is implemented only for Linux.

# Functions

EpollCreate creates new epoll instance.
Handle creates new Desc with given conn and event.
HandleListener returns descriptor for a net.Listener.
HandleRead creates read descriptor for further use in Poller methods.
HandleReadOnce creates read descriptor for further use in Poller methods.
HandleReadWrite creates read and write descriptor for further use in Poller methods.
HandleWrite creates write descriptor for further use in Poller methods.
HandleWriteOnce creates write descriptor for further use in Poller methods.
Must is a helper that wraps a call to a function returning (*Desc, error).
New creates new epoll-based Poller instance with given config.
NewDesc creates descriptor from custom fd.

# Constants

EpollEvents that are mapped to epoll_event.events possible values.
EpollEvents that are mapped to epoll_event.events possible values.
EpollEvents that are mapped to epoll_event.events possible values.
EpollEvents that are mapped to epoll_event.events possible values.
EpollEvents that are mapped to epoll_event.events possible values.
EpollEvents that are mapped to epoll_event.events possible values.
EpollEvents that are mapped to epoll_event.events possible values.
EpollEvents that are mapped to epoll_event.events possible values.
Event values that configure the Poller's behavior.
Event values that could be passed to CallbackFn as additional information event.
EventHup is indicates that some side of i/o operations (receive, send or both) is closed.
Event values that configure the Poller's behavior.
EventPollerClosed is a special Event value the receipt of which means that the Poller instance is closed.
Event values that denote the type of events that caller want to receive.
Event values that could be passed to CallbackFn as additional information event.
Event values that denote the type of events that caller want to receive.
Event values that could be passed to CallbackFn as additional information event.

# Variables

ErrClosed is returned by Poller methods to indicate that instance is closed and operation could not be processed.
ErrNotFiler is returned by Handle* functions to indicate that given net.Conn does not provide access to its file descriptor.
ErrNotRegistered is returned by Poller Stop() and Resume() methods to indicate that connection with the same underlying file descriptor was not registered before within the poller instance.
ErrRegistered is returned by Poller Start() method to indicate that connection with the same underlying file descriptor was already registered within the poller instance.

# Structs

Config contains options for Poller configuration.
Desc is a network connection within netpoll descriptor.
Epoll represents single epoll instance.
EpollConfig contains options for Epoll instance configuration.

# Interfaces

Poller describes an object that implements logic of polling connections for i/o events such as availability of read() or write() operations.

# Type aliases

CallbackFn is a function that will be called on kernel i/o event notification.
EpollEvent represents epoll events configuration bit mask.
Event represents netpoll configuration bit mask.