Struct zenoh_protocol::io::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>

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) -> ZBuf

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<(), Error>

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<(), Error>

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

fn from(buf: Vec<u8, Global>) -> 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) -> <&'a ZBuf as HasReader>::Reader

Returns the most appropriate reader for self

impl<T> InsertBuffer<T> for ZBufwhere
    T: Into<ZSlice>,

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: &ZBuf) -> 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) -> <ZBuf as SplitBuffer<'a>>::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.