chore: update comments for log store stuff

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<AppendResponse, Self::Error>;
 
-    /// 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<Self::Entry>,
     ) -> Result<AppendBatchResponse, Self::Error>;
 
-    /// 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<SendableEntryStream<Self::Entry, Self::Error>, 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<Vec<Self::Namespace>, Self::Error>;
 
-    /// Create an entry of the associate Entry type
+    /// Creates an entry of the associated Entry type
     fn entry<D: AsRef<[u8]>>(&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<EntryOffset>,
+    /// 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<u64, EntryOffset>,
+    /// 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<u64, EntryId>,
 }

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;
 }

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;
 }