Struct FrameAllocator

pub struct FrameAllocator {
    inner: *mut FrameInnerAllocator,
    frame_id: Option<FrameId>,
}

A memory allocator for allocations that have the same lifetime as a built frame.

A custom allocator is used because:

• The frame is created on a thread and dropped on another thread, which causes lock contention in jemalloc.
• Since all allocations have a very similar lifetime, we can implement much faster allocation and deallocation with a specialized allocator than can be achieved with a general purpose allocator.

If the allocator is created using FrameAllocator::fallback(), it is not attached to a FrameMemory and simply falls back to the global allocator. This should only be used to handle deserialization (for wrench replays) and tests.

Safety

None of the safety restrictions below apply if the allocator is created using FrameAllocator::fallback.

FrameAllocator can move between thread if and only if it does so along with the FrameMemory it is associated to (if any). The opposite is also true: it is safe to move FrameMemory between threads if and only if all live frame allocators associated to it move along with it.

FrameAllocator must be dropped before the FrameMemory it is associated to.

In other words, FrameAllocator should only be used for containers that are in the Frame data structure and not stored elsewhere. The Frame holds on to its FrameMemory, allowing it all to be sent from the frame builder thread to the renderer thread together.

Another way to think of it is that the frame is a large self-referential data structure, holding on to its memory and a large number of containers that point into the memory.

Fields

inner: *mut FrameInnerAllocator

frame_id: Option<FrameId>

Implementations

impl FrameAllocator

pub fn fallback() -> Self

Creates a FrameAllocator that defaults to the global allocator.

Should only be used for testing purposes or desrialization in wrench replays.

pub fn new_vec<T>(self) -> Vec<T, FrameAllocator>

Shorthand for creating a FrameVec.

pub fn new_vec_with_capacity<T>(self, cap: usize) -> Vec<T, FrameAllocator>

Shorthand for creating a FrameVec.

fn allocate_impl( mem: *mut FrameInnerAllocator, layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

unsafe fn deallocate_impl( mem: *mut FrameInnerAllocator, ptr: NonNull<u8>, layout: Layout, )

unsafe fn grow_impl( mem: *mut FrameInnerAllocator, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

unsafe fn shrink_impl( mem: *mut FrameInnerAllocator, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

fn allocate_fallback(layout: Layout) -> Result<NonNull<[u8]>, AllocError>

fn deallocate_fallback(ptr: NonNull<u8>, layout: Layout)

fn grow_fallback( ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

fn check_frame_id(&self)

Trait Implementations

impl Allocator for FrameAllocator

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

Attempts to allocate a block of memory.

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

Deallocates the memory referenced by ptr.

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

Attempts to extend the memory block.

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

Attempts to shrink the memory block.

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

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

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

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

fn by_ref(&self) -> &Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Allocator.

impl Clone for FrameAllocator

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for FrameAllocator

fn drop(&mut self)

Executes the destructor for this type.

impl Serialize for FrameAllocator

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Send for FrameAllocator