PyO3 为 PyBuffer 新增 as_slice_ptr 与 as_fortran_slice_ptr:无需 GIL 令牌的零拷贝缓冲区切片访问
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 的实现非常精简,但背后依赖两层逻辑:
-
连续性判定:
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”。 -
胖指针构造:
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+ 下可用,模块顶层声明了
#;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() 更安全的中间选择。