poll

Documentation

Overview

Package poll supports non-blocking I/O on file descriptors with polling. This supports I/O operations that block only a goroutine, not a thread. This is used by the net and os packages. It uses a poller built into the runtime, with support from the runtime scheduler.

Index

• Variables
• func DupCloseOnExec(fd int) (int, string, error)
• func IsPollDescriptor(fd uintptr) bool
• func SendFile(dstFD *FD, src int, pos, remain int64) (int64, error)
• type DeadlineExceededError
  • func (e *DeadlineExceededError) Error() string
  • func (e *DeadlineExceededError) Temporary() bool
  • func (e *DeadlineExceededError) Timeout() bool
• type FD
  • func (fd *FD) Accept() (int, syscall.Sockaddr, string, error)
  • func (fd *FD) Close() error
  • func (fd *FD) Copy() FD
  • func (fd *FD) Dup() (int, string, error)
  • func (fd *FD) Fchdir() error
  • func (fd *FD) Fchmod(mode uint32) error
  • func (fd *FD) Fchown(uid, gid int) error
  • func (fd *FD) Fstat(s *syscall.Stat_t) error
  • func (fd *FD) Fsync() error
  • func (fd *FD) Ftruncate(size int64) error
  • func (fd *FD) GetsockoptInt(level, name int) (int, error)
  • func (fd *FD) Init(net string, pollable bool) error
  • func (fd *FD) OpenDir() (uintptr, string, error)
  • func (fd *FD) Pread(p []byte, off int64) (int, error)
  • func (fd *FD) Pwrite(p []byte, off int64) (int, error)
  • func (fd *FD) RawControl(f func(uintptr)) error
  • func (fd *FD) RawRead(f func(uintptr) bool) error
  • func (fd *FD) RawWrite(f func(uintptr) bool) error
  • func (fd *FD) Read(p []byte) (int, error)
  • func (fd *FD) ReadDir(buf []byte, cookie syscall.Dircookie) (int, error)
  • func (fd *FD) ReadDirent(buf []byte) (int, error)
  • func (fd *FD) ReadFrom(p []byte) (int, syscall.Sockaddr, error)
  • func (fd *FD) ReadFromInet4(p []byte, from *syscall.SockaddrInet4) (int, error)
  • func (fd *FD) ReadFromInet6(p []byte, from *syscall.SockaddrInet6) (int, error)
  • func (fd *FD) ReadMsg(p []byte, oob []byte, flags int) (int, int, int, syscall.Sockaddr, error)
  • func (fd *FD) ReadMsgInet4(p []byte, oob []byte, flags int, sa4 *syscall.SockaddrInet4) (int, int, int, error)
  • func (fd *FD) ReadMsgInet6(p []byte, oob []byte, flags int, sa6 *syscall.SockaddrInet6) (int, int, int, error)
  • func (fd *FD) Seek(offset int64, whence int) (int64, error)
  • func (fd *FD) SetBlocking() error
  • func (fd *FD) SetDeadline(t time.Time) error
  • func (fd *FD) SetReadDeadline(t time.Time) error
  • func (fd *FD) SetWriteDeadline(t time.Time) error
  • func (fd *FD) SetsockoptByte(level, name int, arg byte) error
  • func (fd *FD) SetsockoptIPMreq(level, name int, mreq *syscall.IPMreq) error
  • func (fd *FD) SetsockoptIPv6Mreq(level, name int, mreq *syscall.IPv6Mreq) error
  • func (fd *FD) SetsockoptInet4Addr(level, name int, arg [4]byte) error
  • func (fd *FD) SetsockoptInt(level, name, arg int) error
  • func (fd *FD) SetsockoptLinger(level, name int, l *syscall.Linger) error
  • func (fd *FD) Shutdown(how int) error
  • func (fd *FD) WaitWrite() error
  • func (fd *FD) Write(p []byte) (int, error)
  • func (fd *FD) WriteMsg(p []byte, oob []byte, sa syscall.Sockaddr) (int, int, error)
  • func (fd *FD) WriteMsgInet4(p []byte, oob []byte, sa *syscall.SockaddrInet4) (int, int, error)
  • func (fd *FD) WriteMsgInet6(p []byte, oob []byte, sa *syscall.SockaddrInet6) (int, int, error)
  • func (fd *FD) WriteOnce(p []byte) (int, error)
  • func (fd *FD) WriteTo(p []byte, sa syscall.Sockaddr) (int, error)
  • func (fd *FD) WriteToInet4(p []byte, sa *syscall.SockaddrInet4) (int, error)
  • func (fd *FD) WriteToInet6(p []byte, sa *syscall.SockaddrInet6) (int, error)
  • func (fd *FD) Writev(v *[][]byte) (int64, error)
• type SysFile

Variables

var AcceptFunc func(int) (int, syscall.Sockaddr, error) = syscall.Accept

AcceptFunc is used to hook the accept call.

var CloseFunc func(int) error = syscall.Close

CloseFunc is used to hook the close call.

var ErrDeadlineExceeded error = &DeadlineExceededError{}

ErrDeadlineExceeded is returned for an expired deadline. This is exported by the os package as os.ErrDeadlineExceeded.

var ErrFileClosing = errors.New("use of closed file")

ErrFileClosing is returned when a file descriptor is used after it has been closed.

var ErrNetClosing = errNetClosing{}

ErrNetClosing is returned when a network descriptor is used after it has been closed.

var ErrNoDeadline = errors.New("file type does not support deadline")

ErrNoDeadline is returned when a request is made to set a deadline on a file type that does not use the poller.

var ErrNotPollable = errors.New("not pollable")

ErrNotPollable is returned when the file or socket is not suitable for event notification.

var TestHookDidWritev = func(wrote int) {}

TestHookDidWritev is a hook for testing writev.

Functions

func DupCloseOnExec

func DupCloseOnExec(fd int) (int, string, error)

DupCloseOnExec dups fd and marks it close-on-exec.

func IsPollDescriptor

func IsPollDescriptor(fd uintptr) bool

IsPollDescriptor reports whether fd is the descriptor being used by the poller. This is only used for testing.

func SendFile

func SendFile(dstFD *FD, src int, pos, remain int64) (int64, error)

SendFile wraps the sendfile system call.

Types

type DeadlineExceededError

type DeadlineExceededError struct{}

DeadlineExceededError is returned for an expired deadline.

func (*DeadlineExceededError) Error

func (e *DeadlineExceededError) Error() string

Implement the net.Error interface. The string is "i/o timeout" because that is what was returned by earlier Go versions. Changing it may break programs that match on error strings.

func (*DeadlineExceededError) Temporary

func (e *DeadlineExceededError) Temporary() bool

func (*DeadlineExceededError) Timeout

func (e *DeadlineExceededError) Timeout() bool

type FD

type FD struct {

	// System file descriptor. Immutable until Close.
	Sysfd int

	// Platform dependent state of the file descriptor.
	SysFile

	// Whether this is a streaming descriptor, as opposed to a
	// packet-based descriptor like a UDP socket. Immutable.
	IsStream bool

	// Whether a zero byte read indicates EOF. This is false for a
	// message based socket connection.
	ZeroReadIsEOF bool
	// contains filtered or unexported fields
}

FD is a file descriptor. The net and os packages use this type as a field of a larger type representing a network connection or OS file.

func (*FD) Accept

func (fd *FD) Accept() (int, syscall.Sockaddr, string, error)

Accept wraps the accept network call.

func (*FD) Close

func (fd *FD) Close() error

Close closes the FD. The underlying file descriptor is closed by the destroy method when there are no remaining references.

func (*FD) Copy

func (fd *FD) Copy() FD

Copy creates a copy of the FD.

The FD instance points to the same underlying file descriptor. The file descriptor isn't closed until all FD instances that refer to it have been closed/destroyed.

func (*FD) Dup

func (fd *FD) Dup() (int, string, error)

Dup duplicates the file descriptor.

func (*FD) Fchdir

func (fd *FD) Fchdir() error

Fchdir wraps syscall.Fchdir.

func (*FD) Fchmod

func (fd *FD) Fchmod(mode uint32) error

Fchmod wraps syscall.Fchmod.

func (*FD) Fchown

func (fd *FD) Fchown(uid, gid int) error

Fchown wraps syscall.Fchown.

func (*FD) Fstat

func (fd *FD) Fstat(s *syscall.Stat_t) error

Fstat wraps syscall.Fstat

func (*FD) Fsync

func (fd *FD) Fsync() error

Fsync invokes SYS_FCNTL with SYS_FULLFSYNC because on OS X, SYS_FSYNC doesn't fully flush contents to disk. See Issue #26650 as well as the man page for fsync on OS X.

func (*FD) Ftruncate

func (fd *FD) Ftruncate(size int64) error

Ftruncate wraps syscall.Ftruncate.

func (*FD) GetsockoptInt

func (fd *FD) GetsockoptInt(level, name int) (int, error)

GetsockoptInt wraps the getsockopt network call with an int argument.

func (*FD) Init

func (fd *FD) Init(net string, pollable bool) error

Init initializes the FD. The Sysfd field should already be set. This can be called multiple times on a single FD. The net argument is a network name from the net package (e.g., "tcp"), or "file". Set pollable to true if fd should be managed by runtime netpoll.

func (*FD) OpenDir

func (fd *FD) OpenDir() (uintptr, string, error)

OpenDir returns a pointer to a DIR structure suitable for ReadDir. In case of an error, the name of the failed syscall is returned along with a syscall.Errno.

func (*FD) Pread

func (fd *FD) Pread(p []byte, off int64) (int, error)

Pread wraps the pread system call.

func (*FD) Pwrite

func (fd *FD) Pwrite(p []byte, off int64) (int, error)

Pwrite wraps the pwrite system call.

func (*FD) RawControl

func (fd *FD) RawControl(f func(uintptr)) error

RawControl invokes the user-defined function f for a non-IO operation.

func (*FD) RawRead

func (fd *FD) RawRead(f func(uintptr) bool) error

RawRead invokes the user-defined function f for a read operation.

func (*FD) RawWrite

func (fd *FD) RawWrite(f func(uintptr) bool) error

RawWrite invokes the user-defined function f for a write operation.

func (*FD) Read

func (fd *FD) Read(p []byte) (int, error)

Read implements io.Reader.

func (*FD) ReadDir

func (fd *FD) ReadDir(buf []byte, cookie syscall.Dircookie) (int, error)

ReadDir wraps syscall.ReadDir. We treat this like an ordinary system call rather than a call that tries to fill the buffer.

func (*FD) ReadDirent

func (fd *FD) ReadDirent(buf []byte) (int, error)

ReadDirent wraps syscall.ReadDirent. We treat this like an ordinary system call rather than a call that tries to fill the buffer.

func (*FD) ReadFrom

func (fd *FD) ReadFrom(p []byte) (int, syscall.Sockaddr, error)

ReadFrom wraps the recvfrom network call.

func (*FD) ReadFromInet4

func (fd *FD) ReadFromInet4(p []byte, from *syscall.SockaddrInet4) (int, error)

ReadFromInet4 wraps the recvfrom network call for IPv4.

func (*FD) ReadFromInet6

func (fd *FD) ReadFromInet6(p []byte, from *syscall.SockaddrInet6) (int, error)

ReadFromInet6 wraps the recvfrom network call for IPv6.

func (*FD) ReadMsg

func (fd *FD) ReadMsg(p []byte, oob []byte, flags int) (int, int, int, syscall.Sockaddr, error)

ReadMsg wraps the recvmsg network call.

func (*FD) ReadMsgInet4

func (fd *FD) ReadMsgInet4(p []byte, oob []byte, flags int, sa4 *syscall.SockaddrInet4) (int, int, int, error)

ReadMsgInet4 is ReadMsg, but specialized for syscall.SockaddrInet4.

func (*FD) ReadMsgInet6

func (fd *FD) ReadMsgInet6(p []byte, oob []byte, flags int, sa6 *syscall.SockaddrInet6) (int, int, int, error)

ReadMsgInet6 is ReadMsg, but specialized for syscall.SockaddrInet6.

func (*FD) Seek

func (fd *FD) Seek(offset int64, whence int) (int64, error)

Seek wraps syscall.Seek.

func (*FD) SetBlocking

func (fd *FD) SetBlocking() error

SetBlocking puts the file into blocking mode.

func (*FD) SetDeadline

func (fd *FD) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with fd.

func (*FD) SetReadDeadline

func (fd *FD) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline associated with fd.

func (*FD) SetWriteDeadline

func (fd *FD) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline associated with fd.

func (*FD) SetsockoptByte

func (fd *FD) SetsockoptByte(level, name int, arg byte) error

SetsockoptByte wraps the setsockopt network call with a byte argument.

func (*FD) SetsockoptIPMreq

func (fd *FD) SetsockoptIPMreq(level, name int, mreq *syscall.IPMreq) error

SetsockoptIPMreq wraps the setsockopt network call with an IPMreq argument.

func (*FD) SetsockoptIPv6Mreq

func (fd *FD) SetsockoptIPv6Mreq(level, name int, mreq *syscall.IPv6Mreq) error

SetsockoptIPv6Mreq wraps the setsockopt network call with an IPv6Mreq argument.

func (*FD) SetsockoptInet4Addr

func (fd *FD) SetsockoptInet4Addr(level, name int, arg [4]byte) error

SetsockoptInet4Addr wraps the setsockopt network call with an IPv4 address.

func (*FD) SetsockoptInt

func (fd *FD) SetsockoptInt(level, name, arg int) error

SetsockoptInt wraps the setsockopt network call with an int argument.

func (*FD) SetsockoptLinger

func (fd *FD) SetsockoptLinger(level, name int, l *syscall.Linger) error

SetsockoptLinger wraps the setsockopt network call with a Linger argument.

func (*FD) Shutdown

func (fd *FD) Shutdown(how int) error

Shutdown wraps syscall.Shutdown.

func (*FD) WaitWrite

func (fd *FD) WaitWrite() error

WaitWrite waits until data can be read from fd.

func (*FD) Write

func (fd *FD) Write(p []byte) (int, error)

Write implements io.Writer.

func (*FD) WriteMsg

func (fd *FD) WriteMsg(p []byte, oob []byte, sa syscall.Sockaddr) (int, int, error)

WriteMsg wraps the sendmsg network call.

func (*FD) WriteMsgInet4

func (fd *FD) WriteMsgInet4(p []byte, oob []byte, sa *syscall.SockaddrInet4) (int, int, error)

WriteMsgInet4 is WriteMsg specialized for syscall.SockaddrInet4.

func (*FD) WriteMsgInet6

func (fd *FD) WriteMsgInet6(p []byte, oob []byte, sa *syscall.SockaddrInet6) (int, int, error)

WriteMsgInet6 is WriteMsg specialized for syscall.SockaddrInet6.

func (*FD) WriteOnce

func (fd *FD) WriteOnce(p []byte) (int, error)

WriteOnce is for testing only. It makes a single write call.

func (*FD) WriteTo

func (fd *FD) WriteTo(p []byte, sa syscall.Sockaddr) (int, error)

WriteTo wraps the sendto network call.

func (*FD) WriteToInet4

func (fd *FD) WriteToInet4(p []byte, sa *syscall.SockaddrInet4) (int, error)

WriteToInet4 wraps the sendto network call for IPv4 addresses.

func (*FD) WriteToInet6

func (fd *FD) WriteToInet6(p []byte, sa *syscall.SockaddrInet6) (int, error)

WriteToInet6 wraps the sendto network call for IPv6 addresses.

func (*FD) Writev

func (fd *FD) Writev(v *[][]byte) (int64, error)

Writev wraps the writev system call.

type SysFile

type SysFile struct {
	// RefCountPtr is a pointer to the reference count of Sysfd.
	//
	// WASI preview 1 lacks a dup(2) system call. When the os and net packages
	// need to share a file/socket, instead of duplicating the underlying file
	// descriptor, we instead provide a way to copy FD instances and manage the
	// underlying file descriptor with reference counting.
	RefCountPtr *int32

	// RefCount is the reference count of Sysfd. When a copy of an FD is made,
	// it points to the reference count of the original FD instance.
	RefCount int32

	// Cache for the file type, lazily initialized when Seek is called.
	Filetype uint32

	// If the file represents a directory, this field contains the current
	// readdir position. It is reset to zero if the program calls Seek(0, 0).
	Dircookie uint64

	// Absolute path of the file, as returned by syscall.PathOpen;
	// this is used by Fchdir to emulate setting the current directory
	// to an open file descriptor.
	Path string
}