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

pub unsafe trait AllocRef: Copy {
    fn alloc(
        self, 
        layout: Layout, 
        init: AllocInit
    ) -> Result<MemoryBlock, AllocErr>;

    unsafe fn dealloc(self, memory: MemoryBlock);

    unsafe fn grow(
        self, 
        memory: &mut MemoryBlock, 
        new_size: usize, 
        placement: ReallocPlacement, 
        init: AllocInit
    ) -> Result<(), AllocErr> { ... }

    unsafe fn shrink(
        self, 
        memory: &mut MemoryBlock, 
        new_size: usize, 
        placement: ReallocPlacement
    ) -> Result<(), AllocErr> { ... }
}

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 case must be caught.

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, and

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

Required methods

fn alloc(self, layout: Layout, init: AllocInit) -> Result<MemoryBlock, AllocErr>

On success, returns a memory block 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(self, memory: MemoryBlock)

Deallocates the memory denoted by memory.

Safety

memory must be a memory block returned by this allocator.

Loading content...

Provided methods

unsafe fn grow(
    self,
    memory: &mut MemoryBlock,
    new_size: usize,
    placement: ReallocPlacement,
    init: AllocInit
) -> Result<(), AllocErr>

Attempts to extend the memory block.

The behavior of how the allocator tries to grow the memory is specified by placement. The first memory.size() bytes are preserved or copied as appropriate from ptr, and the remaining bytes up to the new memory.size() are initialized according to init.

Safety

  • memory must be a memory block returned by this allocator.
  • new_size must be greater than or equal to memory.size()
  • new_size, when rounded up to the nearest multiple of memory.align(), must not overflow (i.e., the rounded value must be less than usize::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(
    self,
    memory: &mut MemoryBlock,
    new_size: usize,
    placement: ReallocPlacement
) -> Result<(), AllocErr>

Attempts to shrink the memory block.

The behavior of how the allocator tries to shrink the memory is specified by placement.

Safety

  • memory must be a memory block returned by this allocator.
  • new_size must be smaller than or equal to memory.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.

Loading content...

Implementors

impl AllocRef for Global[src]

impl AllocRef for System[src]

Loading content...