homa

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 21, 2024 License: ISC Imports: 9 Imported by: 0

README

go-homa

A Go Client For The Homa Transport Protocol.

Usage

For a simple example of how to use this library, see the examples directory.

Documentation

Index

Constants

View Source
const (
	// Homa's protocol number within the IP protocol space (this is not an officially allocated slot).
	IPPROTO_HOMA = 0xFD
	// Option for specifying buffer region.
	SO_HOMA_SET_BUF = 10
	// Disable the output throttling mechanism: always send all packets immediately.
	HOMA_FLAG_DONT_THROTTLE = 2
)
View Source
const (
	// Maximum bytes of payload in a Homa request or response message.
	HOMA_MAX_MESSAGE_LENGTH = 1000000
	// Number of bytes in pages used for receive buffers. Must be power of two.
	HOMA_BPAGE_SHIFT = 16
	HOMA_BPAGE_SIZE  = 1 << HOMA_BPAGE_SHIFT
	// The largest number of bpages that will be required to store an incoming message.
	HOMA_MAX_BPAGES = (HOMA_MAX_MESSAGE_LENGTH + HOMA_BPAGE_SIZE - 1) >> HOMA_BPAGE_SHIFT
)
View Source
const (
	HOMA_RECVMSG_REQUEST     = 0x01
	HOMA_RECVMSG_RESPONSE    = 0x02
	HOMA_RECVMSG_NONBLOCKING = 0x04
	HOMA_RECVMSG_VALID_FLAGS = 0x07
)

Flag bits for homa_recvmsg_args.flags (see man page for documentation).

Variables

View Source
var (
	HOMAIOCREPLY  = ioctl.IOWR(0x89, 0xe2, unsafe.Sizeof(SendmsgArgs{}))
	HOMAIOCABORT  = ioctl.IOWR(0x89, 0xe3, unsafe.Sizeof(AbortArgs{}))
	HOMAIOCFREEZE = ioctl.IO(0x89, 0xef)
)

I/O control calls on Homa sockets. These are mapped into the SIOCPROTOPRIVATE range of 0x89e0 through 0x89ef.

Functions

This section is empty.

Types

type AbortArgs

type AbortArgs struct {
	// ID of RPC to abort, or zero to abort all RPCs on socket.
	ID uint64
	// Zero means destroy and free RPCs; nonzero means complete
	// them with this error (recvmsg will return the RPCs).
	ErrorCode int32
	// Unused padding.
	Pad1 int32
	Pad2 [2]uint64
}

Structure that passes arguments and results between user space and the HOMAIOCABORT ioctl.

type BufferPool

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

func NewBufferPool

func NewBufferPool() (*BufferPool, error)

NewBufferPool allocates a new buffer pool.

func (*BufferPool) Base

func (bp *BufferPool) Base() unsafe.Pointer

Base returns the base address of the buffer pool.

func (*BufferPool) Close

func (bp *BufferPool) Close() error

Close frees the buffer pools allocated memory.

func (*BufferPool) Size

func (bp *BufferPool) Size() int

Size returns the size of the buffer pool (in bytes).

type Message

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

Message is a Homa RPC message.

func NewMessage

func NewMessage(bp *BufferPool, args RecvmsgArgs, length int64) *Message

NewMessage creates a new message from the given buffer pool and receive message arguments.

func (*Message) Close

func (m *Message) Close() error

Close releases the resources associated with the message.

func (*Message) CompletionCookie

func (m *Message) CompletionCookie() uint64

CompletionCookie returns the completion cookie for the message.

func (*Message) ID

func (m *Message) ID() uint64

ID returns the unique identifier for the message.

func (*Message) PeerAddr

func (m *Message) PeerAddr() net.Addr

PeerAddr returns the address of the peer that sent the message.

func (*Message) Read

func (m *Message) Read(p []byte) (int, error)

Read reads data from the message into p. It returns the number of bytes read into p and an error, if any. Returns io.EOF when the message is empty.

type RecvmsgArgs

type RecvmsgArgs struct {
	// Initially specifies the id of the desired RPC,
	// or 0 if any RPC is OK; returns the actual id received.
	ID uint64
	// If the incoming message is a response, this will return
	// the completion cookie specified when the request was sent.
	// For requests this will always be zero.
	CompletionCookie uint64
	// OR-ed combination of bits that control the operation.
	Flags int32
	// The address of the peer is stored here when available.
	// This field is different from the msg_name field in struct msghdr
	// in that the msg_name field isn't set after errors. This field will
	// always be set when peer information is available, which includes
	// some error cases.
	PeerAddr SockaddrInUnion
	// Number of valid entries in @bpage_offsets.
	// Passes in bpages from previous messages that can now be
	// recycled; returns bpages from the new message.
	NumBPages uint32
	// Unused padding.
	Pad1 [4]byte
	// Each entry is an offset into the buffer region for the socket pool.
	// When returned from recvmsg, the offsets indicate where fragments of
	// the new message are stored. All entries but the last refer to full
	// buffer pages (HOMA_BPAGE_SIZE bytes) and are bpage-aligned. The last
	// entry may refer to a bpage fragment and is not necessarily aligned.
	// The application now owns these bpages and must eventually return them
	// to Homa, using bpage_offsets in a future recvmsg invocation.
	BPageOffsets [HOMA_MAX_BPAGES]uint32
}

RecvmsgArgs - Provides information needed by Homa's recvmsg.

type SendmsgArgs

type SendmsgArgs struct {
	// ID of the message being sent.
	// An initial value of 0 means a new request is being sent; nonzero means the message is a reply to the given id.
	// If the message is a request, then the value is modified to hold the id of the new RPC.
	ID uint64
	// Used only for request messages; will be returned by recvmsg when the RPC completes.
	// Typically used to locate app-specific info about the RPC.
	CompletionCookie uint64
}

Provides information needed by Homa's sendmsg.

type SetBufArgs

type SetBufArgs struct {
	Start  unsafe.Pointer // Pointer to the first byte of the buffer region
	Length uint64         // Total number of bytes in the buffer
}

setsockopt argument for SO_HOMA_SET_BUF.

type SockaddrInUnion

type SockaddrInUnion [28]byte

Enough space to hold any kind of sockaddr_in or sockaddr_in6.

type Socket

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

func NewSocket

func NewSocket(listenAddr net.Addr) (*Socket, error)

func (*Socket) Abort

func (s *Socket) Abort(id uint64, errorCode int32) error

Abort terminates the execution of an RPC associated with this socket. It takes an RPC ID and an error code as arguments. If the ID is 0, it aborts all client RPCs on this socket. The error code specifies how aborted RPCs should be handled. On success, it returns nil; on failure, it returns the encountered error.

func (*Socket) Close

func (s *Socket) Close() error

Close closes the socket and releases any resources associated with it.

func (*Socket) LocalAddr

func (s *Socket) LocalAddr() net.Addr

LocalAddr returns the local network address of the socket. This is useful if the socket was bound to port 0, which causes the kernel to assign an available port number. It returns the local network address of the socket, or nil if the socket is not bound.

func (*Socket) Recv

func (s *Socket) Recv() (*Message, error)

Recv waits for an incoming RPC and returns a message containing the RPC's data. It returns a message containing the RPC's data, or an error if the operation failed.

func (*Socket) Reply

func (s *Socket) Reply(dstAddr net.Addr, id uint64, message []byte) error

Reply sends a response message for an RPC previously received with a call to recvmsg. ID is the unique identifier for the request, as returned by recvmsg when the request was received.

func (*Socket) Send

func (s *Socket) Send(dstAddr net.Addr, message []byte, completionCookie uint64) (uint64, error)

Send initiates an RPC by sending a request message to a server. It takes a message buffer, and completion cookie (a value to be returned by recvmsg when RPC completes). It returns a unique identifier for the request that can be used later to find the response for this request.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL