在 Rust 中写入未初始化的缓冲区

Rust 中的非初始化缓冲区是一个由来已久的问题，例如

最近， John Nunley and Alex Saveau 想到了一种新方法，使用 Buffer Trait，现在已经出现在 rustix 1.0 中，我将在这篇文章中介绍。

更新：这个想法现在可以在一个独立发布的库中找到：buffer-trait。元素周期表

`Buffer` trait 介绍

POSIX 的 read 函数会将文件描述符中的字节读入一个缓冲区，而且读取的字节数可以少于请求的字节数。使用 Buffer，rustix 中的 read 函数如下所示：

pub fn read<Fd: AsFd, Buf: Buffer<u8>>(fd: Fd, buf: Buf) -> Result<Buf::Output>

这使用了 Buffer Trait 来描述缓冲区参数。Buffer Trait 看起来像这样：

pub trait Buffer<T> {
    /// The type of the value returned by functions with `Buffer` arguments.
    type Output;

    /// Return a raw pointer and length to the underlying buffer.
    fn parts_mut(&mut self) -> (*mut T, usize);

    /// Assert that `len` elements were written to, and provide a return value.
    unsafe fn assume_init(self, len: usize) -> Self::Output;
}

(感谢 Yoshua Wuyts 对这个 Trait 的反馈和对整个想法的鼓励！）。

(Rustix自己的Buffer trait 是密封的，其函数也是私有的，但这只是Rustix暂时选择保留在不破坏兼容性的情况下发展该Trait的能力，代价是暂时不允许用户使用Buffer来定义自己的I/O函数)。

Buffer 是为 &mut [T] 实现的，因此用户可以向 read 传递一个要写入的 &mut [u8] 缓冲区，成功后它将返回一个 Result<usize>，其中 usize 表示实际读取的字节数。这与 rustix 中 read 的工作方式一致。使用这种方法如下

let mut buf = [0_u8; 16];
let num_read = read(fd, &mut buf)?;
use(&buf[..num_read]);

Buffer 也是为 &mut [MaybeUninit<T>] 实现的，因此用户可以向 read 传递一个 &mut [MaybeUninit<u8>] ，在这种情况下，他们将得到一个 Result<(&mut[u8], &mut [MaybeUninit<u8>])> 。成功后，会得到一对片段，它们是原始缓冲区的子片段，包含数据被读入的字节范围，以及剩余未初始化的字节。Rustix 以前有一个名为 read_uninit 的函数可以这样工作，在 rustix 1.0 中，它被这个新的支持Buffer的read 函数所取代。使用方法如下

let mut buf = [MaybeUninit::<u8>::uninit(); 16];
let (init, uninit) = read(fd, &mut buf)?;
use(init);

这样就可以通过安全的 API 读取未初始化的缓冲区。

此外，Buffer 还支持读取 Vec 的剩余容量。spare_capacity 函数接收一个 &mut Vec<T>，并返回一个实现了 Buffer 的 SpareCapacity newtype，它会自动设置向量的长度，以包括read后初始化元素的数量，从而封装了 Vec::set_len 的不安全性。使用这种方法看起来像

let mut buf = Vec::<u8>::with_capacity(1024);
let num_read = read(fd, spare_capacity(&mut buf))?;
use(&buf);

在 rustix 中，所有以前使用 &mut [u8] 缓冲区写入的函数现在都使用 impl Buffer<u8> 缓冲区，因此它们支持写入未初始化的缓冲区。

原理

read 是这样实现的

let len = unsafe { backend::io::syscalls::read(fd.as_fd(), buf.parts_mut())? };
unsafe { Ok(buf.assume_init(len)) }

首先，我们调用底层系统调用，它会返回读取的字节数。然后我们将其传递给 assume_init，它将计算要返回的 Buffer::Output。输出可能只是该数字，也可能是反映该数字的一对片段。

如果 T 不是 u8 怎么办？

Buffer 使用类型参数 T 而不是硬编码 u8，这样就可以被 epoll::wait, kevent, and port::get 等函数用来返回事件记录而不是字节。使用方法如下

let mut event_list = Vec::<epoll::Event>::with_capacity(16);
loop {
    let _num = epoll::wait(&epoll, spare_capacity(&mut event_list), None)?;
    for event in event_list.drain(..) {
        handle(event);
    }
}

这将使用 drain 来耗尽 Vec，使其在每次等待前为空，因为 spare_capacity 会追加到 Vec 中，而不是覆盖任何元素。

循环内部没有动态分配；SpareCapacity 只使用现有的空余容量，并且只调用 set_len，而不是 resize。

另外，由于 Buffer 也适用于分片，因此编写此代码时完全可以不使用 Vec：

let mut event_list = [MaybeUninit::<epoll::Event>; 16];
loop {
    let (init, _uninit) = epoll::wait(&epoll, &mut event_list, None)?;
    for event in init {
        handle(event);
    }
}

错误信息

Buffer Trait 方法的一个缺点是有时会唤起 rustc 的错误信息，而这些错误信息并不明显。这种情况时有发生，所以我们现在在 rustix 的文档中有一节是关于它们的，还有一个示例显示了它们出现的地方。

安全使用缓冲区

Rust 的 std 目前包含一个基于 BorrowedBuf 的实验性 API，它有一个很好的特性，就是允许用户在不使用 unsafe 的情况下使用它，而且不会做任何效率极低的事情，比如初始化完整的缓冲区。为此，BorrowedBuf 使用了 “双游标 ”设计，以避免重新初始化已初始化的内存。

这里描述的Buffer Trait 更为简单，避免了使用 “双游标”，不过它确实有一个unsafe 的必需方法。我们有办法修改它以支持安全使用吗？

像 BorrowedCursor 这样的Cursor API 就可以做到。它支持安全地以增量方式写入未初始化的缓冲区。BorrowedCursor 的一个关键特性是，它从不要求急于初始化整个缓冲区。

有了这一点，Buffer Trait 可能会看起来像这样：

pub trait Buffer<T> {
    // ... existing contents

    /// An alternative to `parts_mut` for use with `init`.
    ///
    /// Return a `Cursor`.
    fn cursor(&mut self) -> Cursor<T> {
        Cursor::new(self)
    }
}

impl<T, B: Buffer<T>> Cursor<T, B> {
    /// ... cursor API

    fn finish(self) -> B::Output {
        // SAFETY: `Cursor` ensures that exactly `pos` bytes have been written.
        unsafe { self.b.assume_init(selff.pos) }
    }
}

这样，用户就可以编写自己的函数，使用 Buffer 参数并使用cursor实现它们，而无需使用unsafe函数。

为什么要使用 parts_mut 和原始指针？

Buffer Trait 中的 parts_mut 函数看起来像这样：

fn parts_mut(&mut self) -> (*mut T, usize);

为什么要返回原始指针和长度，而不是 &mut [MaybeUninit<T>]？因为 &mut [MaybeUninit<T>] 会以一种微妙的方式变得不健全。我们为 &mut [T] 实现了缓冲区（Buffer），它不能包含任何未初始化的元素，而以 &mut [MaybeUninit<T>] 的形式公开缓冲区将允许未初始化的元素被写入其中。

有了原始指针，我们就可以让 assume_init 调用负责保证缓冲区已被正确写入。

展望未来

这个 Buffer Trait 的一个有限版本已经出现在 rustix 1.0 中，我们将拭目以待它在实践中的表现。

这个想法现在也可以在一个独立发布的库中找到：buffer-trait。

如果效果不错，我认为值得考虑在 Rust 的 std 中使用这种 Buffer 设计，以替代 BorrowedBuf（目前还不稳定）。它更简单，因为它避免了 “双游标 ”模式，而且还有一个有趣的特点，即支持 Vec 空闲用例并封装了不安全的 Vec::set_len 调用。

阅读余下内容

rust| 2025-05-22