Struct Queue 

pub struct Queue<K, V, S = HashMap<K, Item>> { /* private fields */ }

Queue.

This is a specialization of Store, more specifically Ordered, that maintains insertion order and allows to assign specific deadlines to items. Values themselves don’t need to implement Ord, since the ordering is completely independent and induced by the queue.

When an item is inserted, it is annotated with Instant::now, which on the one hand implements insertion order, and on the other hand allows to change the ordering of an item through Queue::set_deadline. This allows to remove items from visibility until a certain point in time.

Additionally, Queue is not a queue in the traditional sense, since it adds queueing to a Store, an immutable collection of key-value pairs. The queue is self-organizing, and iterating over it will always yield the correct order of items at that specific point in time.

Examples

use zrx_store::{Queue, StoreIterable, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("a", 4);
queue.insert("b", 2);
queue.insert("c", 3);
queue.insert("d", 1);

// Create iterator over the queue
for (key, value) in &queue {
    println!("{key}: {value}");
}

Implementations

impl<K, V, S> Queue<K, V, S>

where K: Key, S: Store<K, Item>,

pub fn new() -> Self

where S: Default,

Creates a queue.

Examples

use std::collections::HashMap;
use zrx_store::{Queue, StoreMut};

// Create queue
let mut queue = Queue::<_, _, HashMap<_, _>>::new();
queue.insert("key", 42);

pub fn get_deadline(&self, key: &K) -> Option<Instant>

Returns the deadline of the item identified by the key.

Examples

use std::time::Instant;
use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Obtain deadline of item
let deadline = queue.get_deadline(&"key");
assert!(deadline < Some(Instant::now()));

impl<K, V, S> Queue<K, V, S>

where K: Key, S: StoreMut<K, Item>,

pub fn set_deadline(&mut self, key: &K, deadline: Instant) -> Option<Instant>

Sets the deadline of the item identified by the key.

Examples

use std::time::Instant;
use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Update deadline of item
queue.set_deadline(&"key", Instant::now());

impl<K, V, S> Queue<K, V, S>

where K: Key, V: Value, S: StoreMut<K, Item> + StoreIterable<K, Item>,

pub fn deadline(&self) -> Option<Instant>

Returns the minimum deadline of all items.

Examples

use std::time::Instant;
use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Obtain minimum deadline of all items
let deadline = queue.deadline();
assert!(deadline < Some(Instant::now()));

pub fn take(&mut self) -> Option<(K, V)>

Takes ownership of the next item that is due.

Items are considered to be due if Instant::now has passed the value stored in Item::deadline, which allows to defer processing.

Examples

use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("a", 4);
queue.insert("b", 2);
queue.insert("c", 3);
queue.insert("d", 1);

// Obtain items from queue
while let Some((key, value)) = queue.take() {
    println!("{key}: {value}");
}

Trait Implementations

impl<K: Clone, V: Clone, S: Clone> Clone for Queue<K, V, S>

fn clone(&self) -> Queue<K, V, S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K, V, S> Debug for Queue<K, V, S>

where K: Debug, V: Debug, S: Debug,

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

Formats the queue for debugging.

impl<K, V> Default for Queue<K, V>

where K: Key,

fn default() -> Self

Creates a queue with HashMap::default as a store.

Note that this method does not allow to customize the BuildHasher, but uses ahash by default, which is the fastest known hasher.

Examples

use zrx_store::{Queue, StoreMut};

// Create queue
let mut queue = Queue::default();

// Insert value
queue.insert("key", 42);

impl<'a, K, V, S> IntoIterator for &'a Queue<K, V, S>

where K: Key, V: Value, S: StoreIterable<K, Item>,

fn into_iter(self) -> Self::IntoIter

Creates an iterator over the queue.

Examples

use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Create iterator over the queue
for (key, value) in &queue {
    println!("{key}: {value}");
}

type Item = (&'a K, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, K, V>

Which kind of iterator are we turning this into?

impl<'a, K, V, S> IntoIterator for &'a mut Queue<K, V, S>

where K: Key, V: Value, S: StoreMut<K, Item> + StoreIterable<K, Item>,

fn into_iter(self) -> Self::IntoIter

Creates a mutable iterator over the queue.

Examples

use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Create iterator over the queue
for (key, value) in &mut queue {
    println!("{key}: {value}");
}

type Item = (&'a K, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, K, V>

Which kind of iterator are we turning this into?

impl<K, V, S> Store<K, V> for Queue<K, V, S>

where K: Key, S: Store<K, Item>,

fn get<Q>(&self, key: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Key,

Returns a reference to the value identified by the key.

Examples

use zrx_store::{Queue, Store, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Obtain reference to value
let value = queue.get(&"key");
assert_eq!(value, Some(&42));

fn contains_key<Q>(&self, key: &Q) -> bool

where K: Borrow<Q>, Q: Key,

Returns whether the queue contains the key.

Examples

use zrx_store::{Queue, Store, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Ensure presence of key
let check = queue.contains_key(&"key");
assert_eq!(check, true);

fn len(&self) -> usize

Returns the number of items in the queue.

fn is_empty(&self) -> bool

Returns whether the store is empty.

impl<K, V, S> StoreIterable<K, V> for Queue<K, V, S>

where K: Key, V: Value, S: StoreIterable<K, Item>,

fn iter(&self) -> Self::Iter<'_>

Creates an iterator over the items of the queue.

Examples

use zrx_store::{Queue, StoreIterable, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Create iterator over the queue
for (key, value) in queue.iter() {
    println!("{key}: {value}");
}

type Iter<'a> = Iter<'a, K, V> where Self: 'a

impl<K, V, S> StoreIterableMut<K, V> for Queue<K, V, S>

where K: Key, V: Value, S: StoreMut<K, Item> + StoreIterable<K, Item>,

fn iter_mut(&mut self) -> Self::IterMut<'_>

Creates a mutable iterator over the items of the queue.

Examples

use zrx_store::{Queue, StoreIterableMut, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Create iterator over the queue
for (key, value) in queue.iter_mut() {
    println!("{key}: {value}");
}

type IterMut<'a> = IterMut<'a, K, V> where Self: 'a

impl<K, V, S> StoreKeys<K, V> for Queue<K, V, S>

where K: Key, S: StoreIterable<K, Item>,

fn keys(&self) -> Self::Keys<'_>

Creates an iterator over the keys of the queue.

Examples

use zrx_store::{Queue, StoreKeys, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Create iterator over the queue
for key in queue.keys() {
    println!("{key}");
}

type Keys<'a> = Keys<'a, K> where Self: 'a

impl<K, V, S> StoreMut<K, V> for Queue<K, V, S>

where K: Key, V: Value, S: StoreMut<K, Item>,

fn insert(&mut self, key: K, value: V) -> Option<V>

Inserts the value identified by the key.

This method only updates the data of the Item, but does not change the values of Item::deadline in case the item already exists.

Examples

use zrx_store::{Queue, StoreMut};

// Create queue
let mut queue = Queue::default();

// Insert value
let value = queue.insert("key", 42);
assert_eq!(value, None);

fn remove<Q>(&mut self, key: &Q) -> Option<V>

where K: Borrow<Q>, Q: Key,

Removes the value identified by the key.

Examples

use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Remove and return value
let value = queue.remove(&"key");
assert_eq!(value, Some(42));

fn remove_entry<Q>(&mut self, key: &Q) -> Option<(K, V)>

where K: Borrow<Q>, Q: Key,

Removes the value identified by the key and returns both.

Examples

use zrx_store::{Queue, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Remove and return entry
let entry = queue.remove_entry(&"key");
assert_eq!(entry, Some(("key", 42)));

fn clear(&mut self)

Clears the queue, removing all items.

Examples

use zrx_store::{Queue, Store, StoreMut};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Clear queue
queue.clear();
assert!(queue.is_empty());

impl<K, V, S> StoreMutRef<K, V> for Queue<K, V, S>

where K: Key, S: StoreMut<K, Item>,

fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: Key,

Returns a mutable reference to the value identified by the key.

Examples

use zrx_store::{Queue, StoreMut, StoreMutRef};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Obtain mutable reference to value
let mut value = queue.get_mut(&"key");
assert_eq!(value, Some(&mut 42));

fn get_or_insert_default(&mut self, key: &K) -> &mut V

where V: Default,

Returns a mutable reference to the value or creates the default.

Examples

use zrx_store::{Queue, StoreMutRef};

// Create queue
let mut queue = Queue::<_, i32>::default();

// Obtain mutable reference to value
let value = queue.get_or_insert_default(&"key");
assert_eq!(value, &mut 0);

impl<K, V, S> StoreValues<K, V> for Queue<K, V, S>

where K: Key, V: Value, S: StoreValues<K, Item>,

fn values(&self) -> Self::Values<'_>

Creates an iterator over the values of the queue.

Examples

use zrx_store::{Queue, StoreMut, StoreValues};

// Create queue and initial state
let mut queue = Queue::default();
queue.insert("key", 42);

// Create iterator over the queue
for value in queue.values() {
    println!("{value}");
}

type Values<'a> = Values<'a, K, V> where Self: 'a