Documentation
¶
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.
Index ¶
Constants ¶
const ( EPOLLIN EpollEvent = unix.EPOLLIN EPOLLOUT = unix.EPOLLOUT EPOLLRDHUP = unix.EPOLLRDHUP EPOLLPRI = unix.EPOLLPRI EPOLLERR = unix.EPOLLERR EPOLLHUP = unix.EPOLLHUP EPOLLET = unix.EPOLLET EPOLLONESHOT = unix.EPOLLONESHOT // EPOLLCLOSED is a special EpollEvent value the receipt of which means // that the epoll instance is closed. EPOLLCLOSED = 0x20 )
EpollEvents that are mapped to epoll_event.events possible values.
const ( EventReadHup Event = 0x10 EventHup = 0x20 EventErr = 0x40 // EventClosed is a special Event value the receipt of which means that the // Poller instance is closed. EventClosed = 0x80 )
Event values that could be passed to CallbackFn as additional information event.
Variables ¶
var ( // ErrNotFiler is returned by Handle* functions to indicate that given // net.Conn does not provide access to its file descriptor. ErrNotFiler = fmt.Errorf("could not get file descriptor") // ErrClosed is returned by Poller methods to indicate that instance is // closed and operation could not be processed. ErrClosed = fmt.Errorf("poller instance is closed") // ErrRegistered is returned by Poller Start() method to indicate that // connection with the same underlying file descriptor is already // registered inside instance. ErrRegistered = fmt.Errorf("file descriptor is already registered in poller instance") )
Functions ¶
This section is empty.
Types ¶
type CallbackFn ¶
type CallbackFn func(Event)
CallbackFn is a function that will be called on kernel i/o event notification.
type Config ¶
type Config struct {
// OnWaitError will be called from goroutine, waiting for events.
OnWaitError func(error)
}
Config contains options for Poller configuration.
type Desc ¶
type Desc struct {
// contains filtered or unexported fields
}
Desc is a network connection within netpoll descriptor. It's methods are not goroutine safe.
func Handle ¶
Handle creates new Desc with given conn and event. Returned descriptor could be used as argument to Start(), Resume() and Stop() methods of some Poller implementation.
func HandleRead ¶
HandleRead creates read descriptor for further use in Poller methods. It is the same as Handle(conn, EventRead|EventEdgeTriggered).
func HandleReadWrite ¶
HandleReadWrite creates read and write descriptor for further use in Poller methods. It is the same as Handle(conn, EventRead|EventWrite|EventEdgeTriggered).
func HandleWrite ¶
HandleWrite creates write descriptor for further use in Poller methods. It is the same as Handle(conn, EventWrite).
type Epoll ¶
type Epoll struct {
// contains filtered or unexported fields
}
Epoll represents single epoll instance.
func EpollCreate ¶
func EpollCreate(c *EpollConfig) (*Epoll, error)
EpollCreate creates new epoll instance. It starts the wait loop in separate gorotuine.
func (*Epoll) Add ¶
func (ep *Epoll) Add(fd int, events EpollEvent, cb func(EpollEvent)) (err error)
Add adds fd to epoll set with given events. Callback will be called on each received event from epoll. Note that EPOLLCLOSED is triggered for every cb when epoll closed.
type EpollConfig ¶
type EpollConfig struct {
// OnWaitError will be called from goroutine, waiting for events.
OnWaitError func(error)
}
EpollConfig contains options for Epoll instance configuration.
type EpollEvent ¶
type EpollEvent uint32
EpollEvent represents epoll events configuration bit mask.
func (EpollEvent) String ¶
func (evt EpollEvent) String() (str string)
String returns a string representation of EpollEvent.
type Event ¶
type Event uint8
Event represents netpoll configuration bit mask.
const ( EventRead Event = 0x1 EventWrite = 0x2 )
Event values that denote the type of events that caller want to receive.
const ( EventOneShot Event = 0x4 EventEdgeTriggered = 0x8 )
Event values that configure the Poller's behavior.
type Poller ¶
type Poller interface {
// Start adds desc to the observation list.
//
// Note that if desc was configured with OneShot event, then poller will
// remove it from its observation list. If you will be interested in
// receiving events after the callback, call Resume(desc).
//
// Note that Resume() call directly inside desc's callback could cause
// deadlock.
//
// Note that multiple calls with same desc will produce unexpected
// behavior.
Start(*Desc, CallbackFn) error
// Stop removes desc from the observation list.
//
// Note that it does not call desc.Close().
Stop(*Desc) error
// Resume enables observation of desc.
//
// It is useful when desc was configured with EventOneShot.
// It should be called only after Start().
//
// Note that if there no need to observe desc anymore, you should call
// Stop() to prevent memory leaks.
Resume(*Desc) error
}
Poller describes an object that implements logic of polling connections for i/o events such as availability of read() or write() operations.
Source Files