aio

Documentation

Overview

Package aio provides asynchronous I/O on host file descriptors.

Index

• func Read(q Queue, id uint64, fd int32, off int64, dst []byte)
• func Readv(q Queue, id uint64, fd int32, off int64, dst []unix.Iovec)
• func Write(q Queue, id uint64, fd int32, off int64, src []byte)
• func Writev(q Queue, id uint64, fd int32, off int64, src []unix.Iovec)
• type Completion
  • func (c Completion) Err() error
• type GoQueue
  • func NewGoQueue(cap int) *GoQueue
  • func (q *GoQueue) Add(r Request)
  • func (q *GoQueue) Cap() int
  • func (q *GoQueue) Destroy()
  • func (q *GoQueue) Wait(cs []Completion, minCompletions int) ([]Completion, error)
• type Op
• type Queue
• type Request

Functions

func Read

func Read(q Queue, id uint64, fd int32, off int64, dst []byte)

Read enqueues a read. The caller must ensure that the memory referred to by dst remains valid until the read is complete.

Preconditions: As for q.Add().

func Readv

func Readv(q Queue, id uint64, fd int32, off int64, dst []unix.Iovec)

Readv enqueues a vectored read. The caller must ensure that the struct iovec array referred to by dst, and the memory that those struct iovecs refer to, remain valid until the read is complete.

Preconditions: As for q.Add().

func Write

func Write(q Queue, id uint64, fd int32, off int64, src []byte)

Write enqueues a write. The caller must ensure that the memory referred to by src remains valid until the write is complete.

Preconditions: As for q.Add().

func Writev

func Writev(q Queue, id uint64, fd int32, off int64, src []unix.Iovec)

Writev enqueues a vectored write. The caller must ensure that the struct iovec array referred to by src, and the memory that those struct iovecs refer to, remain valid until the write is complete.

Preconditions: As for q.Add().

Types

type Completion

type Completion struct {
	ID     uint64 // copied from Request.ID in the corresponding Request
	Result int64  // number of bytes or negative errno
}

Completion provides outputs from an asynchronous I/O operation.

func (Completion) Err

func (c Completion) Err() error

Err returns an error representing the Completion. If Err returns nil, c.Result is the number of bytes completed by the operation.

type GoQueue

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

GoQueue implements Queue using a pool of worker goroutines.

func NewGoQueue

func NewGoQueue(cap int) *GoQueue

NewGoQueue returns a new GoQueue with the given capacity.

func (*GoQueue) Add

func (q *GoQueue) Add(r Request)

Add implements Queue.Add.

func (*GoQueue) Cap

func (q *GoQueue) Cap() int

Cap implements Queue.Cap.

func (*GoQueue) Destroy

func (q *GoQueue) Destroy()

Destroy implements Queue.Destroy.

func (*GoQueue) Wait

func (q *GoQueue) Wait(cs []Completion, minCompletions int) ([]Completion, error)

Wait implements Queue.Wait.

type Op

type Op uint8

Op selects an asynchronous I/O operation.

const (
	// OpRead represents a read into addresses [Buf, Buf+Len).
	OpRead Op = iota

	// OpWrite represents a write from addresses [Buf, Buf+Len).
	OpWrite

	// OpReadv represents a read, where the destination addresses are given by
	// the struct iovec array at address Buf of length Len.
	OpReadv

	// OpWritev represents a write, where the source addresses are given by the
	// struct iovec array at address Buf of length Len.
	OpWritev
)

Possible values for Request.Op.

type Queue

type Queue interface {
	// Destroy cancels all inflight operations and releases resources owned by
	// the Queue. Destroy waits for cancelation, so the Queue will not access
	// memory corresponding to inflight operations after Destroy returns.
	Destroy()

	// Cap returns the Queue's capacity, which is the maximum number of
	// concurrent operations supported by the Queue.
	Cap() int

	// Add enqueues an inflight operation.
	//
	// Note that some Queue implementations may not begin execution of new
	// Requests until the following call to Wait.
	//
	// Preconditions:
	// - The current number of inflight operations < Cap().
	Add(req Request)

	// Wait blocks until at least minCompletions inflight operations have
	// completed, then appends all completed inflight operations to cs and
	// returns the updated slice.
	//
	// If Wait returns a non-nil error, no Queue methods may be subsequently
	// called except Destroy.
	//
	// Preconditions:
	// - 0 <= minCompletions <= Cap().
	Wait(cs []Completion, minCompletions int) ([]Completion, error)
}

A Queue provides the ability to concurrently execute multiple read/write operations on host file descriptors.

Queues are not safe to use concurrently in multiple goroutines.

type Request

type Request struct {
	ID  uint64 // copied to Completion.ID in the corresponding Completion
	Op  Op
	FD  int32          // host file descriptor
	Off int64          // offset into FD
	Buf unsafe.Pointer // depends on Op
	Len int            // depends on Op
}

Request provides inputs to an asynchronous I/O operation.