Struct capnp::message::ScratchSpaceHeapAllocator

pub struct ScratchSpaceHeapAllocator<'a> { /* private fields */ }

An Allocator whose first segment is a backed by a user-provided buffer.

Recall that an Allocator implementation must ensure that allocated segments are initially zeroed. ScratchSpaceHeapAllocator ensures that is the case by zeroing the entire buffer upon initial construction, and then zeroing any potentially used part of the buffer upon deallocate_segment().

You can reuse a ScratchSpaceHeapAllocator by calling message::Builder::into_allocator(), or by initally passing it to message::Builder::new() as a &mut ScratchSpaceHeapAllocator. Such reuse can save significant amounts of zeroing.

Implementations

impl<'a> ScratchSpaceHeapAllocator<'a>

pub fn new(scratch_space: &'a mut [u8]) -> ScratchSpaceHeapAllocator<'a>

Writes zeroes into the entire buffer and constructs a new allocator from it.

If the buffer is large, this operation could be relatively expensive. If you want to reuse the same scratch space in a later message, you should reuse the entire ScratchSpaceHeapAllocator, to avoid paying this full cost again.

pub fn second_segment_words(self, value: u32) -> ScratchSpaceHeapAllocator<'a>

Sets the size of the second segment in words, where 1 word = 8 bytes. (The first segment is the scratch space passed to ScratchSpaceHeapAllocator::new().

pub fn allocation_strategy(
    self,
    value: AllocationStrategy
) -> ScratchSpaceHeapAllocator<'a>

Sets the allocation strategy for segments after the second one.

Trait Implementations

impl<'a> Allocator for ScratchSpaceHeapAllocator<'a>

fn allocate_segment(&mut self, minimum_size: u32) -> (*mut u8, u32)

Allocates zeroed memory for a new segment, returning a pointer to the start of the segment and a u32 indicating the length of the segment in words. The allocated segment must be at least minimum_size words long (minimum_size * 8 bytes long). Allocator implementations commonly allocate much more than the minimum, to reduce the total number of segments needed. A reasonable strategy is to allocate the maximum of minimum_size and twice the size of the previous segment.

fn deallocate_segment(&mut self, ptr: *mut u8, word_size: u32, words_used: u32)

Indicates that a segment, previously allocated via allocate_segment(), is no longer in use. word_size is the length of the segment in words, as returned from allocate_segment(). words_used is always less than or equal to word_size, and indicates how many words (contiguous from the start of the segment) were possibly written with non-zero values.