译:使 Rust library 兼容 no_std

2024-09-2100 分钟
type
status
date
slug
summary
tags
category
icon
password
原文为 Effective Rust 第 33 条,笔者将其翻译后提交至 Effective Rust 中文版,同步转载至此处
 
Rust 附带一个名为 std 的标准库,其中包含了从标准数据结构到网络,从多线程支持到文件 I/O 等用于各种常见任务的代码。为了方便使用, std 中的一些项目会通过 prelude 自动导入到你的程序中,prelude 是一组 use 语句,可以在不需要指定完整名称的情况下直接使用这些常见类型(例如使用 Vec 而不是 std::vec::Vec)。
Rust 还支持为无法提供完整标准库的环境构建代码,如引导加载程序、固件或一般的嵌入式平台。通过在 src/lib.rs 文件顶部添加 #![no_std] 属性,可以指示 crate 在这类受限环境中编译。
 
本节将探讨在 no_std 环境中编译时我们会失去哪些功能,以及仍然可用的库函数。我们会发现,即使在这种受限环境中,依然有相当多的功能可供使用。
不过,这里特别关注的是针对代码的 no_std 支持。构建 no_std 可执行文件的复杂性超出了本文的范围,因此本节重点是对那些不得不在如此极简环境中工作的可怜人来说,如何确保库代码是可用的。
 

core

即使在为最受限的平台构建时,标准库中的许多基本类型也仍然可用。例如 Option 和 Result 以及各种 Iterator,尽管它们名称不同。
这些基本类型的不同名称以 core:: 开头,表明它们来自 core 库,这是一个即使在大多数 no_std 环境中也可用的标准库。这些 core:: 类型的行为与等效的 std:: 类型完全相同,因为它们实际上是同个类型 —— 对应的 std:: 版本都只是底层 core:: 类型的重新导出。
这意味着有一种快速而肮脏的方法来判断某个 std:: 项目在 no_std 环境中是否可用: 访问 doc.rust-lang.org 并找到感兴趣的 std 项目,点击 “soure”(在右上角),如果它跳转到了 src/core/... 中,则说明该项可通过 core:: 在 no_std 下使用。
正常情况下 core 中的类型可自动用于所有 Rust 程序。但在 no_std 环境需要显式 use,因为此时没有 std prelude 帮忙导入。
 
实际中,对于许多环境(甚至是 no_std)来说,纯粹依赖 core 会有很大的限制,因为 core 的一个核心(双关语)约束是它不会进行堆分配。
虽然 Rust 很擅长将数据放入栈中并安全地跟踪其相应的生命周期(第 14 条),但 core 的这种限制仍然意味着无法提供标准数据结构(vector, map, set),因为它们都需要分配堆空间来存放内部元素。所以这个限制也大大减少了在此环境中可用的 crate 数量。
 

alloc

但如果所在的 no_std 环境的确支持堆分配,则 std 中的许多标准数据结构仍然可用。这些数据结构以及其他使用分配功能的部分被分组到 Rust 的 alloc 库中。
和 core 一样,这些 alloc 变体实际上在底层是相同的类型。例如 std::vec::Vec 的真实名称是 alloc::vec::Vec
如果 no_std 的 crate 要使用 alloc,需要在 src/lib.rs 额外显式声明 extern crate alloc;
引入 alloc 库可以启用许多我们熟悉的朋友,现在他们以真实的名称被称呼:
有了这些朋友,许多 crate 就可以兼容 no_std —— 前提是不涉及 I/O 或网络。
 
但 alloc 提供的数据结构显然还缺少了两个集合 —— HashMap 和 HashSet,它们特定于 std 而不是 alloc。这是因为这些基于 hash 的容器依靠随机种子来防止 hash 冲突攻击,但安全的随机数生成需要依赖操作系统的帮助,而 alloc 不能假设操作系统存在。
另一个缺失的部分是同步功能,例如 std::sync::Mutex,这是多线程代码所必需的,但这些类型同样特定于 std,它们依赖操作系统的同步原语,如果没有操作系统,这些同步原语也将不可用。在 no_std 下编写多线程代码,第三方 crate 可能是唯一选择,例如 spin
 

为 no_std 编写代码

前文已经指出,对于某些 crate 库,要使代码兼容 no_std 只需要以下修改:
  • 用相同的 core:: 或 alloc:: crate 替换 std:: 类型(由于缺少 std prelude,还需要 use 完整的类型名称)
  • 将 HashMap / HashSet 迁移为 BTreeMap / BTreeSet
但这些操作只有在依赖的所有 crate(第 25 条)也兼容 no_std 时才有意义 —— 如果使用您 crate 的用户被迫链接到任何 std 中,与 no_std 的兼容就会失去意义。
 
这里还有一个问题:Rust 编译器并不会告诉你一个 no_std crate 中是否有引入使用了 std 的依赖。这意味着只要添加或更新一个使用了 std 的依赖,就能轻松破坏掉 no_std crate 的兼容性。
为了避免这个情况,请为 no_std 构建添加 CI 检查,以便 CI 系统(第 32 条)能在这种情况发生时发出警告。Rust 工具链支持开箱即用的交叉编译,因此只需为不支持 std 的目标系统(例如 --target thumbv6m-none-eabi)执行交叉编译,任何无意中依赖 std 的代码就会在此时编译失败。
 
所以,如果依赖项都支持,并且上面的简单修改就够了的话,不妨考虑让库代码兼容 no_std。这不需要太多额外工作,却能让库有更广泛的适用性。
如果这些转换并没有覆盖 crate 中的所有代码,但未覆盖的只是代码中的一小部分或包装良好的部分,那么可以考虑向 crate 添加一个 feature (第 26 条)以控制是否启用这部分代码。
这种允许使用 std 特定功能的 feature ,通常会将其命名为 std
或是将控制是否启用了 alloc 派生功能的 feature 命名为 alloc
注意,设计这类 feature 时有个容易忽视的陷阱:不要设置一个 no_std feature 来禁用需要 std 的功能(或类似的 no_alloc feature),正如第 26 条中提到的,feature 应当是可累加的,这样做会导致无法将启用了 no_std 和没有启用的两个 crate 用户组合在一起 —— 前者会删除后者所依赖的代码。
和所有带有 feautre 门控的代码一样,确保你的 CI 系统(第 32 条)构建了所有相关的组合 —— 包括在 no_std 平台上关闭 std 特性的构建。
 

可错分配(Fallible Allocation)

前面考虑了两种不同的 no_std 环境:不允许堆分配的完全嵌入式的环境(core)和允许堆分配的更宽松的环境(core + alloc)。
然而,有一些重要的环境介于两者之间,特别是那些允许堆分配但可能会失败的环境,因为堆空间是有限的。
不幸的是,Rust 的标准 alloc 库假设堆分配不会失败,但这个假设并不总是成立。
即使简单地使用 alloc::vec::Vec,也可能在每一行代码中都触发分配:
这些操作都不会返回 Result,当这些分配失败了,会发生什么?
答案取决于工具链、目标平台和配置,但很可能会导致 panic! 和程序终止。这里无法通过某种方式处理第 3 行的分配失败,并让程序继续执行第 4 行。
 
这种可靠分配(infallible allocation)的假设简化了在“正常”用户空间中运行的代码,因为在这些环境中,内存几乎是无限的 —— 或者内存耗尽意味着计算机本身出现了更严重的问题。
但可靠分配不适用于内存有限且程序必须应对内存不足的环境。这是一个在一些较老、内存安全性较差的语言中反而有更好支持的(罕见)领域:
  • C 的级别足够低,分配是手动的,因此可以检查 malloc 的返回值是否为 NULL
  • C++ 可以使用异常机制,捕获以 std::bad_alloc 异常形式出现的分配失败
历史上,Rust 标准库无法处理分配失败的问题在一些备受瞩目的场合(如 Linux 内核、Android 和 Curl 工具)中被指出,因此修复这一缺陷的工作正在进行中。
 
第一个尝试是添加“可错的集合分配”,它为许多涉及分配的集合 API 添加了允许可错分配的替代实现,通常是添加一个会返回 Result<_, AllocError> 的 try_<operation> 操作,例如:
但这些允许可错分配的 API 功能也仅限于此。例如,(目前为止)还没有与 Vec::push 等效的可错分配版本,因此编写组装 vector 的代码时,可能需要进行精确计算,以确保不会发生内存分配错误。
除了增加允许可错分配的入口外,还可以通过关闭默认开启的 no_global_oom_handling 配置来禁用可靠分配操作。在堆内存有限的环境(如 Linux 内核)中,可以显式禁用此标志,以确保不会在代码中无意使用了可靠分配。
 

要记住的事

  • std crate 中的许多项目实际上来自 core 或 alloc
  • 因此,使库代码兼容 no_std 可能比您想象的更简单。
  • 通过在 CI 中检查 no_std 代码来确认 no_std 代码保持 no_std 兼容。
  • 注意,当前支持在有限堆环境中工作的库十分有限。
 

注释

  1. 有关创建 no_std 可执行文件所涉及的内容,请参阅 The Embedonomicon 或 Philipp Opperamann 的早期博客文章
  1. 注意,该方法不一定正确。例如在撰写本文时,Error trait 在 [core::] 中定义,但被标记为不稳定(unstable),只有 std:: 版本是稳定的(stable)
  1. 在 Rust 2018 之前,extern crate 声明用来引入依赖项。现在这些依赖完全由 Cargo.toml 处理,但仍使用 extern crate 机制引入那些 no_std 环境中 Rust 标准库的可选部分(即 sysroot crates)。
  1. 还可以为 new 调用添加 std::nothrow 重载,并检查是否返回 nullptr。但一些容器方法比如 vector<T>::push_back,在内部进行分配,因此只能通过抛出异常来表示分配失败。
 

下一篇

Infra 窘境

Loading...