flag-cell-0.0.1 has been yanked.

flag-cell

English README

Apache-2.0 Licensed

一个用于对值进行“轻量引用 + 逻辑启用/禁用”管理的 Rust 小库。提供 FlagCell（持有者）和 FlagRef（轻量共享引用）两类主要类型，并且实现了在不破坏内存安全、Rust借用规则前提下的逻辑禁用/启用与引用计数检查。

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

主要特性

轻量共享引用（类似于 Rc 但带“逻辑禁用/启用”语义，且仅存在单个Rc（FlagCell），其余引用皆为Weak（FlagRef））
可以临时“禁用”被持有的数据，阻止引用读取内部数据
FlagCell被释放时将自动禁用，且FlagCell可被任意FlagRef复活（仅它死了之后）
支持安全解包FlagCell。
小巧。

何时使用

需要以“软锁/软禁用”方式阻止访问数据（例如：逻辑上挂起某个资源，但不立即释放内存）
需要单所有权时得知所有者是否存在

快速开始

将本库作为依赖（仓库暂未发布到 crates.io，可使用 git 依赖）：

在 Cargo.toml 中添加（示例）：

[dependencies]

flag-cell = { git = "https://github.com/Milk-COCO/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 (不包含 FlagCell 自身): {}", flag_ref.ref_count());
    println!("is_enabled: {}", flag_ref.is_enabled());

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

    // 当所有 FlagRef 被 drop（引用计数为 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() 方法：这是一个“逻辑不安全”操作（不会造成本地内存未定义行为，但可能破坏类型的逻辑契约），需谨慎使用。
Drop 行为：FlagCell 与 FlagRef 的 drop 在语义上互斥，源码中有专门处理内存释放的逻辑（使用 ManuallyDrop、RefCell、Cell<isize> 等原语进行手工管理）。

示例与调试

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

引用计数如何记录（正负值处理表示启用/禁用状态）
FlagRefOption 的几种返回状态以及如何向 Option 转换
try_unwrap 与 unwrap 在不同条件下的行为差异

TODO / 未来工作

添加多线程/同步版本（sync.rs）实现并完善测试
发布到 crates.io（目前可通过 git 依赖使用）
增加示例与文档

贡献

欢迎 PR 与 Issue。建议流程：

Fork → 新分支（feature/xxx 或 fix/xxx）
添加测试与实现
提交 PR 并在描述中附上复现步骤或测试用例

联系

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

flag-cell 0.0.1