unsafe 函数
核心概念
unsafe fn 声明一个 unsafe 函数,表示调用者必须满足该函数的安全前置条件(safety preconditions),否则可能导致未定义行为。unsafe 函数的整个函数体都被视为 unsafe 上下文,可以直接执行 unsafe 操作而不需要额外的 unsafe 块(不过从 Rust 2024 edition 开始,编译器建议在 unsafe fn 内部也使用 unsafe 块来明确标记具体的 unsafe 操作)。调用 unsafe 函数必须在 unsafe 块中进行。unsafe 函数通常用于底层操作,对外暴露时应该附带详细的 # Safety 文档,说明调用者需要满足什么条件。
/// 从裸指针读取一个值
///
/// # Safety
///
/// - `ptr` 必须非空
/// - `ptr` 必须正确对齐
/// - `ptr` 必须指向一个已初始化的 `T` 值
/// - `ptr` 指向的内存在调用期间不能被其他代码修改
unsafe fn read_value<T: Copy>(ptr: *const T) -> T {
// 在 unsafe fn 中可以直接执行 unsafe 操作
*ptr
}
fn main() {
let x = 42;
let ptr = &x as *const i32;
// 调用 unsafe 函数需要在 unsafe 块中
// SAFETY: ptr 来自有效的引用,非空、对齐、指向已初始化的 i32,
// 且在调用期间 x 不会被修改。
let value = unsafe { read_value(ptr) };
println!("值: {}", value);
}unsafe fn 与普通 fn 的区别
// 普通函数:编译器保证安全,任何地方都可以调用
fn safe_add(a: i32, b: i32) -> i32 {
a + b
}
// unsafe 函数:调用者负责安全,必须在 unsafe 块中调用
/// # Safety
/// - `ptr` 必须非空且指向有效的 i32
/// - `offset` 不能导致指针越界
unsafe fn read_at_offset(ptr: *const i32, offset: usize) -> i32 {
*ptr.add(offset)
}
fn main() {
// 普通函数直接调用
let sum = safe_add(1, 2);
println!("safe: {}", sum);
// unsafe 函数必须在 unsafe 块中调用
let data = [10, 20, 30];
// SAFETY: data.as_ptr() 非空且对齐,offset 1 在数组范围内。
let val = unsafe { read_at_offset(data.as_ptr(), 1) };
println!("unsafe: {}", val);
}| 特性 | 普通函数 fn | unsafe 函数 unsafe fn |
|---|---|---|
| 调用方式 | 直接调用 | 必须在 unsafe 块中 |
| 安全保证 | 编译器保证 | 调用者负责 |
| 文档要求 | 普通文档 | 必须有 # Safety 文档 |
| 函数体 | 安全上下文 | unsafe 上下文 |
| 适用场景 | 一般逻辑 | 底层操作、FFI |
unsafe fn 的 Safety 文档
use std::slice;
/// 从裸指针和长度创建一个切片引用。
///
/// # Safety
///
/// 调用者必须保证以下条件:
/// - `ptr` 必须非空且正确对齐到 `T` 的对齐要求
/// - `ptr` 必须指向连续的、已初始化的 `len` 个 `T` 值
/// - 返回的切片的生命周期不能超过 `ptr` 指向的内存的有效期
/// - 在返回的切片存活期间,不能通过其他指针修改这块内存
unsafe fn make_slice<'a, T>(ptr: *const T, len: usize) -> &'a [T] {
slice::from_raw_parts(ptr, len)
}
/// 交换两个裸指针指向的值。
///
/// # Safety
///
/// - `a` 和 `b` 必须非空且正确对齐
/// - `a` 和 `b` 必须指向已初始化的 `T` 值
/// - `a` 和 `b` 指向的内存区域不能重叠
/// - 调用者必须拥有对 `a` 和 `b` 的独占写入权
unsafe fn swap_raw<T>(a: *mut T, b: *mut T) {
std::ptr::swap(a, b);
}
fn main() {
// 使用 make_slice
let data = [1, 2, 3, 4, 5];
// SAFETY: data.as_ptr() 非空、对齐,data 有 5 个元素,
// 返回的切片生命周期在 data 有效范围内。
let slice = unsafe { make_slice(data.as_ptr(), 5) };
println!("切片: {:?}", slice);
// 使用 swap_raw
let mut a = 10;
let mut b = 20;
// SAFETY: 两个指针来自不同的局部变量,非空、对齐、
// 已初始化、不重叠,我们拥有独占访问权。
unsafe { swap_raw(&mut a as *mut i32, &mut b as *mut i32) };
println!("交换后: a={}, b={}", a, b);
}Rust 2024 Edition 中的变化
// 从 Rust 2024 edition 开始,unsafe fn 的函数体不再自动作为 unsafe 上下文
// 需要在内部显式使用 unsafe 块
/// # Safety
/// - `ptr` 必须非空且指向有效的 i32 数组
/// - `len` 不能超过数组实际长度
unsafe fn sum_array_2024(ptr: *const i32, len: usize) -> i32 {
let mut total = 0;
for i in 0..len {
// Rust 2024 edition 中需要显式 unsafe 块
// SAFETY: 由调用者保证 ptr.add(i) 在有效范围内
total += unsafe { *ptr.add(i) };
}
total
}
// 旧风格(Rust 2021 及之前):整个函数体是 unsafe 上下文
// unsafe fn sum_array_old(ptr: *const i32, len: usize) -> i32 {
// let mut total = 0;
// for i in 0..len {
// total += *ptr.add(i); // 不需要 unsafe 块
// }
// total
// }
fn main() {
let data = [10, 20, 30, 40, 50];
// SAFETY: data.as_ptr() 有效,5 是数组实际长度。
let sum = unsafe { sum_array_2024(data.as_ptr(), 5) };
println!("总和: {}", sum);
}封装 unsafe 为安全 API
use std::slice;
// 好的模式:unsafe 操作封装在安全函数中
// 公共 API 是安全的,内部使用 unsafe
/// 将切片分成两半(安全接口)
fn split_at(data: &[i32], mid: usize) -> (&[i32], &[i32]) {
assert!(mid <= data.len(), "mid 超出切片长度");
let ptr = data.as_ptr();
let len = data.len();
// SAFETY:
// - ptr 来自 data.as_ptr(),有效且对齐
// - mid <= len(已通过 assert 检查)
// - 两个切片 [0..mid) 和 [mid..len) 不重叠
// - 生命周期与 data 绑定
unsafe {
(
slice::from_raw_parts(ptr, mid),
slice::from_raw_parts(ptr.add(mid), len - mid),
)
}
}
/// 查找第一个满足条件的元素的指针(安全接口)
fn find_first(data: &[i32], predicate: impl Fn(i32) -> bool) -> Option<&i32> {
let ptr = data.as_ptr();
for i in 0..data.len() {
// SAFETY: i 在 0..data.len() 范围内,ptr.add(i) 有效。
let val = unsafe { &*ptr.add(i) };
if predicate(*val) {
return Some(val);
}
}
None
}
/// 不安全的内部函数 + 安全的公共接口
struct SafeArray {
data: Vec<i32>,
}
impl SafeArray {
fn new(data: Vec<i32>) -> Self {
SafeArray { data }
}
// 安全的公共方法:做了边界检查
fn get(&self, index: usize) -> Option<&i32> {
if index < self.data.len() {
// SAFETY: 已检查 index < len
Some(unsafe { self.get_unchecked(index) })
} else {
None
}
}
// unsafe 的内部方法:跳过边界检查
/// # Safety
/// index 必须小于 self.data.len()
unsafe fn get_unchecked(&self, index: usize) -> &i32 {
&*self.data.as_ptr().add(index)
}
}
fn main() {
// 使用安全接口
let data = vec![5, 15, 25, 35, 45];
let (left, right) = split_at(&data, 3);
println!("左: {:?}", left);
println!("右: {:?}", right);
if let Some(val) = find_first(&data, |x| x > 20) {
println!("第一个大于20的: {}", val);
}
let arr = SafeArray::new(data);
println!("arr[2] = {:?}", arr.get(2));
println!("arr[10] = {:?}", arr.get(10)); // None,不会 panic
}基本示例
用 unsafe fn 实现一个简化的内存池:
use std::alloc::{alloc, dealloc, Layout};
use std::ptr;
struct SimplePool {
buffer: *mut u8, // 缓冲区起始地址
layout: Layout, // 内存布局
offset: usize, // 当前分配偏移
capacity: usize, // 总容量
}
impl SimplePool {
/// 创建一个指定容量的内存池
fn new(capacity: usize) -> Self {
let layout = Layout::from_size_align(capacity, 8).unwrap();
// SAFETY: layout 的 size > 0,对齐为 8(有效的 2 的幂)
let buffer = unsafe { alloc(layout) };
if buffer.is_null() {
panic!("内存分配失败");
}
SimplePool {
buffer,
layout,
offset: 0,
capacity,
}
}
/// 从池中分配一块内存(安全接口)
fn allocate(&mut self, size: usize, align: usize) -> Option<*mut u8> {
// 对齐偏移
let aligned_offset = (self.offset + align - 1) & !(align - 1);
if aligned_offset + size > self.capacity {
return None; // 空间不足
}
// SAFETY: buffer 非空(在 new 中检查过),
// aligned_offset + size <= capacity(刚检查过)
let ptr = unsafe { self.buffer.add(aligned_offset) };
self.offset = aligned_offset + size;
Some(ptr)
}
/// 在池中分配并写入一个值
fn alloc_value<T>(&mut self, value: T) -> Option<&mut T> {
let size = std::mem::size_of::<T>();
let align = std::mem::align_of::<T>();
let ptr = self.allocate(size, align)?;
let typed_ptr = ptr as *mut T;
// SAFETY: ptr 来自 allocate,已正确对齐到 T 的对齐要求,
// 分配的空间足够存放一个 T。typed_ptr 不与其他存活的引用重叠。
unsafe {
ptr::write(typed_ptr, value);
Some(&mut *typed_ptr)
}
}
/// 已使用的字节数
fn used(&self) -> usize {
self.offset
}
/// 剩余字节数
fn remaining(&self) -> usize {
self.capacity - self.offset
}
/// 重置池(不调用析构函数)
///
/// # Safety
///
/// 调用者必须确保池中分配的所有引用都不再被使用。
/// 池中存储的值的析构函数不会被调用。
unsafe fn reset(&mut self) {
self.offset = 0;
}
}
impl Drop for SimplePool {
fn drop(&mut self) {
// SAFETY: buffer 和 layout 在 new 中通过 alloc 获得,
// 现在归还给分配器。
unsafe {
dealloc(self.buffer, self.layout);
}
}
}
fn main() {
let mut pool = SimplePool::new(1024);
println!("内存池容量: {} 字节", pool.remaining());
// 分配整数
if let Some(num) = pool.alloc_value(42_i32) {
println!("分配 i32: {}", num);
*num = 100;
println!("修改后: {}", num);
}
// 分配字符串数据(注意:这里存的是固定大小的数组,不是 String)
if let Some(arr) = pool.alloc_value([1u8, 2, 3, 4, 5]) {
println!("分配数组: {:?}", arr);
}
// 分配多个值
let mut values = Vec::new();
for i in 0..10 {
if let Some(val) = pool.alloc_value(i as f64 * 1.5) {
values.push(val as *const f64);
}
}
println!("\n已用: {} 字节, 剩余: {} 字节", pool.used(), pool.remaining());
// 读取分配的值
for (i, &ptr) in values.iter().enumerate() {
// SAFETY: ptr 是从 alloc_value 返回的有效指针,
// 我们没有释放或重置池,所以它们仍然有效。
let val = unsafe { *ptr };
println!(" values[{}] = {:.1}", i, val);
}
}常见问题
问题一:什么时候应该把函数标记为 unsafe?
当函数有调用者必须满足的前置条件,且这些条件无法通过类型系统或运行时检查来保证时,应该标记为 unsafe fn。如果所有前置条件都能在函数内部检查(如边界检查),就应该做成安全函数。
问题二:unsafe fn 内部还需要 unsafe 块吗?
Rust 2024 edition 建议在 unsafe fn 内部也使用 unsafe 块来标记具体的 unsafe 操作。这样更清晰,也方便用 SAFETY 注释说明每个操作的安全性。旧版本中整个函数体是 unsafe 上下文,不需要额外的 unsafe 块。
问题三:unsafe fn 可以调用安全函数吗?
可以。unsafe fn 内部可以调用任何函数——安全的和 unsafe 的都行。unsafe 只是额外允许了 unsafe 操作,不影响调用安全函数。
问题四:应该暴露 unsafe fn 还是封装成安全 API?
尽量封装成安全 API。只在无法在函数内部验证所有前置条件时才暴露 unsafe fn。标准库的做法是提供安全版本(如 Vec::get)和 unsafe 版本(如 Vec::get_unchecked),让用户根据场景选择。
适用场景
- 底层内存操作:裸指针读写、内存分配
- FFI 桥接:包装 C 函数
- 性能关键路径:跳过边界检查的快速版本
- 硬件交互:设备寄存器读写
注意事项
- unsafe fn 必须附带
# Safety文档说明前置条件 - 调用 unsafe fn 必须在 unsafe 块中
- 优先封装为安全的公共 API
- Rust 2024 edition 建议在 unsafe fn 内也用 unsafe 块
- unsafe fn 不意味着函数一定危险,而是安全性由调用者负责
- unsafe fn 内部的安全操作仍然受编译器检查
总结
unsafe fn 声明安全性由调用者负责的函数,调用时必须在 unsafe 块中。unsafe fn 必须附带 # Safety 文档,明确说明调用者需要满足的前置条件。函数内部可以执行 unsafe 操作,Rust 2024 edition 建议在 unsafe fn 内也使用 unsafe 块标记具体操作。实际项目中应优先将 unsafe 操作封装在安全的公共函数中(内部做完所有检查后再执行 unsafe 操作),只在无法内部验证前置条件时才暴露 unsafe fn。标准库常见的模式是提供安全版本和 unsafe 的 unchecked 版本供不同场景使用。