Struct YCQueue 

pub struct YCQueue<'a> { /* private fields */ }

Implementations

impl<'a> YCQueue<'a>

pub fn new( shared_metadata: YCQueueSharedMeta<'a>, data_region: &'a mut [u8], ) -> Result<YCQueue<'a>, YCQueueError>

Create a queue backed by shared metadata and a contiguous data region.

Arguments

• shared_metadata - Shared ownership state that tracks slot usage across threads.
• data_region - Contiguous slice that will be divided into fixed-size slots.

Returns

Ok(YCQueue) when data_region aligns with the metadata configuration, or Err(YCQueueError::InvalidArgs) if the arguments disagree.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(4, 32);
let shared = YCQueueSharedMeta::new(&owned.meta);
let queue = YCQueue::new(shared, owned.data.as_mut_slice());
assert!(queue.is_ok());

pub fn in_flight_count(&self) -> u16

Returns the number of slots that have been produced (or are being produced into) but not yet consumed.

Returns

Count of slots currently in flight between producers and consumers.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(2, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

assert_eq!(queue.in_flight_count(), 0);
let slot = queue.get_produce_slot().unwrap();
queue.mark_slot_produced(slot).unwrap();
assert_eq!(queue.in_flight_count(), 1);

pub fn produce_idx(&self) -> u16

Returns the circular index that will be reserved by the next producer call.

Returns

The slot index measured modulo the queue capacity.

pub fn consume_idx(&self) -> u16

Returns the circular index that will be reserved by the next consumer call.

Returns

The slot index measured modulo the queue capacity.

pub fn capacity(&self) -> u16

Returns the total number of slots managed by this queue.

pub fn get_produce_slots( &mut self, num_slots: u16, best_effort: bool, ) -> Result<Vec<YCQueueProduceSlot<'a>>, YCQueueError>

Reserve contiguous slots for producers, optionally in best-effort mode.

When best_effort is false, the function succeeds only if all num_slots are available; otherwise it returns as many contiguous slots as currently ready.

Arguments

• num_slots - Maximum number of contiguous slots to attempt to reserve.
• best_effort - When true, grants a partial batch instead of requiring num_slots.

Returns

Ok containing one or more slots when reservation succeeds.

Errors

Returns YCQueueError::InvalidArgs when num_slots is zero or exceeds capacity, YCQueueError::OutOfSpace when there is no remaining capacity, and YCQueueError::SlotNotReady when the requested slots are not owned by the producer.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(4, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

let slots = queue.get_produce_slots(2, false).unwrap();
assert_eq!(slots.len(), 2);
queue.mark_slots_produced(slots).unwrap();

let partial = queue.get_produce_slots(2, true).unwrap();
assert!(!partial.is_empty());
queue.mark_slots_produced(partial).unwrap();

pub fn get_produce_slot( &mut self, ) -> Result<YCQueueProduceSlot<'a>, YCQueueError>

Reserve a single slot to produce into.

Returns

Ok with the next available YCQueueProduceSlot when space exists.

Errors

Propagates the same errors as get_produce_slots when no capacity is available.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(2, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

// Reserve a slot
let slot = queue.get_produce_slot().unwrap();
// Fill it with data
slot.data.fill(0xAB);

pub fn mark_slot_produced( &mut self, queue_slot: YCQueueProduceSlot<'a>, ) -> Result<(), YCQueueError>

Mark a slot as produced into. This makes it available to consumers.

Arguments

• queue_slot - Slot previously obtained from get_produce_slot or get_produce_slots.

Returns

Ok(()) when the slot is successfully handed off to consumers.

Errors

Returns YCQueueError::InvalidArgs when the slot has an unexpected size.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(2, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

let slot = queue.get_produce_slot().unwrap();
queue.mark_slot_produced(slot).unwrap();
assert_eq!(queue.in_flight_count(), 1);

pub fn mark_slots_produced( &mut self, queue_slots: Vec<YCQueueProduceSlot<'a>>, ) -> Result<(), YCQueueError>

Mark multiple slots as produced into. This makes them available to consumers.

Arguments

• queue_slots - Contiguous slots previously obtained from get_produce_slots.

Returns

Ok(()) when ownership is returned to consumers.

Errors

Returns YCQueueError::InvalidArgs when the slots are empty, non-contiguous, exceed capacity, or hold slices of the wrong length.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(4, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

let slots = queue.get_produce_slots(4, false).unwrap();
queue.mark_slots_produced(slots).unwrap();
assert_eq!(queue.in_flight_count(), 4);

pub fn get_consume_slots( &mut self, num_slots: u16, best_effort: bool, ) -> Result<Vec<YCQueueConsumeSlot<'a>>, YCQueueError>

Reserve contiguous slots for consumers, optionally in best-effort mode.

When best_effort is false, the function succeeds only if all num_slots are ready; otherwise it returns as many contiguous slots as currently published.

Arguments

• num_slots - Maximum number of contiguous slots to attempt to dequeue.
• best_effort - When true, grants a partial batch instead of requiring num_slots.

Returns

Ok containing one or more ready slots when the reservation succeeds.

Errors

Returns YCQueueError::InvalidArgs when num_slots is zero or exceeds capacity, YCQueueError::EmptyQueue when nothing has been produced yet, and YCQueueError::SlotNotReady when the requested slots have not all been published.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(4, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

let produce = queue.get_produce_slots(4, false).unwrap();
queue.mark_slots_produced(produce).unwrap();

let consume = queue.get_consume_slots(2, false).unwrap();
assert_eq!(consume.len(), 2);

let partial = queue.get_consume_slots(2, true).unwrap();
assert!(!partial.is_empty());

pub fn get_consume_slot( &mut self, ) -> Result<YCQueueConsumeSlot<'a>, YCQueueError>

Reserve a single slot for consumption.

Returns

Ok with the next ready YCQueueConsumeSlot when data is available.

Errors

Propagates the same errors as get_consume_slots when no slots are ready.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(2, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

let slot = queue.get_produce_slot().unwrap();
queue.mark_slot_produced(slot).unwrap();

let consume = queue.get_consume_slot().unwrap();
assert_eq!(consume.index, 0);

pub fn mark_slot_consumed( &mut self, queue_slot: YCQueueConsumeSlot<'a>, ) -> Result<(), YCQueueError>

Return an individual consumption slot back to the producer pool.

Arguments

• queue_slot - Slot previously obtained from get_consume_slot or get_consume_slots.

Returns

Ok(()) when the slot is successfully reclaimed for producers.

Errors

Returns YCQueueError::InvalidArgs when the slot data length is unexpected.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(2, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

let slot = queue.get_produce_slot().unwrap();
queue.mark_slot_produced(slot).unwrap();
let consume = queue.get_consume_slot().unwrap();
queue.mark_slot_consumed(consume).unwrap();
assert_eq!(queue.in_flight_count(), 0);

pub fn mark_slots_consumed( &mut self, queue_slots: Vec<YCQueueConsumeSlot<'a>>, ) -> Result<(), YCQueueError>

Return multiple consumption slots back to the producer pool at once.

Arguments

• queue_slots - Contiguous slots previously obtained from get_consume_slots.

Returns

Ok(()) when all slots are reclaimed for producers.

Errors

Returns YCQueueError::InvalidArgs when any slot has an unexpected length, is out of order, or when the batch length exceeds the queue capacity.

Examples

use yep_coc::queue_alloc_helpers::YCQueueOwnedData;
use yep_coc::{YCQueue, YCQueueSharedMeta};

let mut owned = YCQueueOwnedData::new(4, 16);
let shared = YCQueueSharedMeta::new(&owned.meta);
let mut queue = YCQueue::new(shared, owned.data.as_mut_slice()).unwrap();

let produce = queue.get_produce_slots(4, false).unwrap();
queue.mark_slots_produced(produce).unwrap();
let consume = queue.get_consume_slots(4, false).unwrap();
queue.mark_slots_consumed(consume).unwrap();
assert_eq!(queue.in_flight_count(), 0);

impl<'a> YCQueue<'a>

pub fn from_owned_data( owned: &'a YCQueueOwnedData, ) -> Result<YCQueue<'a>, YCQueueError>

pub fn from_shared_data( shared: YCQueueSharedData<'a>, ) -> Result<YCQueue<'a>, YCQueueError>