[−][src]Trait sp_std::alloc::AllocRef
allocator_api
)An implementation of AllocRef
can allocate, grow, shrink, 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.
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 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
alloc
,grow
, orshrink
, and -
the memory block has not been subsequently deallocated, where blocks are either deallocated directly by being passed to
dealloc
or were changed by being passed togrow
orshrink
that returnsOk
. Ifgrow
orshrink
have returnedErr
, 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 rangemin ..= max
, where:
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 alloc(
&mut self,
layout: Layout,
init: AllocInit
) -> Result<MemoryBlock, AllocErr>
&mut self,
layout: Layout,
init: AllocInit
) -> Result<MemoryBlock, AllocErr>
allocator_api
)Attempts to allocate a block of memory.
On success, returns a MemoryBlock
meeting the size and alignment guarantees of layout
.
The returned block may have a larger size than specified by layout.size()
and is
initialized as specified by init
, all the way up to the returned size of the block.
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)
allocator_api
)Deallocates the memory referenced by ptr
.
Safety
ptr
must denote a block of memory currently allocated via this allocator, andlayout
must fit that block of memory.
Provided methods
unsafe fn grow(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize,
placement: ReallocPlacement,
init: AllocInit
) -> Result<MemoryBlock, AllocErr>
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize,
placement: ReallocPlacement,
init: AllocInit
) -> Result<MemoryBlock, AllocErr>
allocator_api
)Attempts to extend the memory block.
Returns a new MemoryBlock
containing a pointer and the actual size of the allocated
memory. The pointer is suitable for holding data described by a new layout with layout
’s
alignment and a size given by new_size
. To accomplish this, the allocator may extend the
allocation referenced by ptr
to fit the new layout. If the placement
is
InPlace
, the returned pointer is guaranteed to be the same as the passed ptr
.
If MayMove
is used then ownership of the memory block referenced by ptr
is transferred to this allocator. The memory may or may not be freed, and should be
considered unusable (unless of course it is 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.
The memory block will contain the following contents after a successful call to grow
:
- Bytes
0..layout.size()
are preserved from the original allocation. - Bytes
layout.size()..old_size
will either be preserved or initialized according toinit
, depending on the allocator implementation.old_size
refers to the size of theMemoryBlock
prior to thegrow
call, which may be larger than the size that was originally requested when it was allocated. - Bytes
old_size..new_size
are initialized according toinit
.new_size
refers to the size of theMemoryBlock
returned by thegrow
call.
Safety
ptr
must denote a block of memory currently allocated via this allocator,layout
must fit that block of memory (Thenew_size
argument need not fit it.),new_size
must be greater than or equal tolayout.size()
, andnew_size
, when rounded up to the nearest multiple oflayout.align()
, must not overflow (i.e., the rounded value must be less than or equal tousize::MAX
).
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(
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize,
placement: ReallocPlacement
) -> Result<MemoryBlock, AllocErr>
&mut self,
ptr: NonNull<u8>,
layout: Layout,
new_size: usize,
placement: ReallocPlacement
) -> Result<MemoryBlock, AllocErr>
allocator_api
)Attempts to shrink the memory block.
Returns a new MemoryBlock
containing a pointer and the actual size of the allocated
memory. The pointer is suitable for holding data described by a new layout with layout
’s
alignment and a size given by new_size
. To accomplish this, the allocator may shrink the
allocation referenced by ptr
to fit the new layout. If the placement
is
InPlace
, the returned pointer is guaranteed to be the same as the passed ptr
.
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.
The behavior of how the allocator tries to shrink the memory is specified by placement
.
Safety
ptr
must denote a block of memory currently allocated via this allocator,layout
must fit that block of memory (Thenew_size
argument need not fit it.), andnew_size
must be smaller than or equal tolayout.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(&mut self) -> &mut Selfⓘ
allocator_api
)Creates a "by reference" adaptor for this instance of AllocRef
.
The returned adaptor also implements AllocRef
and will simply borrow this.