Struct QueueMapper 

pub struct QueueMapper<SA, T, A = CurrentStorage>
where
    SA: StorageMapperApi,
    A: StorageAddress<SA>,
    T: TopEncode + TopDecode + 'static,
{ /* private fields */ }

A storage mapper implementing a double-ended queue (deque) with efficient operations at both ends.

Storage Layout

The QueueMapper stores metadata and separates node structure from values:

1. Metadata:

   • base_key + ".info" → QueueMapperInfo struct containing:
     • len: number of elements
     • front: node ID of the first element
     • back: node ID of the last element
     • new: counter for generating unique node IDs

2. Node links:

   • base_key + ".node_links" + node_id → Node struct with:
     • previous: ID of the previous node (0 if none)
     • next: ID of the next node (0 if none)

3. Values:

   • base_key + ".value" + node_id → the stored item

Main Operations

• Enqueue back: push_back(item) - Adds to the end. O(1) with constant storage writes.
• Enqueue front: push_front(item) - Adds to the beginning. O(1) with constant storage writes.
• Dequeue front: pop_front() - Removes from the beginning. O(1).
• Dequeue back: pop_back() - Removes from the end. O(1).
• Peek: front() / back() - Views elements without removing. O(1).
• Iteration: iter() - Traverses from front to back in order.

Trade-offs

• Pros: O(1) operations at both ends; ideal for FIFO/LIFO patterns; maintains insertion order.
• Cons: Cannot insert/remove from middle; no random access by index; higher storage overhead (separate storage for links and values); removed nodes leave gaps in node ID space.

Use Cases

• Task/job queues (FIFO processing)
• Undo/redo stacks
• Any scenario requiring efficient head/tail operations

Example

// Add tasks to the queue
mapper.push_back(100);
mapper.push_back(200);
mapper.push_back(300);

assert_eq!(mapper.len(), 3);
assert_eq!(mapper.front(), Some(100));
assert_eq!(mapper.back(), Some(300));

// Add high-priority task at front
mapper.push_front(50);
assert_eq!(mapper.front(), Some(50));
assert_eq!(mapper.len(), 4);

// Process tasks from front (FIFO)
let task1 = mapper.pop_front();
assert_eq!(task1, Some(50));
assert_eq!(mapper.len(), 3);

let task2 = mapper.pop_front();
assert_eq!(task2, Some(100));

// Can also remove from back
let last = mapper.pop_back();
assert_eq!(last, Some(300));
assert_eq!(mapper.len(), 1);

// Iterate through remaining tasks
for task in mapper.iter() {
    // Process task
}

Implementations

impl<SA, T> QueueMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode,

pub fn push_back(&mut self, elt: T)

Appends an element to the back of a queue.

This operation should compute in O(1) time.

pub fn push_front(&mut self, elt: T)

Adds an element first in the queue.

This operation should compute in O(1) time.

pub fn pop_back(&mut self) -> Option<T>

Removes the last element from a queue and returns it, or None if it is empty.

This operation should compute in O(1) time.

pub fn pop_front(&mut self) -> Option<T>

Removes the first element and returns it, or None if the queue is empty.

This operation should compute in O(1) time.

impl<SA, A, T> QueueMapper<SA, T, A>

where SA: StorageMapperApi, A: StorageAddress<SA>, T: TopEncode + TopDecode + 'static,

pub fn iter(&self) -> Iter<'_, SA, A, T>

pub fn iter_from_node_id(&self, node_id: u32) -> Iter<'_, SA, A, T>

pub fn get_node(&self, node_id: u32) -> Node

pub fn get_value_option(&self, node_id: u32) -> Option<T>

pub fn is_empty(&self) -> bool

Returns true if the Queue is empty.

This operation should compute in O(1) time.

pub fn len(&self) -> usize

Returns the length of the Queue.

This operation should compute in O(1) time.

pub fn front(&self) -> Option<T>

Provides a copy to the front element, or None if the queue is empty.

pub fn back(&self) -> Option<T>

Provides a copy to the back element, or None if the queue is empty.

pub fn check_internal_consistency(&self) -> bool

Runs several checks in order to verify that both forwards and backwards iteration yields the same node entries and that the number of items in the queue is correct. Used for unit testing.

This operation should compute in O(n) time.

Trait Implementations

impl<'a, SA, A, T> IntoIterator for &'a QueueMapper<SA, T, A>

where SA: StorageMapperApi, A: StorageAddress<SA>, T: TopEncode + TopDecode + 'static,

type Item = T

The type of the elements being iterated over.

type IntoIter = Iter<'a, SA, A, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<SA, T> StorageClearable for QueueMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode,

fn clear(&mut self)

Clears all the entries owned by the storage.

impl<SA, T> StorageMapper<SA> for QueueMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode,

fn new(base_key: StorageKey<SA>) -> Self

Will be called automatically by the #[storage_mapper] annotation generated code.

impl<SA, T> StorageMapperFromAddress<SA> for QueueMapper<SA, T, ManagedAddress<SA>>

where SA: StorageMapperApi, T: TopEncode + TopDecode,

fn new_from_address( address: ManagedAddress<SA>, base_key: StorageKey<SA>, ) -> Self

Will be called automatically by the #[storage_mapper_from_address] annotation generated code.

impl<SA, T> TopEncodeMulti for QueueMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode,

Behaves like a MultiResultVec when an endpoint result.

fn multi_encode_or_handle_err<O, H>( &self, output: &mut O, h: H, ) -> Result<(), H::HandledErr>

where O: TopEncodeMultiOutput, H: EncodeErrorHandler,

Version of top_encode that can handle errors as soon as they occur. For instance in can exit immediately and make sure that if it returns, it is a success. By not deferring error handling, this can lead to somewhat smaller bytecode.

fn multi_encode<O>(&self, output: &mut O) -> Result<(), EncodeError>

where O: TopEncodeMultiOutput,

Attempt to serialize the value to output.

impl<SA, T> TypeAbi for QueueMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode + TypeAbi,

Behaves like a MultiResultVec when an endpoint result.

type Unmanaged = QueueMapper<SA, T>

fn type_name() -> TypeName

fn type_name_rust() -> TypeName

fn provide_type_descriptions<TDC: TypeDescriptionContainer>( accumulator: &mut TDC, )

A type can provide more than its own name. For instance, a struct can also provide the descriptions of the type of its fields. TypeAbi doesn’t care for the exact accumulator type, which is abstracted by the TypeDescriptionContainer trait.

fn type_names() -> TypeNames

impl<SA, T> TypeAbiFrom<QueueMapper<SA, T>> for MultiValueEncoded<SA, T>

where SA: StorageMapperApi, T: TopEncode + TopDecode,

impl<SA, T> TypeAbiFrom<QueueMapper<SA, T>> for QueueMapper<SA, T, CurrentStorage>

where SA: StorageMapperApi, T: TopEncode + TopDecode,