Struct FramePool

Source

pub struct FramePool { /* private fields */ }

Expand description

Frame 池（极致优化版）

§核心设计

Free-List 栈式分配器：使用 Vec<u32> 作为 LIFO 栈，O(1) 分配/回收
连续内存存储：Vec<FrameInfo> 连续存储，缓存行友好
单线程持有：无锁设计，每个 Worker 独占一个 FramePool
预分配固定容量：初始化时一次性分配所有帧，运行期禁止扩容

§性能特征

分配：O(1)，仅一次 Vec push/pop
回收：O(1)，仅一次 Vec push
守恒校验：O(n)，但仅在调试/检查时调用
热路径零堆分配、零锁、零系统调用

Implementations§

Source §

impl FramePool

Source

pub fn try_new( name: impl Into<String>, capacity: u32, frame_size: u32, ) -> Result<FramePool, CoreError>

创建新的 Frame 池（fail-closed 版本）

初始化时一次性分配所有数据结构，运行期禁止扩容。

§Arguments

name - 池名称
capacity - 总容量（帧数）
frame_size - 每个 Frame 的大小（字节）

§Returns

Ok(FramePool) - 新的 FramePool 实例

§Errors

frame_size == 0 或 capacity == 0 → CoreError::InvalidConfig
capacity * frame_size 地址空间溢出 u64 → CoreError::ArithmeticOverflow

Source

pub fn new(name: impl Into<String>, capacity: u32, frame_size: u32) -> FramePool

创建新的 Frame 池（兼容版本，禁止 panic）

参数非法（frame_size == 0 / capacity == 0 / 地址空间溢出）时不 panic，回退到最小合法配置（capacity=1, frame_size=1），回退前以 tracing::error! 记录完整原因（池名、参数与底层错误），避免静默降级难以排查。

推荐使用 FramePool::try_new：显式返回错误、可在调用方精确处置；本构造函数仅为不便于传播错误的兼容调用方保留。

§Arguments

name - 池名称
capacity - 总容量（帧数）
frame_size - 每个 Frame 的大小（字节）

§Returns

新的 FramePool 实例

Source

pub fn name(&self) -> &str

获取池名称

Source

pub fn capacity(&self) -> u32

获取总容量

Source

pub fn frame_size(&self) -> u32

获取帧大小

Source

pub fn allocated_count(&self) -> u32

获取已分配数量

Source

pub fn free_count(&self) -> u32

获取空闲数量

Source

pub fn quarantined_count(&self) -> u32

获取隔离区数量

Source

pub fn allocate(&mut self, domain_id: u32) -> Result<FrameToken, CoreError>

分配一个 Frame（O(1)，零锁零堆分配）

从 Free-List 栈顶弹出一个空闲帧，标记为已分配。

§Arguments

domain_id - 域ID

§Returns

Ok(FrameToken) - 成功分配的所有权令牌
Err(CoreError::QuotaExceeded) - 资源不足

Source

pub fn release(&mut self, token: FrameToken) -> Result<(), CoreError>

归还 Frame（O(1)，零锁零堆分配）

验证令牌所有权后，将帧放回 Free-List 栈。

注意：即使验证失败（返回 Err），token 也会被消费（drop），对应的帧将永久泄漏。如果需要在失败后保留令牌以便重试或另行处理，请使用 FramePool::release_recoverable。

§Arguments

token - 所有权令牌（被消费，即使在错误路径上也会被 drop）

§Returns

Ok(()) - 成功归还
Err(CoreError::OwnershipViolation) - 所有权违规（token 已被消费）

Source

pub fn release_recoverable( &mut self, token: FrameToken, ) -> Result<(), (FrameToken, CoreError)>

归还 Frame（可恢复版本，O(1)）

与 release 语义一致，但在验证失败时将 token 随错误一起返回（Err((token, error))），调用方可据此重试或另行处理，避免验证失败时帧被永久泄漏。

§Arguments

token - 所有权令牌（成功时被消费，失败时随错误返回）

§Returns

Ok(()) - 成功归还（token 被消费）
Err((FrameToken, CoreError)) - 验证失败，token 随错误返回供调用方处置

Source

pub fn quarantine( &mut self, token: FrameToken, reason: impl Into<String>, ) -> Result<(), CoreError>

将 Frame 移入隔离区

隔离区帧不会被自动回收，需要手动调用 recover_from_quarantine。

§Arguments

token - 所有权令牌（被消费）
reason - 隔离原因

§Returns

Ok(()) - 成功隔离

Source

pub fn recover_from_quarantine( &mut self, frame_id: FrameId, ) -> Result<(), CoreError>

从隔离区回收 Frame

注意：本方法仅凭 frame_id 回收，不验证代际（CORE-008）。仅适用于调用方可确认帧未被回收重新分配的内部安全场景。数据面路径（持有 frame_id + expected_generation）应使用 recover_from_quarantine_by_id，以代际验证防止陈旧 FrameId 被复用。