docs: add missing docs for memory-tracker crate

util/memory-tracker/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.37.0-pre"
 authors = ["Nervos Core Dev <[email protected]>"]
 edition = "2018"
 license = "MIT"
-description = "TODO(doc): @yangby-cryptape crate description"
+description = "Track the memory usage of CKB."
 homepage = "https://github.com/nervosnetwork/ckb"
 repository = "https://github.com/nervosnetwork/ckb"
 
@@ -13,13 +13,6 @@ ckb-logger = { path = "../logger", version = "= 0.37.0-pre" }
 ckb-metrics = { path = "../metrics", version = "= 0.37.0-pre" }
 ckb-db = { path = "../../db", version = "= 0.37.0-pre" }
 
-# TODO Why don't disable this crate by "target.*" in the crates which are dependent on this crate?
-#
-# I really don't like to write such dirty code. I try a lot. But due to the limit of the "cargo"
-# (and a lot of stupid bugs), at last, I have to write these stupid code.
-#
-# References:
-# - [Cargo Issue-1197: Target-specific features](https://github.com/rust-lang/cargo/issues/1197)
 [target.'cfg(all(not(target_env = "msvc"), not(target_os="macos")))'.dependencies]
 heim = "0.0.10"
 futures = "0.3.1"

util/memory-tracker/src/jemalloc.rs

@@ -1,7 +1,13 @@
 use ckb_logger::info;
 use std::{ffi, mem, ptr};
 
-/// TODO(doc): @yangby-cryptape
+/// Dumps the heap through Jemalloc's API.
+///
+/// This funcions works when the following conditions are satisfied:
+/// - the global allocator is [Jemallocator].
+/// - the profiling is enabled.
+///
+/// [Jemallocator]: https://docs.rs/jemallocator/*/jemallocator/index.html
 pub fn jemalloc_profiling_dump(filename: &str) -> Result<(), String> {
     let mut filename0 = format!("{}\0", filename);
     let opt_name = "prof.dump";

util/memory-tracker/src/lib.rs

@@ -1,4 +1,5 @@
-//! TODO(doc): @yangby-cryptape
+//! Track the memory usage of CKB.
+
 #[cfg(all(
     not(target_env = "msvc"),
     not(target_os = "macos"),
@@ -11,7 +12,9 @@ mod jemalloc;
     feature = "profiling"
 )))]
 mod jemalloc {
-    /// TODO(doc): @yangby-cryptape
+    /// A dummy function which is used when the Jemalloc profiling isn't supported.
+    ///
+    /// Jemalloc profiling is disabled in default, the feature `profiling` is used to enable it.
     pub fn jemalloc_profiling_dump(_: &str) -> Result<(), String> {
         Err("jemalloc profiling dump: unsupported".to_string())
     }
@@ -26,21 +29,21 @@ mod process {
     use crate::rocksdb::TrackRocksDBMemory;
     use ckb_logger::info;
 
-    /// TODO(doc): @yangby-cryptape
+    /// A dummy function which is used when tracking memory usage isn't supported.
     pub fn track_current_process<Tracker: 'static + TrackRocksDBMemory + Sync + Send>(
         _: u64,
         _: Option<sync::Arc<Tracker>>,
     ) {
         info!("track current process: unsupported");
     }
 }
-pub mod rocksdb;
-pub mod utils;
+mod rocksdb;
 
 pub use jemalloc::jemalloc_profiling_dump;
 pub use process::track_current_process;
+pub use rocksdb::TrackRocksDBMemory;
 
-/// TODO(doc): @yangby-cryptape
+/// Track the memory usage of the CKB process and Jemalloc.
 pub fn track_current_process_simple(interval: u64) {
     track_current_process::<rocksdb::DummyRocksDB>(interval, None);
 }

util/memory-tracker/src/process.rs

@@ -30,7 +30,7 @@ macro_rules! mib_read {
     };
 }
 
-/// TODO(doc): @yangby-cryptape
+/// Track the memory usage of the CKB process, Jemalloc and RocksDB through [ckb-metrics](../../ckb_metrics/index.html).
 pub fn track_current_process<Tracker: 'static + TrackRocksDBMemory + Sync + Send>(
     interval: u64,
     tracker_opt: Option<sync::Arc<Tracker>>,
@@ -89,7 +89,7 @@ pub fn track_current_process<Tracker: 'static + TrackRocksDBMemory + Sync + Send
                             metrics!(gauge, "ckb-sys.mem.jemalloc", metadata, "type" => "metadata");
 
                             if let Some(tracker) = tracker_opt.clone() {
-                                let _ignored = tracker.gather_memory_stats();
+                                tracker.gather_memory_stats();
                             }
                         } else {
                             error!("failed to fetch the memory information about current process");

util/memory-tracker/src/rocksdb.rs

@@ -1,63 +1,60 @@
-//! TODO(doc): @yangby-cryptape
 use ckb_db::internal::ops::{GetColumnFamilys, GetProperty, GetPropertyCF};
 use ckb_metrics::metrics;
 
-use crate::utils::{sum_int_values, PropertyValue};
-
-/// TODO(doc): @yangby-cryptape
-// Ref: https://github.com/facebook/rocksdb/wiki/Memory-usage-in-RocksDB
-pub struct RocksDBMemoryStatistics {
-    /// TODO(doc): @yangby-cryptape
-    pub estimate_table_readers_mem: PropertyValue<u64>,
-    /// TODO(doc): @yangby-cryptape
-    pub size_all_mem_tables: PropertyValue<u64>,
-    /// TODO(doc): @yangby-cryptape
-    pub cur_size_all_mem_tables: PropertyValue<u64>,
-    /// TODO(doc): @yangby-cryptape
-    pub block_cache_capacity: PropertyValue<u64>,
-    /// TODO(doc): @yangby-cryptape
-    pub block_cache_usage: PropertyValue<u64>,
-    /// TODO(doc): @yangby-cryptape
-    pub block_cache_pinned_usage: PropertyValue<u64>,
+#[derive(Debug, Clone)]
+enum PropertyValue<T> {
+    Value(T),
+    Null,
+    Error(String),
 }
 
-/// TODO(doc): @yangby-cryptape
-pub trait TrackRocksDBMemory {
-    /// TODO(doc): @yangby-cryptape
-    fn gather_memory_stats(&self) -> RocksDBMemoryStatistics {
-        let estimate_table_readers_mem = self.gather_int_values("estimate-table-readers-mem");
-        let size_all_mem_tables = self.gather_int_values("size-all-mem-tables");
-        let cur_size_all_mem_tables = self.gather_int_values("cur-size-all-mem-tables");
-        let block_cache_capacity = self.gather_int_values("block-cache-capacity");
-        let block_cache_usage = self.gather_int_values("block-cache-usage");
-        let block_cache_pinned_usage = self.gather_int_values("block-cache-pinned-usage");
-        RocksDBMemoryStatistics {
-            estimate_table_readers_mem,
-            size_all_mem_tables,
-            cur_size_all_mem_tables,
-            block_cache_capacity,
-            block_cache_usage,
-            block_cache_pinned_usage,
+impl PropertyValue<u64> {
+    pub(crate) fn as_i64(&self) -> i64 {
+        match self {
+            Self::Value(v) => *v as i64,
+            Self::Null => -1,
+            Self::Error(_) => -2,
         }
     }
-    /// TODO(doc): @yangby-cryptape
-    fn gather_int_values(&self, key: &str) -> PropertyValue<u64>;
 }
 
-/// TODO(doc): @yangby-cryptape
-pub struct DummyRocksDB;
+impl<T> From<Result<Option<T>, String>> for PropertyValue<T> {
+    fn from(res: Result<Option<T>, String>) -> Self {
+        match res {
+            Ok(Some(v)) => Self::Value(v),
+            Ok(None) => Self::Null,
+            Err(e) => Self::Error(e),
+        }
+    }
+}
 
-impl TrackRocksDBMemory for DummyRocksDB {
-    fn gather_int_values(&self, _: &str) -> PropertyValue<u64> {
-        PropertyValue::Null
+/// A trait which used to track the RocksDB memory usage.
+///
+/// References: [Memory usage in RocksDB](https://github.com/facebook/rocksdb/wiki/Memory-usage-in-RocksDB)
+pub trait TrackRocksDBMemory {
+    /// Gather memory statistics through [ckb-metrics](../../ckb_metrics/index.html)
+    fn gather_memory_stats(&self) {
+        self.gather_int_values("estimate-table-readers-mem");
+        self.gather_int_values("size-all-mem-tables");
+        self.gather_int_values("cur-size-all-mem-tables");
+        self.gather_int_values("block-cache-capacity");
+        self.gather_int_values("block-cache-usage");
+        self.gather_int_values("block-cache-pinned-usage");
     }
+
+    /// Gather integer values through [ckb-metrics](../../ckb_metrics/index.html)
+    fn gather_int_values(&self, _: &str) {}
 }
 
+pub(crate) struct DummyRocksDB;
+
+impl TrackRocksDBMemory for DummyRocksDB {}
+
 impl<RocksDB> TrackRocksDBMemory for RocksDB
 where
     RocksDB: GetColumnFamilys + GetProperty + GetPropertyCF,
 {
-    fn gather_int_values(&self, key: &str) -> PropertyValue<u64> {
+    fn gather_int_values(&self, key: &str) {
         let mut values = Vec::new();
         for (cf_name, cf) in self.get_cfs() {
             let value_col: PropertyValue<u64> = self
@@ -67,6 +64,5 @@ where
             metrics!(gauge, "ckb-sys.mem.rocksdb", value_col.as_i64(), "type" => key.to_owned(), "cf" => cf_name.to_owned());
             values.push(value_col);
         }
-        sum_int_values(&values)
     }
 }