unsafe 函数 ​

核心概念 ​

unsafe fn 声明一个 unsafe 函数,表示调用者必须满足该函数的安全前置条件(safety preconditions),否则可能导致未定义行为。unsafe 函数的整个函数体都被视为 unsafe 上下文,可以直接执行 unsafe 操作而不需要额外的 unsafe 块(不过从 Rust 2024 edition 开始,编译器建议在 unsafe fn 内部也使用 unsafe 块来明确标记具体的 unsafe 操作)。调用 unsafe 函数必须在 unsafe 块中进行。unsafe 函数通常用于底层操作,对外暴露时应该附带详细的 # Safety 文档,说明调用者需要满足什么条件。

rust
/// 从裸指针读取一个值
///
/// # 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 的区别 ​

rust
// 普通函数:编译器保证安全,任何地方都可以调用
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);
}
特性普通函数 fnunsafe 函数 unsafe fn
调用方式直接调用必须在 unsafe 块中
安全保证编译器保证调用者负责
文档要求普通文档必须有 # Safety 文档
函数体安全上下文unsafe 上下文
适用场景一般逻辑底层操作、FFI

unsafe fn 的 Safety 文档 ​

rust
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
// 从 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 ​

rust
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 实现一个简化的内存池:

rust
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 版本供不同场景使用。