Struct Message

pub struct Message<T: ?Sized + 'static> { /* private fields */ }

A struct that holds both an arena along with a data buffer that is allocated within that arena.

Implementations

impl<T: ?Sized> Message<T>

pub fn new<'a>( arena: &'a Arena, data: Option<ArenaBox<'a, T>>, handles: Option<ArenaBox<'a, [Option<MixedHandle>]>>, ) -> Self

Consumes the given arena, data buffer, and handles buffers and returns a message that holds all three.

Panics

This function panics if either of the ArenaBoxs are not allocated by Arena.

pub fn new_with<F>(arena: Arena, f: F) -> Self

where F: for<'a> FnOnce(&'a Arena) -> (Option<ArenaBox<'a, T>>, Option<ArenaBox<'a, [Option<MixedHandle>]>>),

Given the Arena, allocates a new Message and runs the given f to allow the caller to allocate data and handles into the Message without requiring a check that the correct Arena was used to allocate the data.

Note that it may be possible to sneak an ArenaBox<'static, T> into this Message object with this function by using an Arena with static lifetime to allocate it. This will not cause any unsoundness, but if you try to send that message through a [Channel] it will cause a runtime error when the arenas don’t match.

pub fn new_with_data<F>(arena: Arena, f: F) -> Self

where F: for<'a> FnOnce(&'a Arena) -> ArenaBox<'a, T>,

A shorthand for Self::new_with when there’s definitely a data body and nothing else.

pub fn arena(&self) -> &Arena

Gets a reference to the arena this message was allocated with.

pub fn take_arena(self) -> Arena

Takes the arena and drops any data or handle bodies held in this message

pub fn data(&self) -> Option<&T>

Gets a reference to the data in this message, if there is any

pub fn data_mut(&mut self) -> Option<&mut T>

Gets a mutable reference to the data in this message, if there is any

pub fn map_data<F, R: ?Sized>(self, f: F) -> Message<R>

where F: for<'a> FnOnce(&'a Arena, ArenaBox<'a, T>) -> ArenaBox<'a, R>,

Maps the message data to a new ArenaBox based on the arena and the old data.

pub fn handles(&self) -> Option<&[Option<MixedHandle>]>

Gets a reference to the handles array in this message, if there is one.

pub fn handles_mut(&mut self) -> Option<&mut [Option<MixedHandle>]>

Gets a mutable reference to the handles array in this message, if there is one.

pub fn as_refs(&self) -> (&Arena, Option<&T>, Option<&[Option<MixedHandle>]>)

Gets a reference to all three of the arena, data, and handles of the message

pub fn as_mut_refs( &mut self, ) -> (&Arena, Option<&mut T>, Option<&mut [Option<MixedHandle>]>)

Gets a reference to the arena and mutable references to the data handles of the message

pub fn into_arena_boxes<'a>( self, arena: &'a mut Option<Arena>, ) -> (Option<ArenaBox<'a, T>>, Option<ArenaBox<'a, [Option<MixedHandle>]>>)

Unpacks the arena and buffers in this message to the caller.

The arena argument provides a place to put the Arena from this message in the local lifetime of the caller so that the ArenaBoxes can be tied to its lifetime.

pub fn take_arena_boxes( &mut self, ) -> (&Arena, Option<ArenaBox<'_, T>>, Option<ArenaBox<'_, [Option<MixedHandle>]>>)

Takes the ArenaBoxes for the data and handles from this Message, but leaves the Arena in the Message to act as a holder of the arena lifetime.

pub fn into_raw( self, ) -> (NonNull<fdf_arena_t>, Option<NonNull<T>>, Option<NonNull<[Option<MixedHandle>]>>)

Unpacks the arena and buffers into raw pointers

Care must be taken to ensure that the data and handle pointers are not used if the arena is freed. If they are never reconstituted into a Message or an Arena and ArenaBoxes, they will be leaked.

impl<T> Message<T>

pub fn take_data(self) -> Option<T>

Takes the data from the message, dropping the Arena and handles array in the process.

pub fn take_data_boxed(self) -> Option<Box<T>>

Takes the data from the message, dropping the Arena and handles array in the process.

impl<T> Message<[T]>

pub fn take_data_boxed_slice(self) -> Option<Box<[T]>>

Takes the data from the message, dropping the Arena and handles array in the process.

impl<T> Message<MaybeUninit<T>>

pub unsafe fn assume_init(self) -> Message<T>

Assumes the contents of the data payload of this message are initialized.

Safety

The caller is responsible for ensuring that the value is initialized properly. See MaybeUninit::assume_init for more details on the safety requirements of this.

impl<T> Message<[MaybeUninit<T>]>

pub unsafe fn assume_init(self) -> Message<[T]>

Assumes the contents of the data payload of this message are initialized.

Safety

The caller is responsible for ensuring that the value is initialized properly. See MaybeUninit::assume_init for more details on the safety requirements of this.

impl Message<[MaybeUninit<u8>]>

pub unsafe fn cast_unchecked<T>(self) -> Message<T>

Transforms the message body into a message of type T

Safety

The caller is responsible for ensuring that the data portion of this message originated from a source with a properly allocated T with correct alignment

Trait Implementations

impl<T: Debug + ?Sized + 'static> Debug for Message<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.