Trait GlobalCache 

pub trait GlobalCache {
    type Entry;

    // Required methods
    fn len(&self) -> usize;
    fn is_empty(&self) -> bool;
    fn cache<Q>(&self, value: Q) -> Self::Entry
       where Self::Entry: Borrow<Q>,
             Q: Into<Self::Entry> + Hash + Eq;

    // Provided methods
    fn gc(&self) -> usize { ... }
    fn try_gc(&self, _key: &mut Self::Entry) -> Option<Self::Entry> { ... }
    fn try_gc_global(&self, _key: &Self::Entry) -> Option<Self::Entry> { ... }
}

A gloabl cache implementation

Required Associated Types

type Entry

The cache entry type

Required Methods

fn len(&self) -> usize

Compute how many items are in a given cache.

Example

use dashcache::{GlobalCache, DashCache};
use elysees::Arc;
let int_cache = DashCache::<Arc<u64>>::new();
assert_eq!(int_cache.len(), 0);
int_cache.cache(10);
assert_eq!(int_cache.len(), 1);
int_cache.cache(20);
assert_eq!(int_cache.len(), 2);
// Since 10 is already in the cache, this is a no-op:
int_cache.cache(10);
assert_eq!(int_cache.len(), 2);

fn is_empty(&self) -> bool

Check if a cache is empty

Example

use dashcache::{GlobalCache, DashCache};
use elysees::Arc;
let int_cache = DashCache::<Arc<u64>>::new();
assert!(int_cache.is_empty());
int_cache.cache(10);
assert!(!int_cache.is_empty());

fn cache<Q>(&self, value: Q) -> Self::Entry

where Self::Entry: Borrow<Q>, Q: Into<Self::Entry> + Hash + Eq,

Attempt to cache a value. If already cached, return the corresponding entry.

Example

use dashcache::{GlobalCache, DashCache};
use elysees::Arc;
let int_cache = DashCache::<Arc<u64>>::new();

let cached_32 = int_cache.cache(32);
let arc_32 = Arc::new(32);
// These are different allocations!
assert!(!Arc::ptr_eq(&arc_32, &cached_32));

// We can use the cache to de-duplicate allocations
let dedup_32 = int_cache.cache(arc_32.clone());
assert!(Arc::ptr_eq(&dedup_32, &cached_32));

// Similarly, we'll get the same `Arc` if we insert the value again
let new_32 = int_cache.cache(32);
assert!(Arc::ptr_eq(&new_32, &cached_32));

// We can also insert an `Arc` from the get-go:
let arc_44 = Arc::new(44);
let cached_44 = int_cache.cache(arc_44.clone());
assert!(Arc::ptr_eq(&arc_44, &cached_44));
// New insertions are also deduplicated:
let dedup_44 = int_cache.cache(44);
assert!(Arc::ptr_eq(&arc_44, &dedup_44));

Provided Methods

fn gc(&self) -> usize

Attempt to garbage-collect this cache, returning how many elements were removed.

Example

use dashcache::{GlobalCache, DashCache};
use elysees::Arc;
let int_cache = DashCache::<Arc<u64>>::new();

// Let's stick 2 used values and 3 unused values into the cache:
let used_1 = int_cache.cache(77);
let used_2 = int_cache.cache(88);
int_cache.cache(99);
int_cache.cache(500);
int_cache.cache(81);
// We can see that at this point there are 5 things in the cache:
assert_eq!(int_cache.len(), 5);
// Now, let's garbage collect the cache, which should bring us down 3 things:
assert_eq!(int_cache.gc(), 3);
// And we have 2 things left:
assert_eq!(int_cache.len(), 2);
assert!(Arc::ptr_eq(&used_1, &int_cache.cache(77)));
assert!(Arc::ptr_eq(&used_2, &int_cache.cache(88)));

Implementation Notes

Note that this implements conservative GC, and in general it is perfectly well defined for this to be a no-op

fn try_gc(&self, _key: &mut Self::Entry) -> Option<Self::Entry>

Garbage collect a single entry if doing so would not break the hash-consing property due to uniqueness. Returns the removed key on success, or Err(key) on failure

Implementation notes

Note that this implements conservative GC, and in general it is perfectly well defined for this to be a no-op

fn try_gc_global(&self, _key: &Self::Entry) -> Option<Self::Entry>

Garbage collect a single entry if doing so would not break the hash-consing property due to uniqueness. Returns the removed key on success, or Err(key) on failure.

Correctness

This function will cause the entry borrowed from to no longer be in the hash cache, so use with caution!

Implementation notes

Note that this implements conservative GC, and in general it is perfectly well defined for this to be a no-op.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<C, S> GlobalCache for DashCache<C, S>

where S: BuildHasher + Clone, C: Hash + Eq + Clone + CanCollect,

type Entry = C