Struct std::alloc::Global

source ·
pub struct Global;
🔬This is a nightly-only experimental API. (allocator_api #32838)
Expand description

全局内存分配器。

此类型通过将调用转发到用 #[global_allocator] 属性注册的分配器 (如果有的话) 或 std crate 的默认值来实现 Allocator trait。

Note: 尽管此类型不稳定,但是可以通过 alloc 中的 free 函数 访问其提供的功能。

Implementations§

source§

impl<T> Box<T, Global>

1.0.0 · source

pub fn new(x: T) -> Box<T, Global>

在堆上分配内存,然后将 x 放入其中。

如果 T 的大小为零,则实际上不会分配。

Examples
let five = Box::new(5);
Run
source

pub fn new_uninit() -> Box<MaybeUninit<T>, Global>

🔬This is a nightly-only experimental API. (new_uninit #63291)

创建一个具有未初始化内容的新 box。

Examples
#![feature(new_uninit)]

let mut five = Box::<u32>::new_uninit();

let five = unsafe {
    // 延迟初始化:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5)
Run
source

pub fn new_zeroed() -> Box<MaybeUninit<T>, Global>

🔬This is a nightly-only experimental API. (new_uninit #63291)

创建一个具有未初始化内容的新 Box,并用 0 字节填充内存。

有关正确和不正确使用此方法的示例,请参见 MaybeUninit::zeroed

Examples
#![feature(new_uninit)]

let zero = Box::<u32>::new_zeroed();
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
Run
1.33.0 · source

pub fn pin(x: T) -> Pin<Box<T, Global>>

创建一个新的 Pin<Box<T>>。如果 T 没有实现 Unpin,那么 x 将被固定在内存中并且无法移动。

Box 的构建和固定也可以分两步完成: Box::pin(x)Box::into_pin(Box::new(x)) 相同。 如果您已经有 Box<T>,或者如果您想以与 Box::new 不同的方式构建 (pinned) Box,请考虑使用 into_pin

source

pub fn try_new(x: T) -> Result<Box<T, Global>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)

在堆上分配内存,然后将 x 放入其中,如果分配失败,则返回错误

如果 T 的大小为零,则实际上不会分配。

Examples
#![feature(allocator_api)]

let five = Box::try_new(5)?;
Run
source

pub fn try_new_uninit() -> Result<Box<MaybeUninit<T>, Global>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)

在堆上创建一个具有未初始化内容的新 box,如果分配失败,则返回错误

Examples
#![feature(allocator_api, new_uninit)]

let mut five = Box::<u32>::try_new_uninit()?;

let five = unsafe {
    // 延迟初始化:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5);
Run
source

pub fn try_new_zeroed() -> Result<Box<MaybeUninit<T>, Global>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)

创建一个具有未初始化内容的新 Box,堆中的内存由 0 字节填充

有关正确和不正确使用此方法的示例,请参见 MaybeUninit::zeroed

Examples
#![feature(allocator_api, new_uninit)]

let zero = Box::<u32>::try_new_zeroed()?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
Run
source§

impl<T> Box<[T], Global>

source

pub fn new_uninit_slice(len: usize) -> Box<[MaybeUninit<T>], Global>

🔬This is a nightly-only experimental API. (new_uninit #63291)

创建一个具有未初始化内容的新 boxed 切片。

Examples
#![feature(new_uninit)]

let mut values = Box::<[u32]>::new_uninit_slice(3);

let values = unsafe {
    // 延迟初始化:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);

    values.assume_init()
};

assert_eq!(*values, [1, 2, 3])
Run
source

pub fn new_zeroed_slice(len: usize) -> Box<[MaybeUninit<T>], Global>

🔬This is a nightly-only experimental API. (new_uninit #63291)

创建一个具有未初始化内容的新 boxed 切片,并用 0 字节填充内存。

有关正确和不正确使用此方法的示例,请参见 MaybeUninit::zeroed

Examples
#![feature(new_uninit)]

let values = Box::<[u32]>::new_zeroed_slice(3);
let values = unsafe { values.assume_init() };

assert_eq!(*values, [0, 0, 0])
Run
source

pub fn try_new_uninit_slice( len: usize ) -> Result<Box<[MaybeUninit<T>], Global>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)

创建一个具有未初始化内容的新 boxed 切片。 如果分配失败,则返回一个错误

Examples
#![feature(allocator_api, new_uninit)]

let mut values = Box::<[u32]>::try_new_uninit_slice(3)?;
let values = unsafe {
    // 延迟初始化:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);
    values.assume_init()
};

assert_eq!(*values, [1, 2, 3]);
Run
source

pub fn try_new_zeroed_slice( len: usize ) -> Result<Box<[MaybeUninit<T>], Global>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)

创建一个具有未初始化内容的新 boxed 切片,并用 0 字节填充内存。 如果分配失败,则返回一个错误

有关正确和不正确使用此方法的示例,请参见 MaybeUninit::zeroed

Examples
#![feature(allocator_api, new_uninit)]

let values = Box::<[u32]>::try_new_zeroed_slice(3)?;
let values = unsafe { values.assume_init() };

assert_eq!(*values, [0, 0, 0]);
Run
source§

impl<T> Box<T, Global>where T: ?Sized,

1.4.0 · source

pub unsafe fn from_raw(raw: *mut T) -> Box<T, Global>

从裸指针构造一个 box。

调用此函数后,结果 Box 拥有裸指针。 具体来说,Box 析构函数将调用 T 的析构函数并释放分配的内存。 为了安全起见,必须根据 Box 所使用的 内存布局 分配内存。

Safety

此函数不安全,因为使用不当可能会导致内存问题。 例如,如果在同一裸指针上两次调用该函数,则可能会出现 double-free。

安全条件在 内存布局 部分中进行了描述。

Examples

重新创建以前使用 Box::into_raw 转换为裸指针的 Box

let x = Box::new(5);
let ptr = Box::into_raw(x);
let x = unsafe { Box::from_raw(ptr) };
Run

使用二进制分配器从头开始手动创建 Box

use std::alloc::{alloc, Layout};

unsafe {
    let ptr = alloc(Layout::new::<i32>()) as *mut i32;
    // 通常,需要 .write 以避免尝试销毁 `ptr` 以前的内容,尽管对于这个简单的示例 `*ptr = 5` 也可以工作。
    ptr.write(5);
    let x = Box::from_raw(ptr);
}
Run

Trait Implementations§

source§

impl Allocator for Global

source§

fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)
尝试分配一块内存。 Read more
source§

fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)
行为类似于 allocate,但也确保返回的内存被零初始化。 Read more
source§

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

🔬This is a nightly-only experimental API. (allocator_api #32838)
释放 ptr 引用的内存。 Read more
source§

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)
尝试扩展内存块。 Read more
source§

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)
行为类似于 grow,但也确保在返回新内容之前将其设置为零。 Read more
source§

unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api #32838)
尝试缩小内存块。 Read more
source§

fn by_ref(&self) -> &Selfwhere Self: Sized,

🔬This is a nightly-only experimental API. (allocator_api #32838)
为这个 Allocator 实例创建一个 “by reference” 适配器。 Read more
source§

impl<S> AsyncIterator for Box<S, Global>where S: AsyncIterator + Unpin + ?Sized,

§

type Item = <S as AsyncIterator>::Item

🔬This is a nightly-only experimental API. (async_iterator #79024)
异步迭代器产生的项的类型。
source§

fn poll_next( self: Pin<&mut Box<S, Global>>, cx: &mut Context<'_> ) -> Poll<Option<<Box<S, Global> as AsyncIterator>::Item>>

🔬This is a nightly-only experimental API. (async_iterator #79024)
尝试提取此异步迭代器的下一个值,如果该值尚不可用,则注册当前任务以进行唤醒,如果异步迭代器耗尽,则返回 NoneRead more
source§

fn size_hint(&self) -> (usize, Option<usize>)

🔬This is a nightly-only experimental API. (async_iterator #79024)
返回异步迭代器剩余长度的界限。 Read more
1.29.0 · source§

impl Clone for Box<CStr, Global>

source§

fn clone(&self) -> Box<CStr, Global>

返回值的副本。 Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

source 执行复制分配。 Read more
1.3.0 · source§

impl Clone for Box<str, Global>

source§

fn clone(&self) -> Box<str, Global>

返回值的副本。 Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

source 执行复制分配。 Read more
source§

impl Clone for Global

source§

fn clone(&self) -> Global

返回值的副本。 Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

source 执行复制分配。 Read more
source§

impl Debug for Global

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

使用给定的格式化程序格式化该值。 Read more
1.0.0 · source§

impl<T> Default for Box<[T], Global>

source§

fn default() -> Box<[T], Global>

返回类型的 “默认值”。 Read more
1.17.0 · source§

impl Default for Box<CStr, Global>

source§

fn default() -> Box<CStr, Global>

返回类型的 “默认值”。 Read more
1.0.0 · source§

impl<T> Default for Box<T, Global>where T: Default,

source§

fn default() -> Box<T, Global>

创建一个 Box<T>,其 T 值为 Default

1.17.0 · source§

impl Default for Box<str, Global>

source§

fn default() -> Box<str, Global>

返回类型的 “默认值”。 Read more
source§

impl Default for Global

source§

fn default() -> Global

返回类型的 “默认值”。 Read more
1.8.0 · source§

impl<T> Error for Box<T, Global>where T: Error,

source§

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()
source§

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting
source§

fn source(&self) -> Option<&(dyn Error + 'static)>

此错误的下级来源 (如果有)。 Read more
source§

fn provide<'a>(&'a self, demand: &mut Demand<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access #99301)
提供对用于错误报告的上下文的基于类型的访问。 Read more
1.17.0 · source§

impl<T> From<&[T]> for Box<[T], Global>where T: Clone,

source§

fn from(slice: &[T]) -> Box<[T], Global>

&[T] 转换为 Box<[T]>

此转换在堆上分配并执行 slice 及其内容的副本。

Examples
// 创建 &[u8] which 将用于创建 Box<[u8]>
let slice: &[u8] = &[104, 101, 108, 108, 111];
let boxed_slice: Box<[u8]> = Box::from(slice);

println!("{boxed_slice:?}");
Run
1.17.0 · source§

impl From<&CStr> for Box<CStr, Global>

source§

fn from(s: &CStr) -> Box<CStr, Global>

通过将内容复制到新分配的 Box 中,将 &CStr 转换为 Box<CStr>

1.6.0 · source§

impl From<&str> for Box<dyn Error + 'static, Global>

source§

fn from(err: &str) -> Box<dyn Error + 'static, Global>

str 转换为 dyn Error 的 box。

Examples
use std::error::Error;
use std::mem;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error>::from(a_str_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run
1.0.0 · source§

impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a, Global>

source§

fn from(err: &str) -> Box<dyn Error + Send + Sync + 'a, Global>

str 转换为 Dyn Error + Send + Sync 的 box。

Examples
use std::error::Error;
use std::mem;

let a_str_error = "a str error";
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_str_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run
1.17.0 · source§

impl From<&str> for Box<str, Global>

source§

fn from(s: &str) -> Box<str, Global>

&str 转换为 Box<str>

此转换在堆上分配并执行 s 的副本。

Examples
let boxed: Box<str> = Box::from("hello");
println!("{boxed}");
Run
1.45.0 · source§

impl<T, const N: usize> From<[T; N]> for Box<[T], Global>

source§

fn from(array: [T; N]) -> Box<[T], Global>

[T; N] 转换为 Box<[T]>

此转换将数组移动到新的堆分配的内存中。

Examples
let boxed: Box<[u8]> = Box::from([4, 2]);
println!("{boxed:?}");
Run
1.20.0 · source§

impl From<CString> for Box<CStr, Global>

source§

fn from(s: CString) -> Box<CStr, Global>

CString 转换为 Box<CStr>,无需复制或分配。

1.45.0 · source§

impl<T> From<Cow<'_, [T]>> for Box<[T], Global>where T: Clone,

source§

fn from(cow: Cow<'_, [T]>) -> Box<[T], Global>

Cow<'_, [T]> 转换为 Box<[T]>

cowCow::Borrowed 变体时,此转换在堆上分配并复制底层切片。 否则,它将尝试重用拥有所有权的 Vec 的分配。

1.45.0 · source§

impl From<Cow<'_, CStr>> for Box<CStr, Global>

source§

fn from(cow: Cow<'_, CStr>) -> Box<CStr, Global>

通过复制借用的内容将 Cow<'a, CStr> 转换为 Box<CStr>

1.45.0 · source§

impl From<Cow<'_, str>> for Box<str, Global>

source§

fn from(cow: Cow<'_, str>) -> Box<str, Global>

Cow<'_, str> 转换为 Box<str>

cowCow::Borrowed 变体时,此转换在堆上分配并复制底层 str。 否则,它将尝试重用拥有所有权的 String 的分配。

Examples
use std::borrow::Cow;

let unboxed = Cow::Borrowed("hello");
let boxed: Box<str> = Box::from(unboxed);
println!("{boxed}");
Run
let unboxed = Cow::Owned("hello".to_string());
let boxed: Box<str> = Box::from(unboxed);
println!("{boxed}");
Run
1.22.0 · source§

impl<'a> From<Cow<'a, str>> for Box<dyn Error + 'static, Global>

source§

fn from(err: Cow<'a, str>) -> Box<dyn Error + 'static, Global>

Cow 转换为 dyn Error 的 box。

Examples
use std::error::Error;
use std::mem;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error>::from(a_cow_str_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run
1.22.0 · source§

impl<'a, 'b> From<Cow<'b, str>> for Box<dyn Error + Send + Sync + 'a, Global>

source§

fn from(err: Cow<'b, str>) -> Box<dyn Error + Send + Sync + 'a, Global>

Cow 转换为 Dyn Error + Send + Sync 的 box。

Examples
use std::error::Error;
use std::mem;
use std::borrow::Cow;

let a_cow_str_error = Cow::from("a str error");
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_cow_str_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run
1.0.0 · source§

impl<'a, E> From<E> for Box<dyn Error + 'a, Global>where E: Error + 'a,

source§

fn from(err: E) -> Box<dyn Error + 'a, Global>

Error 的类型转换为 dyn Error 的 box。

Examples
use std::error::Error;
use std::fmt;
use std::mem;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

let an_error = AnError;
assert!(0 == mem::size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error>::from(an_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run
1.0.0 · source§

impl<'a, E> From<E> for Box<dyn Error + Send + Sync + 'a, Global>where E: Error + Send + Sync + 'a,

source§

fn from(err: E) -> Box<dyn Error + Send + Sync + 'a, Global>

Error + Send + Sync 的类型转换为 Dyn Error + Send + Sync 的 box。

Examples
use std::error::Error;
use std::fmt;
use std::mem;

#[derive(Debug)]
struct AnError;

impl fmt::Display for AnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "An error")
    }
}

impl Error for AnError {}

unsafe impl Send for AnError {}

unsafe impl Sync for AnError {}

let an_error = AnError;
assert!(0 == mem::size_of_val(&an_error));
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(an_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run
1.6.0 · source§

impl From<String> for Box<dyn Error + 'static, Global>

source§

fn from(str_err: String) -> Box<dyn Error + 'static, Global>

String 转换为 dyn Error 的 box。

Examples
use std::error::Error;
use std::mem;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error>::from(a_string_error);
assert!(mem::size_of::<Box<dyn Error>>() == mem::size_of_val(&a_boxed_error))
Run
1.0.0 · source§

impl From<String> for Box<dyn Error + Send + Sync + 'static, Global>

source§

fn from(err: String) -> Box<dyn Error + Send + Sync + 'static, Global>

String 转换为 Dyn Error + Send + Sync 的 box。

Examples
use std::error::Error;
use std::mem;

let a_string_error = "a string error".to_string();
let a_boxed_error = Box::<dyn Error + Send + Sync>::from(a_string_error);
assert!(
    mem::size_of::<Box<dyn Error + Send + Sync>>() == mem::size_of_val(&a_boxed_error))
Run
1.20.0 · source§

impl From<String> for Box<str, Global>

source§

fn from(s: String) -> Box<str, Global>

将给定的 String 转换为拥有所有权的 boxed str 切片。

Examples

基本用法:

let s1: String = String::from("hello world");
let s2: Box<str> = Box::from(s1);
let s3: String = String::from(s2);

assert_eq!("hello world", s3)
Run
1.6.0 · source§

impl<T> From<T> for Box<T, Global>

source§

fn from(t: T) -> Box<T, Global>

T 转换为 Box<T>

转换在堆上分配,并将 t 从栈移到堆中。

Examples
let x = 5;
let boxed = Box::new(5);

assert_eq!(Box::from(x), boxed);
Run
1.32.0 · source§

impl<I> FromIterator<I> for Box<[I], Global>

source§

fn from_iter<T>(iter: T) -> Box<[I], Global>where T: IntoIterator<Item = I>,

从迭代器创建一个值。 Read more
1.43.0 · source§

impl<T, const N: usize> TryFrom<Box<[T], Global>> for Box<[T; N], Global>

source§

fn try_from( boxed_slice: Box<[T], Global> ) -> Result<Box<[T; N], Global>, <Box<[T; N], Global> as TryFrom<Box<[T], Global>>>::Error>

尝试将 Box<[T]> 转换为 Box<[T; N]>

转换就地发生,不需要新的内存分配。

Errors

如果 boxed_slice.len() 不等于 N,则返回 Err 变体中的旧 Box<[T]>

§

type Error = Box<[T], Global>

发生转换错误时返回的类型。
1.66.0 · source§

impl<T, const N: usize> TryFrom<Vec<T, Global>> for Box<[T; N], Global>

source§

fn try_from( vec: Vec<T, Global> ) -> Result<Box<[T; N], Global>, <Box<[T; N], Global> as TryFrom<Vec<T, Global>>>::Error>

尝试将 Vec<T> 转换为 Box<[T; N]>

Vec::into_boxed_slice 一样,如果 vec.capacity() == N 是就地的,则需要重新分配。

Errors

如果 boxed_slice.len() 不等于 N,则返回 Err 变体中的原始 Vec<T>

Examples

这可以与 vec! 一起用于在堆上创建一个数组:

let state: Box<[f32; 100]> = vec![1.0; 100].try_into().unwrap();
assert_eq!(state.len(), 100);
Run
§

type Error = Vec<T, Global>

发生转换错误时返回的类型。
source§

impl Copy for Global

source§

impl<T, U> DispatchFromDyn<Box<U, Global>> for Box<T, Global>where T: Unsize<U> + ?Sized, U: ?Sized,

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

获取 selfTypeIdRead more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

从拥有的值中一成不变地借用。 Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

从拥有的值中借用。 Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

返回未更改的参数。

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

调用 U::from(self)

也就是说,这种转换是 From<T> for U 实现选择执行的任何操作。

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

获得所有权后的结果类型。
source§

fn to_owned(&self) -> T

从借用的数据创建拥有的数据,通常是通过克隆。 Read more
source§

fn clone_into(&self, target: &mut T)

使用借来的数据来替换拥有的数据,通常是通过克隆。 Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

发生转换错误时返回的类型。
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

执行转换。
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

发生转换错误时返回的类型。
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

执行转换。