Lib.rs

prodash 允许将进度报告集成到并发应用程序中，并提供各种方式显示它的渲染器。

它易于集成，因为它有一个实用的API，并默认包含一个终端用户界面。

如何使用…

请务必阅读https://docs.rs/prodash上的文档，其中包含有关如何入门的示例。

或者运行演示应用程序，如下所示 cd prodash && cargo run --all-features --example dashboard。

功能切换

此crate包含各种cargo功能，以满足您的需求。

• progress-tree (默认)
  • 提供用于与render-line和render-tui一起使用的Progress和Root trait实现，由dashmap支持。
  • progress-tree-hp-hashmap - 在超重插入和删除的情况下，为pregree树节点提供高性能注册表。
    • 如果这是必需的，那么无论如何都难以合理地可视化进度树，但这个选项仍然存在，以防万一需要。历史上，这是默认设置，但现在似乎更简单更好，并且适用于典型的程序。
  • progress-tree-log (默认)
    • 如果 log 包已初始化，则将使用 log 来输出所有提供给 tree::Item::message(…) 和相关函数的消息。不会实际写入进度。
    • 可能干扰 render-tui 或 render-line，或任何输出到控制台的工具。
• progress-log
  • 使用 log 包记录消息和进度的 Progress 实现
• local-time
  • 如果设置，则 render-tui 的消息面板中的时间戳将使用本地时间，而不是 UTC
  • 如果设置，则 render-line 的日志消息的时间戳将使用本地时间，而不是 UTC
  • 在没有分别设置 render-tui 或 render-line 的情况下，此设置无效
• render-line
  • 提供一个基于行的最小进度渲染器，可以限制为进度层次结构的一个子集。
  • 它类似于 render-tui，但依赖性更少，视觉保真度更低 - 在绘制字符和块图形时只需要稍微移动光标。
  • 支持 clicolors 规范 和 no-color 规范
  • 支持初始延迟，不会影响日志消息，仅在需要时自动显示进度。
  • 需要设置以下附加功能标志之一才能正常工作
    • 必须选择一项 (互斥)
      • render-line-crossterm - 使用 crossterm 后端，适用于在 Windows 上工作
      • render-line-termion - 使用 termion 后端，适用于仅适用于 Unix 系统的精简构建
  • 可选功能
    • render-line-autoconfigure
      • 如果启用，则会调用 render::line::Options::auto_configure()，并根据是否处于终端以及可能或期望的颜色模式来自动配置显示。
    • signal-hook
      • 如果设置，并且设置了 hide_cursor 行渲染器选项，则光标将被隐藏，并且将安装 SIG_INT 和 SIG_TERM 处理器以在退出时重置光标。否则，您必须确保在 JoinHandle 上调用 shutdown_and_wait()，以便给渲染器机会撤销终端更改。否则，一旦程序完成，光标将保持隐藏。
      • 这会带来额外的线程和额外的依赖项。
• render-tui
  • 提供一个终端用户界面，可视化当前进度状态的所有细节。它将终端视为矩阵显示。
  • 需要设置以下附加功能标志之一才能正常工作 ** （必须选择一项，互斥）
    • render-tui-crossterm
      • 使用 crossterm 包作为终端后端
      • 在所有地方本地工作，但具有更多的依赖项
      • 您可以通过这种方式设置附加功能，例如：cargo build --features render-tui-crossterm,crossterm/event-stream
    • render-tui-termion
      • 使用 termion 包作为终端后端
      • 它具有较少的依赖项，但仅在 unix 系统上工作
      • 要获取此功能，请禁用默认功能并选择至少 render-tui 和 render-tui-termion。
• unit-bytes
  • 支持使用小巧的 bytesize 包动态显示字节。
• unit-human
  • 以人类更易理解的方式显示计数，使用小巧的 human_format crate。
• 单位持续时间
  • 使用小巧的 humantime crate 以 '5m4s' 的形式显示秒。

功能

• 高速插入和更新，以跟踪高并发程序的透明进度
• 消息缓冲区，用于存储成功和失败的信息
• 终端用户界面，用于可视化，具有键盘控制和动态调整大小
• 支持 unicode 和多宽度字符

限制

• 行渲染器 在不产生视觉伪影的情况下，显示进度的能力有限。
• 每次显示进度信息和消息时，都会复制相当多的状态。
• 底层的同步数据结构 dashmap 并未记录每个不安全的用法。
  • 我还评估了 evmap，其不安全用法减少了25%，但接口更复杂。
  • 到目前为止，它似乎“不错”使用，谁知道……我们从多个线程中获取可变哈希表片段，然而，我们从未为同一个子对象提供多个句柄，这应该使得对同一键的实际并发访问变得不可能。
• 如果任务数量超过 2^16
  • 则
    • 在树的同一层并发运行，它们开始互相覆盖
    • 在其生命周期内，即使它们不并发运行，新任务最终会像旧任务一样（它们的ID环绕）
  • 为什么
    • 在删除时，它们从未减少用于生成新ID的子计数
  • 修复
    • 将ID做得更大，比如u32
    • 一旦有性能测试，我们应该这么做
• 如果使用 行渲染器 时日志行太长，超出终端宽度
  • 则
    • 将出现视觉伪影
  • 为什么
    • 尝试在终端边界外绘制将自动添加换行符，这可能导致意外的重绘。
  • 修复
    • 计算绘制的块数量，不使用 ansi 代码，并在边界处停止绘制。

经验教训

• drop() 不保证在 future 返回 Ready 并在 futures::executor::ThreadPool 中时被调用
  • 解决方案：显式删除和清理，容易忘记。
  • 这也是为什么 futures::future::abortable() 工作的原因（通过停止轮询），但清理并未执行，尽管它明显更可取。
  • 修复
    • 使用 join handle 并等待它 - 这将正确删除 future
• select() 可能不与复杂的 futures 一起工作 - 如果未实现 Unpin，则这些应该被 boxed() 包装。