From 60087341a4b064bd57f47575efe940990209e59b Mon Sep 17 00:00:00 2001 From: niebayes Date: Sat, 23 Dec 2023 22:53:48 +0800 Subject: [PATCH] chore: update comments for log store stuff --- src/store-api/src/logstore.rs | 42 +++++++++++-------------- src/store-api/src/logstore/entry.rs | 15 ++++++--- src/store-api/src/logstore/namespace.rs | 3 ++ 3 files changed, 32 insertions(+), 28 deletions(-) diff --git a/src/store-api/src/logstore.rs b/src/store-api/src/logstore.rs index 3fb81d9a62..efb2824e25 100644 --- a/src/store-api/src/logstore.rs +++ b/src/store-api/src/logstore.rs @@ -19,7 +19,7 @@ use std::collections::HashMap; use common_config::wal::WalOptions; use common_error::ext::ErrorExt; -use crate::logstore::entry::{Entry, Id as EntryId, Offset as EntryOffset}; +use crate::logstore::entry::{Entry, Id as EntryId}; use crate::logstore::entry_stream::SendableEntryStream; use crate::logstore::namespace::{Id as NamespaceId, Namespace}; @@ -34,21 +34,20 @@ pub trait LogStore: Send + Sync + 'static + std::fmt::Debug { type Namespace: Namespace; type Entry: Entry; - /// Stop components of logstore. + /// Stops components of the logstore. async fn stop(&self) -> Result<(), Self::Error>; - /// Append an `Entry` to WAL with given namespace and return append response containing - /// the entry id. + /// Appends an entry to the log store and returns a response containing the id of the append entry. async fn append(&self, entry: Self::Entry) -> Result; - /// Append a batch of entries and return an append batch response containing the start entry ids of - /// log entries written to each region. + /// Appends a batch of entries and returns a response containing a map where the key is a region id + /// while the value is the id of the entry, the last entry of the entries belong to the region, written into the log store. async fn append_batch( &self, entries: Vec, ) -> Result; - /// Create a new `EntryStream` to asynchronously generates `Entry` with ids + /// Creates a new `EntryStream` to asynchronously generates `Entry` with ids /// starting from `id`. async fn read( &self, @@ -56,43 +55,40 @@ pub trait LogStore: Send + Sync + 'static + std::fmt::Debug { id: EntryId, ) -> Result, Self::Error>; - /// Create a new `Namespace`. + /// Creates a new `Namespace` from the given ref. async fn create_namespace(&self, ns: &Self::Namespace) -> Result<(), Self::Error>; - /// Delete an existing `Namespace` with given ref. + /// Deletes an existing `Namespace` specified by the given ref. async fn delete_namespace(&self, ns: &Self::Namespace) -> Result<(), Self::Error>; - /// List all existing namespaces. + /// Lists all existing namespaces. async fn list_namespaces(&self) -> Result, Self::Error>; - /// Create an entry of the associate Entry type + /// Creates an entry of the associated Entry type fn entry>(&self, data: D, entry_id: EntryId, ns: Self::Namespace) -> Self::Entry; - /// Create a namespace of the associate Namespace type + /// Creates a namespace of the associated Namespace type // TODO(sunng87): confusion with `create_namespace` fn namespace(&self, ns_id: NamespaceId, wal_options: &WalOptions) -> Self::Namespace; - /// Mark all entry ids `<=id` of given `namespace` as obsolete so that logstore can safely delete - /// the log files if all entries inside are obsolete. This method may not delete log - /// files immediately. + /// Marks all entries with ids `<=entry_id` of the given `namespace` as obsolete, + /// so that the log store can safely delete those entries. This method does not guarantee + /// that the obsolete entries are deleted immediately. async fn obsolete(&self, ns: Self::Namespace, entry_id: EntryId) -> Result<(), Self::Error>; } /// The response of an `append` operation. #[derive(Debug)] pub struct AppendResponse { - /// The entry id of the appended log entry. - pub entry_id: EntryId, - /// The start entry offset of the appended log entry. - /// Depends on the `LogStore` implementation, the entry offset may be missing. - pub offset: Option, + /// The id of the entry appended to the log store. + pub last_entry_id: EntryId, } /// The response of an `append_batch` operation. #[derive(Debug, Default)] pub struct AppendBatchResponse { - /// Key: region id (as u64). Value: the known minimum start offset of the appended log entries belonging to the region. - /// Depends on the `LogStore` implementation, the entry offsets may be missing. - pub offsets: HashMap, + /// Key: region id (as u64). + /// Value: the id of the entry, the last entry of the entries belong to the region, appended to the log store. + pub last_entry_ids: HashMap, } diff --git a/src/store-api/src/logstore/entry.rs b/src/store-api/src/logstore/entry.rs index cb2538086e..17d32f3bc1 100644 --- a/src/store-api/src/logstore/entry.rs +++ b/src/store-api/src/logstore/entry.rs @@ -16,21 +16,26 @@ use common_error::ext::ErrorExt; use crate::logstore::namespace::Namespace; -/// An entry's logical id, allocated by log store users. +/// An entry's id. +/// Different log store implementations may interpret the id to different meanings. pub type Id = u64; -/// An entry's physical offset in the underlying log store. +/// An entry's offset. +/// Notice: it's currently not used. pub type Offset = usize; -/// Entry is the minimal data storage unit in `LogStore`. +/// Entry is the minimal data storage unit through which users interact with the log store. +/// The log store implementation may have larger or smaller data storage unit than an entry. pub trait Entry: Send + Sync { type Error: ErrorExt + Send + Sync; type Namespace: Namespace; - /// Return contained data of entry. + /// Returns the contained data of the entry. fn data(&self) -> &[u8]; - /// Return entry id that monotonically increments. + /// Returns the id of the entry. + /// Usually the namespace id is identical with the region id. fn id(&self) -> Id; + /// Returns the namespace of the entry. fn namespace(&self) -> Self::Namespace; } diff --git a/src/store-api/src/logstore/namespace.rs b/src/store-api/src/logstore/namespace.rs index 35a136d809..ac1b62e31b 100644 --- a/src/store-api/src/logstore/namespace.rs +++ b/src/store-api/src/logstore/namespace.rs @@ -14,8 +14,11 @@ use std::hash::Hash; +/// The namespace id. +/// Usually the namespace id is identical with the region id. pub type Id = u64; pub trait Namespace: Send + Sync + Clone + std::fmt::Debug + Hash + PartialEq + Eq { + /// Returns the namespace id. fn id(&self) -> Id; }