MaybeUninit 未初始化 ​

核心概念 ​

std::mem::MaybeUninit<T> 是 Rust 中用于安全处理未初始化内存的类型。在 Rust 中,创建一个未初始化的值是未定义行为——即使你"打算之后再初始化",编译器也可能基于"值已初始化"的假设做优化,导致意想不到的结果。MaybeUninit<T> 通过将值包装在一个特殊容器中,告诉编译器"这块内存可能还没初始化",从而避免 UB。

MaybeUninit<T> 与 T 大小和对齐完全相同,但它不会自动调用 Drop,也不假设内容是有效的 T 值。你可以安全地创建一个未初始化的 MaybeUninit<T>,写入数据后通过 assume_init() 将其转换为 T。

rust
use std::mem::MaybeUninit;

fn main() {
    // 创建一个未初始化的 i32
    let mut uninit: MaybeUninit<i32> = MaybeUninit::uninit();

    // 写入值
    uninit.write(42);

    // 标记为已初始化,获取值
    // SAFETY: 刚通过 write 初始化了
    let value = unsafe { uninit.assume_init() };
    println!("值: {}", value);

    // 也可以用 zeroed 创建全零初始化
    let zeroed: MaybeUninit<u32> = MaybeUninit::zeroed();
    // SAFETY: 全零对 u32 是有效值
    let zero = unsafe { zeroed.assume_init() };
    println!("全零: {}", zero);
}

为什么需要 MaybeUninit ​

rust
use std::mem::MaybeUninit;

fn main() {
    // === 问题:未初始化值的 UB ===

    // 以下代码是 UB(即使看起来"没问题"):
    // let x: i32 = unsafe { std::mem::uninitialized() };  // 已废弃!UB!
    // 编译器可能假设 x 是有效值并据此优化

    // 对于 bool 更明显:
    // let b: bool = unsafe { std::mem::uninitialized() };
    // bool 只有 0 和 1 有效,未初始化的位模式几乎一定无效 → UB

    // 对于引用:
    // let r: &i32 = unsafe { std::mem::uninitialized() };
    // 引用不能为 null 或无效地址 → UB

    // === 解决方案:MaybeUninit ===

    // MaybeUninit 不假设内容有效
    let _uninit_bool: MaybeUninit<bool> = MaybeUninit::uninit();  // 安全!
    let _uninit_ref: MaybeUninit<&i32> = MaybeUninit::uninit();   // 安全!

    // MaybeUninit 不会调用 Drop
    let _uninit_string: MaybeUninit<String> = MaybeUninit::uninit();  // 安全!
    // 不会尝试 drop 未初始化的 String

    println!("MaybeUninit<bool> 大小: {}", std::mem::size_of::<MaybeUninit<bool>>());
    println!("bool 大小: {}", std::mem::size_of::<bool>());
    // 大小完全相同
}
方式是否 UB说明
mem::uninitialized()是已废弃,创建"有效"的未初始化值
mem::zeroed()可能对某些类型安全(数值),对引用等不安全
MaybeUninit::uninit()否安全地表示未初始化内存
MaybeUninit::zeroed()否安全地创建全零内存

MaybeUninit 的 API ​

rust
use std::mem::MaybeUninit;

fn main() {
    // === uninit():创建未初始化的值 ===
    let uninit: MaybeUninit<i32> = MaybeUninit::uninit();

    // === new(val):创建已初始化的值 ===
    let init: MaybeUninit<i32> = MaybeUninit::new(42);
    // SAFETY: 通过 new 创建的一定已初始化
    println!("new: {}", unsafe { init.assume_init() });

    // === zeroed():全零初始化 ===
    let zeroed: MaybeUninit<[u8; 16]> = MaybeUninit::zeroed();
    // SAFETY: 全零对 [u8; 16] 有效
    println!("zeroed: {:?}", unsafe { zeroed.assume_init() });

    // === write(val):写入值并返回 &mut T ===
    let mut mu = MaybeUninit::<String>::uninit();
    let s_ref = mu.write(String::from("hello"));
    println!("write 返回: {}", s_ref);

    // write 返回的引用可以直接使用
    s_ref.push_str(" world");
    println!("修改后: {}", s_ref);

    // SAFETY: 已通过 write 初始化
    let s = unsafe { mu.assume_init() };
    println!("assume_init: {}", s);

    // === assume_init():标记为已初始化 ===
    // 消耗 MaybeUninit,返回 T
    // 调用者必须保证值已初始化

    // === assume_init_ref() / assume_init_mut():获取引用 ===
    let mu = MaybeUninit::new(vec![1, 2, 3]);
    // SAFETY: 通过 new 创建
    let v_ref: &Vec<i32> = unsafe { mu.assume_init_ref() };
    println!("assume_init_ref: {:?}", v_ref);

    // === as_ptr() / as_mut_ptr():获取内部指针 ===
    let mut mu = MaybeUninit::<i32>::uninit();
    let ptr = mu.as_mut_ptr();
    // SAFETY: ptr 来自有效的 MaybeUninit
    unsafe { ptr.write(99); }
    let val = unsafe { mu.assume_init() };
    println!("通过指针写入: {}", val);
}

初始化数组 ​

rust
use std::mem::MaybeUninit;

fn main() {
    // === 逐个初始化数组元素 ===
    // 不能直接创建 [T; N] 的未初始化数组
    // 用 MaybeUninit 可以安全地逐个初始化

    // 方法1:MaybeUninit 数组
    let mut arr: [MaybeUninit<String>; 5] = [
        MaybeUninit::uninit(),
        MaybeUninit::uninit(),
        MaybeUninit::uninit(),
        MaybeUninit::uninit(),
        MaybeUninit::uninit(),
    ];

    // 逐个初始化
    for i in 0..5 {
        arr[i].write(format!("元素 {}", i));
    }

    // 将 [MaybeUninit<String>; 5] 转为 [String; 5]
    // SAFETY: 所有元素已通过 write 初始化
    let arr: [String; 5] = unsafe {
        // 使用 transmute 的替代方案
        let ptr = arr.as_ptr() as *const [String; 5];
        std::ptr::read(ptr)
    };

    println!("数组: {:?}", arr);

    // 方法2:使用 uninit_array(nightly)或手动方式
    // 对于 Copy 类型更简单
    let mut nums: [MaybeUninit<i32>; 10] = unsafe {
        MaybeUninit::uninit().assume_init()
    };

    for i in 0..10 {
        nums[i] = MaybeUninit::new((i + 1) as i32 * 10);
    }

    // 安全地读取
    print!("数字: ");
    for i in 0..10 {
        // SAFETY: 所有元素已初始化
        print!("{} ", unsafe { nums[i].assume_init() });
    }
    println!();

    // 方法3:使用 Vec 收集后转数组
    let arr: [i32; 5] = std::array::from_fn(|i| (i + 1) as i32 * 100);
    println!("from_fn: {:?}", arr);
}

部分初始化的处理 ​

rust
use std::mem::MaybeUninit;
use std::ptr;

/// 安全地处理可能部分初始化的数组
fn try_init_array<T, F>(init_fn: F) -> Result<[T; 5], String>
where
    F: Fn(usize) -> Result<T, String>,
{
    let mut arr: [MaybeUninit<T>; 5] = unsafe {
        MaybeUninit::uninit().assume_init()
    };

    let mut initialized = 0;

    for i in 0..5 {
        match init_fn(i) {
            Ok(val) => {
                arr[i] = MaybeUninit::new(val);
                initialized += 1;
            }
            Err(e) => {
                // 初始化失败,drop 已初始化的元素
                for j in 0..initialized {
                    // SAFETY: arr[j] 已初始化(j < initialized)
                    unsafe { ptr::drop_in_place(arr[j].as_mut_ptr()); }
                }
                return Err(format!("元素 {} 初始化失败: {}", i, e));
            }
        }
    }

    // SAFETY: 所有 5 个元素都已初始化
    Ok(unsafe {
        let ptr = arr.as_ptr() as *const [T; 5];
        ptr::read(ptr)
    })
}

fn main() {
    // 成功的情况
    println!("=== 成功初始化 ===");
    match try_init_array(|i| Ok(format!("项目 {}", i))) {
        Ok(arr) => println!("成功: {:?}", arr),
        Err(e) => println!("失败: {}", e),
    }

    // 失败的情况(在第3个元素处失败)
    println!("\n=== 部分失败 ===");
    match try_init_array(|i| {
        if i == 3 {
            Err("模拟错误".to_string())
        } else {
            Ok(format!("项目 {}", i))
        }
    }) {
        Ok(arr) => println!("成功: {:?}", arr),
        Err(e) => println!("失败: {} (已初始化的元素已正确释放)", e),
    }

    // 对 Copy 类型更简单
    println!("\n=== Copy 类型 ===");
    let arr: Result<[i32; 5], String> = try_init_array(|i| {
        if i < 5 { Ok((i + 1) as i32 * 10) } else { Err("越界".into()) }
    });
    println!("结果: {:?}", arr);
}

基本示例 ​

用 MaybeUninit 实现一个固定大小的栈:

rust
use std::mem::MaybeUninit;
use std::ptr;
use std::fmt;

/// 固定大小的栈,基于 MaybeUninit
struct FixedStack<T, const N: usize> {
    data: [MaybeUninit<T>; N],
    len: usize,
}

impl<T, const N: usize> FixedStack<T, N> {
    fn new() -> Self {
        FixedStack {
            // SAFETY: [MaybeUninit<T>; N] 不需要初始化
            data: unsafe { MaybeUninit::uninit().assume_init() },
            len: 0,
        }
    }

    fn push(&mut self, value: T) -> Result<(), T> {
        if self.len >= N {
            return Err(value);  // 栈满
        }
        // SAFETY: len < N,data[len] 未初始化,用 write 写入
        self.data[self.len] = MaybeUninit::new(value);
        self.len += 1;
        Ok(())
    }

    fn pop(&mut self) -> Option<T> {
        if self.len == 0 {
            return None;
        }
        self.len -= 1;
        // SAFETY: data[len] 已初始化(之前 push 过)
        Some(unsafe { self.data[self.len].assume_init_read() })
    }

    fn peek(&self) -> Option<&T> {
        if self.len == 0 {
            return None;
        }
        // SAFETY: data[len-1] 已初始化
        Some(unsafe { self.data[self.len - 1].assume_init_ref() })
    }

    fn len(&self) -> usize {
        self.len
    }

    fn is_empty(&self) -> bool {
        self.len == 0
    }

    fn is_full(&self) -> bool {
        self.len == N
    }

    fn capacity(&self) -> usize {
        N
    }

    fn clear(&mut self) {
        // Drop 所有元素
        for i in 0..self.len {
            // SAFETY: data[i] 已初始化(i < len)
            unsafe { ptr::drop_in_place(self.data[i].as_mut_ptr()); }
        }
        self.len = 0;
    }

    /// 获取所有元素的切片
    fn as_slice(&self) -> &[T] {
        // SAFETY: data[0..len] 都已初始化
        unsafe {
            std::slice::from_raw_parts(
                self.data.as_ptr() as *const T,
                self.len,
            )
        }
    }
}

impl<T, const N: usize> Drop for FixedStack<T, N> {
    fn drop(&mut self) {
        self.clear();
    }
}

impl<T: fmt::Debug, const N: usize> fmt::Debug for FixedStack<T, N> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.debug_list().entries(self.as_slice().iter()).finish()
    }
}

fn main() {
    // i32 栈
    println!("=== i32 栈 (容量 5) ===");
    let mut stack: FixedStack<i32, 5> = FixedStack::new();

    for i in 1..=5 {
        match stack.push(i * 10) {
            Ok(()) => println!("push {}: {:?}", i * 10, stack),
            Err(v) => println!("push {} 失败(满)", v),
        }
    }

    // 栈满
    match stack.push(60) {
        Ok(()) => {}
        Err(v) => println!("push {} 失败: is_full={}", v, stack.is_full()),
    }

    println!("peek: {:?}", stack.peek());
    println!("切片: {:?}", stack.as_slice());

    // pop
    println!("\n=== pop ===");
    while let Some(val) = stack.pop() {
        println!("pop: {}, 剩余: {}", val, stack.len());
    }
    println!("is_empty: {}", stack.is_empty());

    // String 栈(测试 Drop)
    println!("\n=== String 栈 (容量 3) ===");
    let mut str_stack: FixedStack<String, 3> = FixedStack::new();
    str_stack.push(String::from("Hello")).unwrap();
    str_stack.push(String::from("World")).unwrap();
    str_stack.push(String::from("Rust")).unwrap();
    println!("{:?}", str_stack);

    // clear 会 drop 所有 String
    str_stack.clear();
    println!("clear 后: {:?}, len={}", str_stack, str_stack.len());

    // 再次使用
    str_stack.push(String::from("重新使用")).unwrap();
    println!("重新使用: {:?}", str_stack);
    // str_stack drop 时正确释放剩余的 String

    // 内存效率
    println!("\n=== 内存 ===");
    println!("FixedStack<i32, 10> 大小: {} 字节",
        std::mem::size_of::<FixedStack<i32, 10>>());
    println!("MaybeUninit<i32> 大小: {} (等于 i32)",
        std::mem::size_of::<MaybeUninit<i32>>());
    println!("MaybeUninit<String> 大小: {} (等于 String)",
        std::mem::size_of::<MaybeUninit<String>>());
}

常见问题 ​

问题一:MaybeUninit 和 Option 有什么区别?

Option<T> 追踪值是否存在(Some/None),有额外的内存开销(判别位)。MaybeUninit<T> 与 T 大小完全相同,没有额外开销,但由程序员负责追踪初始化状态。Option 是安全的,MaybeUninit 需要 unsafe。

问题二:MaybeUninit::zeroed() 安全吗?

创建 MaybeUninit::zeroed() 本身是安全的。但 assume_init() 是否安全取决于全零是否是 T 的有效值。对数值类型(i32、f64 等)安全,对引用(全零=null)不安全,对 bool(全零=false)安全。

问题三:MaybeUninit 会被 Drop 吗?

不会。MaybeUninit<T> 不实现 Drop,它不会自动调用内部值的析构器。如果 T 需要 drop(如 String、Vec),必须在丢弃 MaybeUninit 之前手动调用 assume_init() 获取值让它正常 drop,或者用 ptr::drop_in_place 手动析构。

问题四:什么时候用 MaybeUninit?

当你需要延迟初始化(先分配内存,后填充数据)、逐个初始化数组元素、或者与 FFI 交互时接收外部写入的数据时使用。日常 Rust 编程中很少需要直接使用它。

适用场景 ​

  • 延迟初始化:先分配内存,后续再填充数据
  • 逐个初始化数组:无法一次性构造所有元素时
  • FFI 缓冲区:为 C 函数提供输出缓冲区
  • 自定义集合:Vec、HashMap 等底层实现

注意事项 ​

  • 不要对未初始化的 MaybeUninit 调用 assume_init
  • MaybeUninit 不自动 Drop 内部值
  • 部分初始化失败时要手动 drop 已初始化的元素
  • zeroed() 不是所有类型都安全(引用、NonNull 等不行)
  • 已废弃的 mem::uninitialized() 不要再使用
  • MaybeUninit<T> 与 T 大小和对齐完全相同

总结 ​

MaybeUninit<T> 是 Rust 中安全处理未初始化内存的标准方式。它取代了已废弃的 mem::uninitialized(),通过告诉编译器"这块内存可能未初始化"来避免未定义行为。MaybeUninit<T> 与 T 大小完全相同,不自动调用 Drop。通过 uninit() 创建未初始化值,write() 写入数据,assume_init() 标记为已初始化并获取值。对于数组的逐个初始化,MaybeUninit 是唯一正确的方式。部分初始化失败时必须手动 drop 已初始化的元素防止泄漏。日常编程中很少直接使用 MaybeUninit,它主要用于底层集合实现、FFI 缓冲区和延迟初始化等场景。