Provide a way to iterate entries with their metadata

[tatsuya6502]

Provide a new iterator to iterate entries with their metadata such as last access time.

#311 (comment) by @peter-scholtens

Similar as mentioned in #235, I try to store and read-in my Cache content locally during a re-start of my server. However, this means the expiration state will be reset: the frequency is set to zero and the TTL/TTI maximized. Would it be possible to iterate with Expiration state? So this state information can be stored too.

We will do the followings:

• Add iter_entries method to Cache, which returns an iterator of Entry<K, V>.
• Add metadata method to Entry<K, V>, which returns a reference to a new struct &EntryMetadata.
• EntryMetadata will have the following information:
  • last_modified as std::time::Instant
  • last_accessed as std::time::Instant
  • expiration_time as Option<std::time::Instant>
    • This value will be available only when the Expiry is set.
  • policy_weight as u32

Example

// A new method of Cache that returns an iterator of Entry<K, V>.
for entry in cache.iter_entries() {
    dbg!(entry.key()); //   &K
    dbg!(entry.value()); // &V

    // A new method of Entry.
    let md = entry.metadata(); // &EntryMetadata

    dbg!(md.last_modified()); //  std::time::Instant
    dbg!(md.last_accessed()); //  std::time::Instant

    // This value will be available only when the Expiry is set.
    dbg!(md.expiration_time()); // Option<std::time::Instant>

    dbg!(md.policy_weight()); //   u32
}

Note: If users want to save the entry metadata outside their application, they will need to convert std::time::Instant to a wall-clock time such as time::OffsetDateTime from time crate. The followings will illustrate how to achieve it:

use std::time::Instant
use time::OffsetDateTime;

let md = entry.metadata();

let (now_instant, now_dt) = (Instant::now(), OffsetDateTime::now_utc());
let instant_to_dt = |instant: Instant| -> OffsetDateTime {
    // The `instant` must be earlier than or equal to `now_instant`,
    // otherwise this will panic.
    let duration = now_instant - instant;
    now_dt - time::Duration::seconds(duration.as_secs())
};

let last_modified_dt = instant_to_dt(md.last_modified()); // time::OffsetDateTime

[tatsuya6502]

I realized that EntryMetadata must have region::CacheRegion, otherwise we cannot restore entries to the right places.

• https://github.com/moka-rs/moka/wiki#admission-and-eviction-policies

v0.12.2/src/common.rs#L15-L24

// Note: `CacheRegion` cannot have more than four enum variants. This is because
// `crate::{sync,unsync}::DeqNodes` uses a `tagptr::TagNonNull<DeqNode<T>, 2>`
// pointer, where the 2-bit tag is `CacheRegion`.
#[derive(Clone, Copy, Debug, Eq)]
pub(crate) enum CacheRegion {
    Window = 0,
    MainProbation = 1,
    MainProtected = 2,
    Other = 3,
}

We will use CacheRegion::Window for the temporary admitted entries, and CacheRegion::MainProvation for the admitted entries.

Also, we will provide ways to convert EntryMetadata into JSON and serialize it into a binary (Vec<u8>).