ogg_pager：Rust高效数据分页与流式加载库

概述

ogg_pager是一个专为Rust设计的高性能分页处理库，支持数据分页和流式加载功能。该库提供了简洁的API接口，适用于Web服务、数据库查询以及大数据集处理等场景。

核心特性

• 内存高效的分页数据结构
• 支持同步和异步流式加载
• 可自定义分页策略和页面大小
• 零成本抽象，高性能实现

安装方法

在Cargo.toml中添加依赖：

[dependencies]
ogg_pager = "0.3.0"

基本用法

1. 基础分页示例

use ogg_pager::Pager;

fn main() {
    let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
    let mut pager = Pager::new(data, 3); // 每页3个元素
    
    // 获取第一页
    if let Some(page) = pager.get_page(0) {
        println!("第一页: {:?}", page); // 输出: [1, 2, 3]
    }
    
    // 获取总页数
    println!("总页数: {}", pager.total_pages());
}

2. 流式加载示例

use ogg_pager::{Pager, StreamLoader};
use futures::stream::StreamExt;

async fn stream_example() {
    let loader = StreamLoader::new(|page, size| {
        // 模拟异步数据加载
        async move {
            let start = page * size;
            let end = (page + 1) * size;
            Ok::<_, std::io::Error>((start..end).collect::<Vec<_>>())
        }
    });
    
    let mut stream = loader.stream(5); // 每页5个元素
    
    while let Some(result) = stream.next().await {
        match result {
            Ok(page) => println!("加载页面: {:?}", page),
            Err(e) => eprintln!("加载错误: {}", e),
        }
    }
}

3. 自定义分页策略

use ogg_pager::{Pager, PagingStrategy};

struct CustomStrategy;
impl PagingStrategy for CustomStrategy {
    fn calculate_page_range(&self, total_items: usize, page_size: usize) -> usize {
        // 自定义分页逻辑
        (total_items + page_size - 1) / page_size
    }
}

fn custom_strategy_example() {
    let data = (0..100).collect::<Vec<_>>();
    let pager = Pager::with_strategy(data, 10, CustomStrategy);
    
    println!("使用自定义策略的总页数: {}", pager.total_pages());
}

高级功能

异步分页处理

use ogg_pager::AsyncPager;
use tokio::runtime::Runtime;

async fn async_pager_example() {
    let data = vec!["item1", "item2", "item3", "item4", "item5"];
    let pager = AsyncPager::new(data, 2);
    
    // 异步获取页面
    match pager.get_page_async(1).await {
        Ok(page) => println!("第二页: {:?}", page),
        Err(e) => eprintln!("错误: {}", e),
    }
}

内存映射分页

use ogg_pager::MmapPager;
use std::fs::File;

fn mmap_example() -> Result<(), Box<dyn std::error::Error>> {
    let file = File::open("large_data.bin")?;
    let pager = MmapPager::new(file, 4096)?; // 每页4KB
    
    if let Some(page) = pager.get_page(5) {
        println!("第6页数据: {:?}", &page[..100]); // 显示前100字节
    }
    
    Ok(())
}

性能建议

1. 选择合适的页面大小以减少内存碎片
2. 对于大型数据集，使用流式加载避免内存溢出
3. 考虑使用MmapPager处理超大型文件
4. 利用异步特性提高I/O密集型任务的性能

错误处理

use ogg_pager::PagerError;

fn error_handling_example() -> Result<(), PagerError> {
    let data = vec![1, 2, 3];
    let pager = Pager::new(data, 2);
    
    // 处理不存在的页面
    match pager.get_page(2) {
        Some(page) => println!("页面: {:?}", page),
        None => return Err(PagerError::PageOutOfRange(2)),
    }
    
    Ok(())
}

ogg_pager库为Rust开发者提供了强大而灵活的分页解决方案，适用于各种需要处理分页数据的场景。

完整示例demo

use ogg_pager::{Pager, StreamLoader, PagingStrategy, AsyncPager, PagerError};
use futures::stream::StreamExt;
use tokio::runtime::Runtime;
use std::fs::File;

// 自定义分页策略实现
struct CustomPagingStrategy;
impl PagingStrategy for CustomPagingStrategy {
    fn calculate_page_range(&self, total_items: usize, page_size: usize) -> usize {
        // 自定义分页计算逻辑：向上取整
        (total_items + page_size - 1) / page_size
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== ogg_pager 完整示例演示 ===");
    
    // 1. 基础分页示例
    println!("\n1. 基础分页功能:");
    let data = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
    let mut pager = Pager::new(data, 4); // 每页4个元素
    
    println!("总页数: {}", pager.total_pages());
    
    // 遍历所有页面
    for page_num in 0..pager.total_pages() {
        if let Some(page) = pager.get_page(page_num) {
            println!("第{}页: {:?}", page_num + 1, page);
        }
    }
    
    // 2. 自定义分页策略示例
    println!("\n2. 自定义分页策略:");
    let large_data: Vec<i32> = (0..95).collect();
    let custom_pager = Pager::with_strategy(large_data, 10, CustomPagingStrategy);
    println!("使用自定义策略的总页数: {}", custom_pager.total_pages());
    
    // 3. 流式加载示例
    println!("\n3. 流式加载演示:");
    let loader = StreamLoader::new(|page, size| {
        // 模拟异步数据加载（例如从数据库或API获取）
        async move {
            tokio::time::sleep(tokio::time::Duration::from_millis(100)).await; // 模拟延迟
            let start = page * size;
            let end = std::cmp::min((page + 1) * size, 25); // 模拟只有25个数据
            Ok::<_, std::io::Error>((start..end).collect::<Vec<_>>())
        }
    });
    
    let mut stream = loader.stream(5); // 每页5个元素
    let mut page_count = 0;
    
    while let Some(result) = stream.next().await {
        match result {
            Ok(page) => {
                page_count += 1;
                println!("流式加载第{}页: {:?}", page_count, page);
            }
            Err(e) => eprintln!("流式加载错误: {}", e),
        }
    }
    
    // 4. 异步分页处理
    println!("\n4. 异步分页处理:");
    let async_data = vec!["苹果", "香蕉", "橙子", "葡萄", "芒果"];
    let async_pager = AsyncPager::new(async_data, 2);
    
    match async_pager.get_page_async(1).await {
        Ok(page) => println!("异步获取第二页: {:?}", page),
        Err(e) => eprintln!("异步获取错误: {}", e),
    }
    
    // 5. 错误处理示例
    println!("\n5. 错误处理演示:");
    let small_data = vec![1, 2, 3];
    let error_pager = Pager::new(small_data, 2);
    
    match error_pager.get_page(2) {
        Some(page) => println!("页面存在: {:?}", page),
        None => println!("页面不存在，这是预期的错误情况"),
    }
    
    // 6. 模拟内存映射分页（需要实际文件）
    println!("\n6. 内存映射分页演示:");
    // 注意：实际使用时需要准备一个真实的文件
    if let Ok(file) = File::open("example_data.bin") {
        if let Ok(mmap_pager) = MmapPager::new(file, 1024) { // 每页1KB
            if let Some(page) = mmap_pager.get_page(0) {
                println!("内存映射第一页大小: {} 字节", page.len());
            }
        }
    } else {
        println!("示例文件不存在，跳过内存映射演示");
    }
    
    println!("\n=== 示例演示完成 ===");
    Ok(())
}

// 自定义错误处理函数
fn handle_pager_error() -> Result<(), PagerError> {
    let data = vec![1, 2, 3, 4, 5];
    let pager = Pager::new(data, 3);
    
    // 尝试访问超出范围的页面
    let page_num = 5;
    match pager.get_page(page_num) {
        Some(page) => {
            println!("页面 {}: {:?}", page_num, page);
            Ok(())
        }
        None => Err(PagerError::PageOutOfRange(page_num)),
    }
}

// 运行错误处理示例
fn run_error_example() {
    println!("\n错误处理示例:");
    match handle_pager_error() {
        Ok(_) => println!("页面访问成功"),
        Err(e) => println!("错误: {:?}", e),
    }
}

这个完整示例演示了ogg_pager库的主要功能：

1. 基础分页功能 - 使用Pager进行基本的分页操作
2. 自定义分页策略 - 实现自定义的分页计算逻辑
3. 流式加载 - 使用StreamLoader进行异步数据流处理
4. 异步分页 - 使用AsyncPager进行异步页面获取
5. 错误处理 - 演示如何处理页面超出范围等错误情况
6. 内存映射 - 展示MmapPager的基本用法（需要实际文件）

要运行此示例，需要在Cargo.toml中添加以下依赖：

[dependencies]
ogg_pager = "0.3.0"
tokio = { version = "1.0", features = ["full"] }
futures = "0.3"

这个示例涵盖了ogg_pager库的核心功能，可以根据实际需求进行调整和扩展。