Struct XskRing 

pub struct XskRing { /* private fields */ }

AF_XDP Ring

两种模式（枚举互斥，禁止混用）

1. 模拟模式（[RingStorage::Simulated]）：使用 Vec<XdpDesc> 作为 backing store， 索引通过 AtomicU32 模拟，适合无 root 权限的开发和测试。

2. 内核 mmap 模式（[RingStorage::Kernel]）：通过 mmap 映射内核 ring 内存， producer/consumer 索引与描述符数组均直接读写内核共享区。

Implementations

impl XskRing

pub fn new(ring_type: RingType, capacity: u32) -> Result<Self>

创建模拟模式的 Ring

参数

• ring_type - Ring 类型
• capacity - 容量（向上取整到 2 的幂，最小 16）

返回

• Result<Self> - Ring 实例

Fail-Closed

• capacity == 0：拒绝（原 max(16) 会静默掩盖调用方传 0 的错误）
• 取整后超出 MAX_SIMULATED_CAPACITY：拒绝。模拟模式的 descriptors 是真实堆分配（XdpDesc 16B × capacity），不设上限时 恶意/失控调用方可请求高达 2^31 项（32 GiB）触发 OOM abort—— vec! 分配失败走 alloc_error_handler 直接 abort，连错误都返回不了。
• 取整后超出 u32 可表示的最大 2 的幂（2^31）：拒绝。原 next_power_of_two() 在 capacity > 2^31 时 debug panic、 release 回绕为 0（mask = 0 - 1 = u32::MAX，后续索引全越界）， 此处改用 checked_next_power_of_two() 显式报错。

pub unsafe fn with_kernel_ring( ring_type: RingType, mmap_base: *mut u8, offsets: RingOffsets, ) -> Result<Self>

创建内核 mmap 模式的 Ring（接管 mmap 区域所有权，Drop 时 munmap）

参数

• ring_type - Ring 类型
• mmap_base - mmap 区域基址（必须指向有效的、已映射的内核 ring 内存）
• offsets - Ring 偏移量（由 getsockopt(XDP_MMAP_OFFSETS) 获取； len 为该 ring 的 mmap 总字节数 = desc + ring_size * sizeof(XdpDesc)）

返回

• Result<Self> - Ring 实例；偏移/长度非法时返回 RingError::InvalidOffsets（Fail-Closed）

Safety

调用者必须保证以下条件：

1. mmap_base 指向长度 ≥ offsets.len 的有效 mmap 映射区域（来自 xsk fd 的 ring mmap）。本函数成功后该区域所有权转移给 XskRing，由 Drop 执行 munmap， 调用者不得再自行 munmap。
2. offsets 中的偏移量必须与内核 ring 布局一致（通过 getsockopt 获取， 由内核保证正确性）；本函数仍会对偏移做边界校验，非法即返回错误。
3. 调用者必须保证 XskRing 仅在单 Worker 上下文中使用（单 Owner，无并发共享）， 因为内核 ring 的 producer/consumer 索引需要严格的 happens-before 关系。

pub fn available_space(&self) -> u32

获取可用空间（生产者可写入的位置数）

pub fn available_data(&self) -> u32

获取可读数据（消费者可读取的位置数）

pub fn enqueue_batch(&mut self, descriptors: &[XdpDesc]) -> Result<u32>

批量入队（生产者操作）

参数

• descriptors - 要入队的 XdpDesc 数组

返回

• Result<u32> - 实际入队数量

pub fn dequeue_batch(&mut self, max_batch: u32) -> Result<Vec<XdpDesc>>

批量出队（消费者操作）

参数

• max_batch - 最大批量大小

返回

• Result<Vec<XdpDesc>> - 描述符数组

pub fn dequeue_batch_to(&mut self, buffer: &mut [XdpDesc]) -> Result<u32>

批量出队到预分配缓冲区（零堆分配路径）

参数

• buffer - 预分配的 XdpDesc 缓冲区

返回

• Result<u32> - 实际出队数量

pub fn enqueue_batch_from(&mut self, descriptors: &[XdpDesc]) -> Result<u32>

批量入队到预分配描述符（零 Vec 分配）

参数

• descriptors - 预分配的 XdpDesc 数组切片

返回

• Result<u32> - 实际入队数量

pub fn revert_consumer(&mut self, count: u32)

回退消费者索引

count 不得超过当前消费者索引，否则索引回绕到 u32::MAX 导致后续读取未初始化数据

pub fn revert_producer(&mut self, count: u32)

回退生产者索引

count 不得超过当前生产者索引，否则索引回绕到 u32::MAX 导致后续写入越界

pub fn capacity(&self) -> u32

获取容量

pub fn ring_type(&self) -> RingType

获取 Ring 类型

pub fn producer_index(&self) -> u32

获取当前生产者索引

pub fn consumer_index(&self) -> u32

获取当前消费者索引

pub fn is_kernel_mode(&self) -> bool

是否为内核 mmap 模式

pub fn need_wakeup(&self) -> bool

检查内核是否需要唤醒（XDP_RING_NEED_WAKEUP 标志）

在内核模式下，读取内核 ring 的 flags 字段。 当 XDP_RING_NEED_WAKEUP 标志置位时，用户态须通过 syscall 唤醒内核： sendto(fd, NULL, 0, MSG_DONTWAIT, NULL, 0)。

模拟模式下始终返回 false（无需唤醒）。

Trait Implementations

impl Debug for XskRing

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Send for XskRing

impl Sync for XskRing