Rust fallible_collections 使用指南

介绍

fallible_collections 是一个 Rust 库，提供了可回退的集合操作，专门用于处理内存分配可能失败的情况（如内存不足）。该库为标准库中的集合类型提供了 fallible（可失败）版本，允许开发者在内存敏感的环境中优雅地处理错误。

主要特性

• 提供 FallibleVec、FallibleHashMap 等可失败集合类型
• 支持内存分配错误的显式处理
• 与标准库集合 API 保持高度一致性
• 适用于嵌入式系统和高可靠性应用场景

安装方法

在 Cargo.toml 中添加依赖：

[dependencies]
fallible_collections = "0.4"

基本用法示例

use fallible_collections::{FallibleVec, TryCollect, TryReserveError};

fn main() -> Result<(), TryReserveError> {
    // 创建可失败向量
    let mut vec = FallibleVec::new();
    
    // 尝试推送元素（可能因内存不足而失败）
    vec.try_push(42)?;
    vec.try_push(100)?;
    
    // 尝试预留容量
    vec.try_reserve(10)?;
    
    // 使用 try_collect 从迭代器创建集合
    let numbers: FallibleVec<i32> = (0..5).map(|x| x * 2).try_collect()?;
    
    println!("向量内容: {:?}", numbers);
    Ok(())
}

错误处理示例

use fallible_collections::{FallibleVec, TryReserveError};

fn process_data() -> Result<(), TryReserveError> {
    let mut data = FallibleVec::new();
    
    // 模拟内存不足情况
    match data.try_reserve(usize::MAX) {
        Ok(_) => println!("内存分配成功"),
        Err(TryReserveError::CapacityOverflow) => {
            eprintln!("容量溢出错误");
            return Err(TryReserveError::CapacityOverflow);
        }
        Err(TryReserveError::AllocError { .. }) => {
            eprintln!("内存分配失败");
            return Err(TryReserveError::AllocError { layout: std::alloc::Layout::new::<u8>() });
        }
    }
    
    Ok(())
}

HashMap 使用示例

use fallible_collections::{FallibleHashMap, TryReserveError};
use std::collections::hash_map::RandomState;

fn main() -> Result<(), TryReserveError> {
    let mut map = FallibleHashMap::new();
    
    // 尝试插入键值对
    map.try_insert("key1", "value1")?;
    map.try_insert("key2", "value2")?;
    
    // 尝试预留空间
    map.try_reserve(100)?;
    
    println!("映射内容: {:?}", map);
    Ok(())
}

完整示例代码

use fallible_collections::{FallibleVec, FallibleHashMap, TryCollect, TryReserveError};
use std::collections::hash_map::RandomState;

// 演示 FallibleVec 的基本操作
fn demo_fallible_vec() -> Result<(), TryReserveError> {
    println!("=== FallibleVec 演示 ===");
    
    // 创建新的可失败向量
    let mut vec = FallibleVec::new();
    
    // 尝试添加元素
    vec.try_push(10)?;
    vec.try_push(20)?;
    vec.try_push(30)?;
    
    println!("添加元素后: {:?}", vec);
    
    // 尝试预留容量
    vec.try_reserve(100)?;
    println!("预留容量后，容量: {}", vec.capacity());
    
    // 使用 try_collect 从迭代器创建向量
    let collected: FallibleVec<i32> = (0..10).map(|x| x * 3).try_collect()?;
    println!("从迭代器收集: {:?}", collected);
    
    Ok(())
}

// 演示 FallibleHashMap 的基本操作
fn demo_fallible_hashmap() -> Result<(), TryReserveError> {
    println!("\n=== FallibleHashMap 演示 ===");
    
    let mut map = FallibleHashMap::new();
    
    // 尝试插入键值对
    map.try_insert("name", "Alice")?;
    map.try_insert("age", "30")?;
    map.try_insert("city", "Beijing")?;
    
    println!("HashMap 内容: {:?}", map);
    
    // 尝试预留更多空间
    map.try_reserve(50)?;
    println!("预留空间后，容量: {}", map.capacity());
    
    // 访问元素
    if let Some(name) = map.get("name") {
        println!("获取到的名字: {}", name);
    }
    
    Ok(())
}

// 演示错误处理
fn demo_error_handling() -> Result<(), TryReserveError> {
    println!("\n=== 错误处理演示 ===");
    
    let mut vec = FallibleVec::new();
    
    // 尝试分配极大内存（应该会失败）
    match vec.try_reserve(usize::MAX) {
        Ok(_) => println!("意外成功：分配了极大内存"),
        Err(TryReserveError::CapacityOverflow) => {
            println!("正确处理：容量溢出错误");
        }
        Err(TryReserveError::AllocError { .. }) => {
            println!("正确处理：内存分配错误");
        }
    }
    
    Ok(())
}

fn main() -> Result<(), TryReserveError> {
    // 演示各种功能
    demo_fallible_vec()?;
    demo_fallible_hashmap()?;
    demo_error_handling()?;
    
    println!("\n=== 所有演示完成 ===");
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_basic_operations() -> Result<(), TryReserveError> {
        let mut vec = FallibleVec::new();
        vec.try_push(1)?;
        vec.try_push(2)?;
        assert_eq!(vec.len(), 2);
        Ok(())
    }
}

最佳实践

1. 在内存受限环境中使用 fallible_collections
2. 始终处理可能的分配错误
3. 使用 ? 操作符简化错误传播
4. 结合 #[cfg(feature = "...")] 条件编译在不同环境中切换实现

注意事项

• 该库会增加一定的运行时开销
• 需要显式处理所有可能的内存分配错误
• 建议仅在确实需要处理内存分配失败的场景中使用

通过使用 fallible_collections，开发者可以在保持代码健壮性的同时，优雅地处理内存分配失败的情况。