#![forbid(unsafe_code)]
#![warn(missing_docs)]
use std::error::Error;
use std::fmt;
use std::future::Future;
use std::pin::Pin;
#[cfg(feature = "memory")]
mod lru;
#[cfg(feature = "memory")]
pub use lru::Lru;
pub type BoxError = Box<dyn Error + Send + Sync>;
pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
pub trait CacheStore: Send + Sync {
fn get<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<Option<Vec<u8>>, BoxError>>;
fn put<'a>(&'a self, key: &'a str, value: &'a [u8]) -> BoxFuture<'a, Result<(), BoxError>>;
fn delete<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<(), BoxError>>;
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Op {
Get,
Put,
Delete,
}
#[derive(Debug)]
pub struct DeleteError {
pub failures: Vec<(usize, BoxError)>,
}
impl fmt::Display for DeleteError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "delete failed on {} level(s):", self.failures.len())?;
for (level, e) in &self.failures {
write!(f, " [{level}] {e};")?;
}
Ok(())
}
}
impl Error for DeleteError {}
type ErrorHook = Box<dyn Fn(usize, Op, &BoxError) + Send + Sync>;
pub struct Cache {
levels: Vec<Box<dyn CacheStore>>,
on_error: Option<ErrorHook>,
}
impl fmt::Debug for Cache {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Cache")
.field("levels", &self.levels.len())
.finish_non_exhaustive()
}
}
impl Cache {
#[must_use]
pub fn new(levels: Vec<Box<dyn CacheStore>>) -> Self {
Self {
levels,
on_error: None,
}
}
#[must_use]
pub fn on_error(mut self, hook: impl Fn(usize, Op, &BoxError) + Send + Sync + 'static) -> Self {
self.on_error = Some(Box::new(hook));
self
}
#[must_use]
pub fn len(&self) -> usize {
self.levels.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.levels.is_empty()
}
fn report(&self, level: usize, op: Op, e: &BoxError) {
if let Some(hook) = &self.on_error {
hook(level, op, e);
}
}
pub async fn get(&self, key: &str) -> Option<Vec<u8>> {
for (i, level) in self.levels.iter().enumerate() {
match level.get(key).await {
Ok(Some(value)) => {
for (j, nearer) in self.levels[..i].iter().enumerate() {
if let Err(e) = nearer.put(key, &value).await {
self.report(j, Op::Put, &e);
}
}
return Some(value);
}
Ok(None) => {}
Err(e) => self.report(i, Op::Get, &e),
}
}
None
}
pub async fn put(&self, key: &str, value: &[u8]) {
for (i, level) in self.levels.iter().enumerate() {
if let Err(e) = level.put(key, value).await {
self.report(i, Op::Put, &e);
}
}
}
pub async fn delete(&self, key: &str) -> Result<(), DeleteError> {
let mut failures = Vec::new();
for (i, level) in self.levels.iter().enumerate() {
if let Err(e) = level.delete(key).await {
self.report(i, Op::Delete, &e);
failures.push((i, e));
}
}
if failures.is_empty() {
Ok(())
} else {
Err(DeleteError { failures })
}
}
pub async fn get_or_compute<F, Fut, E>(&self, key: &str, compute: F) -> Result<Vec<u8>, E>
where
F: FnOnce() -> Fut,
Fut: Future<Output = Result<Vec<u8>, E>>,
{
if let Some(value) = self.get(key).await {
return Ok(value);
}
let value = compute().await?;
self.put(key, &value).await;
Ok(value)
}
}
impl CacheStore for Cache {
fn get<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<Option<Vec<u8>>, BoxError>> {
Box::pin(async move { Ok(Cache::get(self, key).await) })
}
fn put<'a>(&'a self, key: &'a str, value: &'a [u8]) -> BoxFuture<'a, Result<(), BoxError>> {
Box::pin(async move {
Cache::put(self, key, value).await;
Ok(())
})
}
fn delete<'a>(&'a self, key: &'a str) -> BoxFuture<'a, Result<(), BoxError>> {
Box::pin(async move {
Cache::delete(self, key)
.await
.map_err(|e| Box::new(e) as BoxError)
})
}
}
#[doc(hidden)]
pub fn block_on_ready<F: Future>(fut: F) -> F::Output {
let mut fut = std::pin::pin!(fut);
let mut cx = std::task::Context::from_waker(std::task::Waker::noop());
match fut.as_mut().poll(&mut cx) {
std::task::Poll::Ready(v) => v,
std::task::Poll::Pending => panic!("block_on_ready: the future was not ready"),
}
}