Struct PaperCache

pub struct PaperCache<K, V, S = RandomState> { /* private fields */ }

Implementations

impl<K, V, S> PaperCache<K, V, S>

where K: 'static + Eq + Hash + TypeSize, V: 'static + TypeSize, S: Default + Clone + BuildHasher,

pub fn new( max_size: CacheSize, policies: &[PaperPolicy], policy: PaperPolicy, ) -> Result<Self, CacheError>

Creates an empty PaperCache with maximum size max_size and eviction policy policy. If the maximum size is zero, a CacheError will be returned.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
);

assert!(cache.is_ok());

// Supplying a maximum size of zero will return a `CacheError`.
let cache = PaperCache::<u32, u32>::new(
    0,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
);

assert!(cache.is_err());

// Supplying duplicate policies will return a `CacheError`.
let cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu, PaperPolicy::Lru, PaperPolicy::Lfu],
    PaperPolicy::Lfu,
);

assert!(cache.is_err());

// Supplying a non-configured policy will return a `CacheError`.
let cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lru,
);

assert!(cache.is_err());

pub fn with_hasher( max_size: CacheSize, policies: &[PaperPolicy], policy: PaperPolicy, hasher: S, ) -> Result<Self, CacheError>

Creates an empty PaperCache with the supplied hasher.

Examples

use std::hash::RandomState;
use paper_cache::{PaperCache, PaperPolicy};

let cache = PaperCache::<u32, u32>::with_hasher(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
    RandomState::default(),
);

assert!(cache.is_ok());

pub fn version(&self) -> String

Returns the current cache version.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu
).unwrap();

assert_eq!(cache.version(), env!("CARGO_PKG_VERSION"));

pub fn status(&self) -> Result<Status, CacheError>

Returns the current statistics.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.set(0, 0, None);

let status = cache.status().unwrap();
assert!(status.used_size() > 0);

pub fn get(&self, key: &K) -> Result<Arc<V>, CacheError>

Gets the value associated with the supplied key. If the key was not found in the cache, returns a CacheError.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.set(0, 0, None);

// Getting a key which exists in the cache will return the associated value.
assert!(cache.get(&0).is_ok());
// Getting a key which does not exist in the cache will return a CacheError.
assert!(cache.get(&1).is_err());

pub fn set(&self, key: K, value: V, ttl: Option<u32>) -> Result<(), CacheError>

Sets the supplied key and value in the cache. Returns a CacheError if the value size is zero or larger than the cache’s maximum size.

If the key already exists in the cache, the associated value is updated to the supplied value.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

assert!(cache.set(0, 0, None).is_ok());

pub fn del(&self, key: &K) -> Result<(), CacheError>

Deletes the object associated with the supplied key in the cache. Returns a CacheError if the key was not found in the cache.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.set(0, 0, None);
assert!(cache.del(&0).is_ok());

// Deleting a key which does not exist in the cache will return a CacheError.
assert!(cache.del(&1).is_err());

pub fn has(&self, key: &K) -> bool

Checks if an object with the supplied key exists in the cache without altering any of the cache’s internal queues.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.set(0, 0, None);

assert!(cache.has(&0));
assert!(!cache.has(&1));

pub fn peek(&self, key: &K) -> Result<Arc<V>, CacheError>

Gets (peeks) the value associated with the supplied key without altering any of the cache’s internal queues. If the key was not found in the cache, returns a CacheError.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.set(0, 0, None);
cache.set(1, 0, None);

// Peeking a key which exists in the cache will return the associated value.
assert!(cache.peek(&0).is_ok());
// Peeking a key which does not exist in the cache will return a CacheError.
assert!(cache.peek(&2).is_err());

cache.set(2, 0, None);

// Peeking a key will not alter the eviction order of the objects.
assert!(cache.peek(&1).is_ok());
assert!(cache.peek(&2).is_ok());

pub fn ttl(&self, key: &K, ttl: Option<u32>) -> Result<(), CacheError>

Sets the TTL associated with the supplied key. If the key was not found in the cache, returns a CacheError.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.set(0, 0, None); // value will not expire
cache.ttl(&0, Some(5)); // value will expire in 5 seconds

pub fn size(&self, key: &K) -> Result<u32, CacheError>

Gets the size of the value associated with the supplied key in bytes. If the key was not found in the cache, returns a CacheError.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.set(0, 0, None);

// Sizing a key which exists in the cache will return the size of the associated value.
assert!(cache.size(&0).is_ok());
// Sizing a key which does not exist in the cache will return a CacheError.
assert!(cache.size(&1).is_err());

pub fn wipe(&self) -> Result<(), CacheError>

Deletes all objects in the cache and sets the cache’s used size to zero. Returns a CacheError if the objects could not be wiped.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

cache.wipe();

pub fn resize(&self, max_size: CacheSize) -> Result<(), CacheError>

Resizes the cache to the supplied maximum size. If the supplied size is zero, returns a CacheError.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

assert!(cache.resize(1).is_ok());

// Resizing to a size of zero will return a CacheError.
assert!(cache.resize(0).is_err());

pub fn policy(&self, policy: PaperPolicy) -> Result<(), CacheError>

Sets the eviction policy of the cache to the supplied policy.

Examples

use paper_cache::{PaperCache, PaperPolicy};

let mut cache = PaperCache::<u32, u32>::new(
    1000,
    &[PaperPolicy::Lfu],
    PaperPolicy::Lfu,
).unwrap();

assert!(cache.policy(PaperPolicy::Lfu).is_ok());
assert!(cache.policy(PaperPolicy::Lru).is_err());

Trait Implementations

impl<K, V, S> Send for PaperCache<K, V, S>