Struct Socket

pub struct Socket<const t: _Direction> { /* private fields */ }

A high-level interface for an AF_XDP socket.

This struct is generic over the _Direction const parameter, which determines whether the socket is for sending (_TX) or receiving (_RX).

Implementations

impl<const t: _Direction> Socket<t>

where Socket<t>: Seek_<t> + Commit_<t> + Send,

pub fn seek(&mut self) -> Result<usize, RingError>

Ensures that at least one descriptor is available for the next operation and returns the total number of available descriptors.

For a TxSocket, this may involve reclaiming completed descriptors from the Completion Ring. For an RxSocket, this checks for newly received packets.

Returns

A Result containing the total number of available descriptors, or a RingError if the operation fails.

pub fn seek_n(&mut self, count: usize) -> Result<usize, RingError>

Ensures that at least count descriptors are available for the next operation and returns the total number of available descriptors.

For a TxSocket, this may involve reclaiming completed descriptors from the Completion Ring. For an RxSocket, this checks for newly received packets.

Arguments

• count - The desired number of available descriptors.

Returns

A Result containing the total number of available descriptors, or a RingError if the operation fails.

pub fn commit(&mut self) -> Result<(), RingError>

Commits one descriptor, making it available to the kernel.

For a TxSocket, this signals to the kernel that a packet written to the corresponding UMEM frame is ready to be sent.

For an RxSocket, this returns a UMEM frame to the kernel’s Fill Ring after the application has finished processing the received packet, making the frame available for new packets.

Returns

Ok(()) on success, or a RingError on failure.

pub fn commit_n(&mut self, n: usize) -> Result<(), RingError>

Commits n descriptors, making them available to the kernel.

For a TxSocket, this signals to the kernel that n packets are ready to be sent. For an RxSocket, this returns n UMEM frames to the kernel’s Fill Ring.

Arguments

• n - The number of descriptors to commit.

Returns

Ok(()) on success, or a RingError on failure.

pub fn frame_size(&self) -> usize

Returns the size of a single frame in the UMEM.

Returns

The size of a single frame in the UMEM in bytes.

impl<const T: _Direction> Socket<T>

where Socket<T>: Commit_<T>,

Implements the kernel wakeup logic for Socket.

pub fn kick(&self) -> Result<(), Error>

Wakes up the kernel to process descriptors in the rings.

This method is used to notify the kernel that it needs to process packets, which is particularly important when the XDP_USE_NEED_WAKEUP flag is set on the socket. It checks if the XDP_RING_NEED_WAKEUP flag is set in the ring’s flags field and, if so, performs a syscall to wake up the kernel.

How it works

It performs a sendto syscall with a zero-length buffer. This syscall does not transfer any data but acts as a signal to the kernel.

Returns

Returns Ok(()) on success. On failure, it returns an io::Error, except for certain non-critical errors like EBUSY or EAGAIN. A warning is logged for ENETDOWN.

pub fn commit_and_kick(&mut self, n: usize) -> Result<(), RingError>

Commits a number of descriptors and notifies the kernel to process them.

This method first calls commit_ to commit n descriptors, and then calls kick to notify the kernel to process the descriptors. The commit_ method is used to finalize operations on descriptors and make them available to the kernel, and the kick method is used to signal to the kernel that it needs to process the descriptors.

Returns

This method returns Ok(()) on success. If commit_ fails, it returns a RingError. If kick fails, it maps the error to a RingError using RingError::Io.

impl Socket<_TX>

where Socket<_TX>: Seek_<_TX>,

pub fn peek(&mut self, len: usize) -> Result<&mut [u8], RingError>

Peeks at the next available chunk in the ring without advancing the head.

This function finds the next available descriptor using seek and returns a mutable slice into the UMEM for writing (TX) or reading (RX).

Arguments

• len - The desired length of the chunk.

Returns

A Result containing a mutable byte slice and its corresponding descriptor index.

pub fn peek_at( &mut self, index: usize, len: usize, ) -> Result<&mut [u8], RingError>

Peeks at the index-th available chunk in the ring without advancing the head.

This function finds the index-th descriptor in the range of available descriptors and returns a mutable slice into the UMEM for writing (TX).

Arguments

• index - The index in the range of available descriptors.
• len - The desired length of the chunk.

Returns

A Result containing a mutable byte slice and its corresponding descriptor index.

pub fn seek_and_peek(&mut self, len: usize) -> Result<&mut [u8], RingError>

Seeks to the next available descriptor in the ring and peeks at the descriptor without advancing the head.

This function calls seek_ with a count of 1, and then calls peek_ with a length of len. It returns a mutable slice into the UMEM for writing (TX).

Arguments

• len - The desired length of the chunk.

Returns

A Result containing a mutable byte slice and its corresponding descriptor index.

impl Socket<_RX>

where Socket<_RX>: Seek_<_RX>,

pub fn peek(&mut self) -> Result<&[u8], RingError>

Peeks at the first available chunk in the ring without advancing the head.

This function finds the first descriptor in the range of available descriptors and returns a byte slice into the UMEM for reading (RX).

Returns

A Result containing a byte slice and its corresponding descriptor index.

pub fn peek_at(&mut self, index: usize) -> Result<&[u8], RingError>

Peeks at the index-th available chunk in the ring without advancing the head.

This function finds the index-th descriptor in the range of available descriptors and returns a byte slice into the UMEM for reading (RX).

Arguments

• index - The index in the range of available descriptors.

Returns

A Result containing a byte slice and its corresponding descriptor index.

pub fn seek_and_peek(&mut self) -> Result<&[u8], RingError>

Seeks to the next available descriptor in the ring and peeks at the descriptor without advancing the head.

This function calls seek_ with a count of 1, and then calls peek_ with a length of the descriptor length. It returns a byte slice into the UMEM for reading (RX).

Returns

A Result containing a byte slice and its corresponding descriptor index.

Trait Implementations

impl<const t: _Direction> Default for Socket<t>

fn default() -> Self

Returns the “default value” for a type.

impl<const t: _Direction> PollWaitExt<t> for Socket<t>

where Socket<t>: Commit_<t>,

fn poll_wait(&self, _timeout: Option<Duration>) -> Result<(), Error>

Waits for the socket to become ready for I/O, blocking until an event occurs.

This function uses poll to wait for the socket’s file descriptor to become ready. For a TxSocket, it waits for POLLOUT (writable). For an RxSocket, it waits for POLLIN (readable).

Arguments

• _timeout - An optional timeout. If None, it blocks indefinitely.

Returns

An io::Result indicating success or failure.

impl SendExt for Socket<_TX>

where Socket<_TX>: Seek_<_TX> + Commit_<_TX> + PollWaitExt<_TX>,

An implementation block for the transmit socket (TxSocket) that provides high-level sending methods.

fn send(&mut self, data: &[u8], header: Option<&[u8]>) -> Result<(), RingError>

Sends a packet in a non-blocking manner.

This method copies the provided data into a UMEM frame that has been previously acquired via a call to seek or seek_n, and then submits it to the kernel for transmission.

Before calling this function, you must ensure that a frame is available by calling seek or seek_n.

Arguments

• data - A byte slice containing the packet payload.
• header - An optional byte slice for the packet header. If provided, it is prepended to the data.

Returns

A Result indicating success or a RingError on failure.

Errors

Returns RingError::InvalidLength if data.len() + header.len() exceeds the UMEM frame size. Returns RingError::InvalidIndex if seek has not been called to make a frame available.

fn send_blocking( &mut self, data: &[u8], header: Option<&[u8]>, ) -> Result<(), RingError>

Sends a packet and blocks until the kernel has processed the send.

This method first calls send to queue the packet and then blocks, waiting for a kernel notification that the send is complete.

Before calling this function, you must ensure that a frame is available by calling seek or seek_n.

Arguments

• data - A byte slice containing the packet payload.
• header - An optional byte slice for the packet header.

Returns

A Result indicating success or a RingError on failure.

Errors

In addition to the errors from send, this function can return RingError::Io if the underlying poll_wait fails.

impl<const t: _Direction> Send for Socket<t>