Struct rocket_file_cache::Cache

pub struct Cache {
    pub size_limit: usize,
    pub min_file_size: usize,
    pub max_file_size: usize,
    pub priority_function: fn(_: usize, _: usize) -> usize,
    // some fields omitted
}

The cache holds a number of files whose bytes fit into its size_limit. The cache acts as a proxy to the filesystem, returning cached files if they are in the cache, or reading a file directly from the filesystem if the file is not in the cache.

When the cache is full, each file in the cache will have priority score determined by a provided priority function. When a call to get() is made, an access counter for the file in question is incremented, usually (depending on the supplied priority function) increasing the priority score of the file. When a a new file is attempted to be stored, it will calculate the priority of the new score and compare that against the score of the file with the lowest priority in the cache. If the new file's priority is higher, then the file in the cache will be removed and replaced with the new file. If removing the first file doesn't free up enough space for the new file, then the file with the next lowest priority will have its priority added to the other removed file's and the aggregate cached file's priority will be tested against the new file's.

This will repeat until either enough space can be freed for the new file, and the new file is inserted, or until the priority of the cached files is greater than that of the new file, in which case, the new file isn't inserted.

Fields

size_limit: usize

The number of bytes the file_map should be able hold at once.

min_file_size: usize

The minimum number of bytes a file must have in order to be accepted into the Cache.

max_file_size: usize

The maximum number of bytes a file can have in order to be accepted into the Cache.

priority_function: fn(_: usize, _: usize) -> usize

The function that is used to calculate the priority score that is used to determine which files should be in the cache.

Methods

impl Cache

fn new(size_limit: usize) -> Cache

Creates a new Cache with the given size limit, no limits on individual file size, and the default priority function. These settings can be set by using the CacheBuilder instead.

Arguments

• size_limit - The number of bytes that the Cache is allowed to hold at a given time.

Example

use rocket_file_cache::Cache;
let mut cache = Cache::new(1024 * 1024 * 30); // Create a cache that can hold 30 MB of files

fn get<'a, P: AsRef<Path>>(&'a self, path: P) -> CachedFile<'a>

Either gets the file from the cache if it exists there, gets it from the filesystem and tries to cache it, or fails to find the file.

The CachedFile that is returned takes a lock out on that file in the cache, if that file happens to exist in the cache. This lock will release when the CachedFile goes out of scope.

Arguments

• path - A path that represents the path of the file in the filesystem. The path also acts as a key for the file in the cache. The path will be used to find a cached file in the cache or find a file in the filesystem if an entry in the cache doesn't exist.

Example

#![feature(attr_literals)]
#![feature(custom_attribute)]

use rocket_file_cache::{Cache, CachedFile};
use std::path::{Path, PathBuf};
use rocket::State;
use std::sync::Arc;
use std::sync::atomic::AtomicPtr;


#[get("/<file..>")]
fn files<'a>(file: PathBuf,  cache: State<'a, Cache> ) -> CachedFile<'a> {
    let path: PathBuf = Path::new("www/").join(file).to_owned();
    cache.inner().get(path)
}

fn refresh<P: AsRef<Path>>(&self, path: P) -> bool

If a file has changed on disk, the cache will not automatically know that a change has occurred. Calling this function will check if the file exists, read the new file into memory, replace the old file, and update the priority score to reflect the new size of the file.

Arguments

• path - A path that represents the path of the file in the filesystem, and key to the file in the cache. The path will be used to find the new file in the filesystem and to find the old file to replace in the cache.

fn remove<P: AsRef<Path>>(&self, path: P) -> bool

Removes the file from the cache. This will not reset the access count, so the next time the file is accessed, it will be added to the cache again. The access count will have to be reset separately using alter_access_count().

Arguments

• path - A path that acts as a key to look up the file that should be removed from the cache.

Example

use rocket_file_cache::Cache;
use std::path::PathBuf;

let mut cache = Cache::new(1024 * 1024 * 10);
let pathbuf = PathBuf::new();
cache.remove(&pathbuf);
assert!(cache.contains_key(&pathbuf) == false);

fn contains_key<P: AsRef<Path>>(&self, path: P) -> bool

Returns a boolean indicating if the cache has an entry corresponding to the given key.

Arguments

• path - A path that is used as a key to look up the file.

Example

use rocket_file_cache::Cache;
use std::path::PathBuf;

let mut cache = Cache::new(1024 * 1024 * 20);
let pathbuf: PathBuf = PathBuf::new();
cache.get(&pathbuf);
assert!(cache.contains_key(&pathbuf) == false);

fn alter_access_count<P: AsRef<Path>>(
    &self,
    path: P,
    alter_count_function: fn(_: &usize) -> usize
) -> bool

Alters the access count value of one file in the access_count_map.

Arguments

• path - The key to look up the file.
• alter_count_function - A function that determines how to alter the access_count for the file.

Example

use rocket_file_cache::Cache;
use std::path::PathBuf;

let mut cache = Cache::new(1024 * 1024 * 10);
let pathbuf = PathBuf::new();
cache.get(&pathbuf); // Add a file to the cache
cache.remove(&pathbuf); // Removing the file will not reset its access count.
cache.alter_access_count(&pathbuf, | x | { 0 }); // Set the access count to 0.

fn alter_all_access_counts(&self, alter_count_function: fn(_: &usize) -> usize)

Alters the access count value of every file in the access_count_map. This is useful for manually aging-out entries in the cache.

Arguments

• alter_count_function - A function that determines how to alter the access_count for the file.

Example

use rocket_file_cache::Cache;
use std::path::PathBuf;

let mut cache = Cache::new(1024 * 1024 * 10);
let pathbuf = PathBuf::new();
let other_pathbuf = PathBuf::new();
cache.get(&pathbuf);
cache.get(&other_pathbuf);
// Reduce all access counts by half,
// allowing newer files to enter the cache more easily.
cache.alter_all_access_counts(| x | { x / 2 });

fn used_bytes(&self) -> usize

Gets the sum of the sizes of the files that are stored in the cache.

Example

use rocket_file_cache::Cache;

let cache = Cache::new(1024 * 1024 * 30);
assert!(cache.used_bytes() == 0);

Trait Implementations

impl Debug for Cache

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.