Struct rocket_file_cache::Cache

pub struct Cache { /* 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.

Methods

impl Cache

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

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)
}

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

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.

Return

The CachedFile will indicate NotFound if the file isn't already in the cache or if it can't be found in the filesystem. It will otherwise return a CachedFile::InMemory variant.

pub 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, CacheBuilder};
use std::path::PathBuf;

let mut cache = CacheBuilder::new().build().unwrap();
let pathbuf = PathBuf::new();
cache.remove(&pathbuf);
assert!(cache.contains_key(&pathbuf) == false);

pub 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::{CacheBuilder};
use std::path::PathBuf;

let mut cache = CacheBuilder::new().build().unwrap();
let pathbuf: PathBuf = PathBuf::new();
cache.get(&pathbuf);
assert!(cache.contains_key(&pathbuf) == false);

pub 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, CacheBuilder};
use std::path::PathBuf;

let mut cache = CacheBuilder::new().build().unwrap();
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.

pub 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, CacheBuilder};
use std::path::PathBuf;

let mut cache = CacheBuilder::new().build().unwrap();
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 });

pub 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, CacheBuilder};

let cache = CacheBuilder::new().build().unwrap();
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.