Utils_ProgressBar

ProgressManager API 文档

概述

ProgressManager 是 utilsCore Utils 模块的核心类，提供多进度条管理功能，支持同时显示多个进度条。

职责

• 管理多个进度条
• 显示进度条
• 支持百分比显示
• 支持自定义宽度

适用场景

• 多任务进度监控
• 批量处理
• 长时间任务
• 进度并行显示

依赖关系

• 依赖: 标准库
• 被依赖: 批量处理、文件操作等模块

---

类分析

ProgressManager 类

职责与用途

ProgressManager 是多进度条管理的封装类，提供：

• 添加进度条
• 更新进度
• 标记完成
• 自动绘制

设计模式

• 管理者模式: 管理多个进度条

---

Bar 结构体

结构体定义

struct Bar {
    std::string name;     // 进度条名称
    int value = 0;        // 当前进度
    int total = 100;      // 总进度
    int width = 50;       // 显示宽度
};

字段说明

字段	类型	默认值	说明
name	string	-	进度条名称
value	int	0	当前进度
total	int	100	总进度
width	int	50	显示宽度

---

公共 API 方法

addBar() - 添加进度条

int addBar(const std::string& name, int total = 100);

参数说明:

• name (输入): 进度条名称
• total (输入): 总进度（默认 100）

返回值: 进度条索引

所有权归属:

• ProgressManager 持有进度条的所有权

注意事项:

1. 返回的索引用于后续更新
2. 线程安全操作
3. 可以添加多个进度条

使用例程:

ProgressManager pm;

// 添加进度条
int bar1 = pm.addBar("Task 1", 1000);
int bar2 = pm.addBar("Task 2", 500);

---

update() - 更新进度

void update(int index, int current);

参数说明:

• index (输入): 进度条索引
• current (输入): 当前进度

返回值: 无

所有权归属:

• 无所有权转移

注意事项:

1. index 必须有效
2. 自动绘制进度条
3. 线程安全操作

使用例程:

// 更新进度
pm.update(bar1, 500);
pm.update(bar2, 250);

---

done() - 标记完成

void done(int index);

参数说明:

• index (输入): 进度条索引

返回值: 无

所有权归属:

• 无所有权转移

注意事项:

1. index 必须有效
2. 将进度设置为 total
3. 自动绘制进度条
4. 线程安全操作

使用例程:

// 标记完成
pm.done(bar1);
pm.done(bar2);

---

draw() - 绘制进度条

void draw();

参数说明: 无

返回值: 无

所有权归属:

• 无所有权转移

注意事项:

1. 光标上移到顶部
2. 绘制所有进度条
3. 自动刷新输出

使用例程:

// 手动绘制
pm.draw();

---

内部实现

同步机制

std::vector<Bar> bars;
std::mutex mtx;

说明:

• bars 存储所有进度条
• mtx 保护所有操作

---

典型使用场景

场景 1: 基本使用

ProgressManager pm;

// 添加进度条
int bar1 = pm.addBar("Download", 1000);

// 更新进度
for (int i = 0; i <= 1000; i += 10) {
    pm.update(bar1, i);
    std::this_thread::sleep_for(std::chrono::milliseconds(10));
}

// 标记完成
pm.done(bar1);

场景 2: 多进度条

ProgressManager pm;

// 添加多个进度条
int bar1 = pm.addBar("Task 1", 100);
int bar2 = pm.addBar("Task 2", 200);
int bar3 = pm.addBar("Task 3", 150);

// 并行更新
std::vector<std::thread> threads;
threads.emplace_back([&]() {
    for (int i = 0; i <= 100; i++) {
        pm.update(bar1, i);
        std::this_thread::sleep_for(std::chrono::milliseconds(10));
    }
});

threads.emplace_back([&]() {
    for (int i = 0; i <= 200; i++) {
        pm.update(bar2, i);
        std::this_thread::sleep_for(std::chrono::milliseconds(5));
    }
});

threads.emplace_back([&]() {
    for (int i = 0; i <= 150; i++) {
        pm.update(bar3, i);
        std::this_thread::sleep_for(std::chrono::milliseconds(7));
    }
});

for (auto& t : threads) t.join();

pm.done(bar1);
pm.done(bar2);
pm.done(bar3);

场景 3: 批量处理

ProgressManager pm;

// 添加进度条
int bar = pm.addBar("Processing", files.size());

// 处理文件
for (size_t i = 0; i < files.size(); i++) {
    process_file(files[i]);
    pm.update(bar, i + 1);
}

pm.done(bar);

场景 4: 自定义总数

ProgressManager pm;

// 添加进度条（自定义总数）
int bar = pm.addBar("Upload", 5000);

// 更新进度
for (int i = 0; i <= 5000; i += 100) {
    pm.update(bar, i);
}

pm.done(bar);

---

注意事项

1. 线程安全: 所有操作都是线程安全的
2. 索引有效性: 确保 index 有效
3. 终端控制: 使用 ANSI 转义序列控制光标
4. 自动绘制: update() 和 done() 会自动调用 draw()
5. 多进度条: 可以同时管理多个进度条
6. 完成状态: done() 将进度设置为 total
7. 宽度: 默认宽度为 50，可以修改 Bar.width
8. 输出: 输出到 stdout

---

相关文档

• AsyncThreadPool - 异步线程池
• Utils 模块总览

---

参考资料

• ANSI Escape Codes