Struct Producer 

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

Producer part of ring buffer.

Implementations

impl<T: Send + Sized + 'static> Producer<T>

pub fn capacity(&self) -> usize

Returns capacity of the ring buffer.

The capacity of the buffer is constant.

pub fn is_empty(&self) -> bool

Checks if the ring buffer is empty.

The result is relevant until you push items to the producer.

pub fn is_full(&self) -> bool

Checks if the ring buffer is full.

The result may become irrelevant at any time because of concurring activity of the consumer.

Examples found in repository

examples/message.rs (line 24)

fn main() {
    let collector = Collector::new();

    let buf = RingBuffer::<u8>::new(10);
    let (mut prod, mut cons) = buf.split(&collector.handle());

    let smsg = "The quick brown fox jumps over the lazy dog";

    let pjh = thread::spawn(move || {
        println!("-> sending message: '{}'", smsg);

        let zero = [0];
        let mut bytes = smsg.as_bytes().chain(&zero[..]);
        loop {
            if prod.is_full() {
                println!("-> buffer is full, waiting");
                thread::sleep(Duration::from_millis(1));
            } else {
                let n = prod.read_from(&mut bytes, None).unwrap();
                if n == 0 {
                    break;
                }
                println!("-> {} bytes sent", n);
            }
        }

        println!("-> message sent");
    });

    let cjh = thread::spawn(move || {
        println!("<- receiving message");

        let mut bytes = Vec::<u8>::new();
        loop {
            if cons.is_empty() {
                if bytes.ends_with(&[0]) {
                    break;
                } else {
                    println!("<- buffer is empty, waiting");
                    thread::sleep(Duration::from_millis(1));
                }
            } else {
                let n = cons.write_into(&mut bytes, None).unwrap();
                println!("<- {} bytes received", n);
            }
        }

        assert_eq!(bytes.pop().unwrap(), 0);
        let msg = String::from_utf8(bytes).unwrap();
        println!("<- message received: '{}'", msg);

        msg
    });

    pjh.join().unwrap();
    let rmsg = cjh.join().unwrap();

    assert_eq!(smsg, rmsg);
}

pub fn len(&self) -> usize

The length of the data stored in the buffer.

Actual length may be equal to or less than the returned value.

pub fn remaining(&self) -> usize

The remaining space in the buffer.

Actual remaining space may be equal to or greater than the returning value.

pub unsafe fn push_access<F>(&mut self, f: F) -> usize

where F: FnOnce(&mut [MaybeUninit<T>], &mut [MaybeUninit<T>]) -> usize,

Allows to write into ring buffer memory directly.

This function is unsafe because it gives access to possibly uninitialized memory

The method takes a function f as argument. f takes two slices of ring buffer content (the second one or both of them may be empty). First slice contains older elements.

f should return number of elements been written. There is no checks for returned number - it remains on the developer’s conscience.

The method always calls f even if ring buffer is full.

The method returns number returned from f.

Safety

The method gives access to ring buffer underlying memory which may be uninitialized.

pub unsafe fn push_copy(&mut self, elems: &[MaybeUninit<T>]) -> usize

Copies data from the slice to the ring buffer in byte-to-byte manner.

The elems slice should contain initialized data before the method call. After the call the copied part of data in elems should be interpreted as un-initialized.

Returns the number of items been copied.

Safety

The method copies raw data into the ring buffer.

You should properly fill the slice and manage remaining elements after copy.

pub fn push(&mut self, elem: T) -> Result<(), T>

Appends an element to the ring buffer. On failure returns an error containing the element that hasn’t been appended.

Examples found in repository

examples/simple.rs (line 12)

fn main() {
    let collector = Collector::new();

    let rb = RingBuffer::<i32>::new(2);
    let (mut prod, mut cons) = rb.split(&collector.handle());

    prod.push(0).unwrap();
    prod.push(1).unwrap();
    assert_eq!(prod.push(2), Err(2));

    assert_eq!(cons.pop().unwrap(), 0);

    prod.push(2).unwrap();

    assert_eq!(cons.pop().unwrap(), 1);
    assert_eq!(cons.pop().unwrap(), 2);
    assert_eq!(cons.pop(), None);
}

pub fn push_each<F: FnMut() -> Option<T>>(&mut self, f: F) -> usize

Repeatedly calls the closure f and pushes elements returned from it to the ring buffer.

The closure is called until it returns None or the ring buffer is full.

The method returns number of elements been put into the buffer.

pub fn push_iter<I: Iterator<Item = T>>(&mut self, elems: &mut I) -> usize

Appends elements from an iterator to the ring buffer. Elements that haven’t been added to the ring buffer remain in the iterator.

Returns count of elements been appended to the ring buffer.

pub fn move_from( &mut self, other: &mut Consumer<T>, count: Option<usize>, ) -> usize

Removes at most count elements from the consumer and appends them to the producer. If count is None then as much as possible elements will be moved. The producer and consumer parts may be of different buffers as well as of the same one.

On success returns number of elements been moved.

impl<T: Copy + Send + Sized + 'static> Producer<T>

pub fn push_slice(&mut self, elems: &[T]) -> usize

Appends elements from slice to the ring buffer. Elements should be Copy.

Returns count of elements been appended to the ring buffer.

impl Producer<u8>

pub fn read_from( &mut self, reader: &mut dyn Read, count: Option<usize>, ) -> Result<usize>

Reads at most count bytes from Read instance and appends them to the ring buffer. If count is None then as much as possible bytes will be read.

Returns Ok(n) if read succeeded. n is number of bytes been read. n == 0 means that either read returned zero or ring buffer is full.

If read is failed or returned an invalid number then error is returned.

Examples found in repository

examples/message.rs (line 28)

fn main() {
    let collector = Collector::new();

    let buf = RingBuffer::<u8>::new(10);
    let (mut prod, mut cons) = buf.split(&collector.handle());

    let smsg = "The quick brown fox jumps over the lazy dog";

    let pjh = thread::spawn(move || {
        println!("-> sending message: '{}'", smsg);

        let zero = [0];
        let mut bytes = smsg.as_bytes().chain(&zero[..]);
        loop {
            if prod.is_full() {
                println!("-> buffer is full, waiting");
                thread::sleep(Duration::from_millis(1));
            } else {
                let n = prod.read_from(&mut bytes, None).unwrap();
                if n == 0 {
                    break;
                }
                println!("-> {} bytes sent", n);
            }
        }

        println!("-> message sent");
    });

    let cjh = thread::spawn(move || {
        println!("<- receiving message");

        let mut bytes = Vec::<u8>::new();
        loop {
            if cons.is_empty() {
                if bytes.ends_with(&[0]) {
                    break;
                } else {
                    println!("<- buffer is empty, waiting");
                    thread::sleep(Duration::from_millis(1));
                }
            } else {
                let n = cons.write_into(&mut bytes, None).unwrap();
                println!("<- {} bytes received", n);
            }
        }

        assert_eq!(bytes.pop().unwrap(), 0);
        let msg = String::from_utf8(bytes).unwrap();
        println!("<- message received: '{}'", msg);

        msg
    });

    pjh.join().unwrap();
    let rmsg = cjh.join().unwrap();

    assert_eq!(smsg, rmsg);
}

Trait Implementations

impl Write for Producer<u8>

fn write(&mut self, buffer: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.