Limited Queue

LimQ is a queue that holds a Controller implementation that can be used to limit/monitor the queue elements.

lib.rs:

LimQ is a queue (implemented as a wrapper around VecDeque) that allows an internal Controller implementor to control when the queue is full/overflown.

Controller objects are responsible for:

• Determining if:
  • the queue is "full".
  • the queue has "overflown".
  • a new queue element will fit in the queue or not.
• Registering a new element being added to the queue.
• Deregistering an element being removoed from the queue.

It is up to the implementor to interpret what "full" and "overflown" means. Typical use-cases are to ensure that the length of the queue is limited, or a queue of Vec<u8> elements could keep an internal counter to ensure that the total buffer size does not exceed a limit).

Rather than supplying the traditional push() method to add elements to the queue, LimQ implements [LimQ::try_push()] and [LimQ::force_push()]/[LimQ::force_push_oc()]. If no queue limit has been enabled, both of these act exactly like a traditional push() would. When a limit has been set, and reached, try_push() will fail, returning the input element. force_push() will forcibly add the new element while dropping the next element in line to be pulled off the queue.

Provided length limit controller

use limq::{LimQ, LengthLimit, Error};

// Construct a controller object that will limit the length solely based on
// the length of the queue.
let limlen = LengthLimit::new(2);

// Construct a queue with a maximum 2 element length limit
let mut q: LimQ<_, u32> = LimQ::new(limlen);

// Add elements to fill up to queue
q.try_push(1).unwrap();
q.force_push(2);

// Fail to add a new node
assert_eq!(q.try_push(3), Err(Error::WontFit(3)));

// Forcibly add node; expelling the oldest node
q.force_push(4);

// Remaining nodes should be 2 and 4
assert_eq!(q.pop(), Some(2));
assert_eq!(q.pop(), Some(4));
assert_eq!(q.pop(), None);

Provided buffer queue limit controller

limq comes with a limit controller BufLim that assumes the queue item type is Vec<u8>, and which can limit the queue according to both the number of buffers and the total size of all the buffers in the queue.

use limq::{LimQ, BufLim, Error};

// Create a buffer queue that is limited to 4 buffers with a total size of
// 8 bytes
let lim = BufLim::new(Some(4), Some(8));
let mut q = LimQ::new(lim);

// Add a buffer
q.try_push(Vec::from("1234")).unwrap();
assert_eq!(q.len(), 1);
assert_eq!(q.controller().size(), 4);

// Fill up the queue (there still room for two more buffers, but it's full
// with regards to total buffer size).
q.try_push(Vec::from("5678")).unwrap();
assert_eq!(q.len(), 2);
assert_eq!(q.controller().size(), 8);

// Attempting to add more data will fail, because the total size limit has
// been reached.
let Err(Error::WontFit(buf)) = q.try_push(Vec::from("ab")) else {
  panic!("Unexpectedly not Err(Error::WontFit())");
};
assert_eq!(buf, b"ab");
assert_eq!(q.len(), 2);
assert_eq!(q.controller().size(), 8);

Features