queue

Documentation

Overview

Package queue provides the implementation of transmit and receive queues based on shared memory ring buffers.

Index

• Constants
• func EncodeRxCompletion(b []byte, size, reserved uint32)
• func EncodeRxCompletionBuffer(b []byte, i int, rxb RxBuffer)
• func EncodeTxCompletion(b []byte, id uint64)
• func RxCompletionSize(count int) uint64
• type Rx
  • func (r *Rx) Bytes() (tx, rx []byte)
  • func (r *Rx) Dequeue(bufs []RxBuffer) ([]RxBuffer, uint32)
  • func (r *Rx) DisableNotification()
  • func (r *Rx) EnableNotification()
  • func (r *Rx) Init(tx, rx []byte, sharedEventFDState *uint32)
  • func (r *Rx) PostBuffers(buffers []RxBuffer) bool
  • func (r *Rx) PostedBuffersLimit() uint64
• type RxBuffer
  • func DecodeRxBufferHeader(b []byte) RxBuffer
• type Tx
  • func (t *Tx) Bytes() (tx, rx []byte)
  • func (t *Tx) CompletedPacket() (id uint64, ok bool)
  • func (t *Tx) Enqueue(id uint64, totalDataLen, bufferCount uint32, buffer *TxBuffer) bool
  • func (t *Tx) Init(tx, rx []byte, sharedEventFDState *uint32)
  • func (t *Tx) NotificationsEnabled() bool
• type TxBuffer
  • func DecodeTxBufferHeader(b []byte, i int) TxBuffer
• type TxPacketInfo
  • func DecodeTxPacketHeader(b []byte) TxPacketInfo

Constants

const (

	// The following are the allowed states of the shared data area.
	// EventFDUinitialized is the value stored at the start of the shared data
	// region when it hasn't been initialized.
	EventFDUninitialized = 0
	// EventFDDisabled is the value stored at the start of the shared data region
	// when notifications using eventFD has been disabled.
	EventFDDisabled = 1
	// EventFDEnabled is the value stored at the start of the shared data region
	// when eventFD should be notified as the peer might be blocked waiting on
	// notifications.
	EventFDEnabled = 2
)

Functions

func EncodeRxCompletion

func EncodeRxCompletion(b []byte, size, reserved uint32)

EncodeRxCompletion encodes an rx completion header.

func EncodeRxCompletionBuffer

func EncodeRxCompletionBuffer(b []byte, i int, rxb RxBuffer)

EncodeRxCompletionBuffer encodes the i-th rx completion buffer header.

func EncodeTxCompletion

func EncodeTxCompletion(b []byte, id uint64)

EncodeTxCompletion encodes a tx completion header.

func RxCompletionSize

func RxCompletionSize(count int) uint64

RxCompletionSize returns the number of bytes needed to encode an rx completion containing "count" buffers.

Types

type Rx

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

Rx is a receive queue. It is implemented with one tx and one rx pipe: the tx pipe is used to "post" buffers, while the rx pipe is used to receive packets whose contents have been written to previously posted buffers.

This struct is thread-compatible.

func (*Rx) Bytes

func (r *Rx) Bytes() (tx, rx []byte)

Bytes returns the byte slices on which the queue operates.

func (*Rx) Dequeue

func (r *Rx) Dequeue(bufs []RxBuffer) ([]RxBuffer, uint32)

Dequeue receives buffers that have been previously posted by PostBuffers() and that have been filled by the peer and posted back.

This is similar to append() in that new buffers are appended to "bufs", with reallocation only if "bufs" doesn't have enough capacity.

func (*Rx) DisableNotification

func (r *Rx) DisableNotification()

DisableNotification updates the shared state such that the peer will not notify the eventfd.

func (*Rx) EnableNotification

func (r *Rx) EnableNotification()

EnableNotification updates the shared state such that the peer will notify the eventfd when there are packets to be dequeued.

func (*Rx) Init

func (r *Rx) Init(tx, rx []byte, sharedEventFDState *uint32)

Init initializes the receive queue with the given pipes, and shared state pointer -- the latter is used to enable/disable eventfd notifications.

func (*Rx) PostBuffers

func (r *Rx) PostBuffers(buffers []RxBuffer) bool

PostBuffers makes the given buffers available for receiving data from the peer. Once they are posted, the peer is free to write to them and will eventually post them back for consumption.

func (*Rx) PostedBuffersLimit

func (r *Rx) PostedBuffersLimit() uint64

PostedBuffersLimit returns the maximum number of buffers that can be posted before the tx queue fills up.

type RxBuffer

type RxBuffer struct {
	Offset   uint64
	Size     uint32
	ID       uint64
	UserData uint64
}

RxBuffer is the descriptor of a receive buffer.

func DecodeRxBufferHeader

func DecodeRxBufferHeader(b []byte) RxBuffer

DecodeRxBufferHeader decodes the header of a buffer posted on an rx queue.

type Tx

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

Tx is a transmit queue. It is implemented with one tx and one rx pipe: the tx pipe is used to request the transmission of packets, while the rx pipe is used to receive which transmissions have completed.

This struct is thread-compatible.

func (*Tx) Bytes

func (t *Tx) Bytes() (tx, rx []byte)

Bytes returns the byte slices on which the queue operates.

func (*Tx) CompletedPacket

func (t *Tx) CompletedPacket() (id uint64, ok bool)

CompletedPacket returns the id of the last completed transmission. The returned id, if any, refers to a value passed on a previous call to Enqueue().

func (*Tx) Enqueue

func (t *Tx) Enqueue(id uint64, totalDataLen, bufferCount uint32, buffer *TxBuffer) bool

Enqueue queues the given linked list of buffers for transmission as one packet. While it is queued, the caller must not modify them.

func (*Tx) Init

func (t *Tx) Init(tx, rx []byte, sharedEventFDState *uint32)

Init initializes the transmit queue with the given pipes.

func (*Tx) NotificationsEnabled

func (t *Tx) NotificationsEnabled() bool

NotificationsEnabled returns true if eventFD should be used to notify the peer of events (eg. packet transmit etc).

type TxBuffer

type TxBuffer struct {
	Next   *TxBuffer
	Offset uint64
	Size   uint32
}

TxBuffer is the descriptor of a transmit buffer.

func DecodeTxBufferHeader

func DecodeTxBufferHeader(b []byte, i int) TxBuffer

DecodeTxBufferHeader decodes the header of the i-th buffer of a packet sent over a tx queue.

type TxPacketInfo

type TxPacketInfo struct {
	ID          uint64
	Size        uint32
	Reserved    uint32
	BufferCount int
}

TxPacketInfo holds information about a packet sent on a tx queue.

func DecodeTxPacketHeader

func DecodeTxPacketHeader(b []byte) TxPacketInfo

DecodeTxPacketHeader decodes the header of a packet sent over a tx queue.