flag-cell

Apache-2.0 许可证

一个用于对值进行轻量引用 + 逻辑启用/禁用管理的 Rust 轻量库。提供 FlagCell（值持有者）与 FlagRef（轻量共享引用）两大核心类型，并在不违背内存安全与 Rust 借用规则的前提下，实现逻辑启用/禁用与引用计数校验。

本仓库当前仅实现单线程版本（src/local.rs）；src/sync.rs 待实现。

主要特性

轻量共享引用：类似 Rc<RefCell> 但具备逻辑启用/禁用语义，仅保留单个所有权持有者（FlagCell），其余引用均为弱引用（FlagRef）
可对托管数据执行临时「逻辑禁用」，阻止引用读取内部数据
FlagCell 被释放时会自动禁用，且可被任意 FlagRef 重新复活（仅在其被释放后）
支持安全解包 FlagCell
体积小巧

适用场景

需要以「软锁/软禁用」方式限制数据访问（例如：逻辑上挂起某资源，但不立即释放内存）
需要在单所有权模型下感知所有者是否存活

快速开始

将本库作为依赖引入，用法与普通 Rust 库一致：

在 Cargo.toml 中添加：

[dependencies]

flag-cell = "0.0.2"

或使用指令：

crago add flag-cell

随后在代码中使用：

use flag_cell::*;

fn main() {
    // 创建 FlagCell 持有目标值
    let cell = FlagCell::new(String::from("hello"));

    // 从 FlagCell 生成轻量引用（FlagRef）
    let flag_ref = cell.flag_borrow();

    // 查询引用计数与启用状态
    println!("ref_count: {}", flag_ref.ref_count());
    println!("is_enabled: {}", flag_ref.is_enabled());

    // 强制启用（危险操作，需 unsafe）
    // unsafe { flag_ref.enable(); } // 返回 FlagRefOption<()>

    // 当所有 FlagRef 被释放（引用计数为 0 且未被禁用）时，可尝试取出内部值
    // 若存在活跃引用或已被禁用，try_unwrap 会返回 Err(self)
    match cell.try_unwrap() {
        Ok(value) => println!("取到值: {}", value),
        Err(_cell) => println!("存在活跃引用或已被禁用，无法解包"),
    }

    // 注意：调用 unwrap() 时若存在活跃引用或已被禁用，会直接 panic
}

主要 API 概览

crate 根导出类型
- FlagCell<T>：持有值的主体类型。核心方法（节选）：
  - FlagCell::new(value: T) -> FlagCell<T>
  - flag_borrow(&self) -> FlagRef<T>：生成一个 FlagRef
  - ref_count(&self) -> isize：返回当前引用数量（实现中会减去自身计数，语义详见源码）
  - is_enabled(&self) -> bool
  - enable(&self) -> Option<()> / disable(&self) -> Option<()>
  - try_unwrap(self) -> Result<T, Self>：非 panic 版本的内部值取出方法
  - unwrap(self) -> T：若存在活跃引用或已被禁用会触发 panic
- FlagRef<T>：由 FlagCell 生成的轻量引用（可 Clone）。核心方法（节选）：
  - ref_count(&self) -> isize：返回引用计数（实现层对计数的解读与 FlagCell 略有差异，详见源码）
  - is_enabled(&self) -> bool
  - unsafe fn enable(&self) -> FlagRefOption<()>：强制逻辑启用数据（逻辑不安全）
- FlagRefOption<T>：枚举，表示引用读取结果的状态：
  - Some(T)、Conflict、Empty、Disabled
  - 实现了 FlagRefOption<T> 到 Option<T> 的转换

说明：以上 API 概览均摘录自当前 src/local.rs 实现。如需更详细的方法签名与行为（如 panic 条件、并发安全约定），请查阅源码注释。

设计与注意事项（源自源码核心说明）

FlagCell::unwrap() 在存在任意活跃 FlagRef（ref_count > 0）或已被禁用时会触发 panic。
try_unwrap() 提供非 panic 替代方案，返回 Err(self) 交由调用方处理。
FlagRef 提供 unsafe fn enable() 方法：属于逻辑不安全操作（不会产生内存未定义行为，但可能破坏类型的逻辑契约），需谨慎使用。
析构行为：FlagCell 与 FlagRef 的析构逻辑在语义上互斥，源码中使用 ManuallyDrop、RefCell、Cell<isize> 等原语做手工内存管理。

示例与调试

仓库源码（src/local.rs）包含大量注释与实现细节，建议阅读以理解以下关键点：

引用计数的记录方式（正负值分别表示启用/禁用状态）
FlagRefOption 的各类返回状态及其与 Option 的转换规则
try_unwrap 与 unwrap 在不同条件下的行为差异

TODO / 未来规划

实现多线程/同步版本（sync.rs）并完善测试
补充更多示例与文档

贡献

欢迎提交 PR 与 Issue。

联系

详见仓库所有者主页 Milk-COCO

flag-cell 0.0.2