Struct XskSocket 

pub struct XskSocket { /* private fields */ }

AF_XDP Socket

封装单个 AF_XDP Socket 的完整生命周期管理。 单 Owner 设计：每个 Socket 由一个 Worker 独占。

Implementations

impl XskSocket

pub fn new(config: XskConfig) -> Result<Self>

创建 AF_XDP Socket（模拟模式，显式选择）

四环使用用户态 Vec<XdpDesc> backing store，不触碰任何内核 AF_XDP 资源， 适合无 root / 无 XDP 内核支持环境下的开发与测试。

真实内核模式请显式使用 XskSocket::new_real（或手动串联 create_socket → configure → bind）。本类型绝不静默降级： 模式在构造时选定，bind 失败一律返回错误（Fail-Closed）。

pub fn new_real(config: XskConfig, umem: Arc<UmemManager>) -> Result<Self>

创建真实内核模式 AF_XDP Socket（显式选择，Fail-Closed）

完整执行真实系统调用链：

1. socket(AF_XDP, SOCK_RAW, 0)
2. setsockopt(SO_RCVBUF/SO_SNDBUF)
3. bind()：XDP_UMEM_REG 注册 → 四环大小 → getsockopt(XDP_MMAP_OFFSETS) → 四环 mmap → bind(sockaddr_xdp) → Fill Ring 预填

任何一步失败立即返回错误（WSL2 等不支持环境下返回明确错误）， 绝不回退到模拟模式；模拟模式请显式使用 XskSocket::new。

参数

• config - Socket 配置（ifindex/queue_id/四环大小/帧大小等）
• umem - 已完成 create()（mmap）的 UMEM 管理器

pub fn create_socket(&mut self) -> Result<()>

创建 Socket（系统调用）

pub fn configure(&mut self) -> Result<()>

配置 Socket 选项

pub fn bind(&mut self, umem: Arc<UmemManager>) -> Result<()>

绑定到网卡队列（真实内核注册，Fail-Closed）

完整 AF_XDP 绑定序列（与 libbpf xsk_socket__create 顺序一致）：

1. setsockopt(XDP_UMEM_REG) 注册 UMEM 内存区
2. setsockopt(XDP_UMEM_FILL_RING/COMPLETION_RING/RX_RING/TX_RING) 配置四环大小
3. getsockopt(XDP_MMAP_OFFSETS) 获取四环内核布局偏移
4. mmap 四环（XDP_PGOFF_RX_RING / XDP_PGOFF_TX_RING / XDP_UMEM_PGOFF_FILL_RING / XDP_UMEM_PGOFF_COMPLETION_RING）， 四环切换为内核 mmap 模式（任一失败，已映射区域由 RingMmapGuard 回收）
5. bind(sockaddr_xdp) 绑定到 ifindex+queue_id
6. Fill Ring 预填帧地址，XDP_RING_NEED_WAKEUP 置位时 sendto(MSG_DONTWAIT) 唤醒内核

WSL2 等不支持环境下任一步骤失败即返回明确错误，绝不静默降级为模拟模式。

pub fn prefill_fill_ring(&mut self) -> Result<u32>

Fill Ring 预填：将 UMEM 前 N 个帧地址写入 Fill Ring

N = min(fill_ring 容量, UMEM 帧数)。每个帧同时在描述符引擎中登记 （位图置位），保证守恒等式成立。预填后若内核 XDP_RING_NEED_WAKEUP 置位，通过 sendto(fd, NULL, 0, MSG_DONTWAIT, NULL, 0) 唤醒内核轮询。

返回

• Result<u32> - 实际预填的帧数

pub fn is_kernel_mode(&self) -> bool

是否为内核 mmap 模式（bind 成功后四环已切换为内核共享映射）

pub fn close(&mut self) -> Result<()>

关闭 Socket

pub fn fd(&self) -> Option<i32>

获取 Socket FD

pub fn state(&self) -> XskState

获取状态

pub fn is_active(&self) -> bool

是否活跃

pub fn fill_ring(&self) -> &XskRing

获取 Fill Ring 引用

pub fn fill_ring_mut(&mut self) -> &mut XskRing

获取 Fill Ring 可变引用

pub fn rx_ring(&self) -> &XskRing

获取 RX Ring 引用

pub fn rx_ring_mut(&mut self) -> &mut XskRing

获取 RX Ring 可变引用

pub fn tx_ring(&self) -> &XskRing

获取 TX Ring 引用

pub fn tx_ring_mut(&mut self) -> &mut XskRing

获取 TX Ring 可变引用

pub fn completion_ring(&self) -> &XskRing

获取 Completion Ring 引用

pub fn completion_ring_mut(&mut self) -> &mut XskRing

获取 Completion Ring 可变引用

pub fn descriptor_engine(&self) -> &DescriptorEngine

获取描述符引擎引用

pub fn fill_descriptors(&mut self, count: u32) -> Result<u32>

批量填充 Fill Ring

向 Fill Ring 注入可用的 XdpDesc，供内核接收数据包。

参数

• count - 填充数量

返回

• Result<u32> - 实际填充数量

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

接收数据包（从 RX Ring）

参数

• max_batch - 最大批量

返回

• Result<Vec<Descriptor>> - 接收到的描述符列表

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

接收数据包到预分配缓冲区（零堆分配路径）

参数

• buffer - 预分配的 Descriptor 缓冲区

返回

• Result<u32> - 实际接收数量

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

发送数据包（到 TX Ring）

参数

• descriptors - 要发送的描述符列表

返回

• Result<u32> - 实际发送数量

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

批量发送（从预分配缓冲区）

参数

• descriptors - 预分配的 XdpDesc 数组

返回

• Result<u32> - 实际发送数量

pub fn notify_tx(&self) -> Result<()>

唤醒内核处理 TX Ring（sendto 系统调用）

当 XDP_RING_NEED_WAKEUP 标志置位时，通过 sendto(fd, NULL, 0, MSG_DONTWAIT, NULL, 0) 通知内核从 TX Ring 消费描述符并发送数据包。

模拟模式下为空操作（无需唤醒）。

pub fn notify_fill(&self) -> Result<()>

唤醒内核处理 Fill Ring（sendto 系统调用）

当 XDP_RING_NEED_WAKEUP 标志置位时，通过 sendto(fd, NULL, 0, MSG_DONTWAIT, NULL, 0) 通知内核从 Fill Ring 获取空描述符并接收数据包。 （本实现四环齐备，xsk_sendmsg 路径可正常进入内核唤醒逻辑。）

模拟模式下为空操作（无 fd，无需唤醒）。

pub fn recycle_completed(&mut self, max_batch: u32) -> Result<u32>

回收发送完成的描述符（从 Completion Ring）

参数

• max_batch - 最大批量

返回

• Result<u32> - 回收数量

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

批量接收并回收（零拷贝路径）

参数

• max_batch - 最大批量

返回

• Result<Vec<Descriptor>> - 接收到的描述符

pub fn umem(&self) -> Option<&Arc<UmemManager>>

获取 UMEM 引用

pub fn get_fd(&self) -> Result<i32>

返回底层 AF_XDP socket 文件描述符。

• socket 已创建且未关闭：Ok(fd)，fd ≥ 0
• 尚未调用 create_socket() 或已关闭：Err(XskError::NotBound)

该 fd 可用于 poll(2)/select(2)/epoll(2) 等待 RX 队列唤醒， 或用于 SO_RCVBUF / SO_SNDBUF 调优。调用方不应 close 该 fd。

pub fn queue_id(&self) -> u32

队列 ID（构造配置原值；XSKMAP 注册 queue_id → xsk_fd 的 map key）

Trait Implementations

impl Debug for XskSocket

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

Formats the value using the given formatter.

impl Drop for XskSocket

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.