Trait core::alloc::Allocator[][src]

pub unsafe trait Allocator {
    fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>;
unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout); fn allocate_zeroed(
        &self,
        layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
unsafe fn grow(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
unsafe fn grow_zeroed(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
unsafe fn shrink(
        &self,
        ptr: NonNull<u8>,
        old_layout: Layout,
        new_layout: Layout
    ) -> Result<NonNull<[u8]>, AllocError> { ... }
fn by_ref(&self) -> &Self
    where
        Self: Sized
, { ... } }
🔬 This is a nightly-only experimental API. (allocator_api #32838)
Expand description

Allocator 的实现可以分配,增长,收缩和释放通过 Layout 描述的任意数据块。

Allocator 之所以将其设计为在 ZST,引用或智能指针上实现,是因为如果不更新指向已分配内存的指针,则无法移动具有 MyAlloc([u8; N]) 之类的分配器。

GlobalAlloc 不同,Allocator 允许零大小的分配。 如果基础分配器不支持此功能 (例如 jemalloc) 或返回空指针 (例如 libc::malloc),则必须由实现捕获。

当前分配的内存

某些方法要求通过分配器 currently 分配存储块。这意味着:

  • 该内存块的起始地址先前由 allocategrowshrink 返回,并且

  • 内存块随后并未被释放,其中的块要么通过传递到 deallocate 直接释放,要么通过传递到返回 Okgrowshrink 进行了更改。

如果 growshrink 返回了 Err,则传递的指针保持有效。

内存拟合

有些方法要求布局适合内存块。 对于到 “fit” 的布局,存储块意味着 (或者,对于到 “fit” 的存储块,布局意味着) 必须满足以下条件:

  • 必须以与 layout.align() 相同的对齐方式分配该块,并且

  • 提供的 layout.size() 必须在 min ..= max 范围内,其中:

    • min 是最近用于分配块的布局的大小,并且
    • max 是从 allocategrowshrink 返回的最新实际大小。

Safety

  • 从分配器返回的内存块必须指向有效内存并保持其有效性,直到丢弃实例及其所有克隆为止,

  • 克隆或移动分配器不得使此分配器返回的内存块无效。克隆的分配器的行为必须类似于相同的分配器,并且

  • 指向 currently allocated 的存储块的任何指针都可以传递给分配器的任何其他方法。

Required methods

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

尝试分配一块内存。

成功后,返回满足 layout 大小和对齐保证的 NonNull<[u8]>

返回的块的大小可能大于 layout.size() 指定的大小,并且可能已初始化或未初始化其内容。

Errors

返回 Err 表示内存已耗尽,或者 layout 不满足分配器的大小或对齐约束。

鼓励实现在内存耗尽时返回 Err,而不是恐慌或终止,但是这不是严格的要求。 (具体来说: 在一个底层的原生分配库上实现此 trait 是 合法的,该本地分配库在内存耗尽时中止。)

鼓励希望因分配错误而终止计算的客户调用 handle_alloc_error 函数,而不是直接调用 panic! 或类似方法。

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

释放 ptr 引用的内存。

Safety

  • ptr 必须通过此分配器表示一个内存块 currently allocated,并且
  • layout 必须 fit 该内存块。

Provided methods

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

行为类似于 allocate,但也确保返回的内存被零初始化。

Errors

返回 Err 表示内存已耗尽,或者 layout 不满足分配器的大小或对齐约束。

鼓励实现在内存耗尽时返回 Err,而不是恐慌或终止,但是这不是严格的要求。 (具体来说: 在一个底层的原生分配库上实现此 trait 是 合法的,该本地分配库在内存耗尽时中止。)

鼓励希望因分配错误而终止计算的客户调用 handle_alloc_error 函数,而不是直接调用 panic! 或类似方法。

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

尝试扩展内存块。

返回一个新的 NonNull<[u8]>,其中包含一个指针和分配的内存的实际大小。该指针适用于保存 new_layout 描述的数据。 为此,分配器可以扩展 ptr 引用的分配以适合新的布局。

如果返回 Ok,则 ptr 引用的内存块的所有权已转移到此分配器。 内存可能已释放,也可能尚未释放,除非已通过此方法的返回值再次将其转移回调用方,否则应将其视为不可用。

如果此方法返回 Err,则该存储块的所有权尚未转移到此分配器,并且该存储块的内容未更改。

Safety

  • ptr 必须通过此分配器表示一个内存 currently allocated 块。
  • old_layout 必须 fit 该内存块 (new_layout 参数不需要适合它。)。
  • new_layout.size() 必须大于或等于 old_layout.size()

Errors

如果新布局不符合分配器的大小和分配器的对齐约束,或者如果增长失败,则返回 Err

鼓励实现在内存耗尽时返回 Err,而不是恐慌或终止,但是这不是严格的要求。 (具体来说: 在一个底层的原生分配库上实现此 trait 是 合法的,该本地分配库在内存耗尽时中止。)

鼓励希望因分配错误而终止计算的客户调用 handle_alloc_error 函数,而不是直接调用 panic! 或类似方法。

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

行为类似于 grow,但也确保在返回新内容之前将其设置为零。

成功调用后,该存储块将包含以下内容 grow_zeroed:

  • 字节 0..old_layout.size() 从原始分配中保留。
  • 字节 old_layout.size()..old_size 将保留还是清零,具体取决于分配器的实现。 old_size 指的是 grow_zeroed 调用之前的内存块的大小,它可能大于分配时最初请求的大小。
  • 字节 old_size..new_size 被清零。new_size 是指 grow_zeroed 调用返回的存储块的大小。

Safety

  • ptr 必须通过此分配器表示一个内存 currently allocated 块。
  • old_layout 必须 fit 该内存块 (new_layout 参数不需要适合它。)。
  • new_layout.size() 必须大于或等于 old_layout.size()

Errors

如果新布局不符合分配器的大小和分配器的对齐约束,或者如果增长失败,则返回 Err

鼓励实现在内存耗尽时返回 Err,而不是恐慌或终止,但是这不是严格的要求。 (具体来说: 在一个底层的原生分配库上实现此 trait 是 合法的,该本地分配库在内存耗尽时中止。)

鼓励希望因分配错误而终止计算的客户调用 handle_alloc_error 函数,而不是直接调用 panic! 或类似方法。

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

尝试缩小内存块。

返回一个新的 NonNull<[u8]>,其中包含一个指针和分配的内存的实际大小。该指针适用于保存 new_layout 描述的数据。 为此,分配器可以缩小 ptr 引用的分配以适合新的布局。

如果返回 Ok,则 ptr 引用的内存块的所有权已转移到此分配器。 内存可能已释放,也可能尚未释放,除非已通过此方法的返回值再次将其转移回调用方,否则应将其视为不可用。

如果此方法返回 Err,则该存储块的所有权尚未转移到此分配器,并且该存储块的内容未更改。

Safety

  • ptr 必须通过此分配器表示一个内存 currently allocated 块。
  • old_layout 必须 fit 该内存块 (new_layout 参数不需要适合它。)。
  • new_layout.size() 必须小于或等于 old_layout.size()

Errors

如果新的布局不符合分配器的大小和分配器的对齐约束,或者缩小失败,则返回 Err

鼓励实现在内存耗尽时返回 Err,而不是恐慌或终止,但是这不是严格的要求。 (具体来说: 在一个底层的原生分配库上实现此 trait 是 合法的,该本地分配库在内存耗尽时中止。)

鼓励希望因分配错误而终止计算的客户调用 handle_alloc_error 函数,而不是直接调用 panic! 或类似方法。

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

为此 Allocator 实例创建 “by reference” 适配器。

返回的适配器还实现了 Allocator,将仅借用此适配器。

Implementors

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