MaybeUninit 未初始化
核心概念
std::mem::MaybeUninit<T> 是 Rust 中用于安全处理未初始化内存的类型。在 Rust 中,创建一个未初始化的值是未定义行为——即使你"打算之后再初始化",编译器也可能基于"值已初始化"的假设做优化,导致意想不到的结果。MaybeUninit<T> 通过将值包装在一个特殊容器中,告诉编译器"这块内存可能还没初始化",从而避免 UB。
MaybeUninit<T> 与 T 大小和对齐完全相同,但它不会自动调用 Drop,也不假设内容是有效的 T 值。你可以安全地创建一个未初始化的 MaybeUninit<T>,写入数据后通过 assume_init() 将其转换为 T。
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
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
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);
}初始化数组
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);
}部分初始化的处理
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 实现一个固定大小的栈:
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 缓冲区和延迟初始化等场景。