pub unsafe trait Allocator {
// Required methods
fn allocate_segment(&mut self, minimum_size: u32) -> (*mut u8, u32);
unsafe fn deallocate_segment(
&mut self,
ptr: *mut u8,
word_size: u32,
words_used: u32
);
}
Expand description
An object that allocates memory for a Cap’n Proto message as it is being built.
Users of capnproto-rust who wish to provide memory in non-standard ways should
implement this trait. Objects implementing this trait are intended to be wrapped
by capnp::private::BuilderArena
, which handles calling the methods at the appropriate
times, including calling deallocate_segment()
on drop.
Safety
Implementions must ensure all of the following:
- The memory returned by
allocate_segment
is initialized to all zeroes. - The memory returned by
allocate_segment
is valid untildeallocate_segment()
is called on it. - The allocated memory does not overlap with other allocated memory.
- The allocated memory is 8-byte aligned (or the “unaligned” feature is enabled for the capnp crate).
Required Methods§
sourcefn allocate_segment(&mut self, minimum_size: u32) -> (*mut u8, u32)
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.
sourceunsafe fn deallocate_segment(
&mut self,
ptr: *mut u8,
word_size: u32,
words_used: u32
)
unsafe 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.
Safety
Callers must only call this method on a pointer that has previously been been returned
from allocate_segment()
, and only once on each such segment. word_size
must
equal the word size returned from allocate_segment()
, and words_used
must be at
most word_size
.