rename some meta trait and add docs

src/cas/fjall_store.rs

@@ -173,12 +173,9 @@ impl MetaStore for FjallStore {
         Ok(buckets)
     }
 
-    fn delete_objects(&self, bucket: &str, key: &str) -> Result<Vec<Block>, MetaError> {
-        // Remove an object. This fetches the object, decrements the refcount of all blocks,
-        // and removes blocks which are no longer referenced.
+    fn delete_object(&self, bucket: &str, key: &str) -> Result<Vec<Block>, MetaError> {
         let bucket = self.get_partition(bucket)?;
 
-        // transaction
         let raw_object = match bucket.get(key) {
             Ok(Some(o)) => o,
             Ok(None) => return Ok(vec![]),
@@ -219,7 +216,7 @@ impl MetaStore for FjallStore {
         Ok(to_delete)
     }
 
-    fn write_block_and_path_meta(
+    fn write_block(
         &self,
         block_hash: BlockID,
         data_len: usize,

src/cas/fs.rs

@@ -184,9 +184,12 @@ impl CasFS {
     pub async fn delete_object(&self, bucket: &str, key: &str) -> Result<(), MetaError> {
         let path_map = self.path_tree()?;
 
-        let blocks_to_delete = self.meta_store.delete_objects(bucket, key)?;
+        // get blocks that safe to delete
+        let blocks_to_delete = self.meta_store.delete_object(bucket, key)?;
 
-        // Now delete all the blocks from disk, and unlink them in the path map.
+        // Now
+        // - delete all the blocks from disk
+        // - and unlink them in the path map.
         for block in blocks_to_delete {
             async_fs::remove_file(block.disk_path(self.root.clone()))
                 .await
@@ -279,15 +282,17 @@ impl CasFS {
                 hasher.update(&bytes);
                 let block_hash: BlockID = hasher.finalize().into();
                 let data_len = bytes.len();
+
+                // check if this key already has this block
                 let key_has_block = if let Some(obj) = old_obj_meta.as_ref() {
                     obj.has_block(&block_hash)
                 } else {
                     false
                 };
 
-                let should_write =
-                    self.meta_store
-                        .write_block_and_path_meta(block_hash, data_len, key_has_block);
+                let should_write = self
+                    .meta_store
+                    .write_block(block_hash, data_len, key_has_block);
 
                 let mut pm = PendingMarker::new(self.metrics.clone());
                 match should_write {

src/cas/meta_store.rs

@@ -49,14 +49,34 @@ pub trait MetaStore: Send + Sync + Debug + 'static {
     /// TODO: this should be paginated and return a stream.
     fn list_buckets(&self) -> Result<Vec<BucketMeta>, MetaError>;
 
-    /// delete all objects in a bucket for the given key.
-    /// it returns a list of blocks that were deleted.
-    fn delete_objects(&self, bucket: &str, key: &str) -> Result<Vec<Block>, MetaError>;
-
-    // Check if the hash is present in the block map. If it is not, try to find a path, and
-    // insert it.
-    // it returns true if the block was not exists
-    fn write_block_and_path_meta(
+    /// delete object in a bucket for the given key.
+    ///
+    /// It should do at least the following:
+    /// - get all the blocks from the object
+    /// - decrements the refcount of all blocks, then removes blocks which are no longer referenced.
+    /// - and return the deleted blocks, so that the caller can remove the blocks from the storage.
+    ///
+    /// TODO: all the above steps shouldn't be done in the meta storage layer.
+    ///       we do it there because we still couldn't abstract the DB transaction.
+    fn delete_object(&self, bucket: &str, key: &str) -> Result<Vec<Block>, MetaError>;
+
+    // Write a block to the block map.
+    //
+    // block_hash is hash of the block, which become the key in the block map.
+    // data_len is the length of the block data.
+    // key_has_block is true if the coresponding key already has the block
+    //
+    // It should do at least the following:
+    // - Check if the hash is present in the block map
+    //    - if exists and key_has_block is false: increment the refcount
+    //   - if exists and key_has_block is true: do nothing
+    //    - if not exists:
+    //          - find the path for it
+    //          - insert the block into the block map
+    //
+    // TODO: all the above steps shouldn't be done in the meta storage layer.
+    //       we do it there because we still couldn't abstract the DB transaction.
+    fn write_block(
         &self,
         block_hash: BlockID,
         data_len: usize,