mod.rs

Overview

This file defines the MessagesRange struct, which manages a sequence of messages identified by keys. It provides a data structure combining a potentially compacted history range with a tail queue of message-key pairs, allowing efficient appending and tracking of message sequences. The file includes core functionality to create an empty message range, check if it is empty, add new messages, and retrieve its current length. It also implements traits for serialization, deserialization, getters, setters, cloning, and a debug formatter.

The file exposes a submodule named next, which is not detailed here but is part of the message range handling.

Struct: MessagesRange<MessageKey, Message>

Purpose

MessagesRange represents a collection of messages ordered by their keys with two main components:

• compacted_history: An optional inclusive range indicating a compacted or summarized segment of the message history.

• tail_sequence: A VecDeque holding tuples of (MessageKey, Message), representing the most recent or tail portion of messages.

This structure supports scenarios where older messages might be summarized or compacted, while newer messages remain accessible in sequence.

Type Parameters

• MessageKey: The type used to identify messages. Must implement traits for equality, hashing, cloning, and debugging.

• Message: The message data type, which is generic and can be any type.

Derives and Traits

• Clone: Enables cloning of the struct.

• Getters and Setters: Provides automatic getter and setter methods. Setter methods use a set_ prefix and borrow self.

• Serialize and Deserialize: Supports serialization and deserialization, useful for persistence or network transmission.

• Debug: Custom debug implementation to display the compacted history and the tail sequence.

Fields

• compacted_history: Option<RangeInclusive<MessageKey>>
  Represents a range of message keys that have been compacted or summarized. If None, no compacted history exists.

• tail_sequence: VecDeque<(MessageKey, Message)>
  A double-ended queue storing the most recent message-key pairs in order.

Methods

empty() -> Self

Creates and returns an empty MessagesRange instance, with no compacted history and an empty tail sequence.

Usage example:

let empty_range: MessagesRange<u32, String> = MessagesRange::empty();
assert!(empty_range.is_empty());

is_empty(&self) -> bool

Checks whether the MessagesRange is empty. Returns true if there is no compacted history and the tail sequence is empty.

Usage example:

if messages_range.is_empty() {
    println!("No messages available.");
}

add_messages(&mut self, messages: Vec<(MessageKey, Message)>)

Appends a vector of (MessageKey, Message) tuples to the tail sequence.

Parameters:

• messages: Vector of message-key pairs to add.

Usage example:

messages_range.add_messages(vec![(1, "msg1".to_string()), (2, "msg2".to_string())]);

length(&self) -> usize

Returns the number of messages currently in the tail sequence.

Usage example:

let count = messages_range.length();
println!("Number of messages in tail: {}", count);

Debug Implementation

A manual implementation of Debug is provided to display the compacted_history and tail_sequence contents in debug logs. This aids in inspection during development or testing.

Implementation Details

• The use of VecDeque for tail_sequence allows efficient appending and potential future operations at both ends.

• The optional compacted_history field indicates that the data structure supports partial summarization or compaction of message ranges to optimize storage or processing.

• The getters and setters macros simplify access and mutation of fields, with setters borrowing self for ergonomic API usage.

• The file includes a placeholder test module with a trivial test, indicating testing is expected but not yet implemented.

Interaction with Other Parts of the Application

• The submodule next (imported as pub mod next;) likely provides additional functionality related to message range progression or iteration, though its content is outside this file.

• Serialization and deserialization traits enable integration with persistence layers or communication protocols.

• The design of MessagesRange supports usage in systems where message history needs to be managed efficiently, such as messaging queues, event sourcing, or distributed logs.

Diagram: MessagesRange Structure and Methods

classDiagram
class MessagesRange {
+Option<RangeInclusive<MessageKey>> compacted_history
+VecDeque<(MessageKey, Message)> tail_sequence
+empty()
+is_empty()
+add_messages()
+length()
}