Crate limq

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

Feature	Function
bytes	Enable BytesLim.

Structs

BufLim

A Controller for queue of Vec<u8> that can optionally limit the queue length as well as total buffer size.

BufQStats

Statistics for controllers that contain queues of buffers.

BytesLimbytes

A Controller for queue of Bytes that can optionally limit the queue length as well as total buffer size.

LengthLimit

LimQ controller that imposes a queue length limit.

LimQ

A queue with an controller that can limit the number of elements in the queue based on implementor-specific criteria.

NullCtrl

LimQ controller that does not impose any limit.

OptLenLim

LimQ controller that imposes an optional queue length limit.

Enums

CheckErr

Errors that can be returned by Controller::check().

Error

limq errors.

Overflow

Control how forced push handles overflow.

Traits

Controller

Implemented for objects that are used to monitor/control queue limits.