Struct Consumer 

pub struct Consumer<E, W> { /* private fields */ }

A handle with immutable access to events on the ring buffer.

Can access events concurrently to other handles with immutable access.

Implementations

impl<E, W> Consumer<E, W>

pub fn sequence(&self) -> i64

Returns the current sequence value for this consumer’s cursor.

Examples

let (mut producer, mut consumer) = ansa::spsc(64, || 0);
// sequences start at -1, but accesses always occur at the next sequence,
// so the first accessed sequence will be 0
assert_eq!(producer.sequence(), -1);

// move the producer up by 10, otherwise the consumer will block the
// thread while waiting for available events
producer.wait(10).for_each(|_, _, _| ());
assert_eq!(producer.sequence(), 9);

// now we can move the consumer
consumer.wait(5).for_each(|_, _, _| ());
assert_eq!(consumer.sequence(), 4);

pub fn buffer_size(&self) -> usize

Returns the size of the ring buffer.

Examples

let (_, consumer) = ansa::spsc(64, || 0);
assert_eq!(consumer.buffer_size(), 64);

pub fn set_wait_strategy<W2>(self, wait_strategy: W2) -> Consumer<E, W2>

Returns a new handle with the given wait_strategy, consuming this handle.

All other properties of the original handle remain unchanged in the new handle.

Does not alter the wait strategy for any other handle.

Examples

use ansa::Consumer;
use ansa::wait::WaitBusy;

let (_, consumer) = ansa::spsc(64, || 0u8);
let _: Consumer<u8, WaitBusy> = consumer.set_wait_strategy(WaitBusy);

impl<E, W> Consumer<E, W>

where W: WaitStrategy,

pub fn wait(&mut self, size: usize) -> Events<'_, E>

Wait until exactly size number of events are available.

size values larger than the buffer will cause permanent stalls.

pub fn wait_range<R>(&mut self, range: R) -> Events<'_, E>

where R: RangeBounds<usize>,

Wait until a number of events within the given range are available.

If a lower bound is provided, it must be less than the buffer size.

Any range which starts from 0 or is unbounded enables non-blocking waits for [well-behaved] WaitStrategy implementations

Examples

let (mut producer, mut consumer) = ansa::spsc(64, || 0);

let events = consumer.wait_range(..); // wait for any number of events
assert_eq!(events.size(), 0);

// Whereas this would block the thread waiting for the producer to move.
// consumer.wait_range(1..);

// move the lead producer
producer.wait(20).for_each(|_, _, _| ());

let events = consumer.wait_range(..=10); // wait for a batch of at most 10 events
assert_eq!(events.size(), 10);

let events = consumer.wait_range(10..); // wait for a batch of at least 10 events
assert_eq!(events.size(), 20);

let events = consumer.wait_range(..);
assert_eq!(events.size(), 20);

Can be used to for non-blocking waits. .. is always non-blocking

impl<E, W> Consumer<E, W>

where W: TryWaitStrategy,

pub fn try_wait(&mut self, size: usize) -> Result<Events<'_, E>, W::Error>

Wait until exactly size number of events are available.

Otherwise, return the wait strategy error.

size values larger than the buffer will cause permanent stalls.

Examples

use std::time::Duration;
use ansa::wait::{Timeout, WaitBusy};

let (mut producer, consumer) = ansa::spsc(64, || 0u32);
let timeout = Timeout::new(Duration::from_millis(10), WaitBusy);
let mut consumer = consumer.set_wait_strategy(timeout);

// Try to wait for 5 events, but timeout if they're not available
match consumer.try_wait(5) {
    Ok(events) => {
        // Events were available within the timeout
        events.for_each(|event, seq, _| println!("Event {}: {}", seq, event));
    }
    Err(_timeout) => {
        // Timeout occurred - no events were available in time
        println!("No events available within timeout");
    }
}

pub fn try_wait_range<R>(&mut self, range: R) -> Result<Events<'_, E>, W::Error>

where R: RangeBounds<usize>,

Wait until a number of events within the given range are available.

If a lower bound is provided, it must be less than the buffer size.

Examples

use std::time::Duration;
use ansa::wait::{Timeout, WaitBusy};

let (mut producer, consumer) = ansa::spsc(64, || 0);
// move the lead producer
producer.wait(20).for_each(|_, _, _| ());

let timeout = Timeout::new(Duration::from_millis(1), WaitBusy);
let mut consumer = consumer.set_wait_strategy(timeout);

consumer.try_wait_range(1..=10)?; // waits for a batch of at most 10 events
consumer.try_wait_range(10..)?; // waits for a batch of at least 10 events
consumer.try_wait_range(1..)?; // waits for any number of events

Trait Implementations

impl<E: Debug, W: Debug> Debug for Consumer<E, W>

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

Formats the value using the given formatter.