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

# [−][src]Trait alloc::alloc::AllocRef

    pub unsafe trait AllocRef {
        fn alloc(
            &mut self,
            layout: Layout
        ) -> Result<(NonNull<u8>, usize), AllocErr>;
        unsafe fn dealloc(&mut self, ptr: NonNull<u8>, layout: Layout);

        fn alloc_zeroed(
            &mut self,
            layout: Layout
        ) -> Result<(NonNull<u8>, usize), AllocErr> { ... }
        unsafe fn realloc(
            &mut self,
            ptr: NonNull<u8>,
            layout: Layout,
            new_size: usize
        ) -> Result<(NonNull<u8>, usize), AllocErr> { ... }
        unsafe fn realloc_zeroed(
            &mut self,
            ptr: NonNull<u8>,
            layout: Layout,
            new_size: usize
        ) -> Result<(NonNull<u8>, usize), AllocErr> { ... }
        unsafe fn grow_in_place(
            &mut self,
            ptr: NonNull<u8>,
            layout: Layout,
            new_size: usize
        ) -> Result<usize, CannotReallocInPlace> { ... }
        unsafe fn grow_in_place_zeroed(
            &mut self,
            ptr: NonNull<u8>,
            layout: Layout,
            new_size: usize
        ) -> Result<usize, CannotReallocInPlace> { ... }
        unsafe fn shrink_in_place(
            &mut self,
            ptr: NonNull<u8>,
            layout: Layout,
            new_size: usize
        ) -> Result<usize, CannotReallocInPlace> { ... }
    }

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

An implementation of `AllocRef` can allocate, reallocate, and deallocate arbitrary blocks of data described via `Layout`.

`AllocRef` 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.

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 a previous call to an allocation method (`alloc`, `alloc_zeroed`) or reallocation method (`realloc`), and

- the memory block has not been subsequently deallocated, where blocks are deallocated either by being passed to a deallocation method (`dealloc`) or by being passed to a reallocation method (see above) that returns `Ok`.

Unlike `GlobalAlloc`, zero-sized allocations are allowed in `AllocRef`. If an underlying allocator does not support this (like jemalloc) or return a null pointer (such as `libc::malloc`), this case must be caught. In this case `Layout::dangling()` can be used to create a dangling, but aligned `NonNull<u8>`.

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 two conditions must hold:

1. The block's starting address must be aligned to `layout.align()`.

2. The block's size must fall in the range `[use_min, use_max]`, where:

   - `use_min` is `layout.size()`, and

   - `use_max` is the capacity that was returned.

Note that:

- the size of the layout most recently used to allocate the block is guaranteed to be in the range `[use_min, use_max]`, and

- a lower-bound on `use_max` can be safely approximated by a call to `usable_size`.

- if a layout `k` fits a memory block (denoted by `ptr`) currently allocated via an allocator `a`, then it is legal to use that layout to deallocate it, i.e., `a.dealloc(ptr, k);`.

- if an allocator does not support overallocating, it is fine to simply return `layout.size()` as the allocated size.

# Safety

The `AllocRef` trait is an `unsafe` trait for a number of reasons, and implementors must ensure that they adhere to these contracts:

- Pointers returned from allocation functions must point to valid memory and retain their validity until at least one instance of `AllocRef` is dropped itself.

- Cloning or moving the allocator must not invalidate pointers returned from this allocator. Cloning must return a reference to the same allocator.

- `Layout` queries and calculations in general must be correct. Callers of this trait are allowed to rely on the contracts defined on each method, and implementors must ensure such contracts remain true.

Note that this list may get tweaked over time as clarifications are made in the future.

## Required methods

### `fn alloc(&mut self, layout: Layout) -> Result<(NonNull<u8>, usize), AllocErr>`

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

On success, returns a pointer meeting the size and alignment guarantees of `layout` and the actual size of the allocated block, which must be greater than or equal to `layout.size()`.

If this method returns an `Ok(addr)`, then the `addr` returned will be non-null address pointing to a block of storage suitable for holding an instance of `layout`.

The returned block of storage may or may not have its contents initialized. (Extension subtraits might restrict this behavior, e.g., to ensure initialization to particular sets of bit patterns.)

# 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 dealloc(&mut self, ptr: NonNull<u8>, layout: Layout)`

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

Deallocate the memory referenced by `ptr`.

# Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

- `ptr` must denote a block of memory currently allocated via this allocator,

- `layout` must fit that block of memory,

- In addition to fitting the block of memory `layout`, the alignment of the `layout` must match the alignment used to allocate that block of memory.

Loading content...

## Provided methods

### `fn alloc_zeroed(
&mut self,
layout: Layout
) -> Result<(NonNull<u8>, usize), AllocErr>`

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

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

# Errors

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

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 realloc(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<(NonNull<u8>, usize), AllocErr>`

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

Returns a pointer suitable for holding data described by a new layout with `layout`’s alignment and a size given by `new_size` and the actual size of the allocated block. The latter is greater than or equal to `layout.size()`. To accomplish this, the allocator may extend or 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 of course 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

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

- `ptr` must be currently allocated via this allocator,

- `layout` must fit the `ptr` (see above). (The `new_size` argument need not fit it.)

- `new_size`, when rounded up to the nearest multiple of `layout.align()`, must not overflow (i.e., the rounded value must be less than `usize::MAX`).

(Extension subtraits might provide more specific bounds on behavior, e.g., guarantee a sentinel address or a null pointer in response to a zero-size allocation request.)

# Errors

Returns `Err` only if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if reallocation 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 a reallocation error are encouraged to call the `handle_alloc_error` function, rather than directly invoking `panic!` or similar.

### `unsafe fn realloc_zeroed(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<(NonNull<u8>, usize), AllocErr>`

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

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

# Safety

This function is unsafe for the same reasons that `realloc` is.

# Errors

Returns `Err` only if the new layout does not meet the allocator's size and alignment constraints of the allocator, or if reallocation 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 a reallocation error are encouraged to call the `handle_alloc_error` function, rather than directly invoking `panic!` or similar.

### `unsafe fn grow_in_place(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<usize, CannotReallocInPlace>`

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

Attempts to extend the allocation referenced by `ptr` to fit `new_size`.

If this returns `Ok`, then the allocator has asserted that the memory block referenced by `ptr` now fits `new_size`, and thus can be used to carry data of a layout of that size and same alignment as `layout`. The returned value is the new size of the allocated block. (The allocator is allowed to expend effort to accomplish this, such as extending the memory block to include successor blocks, or virtual memory tricks.)

Regardless of what this method returns, ownership of the memory block referenced by `ptr` has not been transferred, and the contents of the memory block are unaltered.

# Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

- `ptr` must be currently allocated via this allocator,

- `layout` must fit the `ptr` (see above); note the `new_size` argument need not fit it,

- `new_size` must not be less than `layout.size()`,

# Errors

Returns `Err(CannotReallocInPlace)` when the allocator is unable to assert that the memory block referenced by `ptr` could fit `layout`.

Note that one cannot pass `CannotReallocInPlace` to the `handle_alloc_error` function; clients are expected either to be able to recover from `grow_in_place` failures without aborting, or to fall back on another reallocation method before resorting to an abort.

### `unsafe fn grow_in_place_zeroed(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<usize, CannotReallocInPlace>`

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

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

# Safety

This function is unsafe for the same reasons that `grow_in_place` is.

# Errors

Returns `Err(CannotReallocInPlace)` when the allocator is unable to assert that the memory block referenced by `ptr` could fit `layout`.

Note that one cannot pass `CannotReallocInPlace` to the `handle_alloc_error` function; clients are expected either to be able to recover from `grow_in_place` failures without aborting, or to fall back on another reallocation method before resorting to an abort.

### `unsafe fn shrink_in_place(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<usize, CannotReallocInPlace>`

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

Attempts to shrink the allocation referenced by `ptr` to fit `new_size`.

If this returns `Ok`, then the allocator has asserted that the memory block referenced by `ptr` now fits `new_size`, and thus can only be used to carry data of that smaller layout. The returned value is the new size the allocated block. (The allocator is allowed to take advantage of this, carving off portions of the block for reuse elsewhere.) The truncated contents of the block within the smaller layout are unaltered, and ownership of block has not been transferred.

If this returns `Err`, then the memory block is considered to still represent the original (larger) `layout`. None of the block has been carved off for reuse elsewhere, ownership of the memory block has not been transferred, and the contents of the memory block are unaltered.

# Safety

This function is unsafe because undefined behavior can result if the caller does not ensure all of the following:

- `ptr` must be currently allocated via this allocator,

- `layout` must fit the `ptr` (see above); note the `new_size` argument need not fit it,

- `new_size` must not be greater than `layout.size()`,

# Errors

Returns `Err(CannotReallocInPlace)` when the allocator is unable to assert that the memory block referenced by `ptr` could fit `layout`.

Note that one cannot pass `CannotReallocInPlace` to the `handle_alloc_error` function; clients are expected either to be able to recover from `shrink_in_place` failures without aborting, or to fall back on another reallocation method before resorting to an abort.

Loading content...

## Implementors

### `impl AllocRef for Global`[src]

#### `fn alloc(&mut self, layout: Layout) -> Result<(NonNull<u8>, usize), AllocErr>`[src]

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

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

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

#### `unsafe fn realloc(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize
) -> Result<(NonNull<u8>, usize), AllocErr>`[src]

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

#### `fn alloc_zeroed(
&mut self,
layout: Layout
) -> Result<(NonNull<u8>, usize), AllocErr>`[src]

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