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
- Variables
- type CallbackFn
- type Config
- type Desc
- func Handle(conn net.Conn, event Event) (*Desc, error)
- func HandleListener(ln net.Listener, event Event) (*Desc, error)
- func HandleRead(conn net.Conn) (*Desc, error)
- func HandleReadOnce(conn net.Conn) (*Desc, error)
- func HandleReadWrite(conn net.Conn) (*Desc, error)
- func HandleWrite(conn net.Conn) (*Desc, error)
- func HandleWriteOnce(conn net.Conn) (*Desc, error)
- func Must(desc *Desc, err error) *Desc
- func NewDesc(fd uintptr, ev Event) *Desc
- func NewDescFile(file *os.File, ev Event) *Desc
- type Epoll
- type EpollConfig
- type EpollEvent
- type Event
- type Poller
Constants ¶
const ( EPOLLIN = unix.EPOLLIN EPOLLOUT = unix.EPOLLOUT EPOLLRDHUP = unix.EPOLLRDHUP EPOLLPRI = unix.EPOLLPRI EPOLLERR = unix.EPOLLERR EPOLLHUP = unix.EPOLLHUP EPOLLET = unix.EPOLLET EPOLLONESHOT = unix.EPOLLONESHOT )
EpollEvents that are mapped to epoll_event.events possible values.
const ( // EventHup is indicates that some side of i/o operations (receive, send or // both) is closed. // Usually (depending on operating system and its version) the EventReadHup // or EventWriteHup are also set int Event value. EventHup Event = 0x10 EventReadHup = 0x20 EventWriteHup = 0x40 EventErr = 0x80 // EventPollerClosed is a special Event value the receipt of which means that the // Poller instance is closed. EventPollerClosed = 0x8000 )
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 was already // registered within the poller instance. ErrRegistered = fmt.Errorf("file descriptor is already registered in poller instance") // 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. ErrNotRegistered = fmt.Errorf("file descriptor was not registered before 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 HandleListener ¶
HandleListener returns descriptor for a net.Listener.
func HandleRead ¶
HandleRead creates read descriptor for further use in Poller methods. It is the same as Handle(conn, EventRead|EventEdgeTriggered).
func HandleReadOnce ¶
HandleReadOnce creates read descriptor for further use in Poller methods. It is the same as Handle(conn, EventRead|EventOneShot).
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|EventEdgeTriggered).
func HandleWriteOnce ¶
HandleWriteOnce creates write descriptor for further use in Poller methods. It is the same as Handle(conn, EventWrite|EventOneShot).
func Must ¶
Must is a helper that wraps a call to a function returning (*Desc, error). It panics if the error is non-nil and returns desc if not. It is intended for use in short Desc initializations.
func NewDescFile ¶ added in v1.0.0
NewDescFile creates descriptor from os.File.
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 goroutine.
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 uint16
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.