core::alloc::Allocator - Rust
Description: API documentation for the Rust `Allocator` trait in crate `core`.
Keywords: rust, rustlang, rust-lang, Allocator

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

    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 { ... }
    }

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

An implementation of `Allocator` can allocate, grow, shrink, and deallocate arbitrary blocks of data described via `Layout`.

`Allocator` is designed to be implemented on ZSTs, references, or smart pointers because having an allocator like `MyAlloc([u8; N])` cannot be moved, without updating the pointers to the allocated memory.

Unlike `GlobalAlloc`, zero-sized allocations are allowed in `Allocator`. If an underlying allocator does not support this (like jemalloc) or return a null pointer (such as `libc::malloc`), this must be caught by the implementation.

### Currently allocated memory

Some of the methods require that a memory block be currently allocated via an allocator. This means that:

- the starting address for that memory block was previously returned by `allocate`, `grow`, or `shrink`, and

- the memory block has not been subsequently deallocated, where blocks are either deallocated directly by being passed to `deallocate` or were changed by being passed to `grow` or `shrink` that returns `Ok`. If `grow` or `shrink` have returned `Err`, the passed pointer remains valid.

### Memory fitting

Some of the methods require that a layout fit a memory block. What it means for a layout to "fit" a memory block means (or equivalently, for a memory block to "fit" a layout) is that the following conditions must hold:

- The block must be allocated with the same alignment as `layout.align()`, and

- The provided `layout.size()` must fall in the range `min ..= max`, where:

  - `min` is the size of the layout most recently used to allocate the block, and
  - `max` is the latest actual size returned from `allocate`, `grow`, or `shrink`.

# Safety

- Memory blocks returned from an allocator must point to valid memory and retain their validity until the instance and all of its clones are dropped,

- cloning or moving the allocator must not invalidate memory blocks returned from this allocator. A cloned allocator must behave like the same allocator, and

- any pointer to a memory block which is currently allocated may be passed to any other method of the allocator.

## Required methods

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

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

Attempts to allocate a block of memory.

On success, returns a `NonNull<[u8]>` meeting the size and alignment guarantees of `layout`.

The returned block may have a larger size than specified by `layout.size()`, and may or may not have its contents initialized.

# Errors

Returning `Err` indicates that either memory is exhausted or `layout` does not meet allocator's size or alignment constraints.

Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this trait atop an underlying native allocation library that aborts on memory exhaustion.)

Clients wishing to abort computation in response to an allocation error are encouraged to call the `handle_alloc_error` function, rather than directly invoking `panic!` or similar.

### `unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)`[src]

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

Deallocates the memory referenced by `ptr`.

# Safety

- `ptr` must denote a block of memory currently allocated via this allocator, and
- `layout` must fit that block of memory.

Loading content...

## Provided methods

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

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

Behaves like `allocate`, but also ensures that the returned memory is zero-initialized.

# Errors

Returning `Err` indicates that either memory is exhausted or `layout` does not meet allocator's size or alignment constraints.

Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this trait atop an underlying native allocation library that aborts on memory exhaustion.)

Clients wishing to abort computation in response to an allocation error are encouraged to call the `handle_alloc_error` function, rather than directly invoking `panic!` or similar.

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

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

Attempts to extend the memory block.

Returns a new `NonNull<[u8]>` containing a pointer and the actual size of the allocated memory. The pointer is suitable for holding data described by `new_layout`. To accomplish this, the allocator may extend the allocation referenced by `ptr` to fit the new layout.

If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been transferred to this allocator. The memory may or may not have been freed, and should be considered unusable unless it was transferred back to the caller again via the return value of this method.

If this method returns `Err`, then ownership of the memory block has not been transferred to this allocator, and the contents of the memory block are unaltered.

# Safety

- `ptr` must denote a block of memory currently allocated via this allocator.
- `old_layout` must fit that block of memory (The `new_layout` argument need not fit it.).
- `new_layout.size()` must be greater than or equal to `old_layout.size()`.

# Errors

Returns `Err` if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if growing otherwise fails.

Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this trait atop an underlying native allocation library that aborts on memory exhaustion.)

Clients wishing to abort computation in response to an allocation error are encouraged to call the `handle_alloc_error` function, rather than directly invoking `panic!` or similar.

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

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

Behaves like `grow`, but also ensures that the new contents are set to zero before being returned.

The memory block will contain the following contents after a successful call to `grow_zeroed`:

- Bytes `0..old_layout.size()` are preserved from the original allocation.
- Bytes `old_layout.size()..old_size` will either be preserved or zeroed, depending on the allocator implementation. `old_size` refers to the size of the memory block prior to the `grow_zeroed` call, which may be larger than the size that was originally requested when it was allocated.
- Bytes `old_size..new_size` are zeroed. `new_size` refers to the size of the memory block returned by the `grow_zeroed` call.

# Safety

- `ptr` must denote a block of memory currently allocated via this allocator.
- `old_layout` must fit that block of memory (The `new_layout` argument need not fit it.).
- `new_layout.size()` must be greater than or equal to `old_layout.size()`.

# Errors

Returns `Err` if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if growing otherwise fails.

Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this trait atop an underlying native allocation library that aborts on memory exhaustion.)

Clients wishing to abort computation in response to an allocation error are encouraged to call the `handle_alloc_error` function, rather than directly invoking `panic!` or similar.

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

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

Attempts to shrink the memory block.

Returns a new `NonNull<[u8]>` containing a pointer and the actual size of the allocated memory. The pointer is suitable for holding data described by `new_layout`. To accomplish this, the allocator may shrink the allocation referenced by `ptr` to fit the new layout.

If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been transferred to this allocator. The memory may or may not have been freed, and should be considered unusable unless it was transferred back to the caller again via the return value of this method.

If this method returns `Err`, then ownership of the memory block has not been transferred to this allocator, and the contents of the memory block are unaltered.

# Safety

- `ptr` must denote a block of memory currently allocated via this allocator.
- `old_layout` must fit that block of memory (The `new_layout` argument need not fit it.).
- `new_layout.size()` must be smaller than or equal to `old_layout.size()`.

# Errors

Returns `Err` if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if shrinking otherwise fails.

Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or aborting, but this is not a strict requirement. (Specifically: it is legal to implement this trait atop an underlying native allocation library that aborts on memory exhaustion.)

Clients wishing to abort computation in response to an allocation error are encouraged to call the `handle_alloc_error` function, rather than directly invoking `panic!` or similar.

### `fn by_ref(&self) -> &Self`[src]

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

Creates a "by reference" adaptor for this instance of `Allocator`.

The returned adaptor also implements `Allocator` and will simply borrow this.

Loading content...

## Implementors

### `impl<A: ?Sized> Allocator for &A where
A: Allocator,` [src]

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

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

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

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

#### `unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)`[src]

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

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

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

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

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

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

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