feat: optional tracked metadata for read ops

Author: DevBlocky

benches/benchmarks.rs

@@ -1,21 +1,30 @@
-use criterion::{criterion_group, Criterion};
+use criterion::{criterion_group, BenchmarkId, Criterion};
 use rand::prelude::*;
-use std::time::Instant;
+use std::cell::UnsafeCell;
+use std::thread_local;
 
-fn make_executor() -> (forceps::Cache, tokio::runtime::Runtime) {
+fn make_executor_custom<F: FnOnce() -> forceps::CacheBuilder>(
+    f: F,
+) -> (forceps::Cache, tokio::runtime::Runtime) {
     let rt = tokio::runtime::Builder::new_current_thread()
         .enable_all()
         .build()
         .unwrap();
 
-    let cache = rt.block_on(async move { forceps::CacheBuilder::default().build().await.unwrap() });
+    let cache = rt.block_on(async move { f().build().await.unwrap() });
     (cache, rt)
 }
+fn make_executor() -> (forceps::Cache, tokio::runtime::Runtime) {
+    make_executor_custom(|| forceps::CacheBuilder::default())
+}
 
 fn random_bytes(size: usize) -> Vec<u8> {
+    std::thread_local! {
+        static RNG: UnsafeCell<SmallRng> = UnsafeCell::new(SmallRng::from_entropy());
+    }
+
     let mut buf = vec![0u8; size];
-    let mut rng = rand::rngs::OsRng::default();
-    rng.fill_bytes(&mut buf);
+    RNG.with(|rng| unsafe { (&mut *rng.get()).fill_bytes(&mut buf) });
     buf
 }
 
@@ -50,18 +59,27 @@ pub fn cache_write_random_key(c: &mut Criterion) {
 }
 
 pub fn cache_read_const_key(c: &mut Criterion) {
-    c.bench_function("cache::read_const_key", move |b| {
-        let (db, rt) = make_executor();
-        const KEY: [u8; 4] = [0xDE, 0xAD, 0xBE, 0xEF];
-        let value = random_bytes(VALUE_SZ);
-
-        // assert there is the key in the db
-        rt.block_on(db.write(&KEY, &value)).unwrap();
-
-        b.iter(|| {
-            rt.block_on(db.read(&KEY)).unwrap();
-        });
-    });
+    let mut group = c.benchmark_group("cache::read_const_key");
+    for &tracking in [false, true].iter() {
+        group.bench_with_input(
+            BenchmarkId::from_parameter(if tracking { "tracked" } else { "untracked" }),
+            &tracking,
+            move |b, &tracking| {
+                let (db, rt) = make_executor_custom(|| {
+                    forceps::CacheBuilder::default().track_access(tracking)
+                });
+                const KEY: [u8; 4] = [0xDE, 0xAD, 0xBE, 0xEF];
+                let value = random_bytes(VALUE_SZ);
+
+                // assert there is the key in the db
+                rt.block_on(db.write(&KEY, &value)).unwrap();
+
+                b.iter(|| {
+                    rt.block_on(db.read(&KEY)).unwrap();
+                });
+            },
+        );
+    }
 }
 
 pub fn cache_remove_const_key(c: &mut Criterion) {

src/builder.rs

@@ -45,7 +45,7 @@ impl CacheBuilder {
         let opts = Options {
             path: path.as_ref().to_owned(),
             dir_depth: 2,
-            save_last_access: false,
+            track_access: false,
 
             // default buffer sizes to 8kb
             rbuff_sz: 8192,
@@ -83,6 +83,18 @@ impl CacheBuilder {
         self
     }
 
+    /// If set to `true`, this will track track the total hits and the last time an entry was
+    /// accessed in the metadata.
+    ///
+    /// **Default is `false`**
+    ///
+    /// Be warned, turning this on will cause blocking metadata database calls to occur on `read`
+    /// operations. This does not normally occur and can cause problems for `async` applications.
+    pub fn track_access(mut self, toggle: bool) -> Self {
+        self.opts.track_access = toggle;
+        self
+    }
+
     /// Builds the new [`Cache`] instance using the configured options of the builder.
     ///
     /// # Examples

src/cache.rs

@@ -22,8 +22,7 @@ async fn tempfile(dir: &path::Path) -> Result<(afs::File, path::PathBuf)> {
 pub(crate) struct Options {
     pub(crate) path: path::PathBuf,
     pub(crate) dir_depth: u8,
-    // TODO: implement below option
-    pub(crate) save_last_access: bool,
+    pub(crate) track_access: bool,
 
     // read and write buffer sizes
     pub(crate) rbuff_sz: usize,
@@ -119,6 +118,12 @@ impl Cache {
     /// If the entry is not found, then it will return
     /// `Err(`[`Error::NotFound`](ForcepError::NotFound)`)`.
     ///
+    /// # Metadata
+    ///
+    /// This function will *not* perform a metadata read or write **unless** the `track_access`
+    /// build option is set. If the option is set, then it will perform a blocking read/write to
+    /// write new values to track the last access time and the total hits.
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -160,6 +165,12 @@ impl Cache {
             .read_to_end(&mut buf)
             .await
             .map_err(ForcepError::Io)?;
+
+        // track this access if the flag is set
+        if self.opts.track_access {
+            self.meta.track_access_for(key.as_ref())?;
+        }
+
         Ok(Bytes::from(buf))
     }
 
@@ -355,6 +366,21 @@ mod test {
         cache.remove(&b"CACHE_KEY").await.unwrap();
     }
 
+    #[tokio::test]
+    async fn tracking_test() {
+        let cache = CacheBuilder::default()
+            .track_access(true)
+            .build()
+            .await
+            .unwrap();
+
+        cache.write(b"CACHE_KEY", b"Hello World").await.unwrap();
+        for _ in 0..100 {
+            cache.read(b"CACHE_KEY").await.unwrap();
+        }
+        assert_eq!(cache.read_metadata(b"CACHE_KEY").unwrap().get_hits(), 100);
+    }
+
     #[tokio::test]
     async fn read_metadata() {
         let cache = default_cache().await;

src/metadata.rs

@@ -36,6 +36,8 @@ pub struct Metadata {
     last_modified: u64,
     /// Last time since this entry was accessed, milliseconds since epoch
     last_accessed: u64,
+    /// Number of times this entry has been HIT (total accesses)
+    hits: u64,
     /// Md5 hash of the underlying data
     integrity: Md5Bytes,
 }
@@ -61,6 +63,7 @@ impl Metadata {
             size: data.len() as u64,
             last_modified: now_since_epoch(),
             last_accessed: now_since_epoch(),
+            hits: 0,
             integrity: md5::compute(data).into(),
         }
     }
@@ -109,6 +112,43 @@ impl Metadata {
         self.last_modified
     }
 
+    /// The total number of times this entry has been read.
+    ///
+    /// **NOTE:** This will be 0 unless `track_access` is enabled from the [`CacheBuilder`]
+    ///
+    /// [`CacheBuilder`]: crate::CacheBuilder
+    #[inline]
+    pub fn get_hits(&self) -> u64 {
+        self.hits
+    }
+
+    /// Retrives the last time this entry was accessed (read from).
+    ///
+    /// **NOTE:** This will be the same as [`get_last_modified`] unless `track_access` is enabled from
+    /// the [`CacheBuilder`]
+    ///
+    /// [`get_last_modified`]: Self::get_last_modified
+    /// [`CacheBuilder`]: crate::CacheBuilder
+    pub fn get_last_acccessed(&self) -> Option<time::SystemTime> {
+        match self.last_accessed {
+            0 => None,
+            millis => Some(time::UNIX_EPOCH + time::Duration::from_millis(millis)),
+        }
+    }
+    /// Retrieves the raw `last_accessed` time, which is the milliseconds since
+    /// [`time::UNIX_EPOCH`]. If the returned result is `0`, that means there is no `last_accessed`
+    /// time.
+    ///
+    /// **NOTE:** This will be the same as [`get_last_modified_raw`] unless `track_access` is enabled
+    /// from the [`CacheBuilder`]
+    ///
+    /// [`get_last_modified_raw`]: Self::get_last_modified_raw
+    /// [`CacheBuilder`]: crate::CacheBuilder
+    #[inline]
+    pub fn get_last_accessed_raw(&self) -> u64 {
+        self.last_accessed
+    }
+
     /// Retrieves the internal [`Md5Bytes`] integrity of the corresponding metadata entry.
     #[inline]
     pub fn get_integrity(&self) -> &Md5Bytes {
@@ -161,6 +201,22 @@ impl MetaDb {
         }
     }
 
+    /// Will increment the `hits` counter and set the `last_accessed` value to now for the found
+    /// metadata key.
+    pub fn track_access_for(&self, key: &[u8]) -> Result<Metadata> {
+        let mut meta = match self.db.get(key) {
+            Ok(Some(entry)) => Metadata::deserialize(&entry[..])?,
+            Err(e) => return Err(ForcepError::MetaDb(e)),
+            Ok(None) => return Err(ForcepError::NotFound),
+        };
+        meta.last_accessed = now_since_epoch();
+        meta.hits += 1;
+        self.db
+            .insert(key, Metadata::serialize(&meta)?)
+            .map_err(ForcepError::MetaDb)?;
+        Ok(meta)
+    }
+
     /// Iterator over the entire metadata database
     pub fn metadata_iter(&self) -> impl Iterator<Item = Result<(Vec<u8>, Metadata)>> {
         self.db.iter().map(|x| match x {