Trait MutableWritableMessage

pub trait MutableWritableMessage: MinimalWritableMessage {
    // Required methods
    fn available_space(&self) -> usize;
    fn payload_mut_with_len(
        &mut self,
        len: usize,
    ) -> Result<&mut [u8], Self::SetPayloadError>;
    fn truncate(&mut self, len: usize) -> Result<(), Self::SetPayloadError>;
    fn mutate_options<F>(&mut self, callback: F)
       where F: FnMut(Self::OptionNumber, &mut [u8]);
}

A message that allows later manipulation of a once set payload, and later truncation.

This is a bit of an unsorted bag that needs further cleanup (FIXME) – most of this is motivated by block-wise and write-in-place. Might need a bit of reshape, possibly following the Rust RFC 2884.

The available_space is mainly needed for applications that want to use up the last byte by not zero-padding the Block2 option to its szx=0 equivalent.

Can that be efficiently be replaced with something like this, and can it be optimized down to the hand-written counting-of-option-bytes that’s involved in the use of available_space?

let mut m = allocated_message;
for szx in 6..0 {
    snap = m.snapshot();
    m.add_option(BLOCK2, ...);
    m.add_option(..., ...);

    if let Ok(_) = m.write_payload(|p| {
        if (p.len() < 1 << (4 + szx)) {
            return Err(());
        }

        let written = write_block(...);

        Ok(written)
    }) {
        break;
    } else {
        m = m.revert_to(snap);
    }
} else {
    panic!("Allocated space doesn't even suffice for 16 byte payload");
}

Required Methods

fn available_space(&self) -> usize

Number of bytes available for additional options, payload marker and payload

fn payload_mut_with_len( &mut self, len: usize, ) -> Result<&mut [u8], Self::SetPayloadError>

Memory-map len bytes of the payload for writing

If a payload has been set previously, that payload will be available in the slice; in that case, the caller must make sure to not exceed its length.

If no payload has been set previously, and the requested length exceeds the available buffer space, the longest possible payload should be mapped.

fn truncate(&mut self, len: usize) -> Result<(), Self::SetPayloadError>

Truncate an already-set payload to the given length; that payload must have been written to before using MinimalWritableMessage::set_payload, or with a suitable MutableWritableMessage::payload_mut_with_len call.

fn mutate_options<F>(&mut self, callback: F)

where F: FnMut(Self::OptionNumber, &mut [u8]),

Apply a callback to all options in sequence

This is a possibly inefficient but generic way achieve “allocate first, set when done” pattern typically found for options like ETag.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T: MutableWritableMessage> MutableWritableMessage for &mut T

fn available_space(&self) -> usize

fn payload_mut_with_len( &mut self, len: usize, ) -> Result<&mut [u8], Self::SetPayloadError>

fn truncate(&mut self, len: usize) -> Result<(), Self::SetPayloadError>

fn mutate_options<F>(&mut self, callback: F)

where F: FnMut(Self::OptionNumber, &mut [u8]),

Implementors