Struct DescriptorEngine 

pub struct DescriptorEngine { /* private fields */ }

描述符校验引擎

提供完整的描述符校验、所有权管理和守恒等式校验。 单线程无锁设计：内部状态通过原子类型以 &self 变更 （单 Owner 持有 XskSocket，生命周期内不跨线程共享）。

Ordering 论证

本引擎由单个 XskSocket 独占持有，生命周期内不跨线程共享（单 Owner 顺序访问，无并发发布场景）。原子类型仅用于以 &self 变更内部状态， 因此全部使用 Ordering::Relaxed：不存在跨线程 happens-before 需求。 若未来引入跨线程共享（如 Arc<DescriptorEngine>），必须重审本论证。

Implementations

impl DescriptorEngine

pub fn new(max_frames: u64) -> Result<Self>

创建描述符校验引擎（默认 4096 字节帧，shift = 12，fail-closed）

参数

• max_frames - 最大帧数量（必须 ≤ 2^20，即 20-bit 帧索引域）

返回

• Ok(Self) - 引擎实例
• Err(DescriptorError::InvalidCapacity) - max_frames > 2^20， 拒绝构造：超域帧索引与 MAX_FRAME_INDEX 契约冲突

pub fn with_frame_shift(max_frames: u64, frame_shift: u32) -> Result<Self>

创建描述符校验引擎（显式帧移位，fail-closed）

参数

• max_frames - 最大帧数量（必须 ≤ 2^20，即 20-bit 帧索引域）
• frame_shift - log2(frame_size)，合法区间 11..=15 （帧大小 2048..=32768 字节）

返回

• Ok(Self) - 引擎实例
• Err(DescriptorError::InvalidFrameShift) - frame_shift 非法， 拒绝构造：防止 frame_index << frame_shift 在 debug shift-overflow panic / release 移位掩码静默错误地址
• Err(DescriptorError::InvalidCapacity) - max_frames > 2^20， 拒绝构造：20-bit frame index 域容量上限为 2^20（MAX_FRAME_INDEX + 1）， 超域帧索引会与 Descriptor::from_xdp 的越界拒绝语义冲突

pub fn frame_shift(&self) -> u32

获取帧移位（log2(frame_size)）

pub fn allocate(&self, frame_index: u32, owner: u16) -> Result<Descriptor>

分配描述符（从帧索引创建）

参数

• frame_index - 帧索引
• owner - 所有者 ID

返回

• Result<Descriptor> - 新描述符

pub fn release(&self, desc: &Descriptor) -> Result<()>

释放描述符

参数

• desc - 要释放的描述符

返回

• Result<()> - 成功或错误

pub fn rollback_allocate(&self, frame_index: u32) -> bool

回滚 allocate（清除位图 + 递减计数，不生成描述符）

用于 fill_descriptors 等“先批量 allocate 再 enqueue“场景： enqueue 失败时帧已位图置位但未入环，形成孤立帧； 通过位图为权威回滚，恢复 allocated == freed + active 守恒等式。

参数

• frame_index - 要回滚的帧索引

返回

• true - 位图存在且已清除；false - 帧索引越界或位图未置位（fail-closed 不 panic）

pub fn verify(&self, desc: &Descriptor, expected_owner: u16) -> Result<()>

校验描述符有效性

基于位图的权威校验：检查帧索引范围、活跃状态和所有权。 位图是描述符有效性的唯一权威来源，不依赖描述符字段值。

参数

• desc - 要校验的描述符
• expected_owner - 期望的所有者

返回

• Result<()> - 成功或错误

pub fn transfer_ownership( &self, desc: &Descriptor, old_owner: u16, new_owner: u16, ) -> Result<Descriptor>

事务化所有权迁移

原子性地将描述符的所有者从 old_owner 迁移到 new_owner。

参数

• desc - 描述符引用
• old_owner - 旧所有者
• new_owner - 新所有者

返回

• Result<Descriptor> - 新的描述符（已迁移所有者）

pub fn is_allocated(&self, index: u32) -> bool

查询帧是否已被引擎分配（位图是否置位）

供 Fill Ring 预填/补填路径判定「帧是否已登记」：与 allocate 的 AlreadyAllocated fail-closed 配套，避免从 0 重复登记已分配帧。

pub fn bump_generation(&self) -> Result<u64>

增加全局代际号（fail-closed：与 transfer_ownership 同域约束）

代际域为 u16（Descriptor.generation: u16）；原实现可无限增长， 与 transfer_ownership「超 u16::MAX 拒绝」语义不一致——调用方若把 返回值截断成 u16 会静默回绕。超域时返回错误而非截断。

返回

• Ok(u64) - 递增后的新代际号（≤ u16::MAX）
• Err(DescriptorError::TransactionFailed) - 代际号超出 u16 范围

pub fn conservation_stats(&self) -> (u64, u64)

获取守恒统计

pub fn verify_conservation(&self) -> bool

检查守恒等式：allocated == freed + active

Trait Implementations

impl Debug for DescriptorEngine

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

Formats the value using the given formatter.