Struct zenoh_buffers::ZBuf

pub struct ZBuf { /* private fields */ }

A zenoh buffer.

ZBuf is a buffer that contains one or more ZSlices. It is used to efficiently send and receive data in zenoh. It provides transparent usage for both network and shared memory operations through a simple API.

By storing a set of ZSlice, it is possible to compose the target payload starting from a set of non-contiguous memory regions. This provides a twofold benefit: (1) the user can compose the payload in an incremental manner without requiring reallocations and (2) the payload is received and recomposed as it arrives from the network without reallocating any receiving buffer.

Example for creating a data buffer:

use zenoh_buffers::{ZBuf, ZSlice, traits::SplitBuffer, traits::buffer::InsertBuffer};

// Create a ZBuf containing a newly allocated vector of bytes.
let zbuf: ZBuf = vec![0_u8; 16].into();
assert_eq!(&vec![0_u8; 16], zbuf.contiguous().as_ref());

// Create a ZBuf containing twice a newly allocated vector of bytes.
// Allocate first a vectore of bytes and convert it into a ZSlice.
let zslice: ZSlice = vec![0_u8; 16].into();

let mut zbuf = ZBuf::default();
zbuf.append(zslice.clone()).unwrap(); // Cloning a ZSlice does not allocate
zbuf.append(zslice).unwrap();

assert_eq!(&vec![0_u8; 32], zbuf.contiguous().as_ref());

Calling contiguous() allows to acces to the whole payload as a contiguous &[u8] via the ZSlice type. However, this operation has a drawback when the original message was large enough to cause network fragmentation. Because of that, the actual message payload may have been received in multiple fragments (i.e. ZSlice) which are non-contiguous in memory.

use zenoh_buffers::{ZBuf, ZSlice, traits::SplitBuffer, traits::buffer::InsertBuffer};

// Create a ZBuf containing twice a newly allocated vector of bytes.
let zslice: ZSlice = vec![0_u8; 16].into();
let mut zbuf = ZBuf::default();
zbuf.append(zslice.clone());

// contiguous() does not allocate since zbuf contains only one slice
assert_eq!(&vec![0_u8; 16], zbuf.contiguous().as_ref());

// Add a second slice to zbuf
zbuf.append(zslice.clone());

// contiguous() allocates since zbuf contains two slices
assert_eq!(&vec![0_u8; 32], zbuf.contiguous().as_ref());

zslices_num() returns the number of ZSlices the ZBuf is composed of. If the returned value is greater than 1, then contiguous() will allocate. In order to retrieve the content of the ZBuf without allocating, it is possible to loop over its ZSlices.

Implementations

impl ZBuf

pub fn get_zslice(&self, index: usize) -> Option<&ZSlice>

Examples found in repository

src/zbuf.rs (line 213)

    fn copy_bytes(&self, bs: &mut [u8], mut pos: (usize, usize)) -> usize {
        let len = bs.len();

        let mut written = 0;
        while written < len {
            if let Some(slice) = self.get_zslice(pos.0) {
                let remaining = slice.len() - pos.1;
                let to_read = remaining.min(bs.len() - written);
                bs[written..written + to_read]
                    .copy_from_slice(&slice.as_slice()[pos.1..pos.1 + to_read]);
                written += to_read;
                pos = (pos.0 + 1, 0);
            } else {
                return written;
            }
        }
        written
    }

    #[cfg(feature = "shared-memory")]
    #[inline(always)]
    pub fn has_shminfo(&self) -> bool {
        self.has_shminfo
    }

    #[cfg(feature = "shared-memory")]
    #[inline(always)]
    pub fn has_shmbuf(&self) -> bool {
        self.has_shmbuf
    }

    #[cfg(feature = "shared-memory")]
    #[inline(never)]
    pub fn map_to_shmbuf(&mut self, shmr: Arc<RwLock<SharedMemoryReader>>) -> ZResult<bool> {
        if !self.has_shminfo() {
            return Ok(false);
        }

        let mut new_len = 0;

        let mut res = false;
        match &mut self.slices {
            ZBufInner::Single(s) => {
                res = s.map_to_shmbuf(shmr)?;
                new_len += s.len();
            }
            ZBufInner::Multiple(m) => {
                for s in m.iter_mut() {
                    res = res || s.map_to_shmbuf(shmr.clone())?;
                    new_len += s.len();
                }
            }
            ZBufInner::Empty => {}
        }
        self.len = new_len;
        self.has_shminfo = false;
        self.has_shmbuf = true;

        Ok(res)
    }

    #[cfg(feature = "shared-memory")]
    #[inline(never)]
    pub fn map_to_shminfo(&mut self) -> ZResult<bool> {
        if !self.has_shmbuf() {
            return Ok(false);
        }

        let mut new_len = 0;

        let mut res = false;
        match &mut self.slices {
            ZBufInner::Single(s) => {
                res = s.map_to_shminfo()?;
                new_len = s.len();
            }
            ZBufInner::Multiple(m) => {
                for s in m.iter_mut() {
                    res = res || s.map_to_shminfo()?;
                    new_len += s.len();
                }
            }
            ZBufInner::Empty => {}
        }
        self.has_shminfo = true;
        self.has_shmbuf = false;
        self.len = new_len;

        Ok(res)
    }
}

impl fmt::Display for ZBuf {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "ZBuf{{ content: ",)?;
        match &self.slices {
            ZBufInner::Single(s) => write!(f, "{}", hex::encode_upper(s.as_slice()))?,
            ZBufInner::Multiple(m) => {
                for s in m.iter() {
                    write!(f, "{}", hex::encode_upper(s.as_slice()))?;
                }
            }
            ZBufInner::Empty => {}
        }
        write!(f, " }}")
    }
}

impl fmt::Debug for ZBuf {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        macro_rules! zsliceprint {
            ($slice:expr) => {
                #[cfg(feature = "shared-memory")]
                {
                    match $slice.buf {
                        ZSliceBuffer::NetSharedBuffer(_) => write!(f, " BUF:")?,
                        ZSliceBuffer::NetOwnedBuffer(_) => write!(f, " BUF:")?,
                        ZSliceBuffer::ShmBuffer(_) => write!(f, " SHM_BUF:")?,
                        ZSliceBuffer::ShmInfo(_) => write!(f, " SHM_INFO:")?,
                    }
                }
                #[cfg(not(feature = "shared-memory"))]
                {
                    write!(f, " BUF:")?;
                }
            };
        }

        write!(f, "ZBuf{{ ")?;
        write!(f, "slices: [")?;
        match &self.slices {
            ZBufInner::Single(s) => {
                zsliceprint!(s);
                write!(f, "{}", hex::encode_upper(s.as_slice()))?;
            }
            ZBufInner::Multiple(m) => {
                for s in m.iter() {
                    zsliceprint!(s);
                    write!(f, " {},", hex::encode_upper(s.as_slice()))?;
                }
            }
            ZBufInner::Empty => {
                write!(f, " None")?;
            }
        }
        write!(f, " ] }}")
    }
}

impl<'a> ZBufReader<'a> {
    #[inline(always)]
    pub fn reset(&mut self) {
        self.read = 0;
        self.slice = 0;
        self.byte = 0;
    }
    // Read 'len' bytes from 'self' and add those to 'dest'
    // This is 0-copy, only ZSlices from 'self' are added to 'dest', without cloning the original buffer.
    pub fn read_into_zbuf(&mut self, dest: &mut ZBuf, len: usize) -> bool {
        if self.remaining() < len {
            return false;
        }
        let mut n = len;
        while n > 0 {
            let pos_1 = self.byte;
            let current = self.curr_slice().unwrap();
            let slice_len = current.len();
            let remain_in_slice = slice_len - pos_1;
            let l = n.min(remain_in_slice);
            let zs = match current.new_sub_slice(pos_1, pos_1 + l) {
                Some(zs) => zs,
                None => return false,
            };
            dest.add_zslice(zs);
            self.skip_bytes_no_check(l);
            n -= l;
        }
        true
    }
    // // Read all the bytes from 'self' and add those to 'dest'
    // #[inline(always)]
    // pub(crate) fn drain_into_zbuf(&mut self, dest: &mut ZBuf) -> bool {
    //     self.read_into_zbuf(dest, self.readable())
    // }
    // Read a subslice of current slice
    pub fn read_zslice(&mut self, len: usize) -> Option<ZSlice> {
        let slice = self.curr_slice()?;
        if len <= slice.len() {
            let slice = slice.new_sub_slice(self.byte, self.byte + len)?;
            self.skip_bytes_no_check(len);
            Some(slice)
        } else {
            None
        }
    }
    #[inline(always)]
    fn curr_slice(&self) -> Option<&ZSlice> {
        self.inner.get_zslice(self.slice)
    }

pub fn zslices_num(&self) -> usize

pub fn clear(&mut self)

Trait Implementations

impl Clone for ZBuf

fn clone(&self) -> ZBuf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl ConstructibleBuffer for ZBuf

fn with_capacities(slice_capacity: usize, _cache_capacity: usize) -> Self

Constructs a split buffer that may accept slice_capacity segments without allocating. It may also accept receiving cached writes for cache_capacity bytes before needing to reallocate its cache.

impl Debug for ZBuf

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

Formats the value using the given formatter.

impl Default for ZBuf

fn default() -> ZBuf

Returns the “default value” for a type.

impl Display for ZBuf

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

Formats the value using the given formatter.

impl<'a> From<Vec<IoSlice<'a>, Global>> for ZBuf

fn from(slices: Vec<IoSlice<'_>>) -> ZBuf

Converts to this type from the input type.

impl From<Vec<ZSlice, Global>> for ZBuf

fn from(slices: Vec<ZSlice>) -> ZBuf

Converts to this type from the input type.

impl From<Vec<u8, Global>> for ZBuf

fn from(buf: Vec<u8>) -> ZBuf

Converts to this type from the input type.

impl From<WBuf> for ZBuf

fn from(wbuf: WBuf) -> ZBuf

Converts to this type from the input type.

impl From<ZSlice> for ZBuf

fn from(slice: ZSlice) -> ZBuf

Converts to this type from the input type.

impl<'a> HasReader for &'a ZBuf

type Reader = ZBufReader<'a>

fn reader(self) -> Self::Reader

Returns the most appropriate reader for self

impl<T: Into<ZSlice>> InsertBuffer<T> for ZBuf

fn append(&mut self, slice: T) -> Option<NonZeroUsize>

Appends a slice to the buffer without copying its data.

impl PartialEq<ZBuf> for ZBuf

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> SplitBuffer<'a> for ZBuf

type Slices = Map<Iter<'a, ZSlice>, fn(_: &'a ZSlice) -> &'a [u8]>

fn slices(&'a self) -> Self::Slices

Gets all the slices of this buffer.

fn is_empty(&self) -> bool

Returns true if the buffer has a length of 0.

fn len(&self) -> usize

Returns the number of bytes in the buffer.

fn contiguous(&'a self) -> Cow<'a, [u8]>

Returns all the bytes of this buffer in a conitguous slice. This may require allocation and copy if the original buffer is not contiguous.