From fa6ab08345d75e5f4b9ea97380e8731ff1b09ec6 Mon Sep 17 00:00:00 2001 From: Zhang Yanpo Date: Fri, 14 Mar 2025 20:36:29 +0800 Subject: [PATCH 1/2] docs: add missing docs for modules --- Makefile | 15 +++++++++++++++ src/compact.rs | 2 ++ src/expirable/mod.rs | 6 ++++++ src/impls/mod.rs | 2 ++ src/seq_value/mod.rs | 6 ++++++ src/seq_value/seq_value_trait.rs | 18 +++++++++++++++--- src/util.rs | 1 + 7 files changed, 47 insertions(+), 3 deletions(-) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..4781b0f --- /dev/null +++ b/Makefile @@ -0,0 +1,15 @@ +all: test fmt clippy doc + +test: + cargo test + +fmt: + cargo fmt + +clippy: + cargo clippy + +doc: + cargo doc + + diff --git a/src/compact.rs b/src/compact.rs index 2281d38..c9bd1a0 100644 --- a/src/compact.rs +++ b/src/compact.rs @@ -12,6 +12,8 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Compact operations on multi levels data. + use std::io; use std::ops::RangeBounds; diff --git a/src/expirable/mod.rs b/src/expirable/mod.rs index c9713f1..cfe51f5 100644 --- a/src/expirable/mod.rs +++ b/src/expirable/mod.rs @@ -12,6 +12,12 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Expirable trait for types that can have an expiration time. +//! +//! This module provides the `Expirable` trait which allows types to define +//! and query their expiration time in milliseconds since the Unix epoch. +//! It's used to implement time-to-live (TTL) functionality for stored values. + /// A trait for evaluating and returning the absolute expiration time. pub trait Expirable { /// Returns the optional expiration time in milliseconds since the Unix epoch (January 1, 1970). diff --git a/src/impls/mod.rs b/src/impls/mod.rs index c5933c4..7633660 100644 --- a/src/impls/mod.rs +++ b/src/impls/mod.rs @@ -12,5 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Implementations of the `MapApi` trait for different storage backends. + pub mod immutable; pub mod level; diff --git a/src/seq_value/mod.rs b/src/seq_value/mod.rs index 592fcc9..3897b83 100644 --- a/src/seq_value/mod.rs +++ b/src/seq_value/mod.rs @@ -12,6 +12,12 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Sequenced values with metadata. +//! +//! This module provides traits and implementations for values that have an associated +//! sequence number and optional metadata. These are used to track the ordering and +//! lifecycle of values in storage systems. + mod seq_value_trait; mod seqv; mod update; diff --git a/src/seq_value/seq_value_trait.rs b/src/seq_value/seq_value_trait.rs index ed93cdd..47ffd85 100644 --- a/src/seq_value/seq_value_trait.rs +++ b/src/seq_value/seq_value_trait.rs @@ -14,31 +14,43 @@ use crate::expirable::Expirable; +/// Trait for some value with sequence number and metadata. pub trait SeqValue> { + /// Return the sequence number of the value. fn seq(&self) -> u64; + + /// Return the reference of the value. fn value(&self) -> Option<&V>; + + /// Consume the value and return the value. fn into_value(self) -> Option; + + /// Return the reference of metadata of the value. fn meta(&self) -> Option<&M>; + /// Consume self and return the sequence number and the value. fn unpack(self) -> (u64, Option) where Self: Sized { (self.seq(), self.into_value()) } - /// Return the expire time in millisecond since 1970. + /// Return the absolute expire time in millisecond since 1970-01-01 00:00:00. fn expires_at_ms_opt(&self) -> Option where M: Expirable { let meta = self.meta()?; meta.expires_at_ms_opt() } - /// Evaluate and returns the absolute expire time in millisecond since 1970. + /// Returns the absolute expiration time in milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). + /// + /// If no expiration time is set, returns `u64::MAX`, effectively meaning the value never expires. + /// This method provides a consistent way to handle both expiring and non-expiring values. fn expires_at_ms(&self) -> u64 where M: Expirable { self.meta().expires_at_ms() } - /// Return true if the record is expired. + /// Return true if the record is expired at the given time in milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). fn is_expired(&self, now_ms: u64) -> bool where M: Expirable { self.expires_at_ms() < now_ms diff --git a/src/util.rs b/src/util.rs index eb612e9..5d32b56 100644 --- a/src/util.rs +++ b/src/util.rs @@ -12,6 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Utility functions and types for the map API. use std::fmt; use std::io; From bacc94b83bcbec3fac3650e27ca42306ddda3896 Mon Sep 17 00:00:00 2001 From: Zhang Yanpo Date: Fri, 14 Mar 2025 20:36:49 +0800 Subject: [PATCH 2/2] BumpVer: 0.1.1 --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index f1c1cd3..c7ac8c2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "map-api" description = "Raft state machine" -version = "0.1.0" +version = "0.1.1" authors = ["Databend Authors "] license = "Apache-2.0" edition = "2021"