package netpoll

import "github.com/mailru/easygo/netpoll"

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 (h *Desc) Close() error
• type Epoll
• func EpollCreate(c *EpollConfig) (*Epoll, error)
• func (ep *Epoll) Add(fd int, events EpollEvent, cb func(EpollEvent)) (err error)
• func (ep *Epoll) Close() (err error)
• func (ep *Epoll) Del(fd int) (err error)
• func (ep *Epoll) Mod(fd int, events EpollEvent) (err error)
• type EpollConfig
• type EpollEvent
• func (evt EpollEvent) String() (str string)
• type Event
• func (ev Event) String() (str string)
• type Poller
• func New(c *Config) (Poller, error)

Package Files ¶

epoll.go handle.go handle_unix.go netpoll.go netpoll_epoll.go util.go

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")
)

type CallbackFn ¶ Uses

type CallbackFn func(Event)

CallbackFn is a function that will be called on kernel i/o event notification.

type Config ¶ Uses

type Config struct {
    // OnWaitError will be called from goroutine, waiting for events.
    OnWaitError func(error)
}

Config contains options for Poller configuration.

type Desc ¶ Uses

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 ¶ Uses

func Handle(conn net.Conn, event Event) (*Desc, error)

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 ¶ Uses

func HandleListener(ln net.Listener, event Event) (*Desc, error)

HandleListener returns descriptor for a net.Listener.

func HandleRead ¶ Uses

func HandleRead(conn net.Conn) (*Desc, error)

HandleRead creates read descriptor for further use in Poller methods. It is the same as Handle(conn, EventRead|EventEdgeTriggered).

func HandleReadOnce ¶ Uses

func HandleReadOnce(conn net.Conn) (*Desc, error)

HandleReadOnce creates read descriptor for further use in Poller methods. It is the same as Handle(conn, EventRead|EventOneShot).

func HandleReadWrite ¶ Uses

func HandleReadWrite(conn net.Conn) (*Desc, error)

HandleReadWrite creates read and write descriptor for further use in Poller methods. It is the same as Handle(conn, EventRead|EventWrite|EventEdgeTriggered).

func HandleWrite ¶ Uses

func HandleWrite(conn net.Conn) (*Desc, error)

HandleWrite creates write descriptor for further use in Poller methods. It is the same as Handle(conn, EventWrite|EventEdgeTriggered).

func HandleWriteOnce ¶ Uses

func HandleWriteOnce(conn net.Conn) (*Desc, error)

HandleWriteOnce creates write descriptor for further use in Poller methods. It is the same as Handle(conn, EventWrite|EventOneShot).

func Must ¶ Uses

func Must(desc *Desc, err error) *Desc

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 NewDesc ¶ Uses

func NewDesc(fd uintptr, ev Event) *Desc

NewDesc creates descriptor from custom fd.

func (*Desc) Close ¶ Uses

func (h *Desc) Close() error

Close closes underlying file.

type Epoll ¶ Uses

type Epoll struct {
    // contains filtered or unexported fields
}

Epoll represents single epoll instance.

func EpollCreate ¶ Uses

func EpollCreate(c *EpollConfig) (*Epoll, error)

EpollCreate creates new epoll instance. It starts the wait loop in separate goroutine.

func (*Epoll) Add ¶ Uses

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.

func (*Epoll) Close ¶ Uses

func (ep *Epoll) Close() (err error)

Close stops wait loop and closes all underlying resources.

func (*Epoll) Del ¶ Uses

func (ep *Epoll) Del(fd int) (err error)

Del removes fd from epoll set.

func (*Epoll) Mod ¶ Uses

func (ep *Epoll) Mod(fd int, events EpollEvent) (err error)

Mod sets to listen events on fd.

type EpollConfig ¶ Uses

type EpollConfig struct {
    // OnWaitError will be called from goroutine, waiting for events.
    OnWaitError func(error)
}

EpollConfig contains options for Epoll instance configuration.

type EpollEvent ¶ Uses

type EpollEvent uint32

EpollEvent represents epoll events configuration bit mask.

func (EpollEvent) String ¶ Uses

func (evt EpollEvent) String() (str string)

String returns a string representation of EpollEvent.

type Event ¶ Uses

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.

func (Event) String ¶ Uses

func (ev Event) String() (str string)

String returns a string representation of Event.

type Poller ¶ Uses

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.

func New ¶ Uses

func New(c *Config) (Poller, error)

New creates new epoll-based Poller instance with given config.