iterable.rs

Overview

This file defines a generic trait and its implementation to provide an iterable interface over a durable storage system containing messages indexed by keys. The main functionality is to enable traversing a range of messages stored durably, yielding them as an iterator that produces either successfully retrieved (Message, MessageKey) pairs or an error encapsulating possible loading issues.

The file focuses on the abstraction DurableStorageIterable which exposes an iter method to obtain an iterator over a specified range of messages. It leverages the MessagesRangeIterator for the actual iteration mechanism and integrates with the DurableStorageRead trait representing the underlying durable storage read operations.

Traits and Implementations

Trait: DurableStorageIterable<MessageKey, Message>

This trait describes an iterable interface on a storage system that can yield messages within a specified range.

Associated Types

• IterError: The error type that the iterator may return during iteration.

Methods

• iter(&self, range: MessagesRange<MessageKey, Message>) -> impl Iterator<Item = Result<(Message, MessageKey), Self::IterError>>

  Creates an iterator over the messages within the given range.

  • Parameters:

    • range (MessagesRange<MessageKey, Message>): Defines the subset of messages to be iterated over, specifying bounds for keys or messages.

  • Returns:
    An iterator which produces Result items. Each item is either:

    • Ok((Message, MessageKey)): A successfully loaded message and its associated key.

    • Err(Self::IterError): An error occurred while loading a message.

  • Usage Example:

    let storage: impl DurableStorageIterable<MyKey, MyMessage> = ...;
    let range = MessagesRange::new(start_key, end_key);
    for result in storage.iter(range) {
        match result {
            Ok((message, key)) => {
                // process message and key
            }
            Err(e) => {
                // handle iteration error
            }
        }
    }
    

Implementation: DurableStorageIterable for any Storage implementing DurableStorageRead

This implementation is generic over MessageKey, Message, and Storage. It requires:

• Storage implements DurableStorageRead<MessageKey, Message>.

• MessageKey implements Clone, PartialEq, and can be constructed from a Message.

• Message implements Clone.

Associated Type

• IterError is defined as IteratorError<Storage::LoadError, MessageKey>, a wrapper error type that combines the underlying storage load error and the message key for which the iteration failed.

Method: iter

• The method creates a new instance of MessagesRangeIterator, passing the storage reference and the requested message range.

• The returned iterator produces items of type Result<(Message, MessageKey), Self::IterError>.

• The iterator internally uses the storage's reading capabilities to yield messages in the specified range, handling errors gracefully by wrapping them in IteratorError.

Important Implementation Details

• The iter method returns an impl Iterator type, allowing the caller to iterate without exposing the concrete iterator type, which is MessagesRangeIterator.

• The use of MessagesRange<MessageKey, Message> as the range parameter allows flexible specification of iteration bounds based on keys or messages.

• The error handling mechanism wraps the underlying storage load errors with IteratorError, providing contextual information including the message key related to an error.

• The trait bounds on MessageKey (Clone, PartialEq, and From<Message>) ensure that keys can be cloned, compared, and constructed from messages, facilitating iterator functionality and error reporting.

Interaction with Other Components

• MessagesRange<MessageKey, Message>: Defines the range of messages to iterate over. This file depends on it to specify iteration bounds.

• MessagesRangeIterator<'a, MessageKey, Message, Storage>: The concrete iterator struct used to perform the iteration over the durable storage. This file constructs and returns instances of this iterator.

• DurableStorageRead<MessageKey, Message>: The underlying storage abstraction providing read access to messages. The iterable trait implementation requires the storage to implement this trait.

• IteratorError<Storage::LoadError, MessageKey>: Error type used for wrapping errors during iteration, combining the storage-specific load error and the message key involved.

This module acts as an adapter layer that connects the durable storage read interface to an iterator interface for convenient and idiomatic iteration over stored messages.

Mermaid Diagram

classDiagram
class DurableStorageIterable~MessageKey, Message~ {
<<trait>>
+iter(range: MessagesRange) Iterator<Result<(Message, MessageKey), IterError>>
+IterError
}
class Storage {
+iter(range: MessagesRange) Iterator<Result<(Message, MessageKey), IterError>>
+LoadError
}
class MessagesRangeIterator~'a, MessageKey, Message, Storage~ {
+new(storage: &Storage, range: MessagesRange) MessagesRangeIterator
+next() Option<Result<(Message, MessageKey), IterError>>
}
class IteratorError~LoadError, MessageKey~ {
}
class MessagesRange~MessageKey, Message~ {
}
DurableStorageIterable <|.. Storage
Storage --> DurableStorageRead
Storage --> IteratorError
Storage --> MessagesRangeIterator
MessagesRangeIterator --> MessagesRange
MessagesRangeIterator --> IteratorError