PyO3 为 PyBuffer 新增 as_slice_ptr 与 as_fortran_slice_ptr:无需 GIL 令牌的零拷贝缓冲区切片访问

原创2026-09-21 20:45:151,674 阅读
文章标签:开发工具

PyO3 为 PyBuffer 新增 as_slice_ptr 与 as_fortran_slice_ptr:无需 GIL 令牌的零拷贝缓冲区切片访问

导读

PyBuffer<T> 是 PyO3 提供的强类型缓冲区封装,用于零拷贝读取 bytes、bytearray、array.array、memoryview 乃至 NumPy 数组等遵循 Python Buffer Protocol 的对象。本文聚焦 PyO3 新增的 as_slice_ptr 与 as_fortran_slice_ptr 两个方法(对应仓库 newsfragments/6382.added.md 记录的变更):与既有 as_slice 系列 API 相比,它们不要求传入 Python<'py> 令牌,直接返回指向缓冲区内存的 NonNull<[T]> 胖指针,适合在无需访问解释器上下文的零拷贝场景中直接使用。读完本文,你将掌握这两个 API 的签名语义、实现原理、与旧 API 的取舍,以及如何借助仓库测试用例规避非连续缓冲区陷阱。

背景:PyO3 的缓冲区抽象

在 PyO3 中,缓冲区支持由两部分构成:

  • PyUntypedBuffer:包装 CPython 的 ffi::Py_buffer 结构(src/buffer.rs),提供 shape()、strides()、format()、item_count()、item_size()、readonly()、is_c_contiguous()、is_fortran_contiguous() 等元数据查询方法;
  • PyBuffer<T>:#<a href="https://link.gitcode.com/i/7ae4b39980ae238e5f056d6fcee5f770" target="_blank">repr(transparent)] 的强类型封装,要求元素类型 T: Element,内置格式、大小与对齐校验(ensure_compatible_with,见 [src/buffer.rs)。

PyBuffer<T> 通过 Deref 解引用到 PyUntypedBuffer(src/buffer.rs),因此所有未类型化的查询方法对 PyBuffer<T> 同样可用。两者都位于公开模块 crate::buffer(在 src/lib.rs 中声明为 pub mod buffer;)。

创建缓冲区有两种入口:PyUntypedBuffer::get(&obj) 或直接 PyBuffer::<T>::get(&obj),后者内部调用 PyObject_GetBuffer 以 PyBUF_FULL_RO 标志获取底层内存视图,并在 Drop 时自动 PyBuffer_Release(见 src/buffer.rs 与 src/buffer.rs),因此无需手动释放。

新增 API:签名与语义

本次变更(newsfragments/6382.added.md)为 impl<T: Element> PyBuffer<T> 增加了两个方法,实现在 src/buffer.rs:

/// Gets the buffer memory as a slice.
///
/// Returns null if the buffer is not C-style contiguous
pub fn as_slice_ptr(&self) -> Option<NonNull<[T]>> {
    self.slice_pointer_internal(self.is_c_contiguous())
}

/// Gets the buffer memory as a slice.
///
/// This function returns null if the buffer is not Fortran-style contiguous
pub fn as_fortran_slice_ptr(&self) -> Option<NonNull<[T]>> {
    self.slice_pointer_internal(self.is_fortran_contiguous())
}

fn slice_pointer_internal(&self, contiguous: bool) -> Option<NonNull<[T]>> {
    if contiguous {
        NonNull::new(ptr::slice_from_raw_parts_mut(
            self.raw().buf.cast(),
            self.item_count(),
        ))
    } else {
        None
    }
}

要点如下:

特性 说明
返回值 Option<NonNull<[T]>>,即携带长度的胖指针;None 表示缓冲区不连续
长度语义 切片长度恒等于 item_count()(总元素数 = raw().len / raw().itemsize,见 src/buffer.rs)
连续性判定 as_slice_ptr 检查 C 序连续(is_c_contiguous()),as_fortran_slice_ptr 检查 Fortran 序连续(is_fortran_contiguous())
可变性 内部以 slice_from_raw_parts_mut 构造,返回 NonNull(非只读语义),但数据是否可写仍取决于底层对象的只读标志
生命周期 借用 &self,返回指针的生命周期被限制在借用期内

一个值得注意的设计差异:as_slice_ptr 与 as_fortran_slice_ptr 不要求 Python<'py> 令牌,而既有 as_slice(py) 系列方法需要显式传入 py。这使得新 API 可以在不触碰解释器上下文的代码路径(如纯数据处理、无 Python 句柄的辅助函数)中直接获取缓冲区内存视图。

与既有 as_slice 系列 API 的对比

PyBuffer<T> 此前已提供四组“以切片视图访问内存”的 API(src/buffer.rs):

方法 需 Python 令牌 返回类型 前置条件
as_slice(py) 是 Option<&[ReadOnlyCell<T>]> 格式/对齐兼容 T,且 C 序连续
as_mut_slice(py) 是 Option<&[Cell<T>]> 非只读,且 C 序连续
as_fortran_slice(py) 是 Option<&[ReadOnlyCell<T>]> 格式/对齐兼容 T,且 Fortran 序连续
as_fortran_mut_slice(py) 是 Option<&[Cell<T>]> 非只读,且 Fortran 序连续
as_slice_ptr() 否 Option<NonNull<[T]>> C 序连续
as_fortran_slice_ptr() 否 Option<NonNull<[T]>> Fortran 序连续

选择建议:

  • 需要安全借用且可迭代的只读/读写视图时,优先用 as_slice / as_mut_slice,它们返回 Rust 切片,可直接 for 遍历与索引;
  • 处于无 Python 上下文、或希望以最小开销拿到裸指针交给其他 Rust 代码(FFI 调用、手写 SIMD、发送给其它线程处理)时,用 as_slice_ptr / as_fortran_slice_ptr;
  • as_slice 返回的 ReadOnlyCell<T> 专为“Python 运行时可能随时修改缓冲区内容”设计(见 src/buffer.rs),是安全的只读视图;而 as_slice_ptr 返回裸的 NonNull<[T]>,内存安全完全由调用方负责。

实现原理:连续性检查与胖指针构造

slice_pointer_internal 的实现非常精简,但背后依赖两层逻辑:

  1. 连续性判定:is_c_contiguous() 与 is_fortran_contiguous() 定义在 PyUntypedBuffer 上(src/buffer.rs),分别调用 CPython 的 PyBuffer_IsContiguous(raw, b'C') 与 PyBuffer_IsContiguous(raw, b'F')。对一维缓冲区,C 序与 Fortran 序定义等价(两者恒为连续),仓库测试也明确断言了这一点(src/buffer.rs):“single-dimensional buffer is always contiguous”。

  2. 胖指针构造:ptr::slice_from_raw_parts_mut(self.raw().buf.cast(), self.item_count()) 把 Py_buffer.buf(*mut c_void)转换为 *mut [T] 元数据指针,再经 NonNull::new 封装。buf 即缓冲区内存起始地址;item_count() 为元素总数。若底层 buf 为 null,NonNull::new 会返回 None,从而避免构造非法指针。

实战示例:从 bytes / array.array 读取内存

以 PyBytes 为例,PyBuffer<u8>::get 即可拿到内存视图(对应仓库测试 src/buffer.rs):

use pyo3::prelude::*;
use pyo3::types::PyBytes;
use pyo3::buffer::PyBuffer;

Python::with_gil(|py| {
    let bytes = PyBytes::new(py, b"abcde");
    let buffer = PyBuffer::<u8>::get(&bytes).unwrap();

    // bytes 是一维缓冲区,C 序与 Fortran 序均连续
    let slice_ptr = buffer.as_slice_ptr().unwrap();
    assert_eq!(slice_ptr.len(), 5);
    assert_eq!(unsafe { *slice_ptr.as_ptr().cast::<u8>() }, b'a');

    let fortran_slice_ptr = buffer.as_fortran_slice_ptr().unwrap();
    assert_eq!(fortran_slice_ptr.len(), 5);
    assert_eq!(unsafe { *fortran_slice_ptr.as_ptr().cast::<u8>() }, b'a');
});

对于 array.array('f', ...) 这类带类型的对象,先 PyBuffer::<f32>::get 再调用 as_slice_ptr,即可获得可直接按 f32 元素寻址的内存区间(元素类型兼容性由 Element trait 校验,支持的整数/浮点类型见 src/buffer.rs)。

非连续缓冲区的处理

仓库测试 test_as_slice_ptr 用带步长的 memoryview 验证了失败路径:

// 步长为 2 的切片视图:shape = [3],strides = [2],非连续
let view = py.eval(c"memoryview(b'abcde')[::2]", None, None).unwrap();
let buffer = PyBuffer::<u8>::get(&view).unwrap();

assert_eq!(buffer.shape(), [3]);
assert_eq!(buffer.strides(), [2]);
assert!(buffer.as_slice_ptr().is_none());          // C 序非连续 -> None
assert!(buffer.as_fortran_slice_ptr().is_none());  // Fortran 序非连续 -> None

对非连续缓冲区,两个方法一律返回 None,不会尝试构造“看似连续”的切片,调用方必须显式处理 Option 的 None 分支(例如回退到 copy_to_slice / to_vec 拷贝语义,见 src/buffer.rs)。这也正是新 API 命名中带 ptr 的原因——它承诺的是“这块内存本身就是连续的元素序列”,而非逻辑索引视图。

内存安全与使用限制

使用 as_slice_ptr 时需要注意以下几点(均可在源码注释中找到依据):

  • 数据竞争风险:缓冲区内存可能被其他代码修改——包括释放 GIL 后运行的 Python 代码,或其他扩展模块。源码对 buf_ptr() 的警告同样适用于此(src/buffer.rs):必须自行保证原子访问或互斥,否则会构成数据竞争。
  • 只读语义由调用方维护:as_slice_ptr 返回可变指针构造的 NonNull<[T]>,但底层对象可能是只读的(readonly() 为真,如 bytes)。写操作前应检查 readonly(),或使用 as_slice 系只读视图。
  • abi3(limited API)限制:缓冲区 API 仅在完整 API 构建或 Python 3.11+ 下可用,模块顶层声明了 #![cfg(any(not(Py_LIMITED_API), Py_3_11))](src/buffer.rs);building-and-distribution 指南 同样注明 buffer API 需 Python 3.11 及以上。
  • 指针生命周期:返回的 NonNull<[T]> 借用自 &self,必须在 PyBuffer<T> 存活期间使用;缓冲区 Drop 时会调用 PyBuffer_Release,其后的指针访问为悬垂访问。

与 PyUntypedBuffer 演进的关系

仓库迁移指南(guide/src/migration.md)记录了缓冲区 API 的架构演进:PyBuffer<T> 现在是 PyUntypedBuffer 之上的类型化封装,format()、shape()、strides() 等大量方法迁移到了 PyUntypedBuffer。本次新增的 as_slice_ptr 与 as_fortran_slice_ptr 正是建立在这一分层之上:元数据查询走 PyUntypedBuffer(通过 Deref),而类型化切片指针落在 PyBuffer<T> 上,保证元素类型 T 与缓冲区格式、大小、对齐均已通过 ensure_compatible_with 校验,从而让 NonNull<[T]> 的转换具备类型安全前提。

结语

as_slice_ptr 与 as_fortran_slice_ptr 填补了 PyBuffer 在“无解释器上下文的零拷贝裸指针访问”场景的空白:签名更轻、语义更明确(连续则 Some,否则 None),并附带了完整的单元测试覆盖(src/buffer.rs)。在需要将 Python 缓冲区数据无缝交给 Rust 高性能代码路径(FFI、SIMD、线程池)时,这两个 API 是比 as_slice 更直接、比 buf_ptr() 更安全的中间选择。

登录后查看全文
pyo3