doc: adds documentation for top-level modules under crate::storage

arindas · Dec 24, 2023 · e3061d5 · e3061d5
1 parent 434d3bf
commit e3061d5
Show file tree

Hide file tree

Showing 6 changed files with 33 additions and 0 deletions.
diff --git a/src/common/mod.rs b/src/common/mod.rs
@@ -43,22 +43,28 @@ pub mod ref_ops {
 }
 
 pub mod cache {
+    //! Module providing [`Cache`] implementation adapters for using with `laminarmq`
+
     pub use generational_cache::{
         cache::lru_cache::LRUCacheBlockArenaEntry,
         prelude::{
             AllocBTreeMap, AllocVec, Cache, Eviction, LRUCache, LRUCacheError, Link, Lookup, Map,
         },
     };
+
     use std::{fmt::Display, marker::PhantomData};
 
+    /// A [`LRUCache`] using an [`AllocVec`] and [`AllocBTreeMap`].
     pub type AllocLRUCache<K, T> =
         LRUCache<AllocVec<LRUCacheBlockArenaEntry<K, T>>, K, T, AllocBTreeMap<K, Link>>;
 
+    /// A [`Cache`] that does a no-op on every cache operation and returns an error instead.
     #[derive(Debug, Default)]
     pub struct NoOpCache<K, V> {
         _phantom_data: PhantomData<(K, V)>,
     }
 
+    /// Error type used by [`NoOpCache`].
     #[derive(Debug, Default)]
     pub struct UnsupportedOp;
 

diff --git a/src/lib.rs b/src/lib.rs
@@ -6,4 +6,12 @@ pub mod storage;
 
 pub mod prelude {
     //! Prelude module for [`laminarmq`](super) with common exports for convenience.
+
+    pub use crate::storage::{
+        commit_log::{
+            segmented_log::{index::Index, segment::Segment, SegmentedLog},
+            CommitLog,
+        },
+        AsyncConsume, AsyncIndexedRead, AsyncTruncate, Storage,
+    };
 }
diff --git a/src/storage/commit_log/mod.rs b/src/storage/commit_log/mod.rs
@@ -1,25 +1,39 @@
+//! Module providing abstractions for modelling an ordered, persistent sequence of records.
+
 use super::{AsyncConsume, AsyncIndexedRead, AsyncTruncate, Sizable};
 
+/// The unit of storage in our [`CommitLog`].
 pub struct Record<M, T> {
     pub metadata: M,
     pub value: T,
 }
 
+/// An absrtact, append-only, ordered sequence of [`Record`] instances.
 #[async_trait::async_trait(?Send)]
 pub trait CommitLog<M, T>:
     AsyncIndexedRead<Value = Record<M, T>, ReadError = Self::Error>
     + AsyncTruncate<Mark = Self::Idx, TruncError = Self::Error>
     + AsyncConsume<ConsumeError = Self::Error>
     + Sizable
 {
+    /// Error type associated with [`CommitLog`].
     type Error: std::error::Error;
 
+    /// Appends the given [`Record`] at the end of this [`CommitLog`].
+    ///
+    /// The [`Record`] may contain a stream of byte slices. Implementations are to exhaustively
+    /// read the stream and append the corresponding byte slices as a single record.
+    ///
+    /// Returns the index at which the [`Record`] was appended.
     async fn append<X, XBuf, XE>(&mut self, record: Record<M, X>) -> Result<Self::Idx, Self::Error>
     where
         X: futures_lite::Stream<Item = Result<XBuf, XE>>,
         X: Unpin + 'async_trait,
         XBuf: std::ops::Deref<Target = [u8]>;
 
+    /// Removes all expired records from this [`CommitLog`].
+    ///
+    /// Returns the number of expired records.
     async fn remove_expired(
         &mut self,
         _expiry_duration: std::time::Duration,

diff --git a/src/storage/common.rs b/src/storage/common.rs
@@ -1,3 +1,5 @@
+//! Module providing common utilities to aid commit-log implementations.
+
 use super::AsyncIndexedRead;
 use futures_core::Stream;
 use num::{CheckedSub, Unsigned};

diff --git a/src/storage/impls/mod.rs b/src/storage/impls/mod.rs
@@ -1,3 +1,5 @@
+//! Module providing different storage backend implementations.
+
 #[cfg(target_os = "linux")]
 pub mod glommio;
 pub mod in_mem;

diff --git a/src/storage/mod.rs b/src/storage/mod.rs
@@ -59,6 +59,7 @@ pub trait AsyncIndexedRead {
     }
 }
 
+/// [`AsyncIndexedRead`] with additional APIs for providing exclusive read access to elements.
 #[async_trait(?Send)]
 pub trait AsyncIndexedExclusiveRead: AsyncIndexedRead {
     /// Exclusively reads the value at the given index from this abstraction.