clache 0.2.0

//! Globally-accessible storage for performant, path-indexed caching.
//!
//! The global cache supports storage of **any type** implementing [`Any`], [`Send`], and [`Sync`],
//! dynamically.
//!
//! It is recommended to use namespacing in the paths in order to avoid conflicts, but this is not
//! required. To ensure consistency, use `namespace://path` for namespacing, and if you don't use
//! namespacing, avoid paths that begin that way. To obtain a list of all currently cached paths in
//! a namespace, use [`namespaced_paths`].
//!
//! ## Type Safety
//!
//! Cached items must implement [`Any`], [`Send`], and [`Sync`] in order to be stored in the global
//! cache. Unless using a dyn method, like [`get_dyn`], the cache uses downcasting. If a
//! downcast fails, [`None`] is returned. This runtime check makes the cache slightly less
//! efficient than [`LocalCache`], which uses static typing.
//!
//! ## Examples
//!
//! ```rust
//! use std::sync::Arc;
//! use clache::prelude::*;
//!
//! fn load_texture() -> String {
//!     "texture data".to_string()
//! }
//!
//! // Slow first lookup
//! let texture = GlobalCache::get_or_else("assets/texture.png", || {
//!     Arc::new(load_texture())
//! });
//!
//! // ...
//!
//! // Much faster lookup, since "assets/texture.png" is already in the cache
//! let texture = GlobalCache::get_or_else("assets/texture.png", || {
//!     Arc::new(load_texture())
//! });
//!
//! ```
//!
//! If only a single type is needed, and the path is not uniquely identifying, use [`LocalCache`].
//!
//! [`LocalCache`]: crate::LocalCache
//! [`get_dyn`]: GlobalCache::get_dyn
//! [`namespaced_paths`]: GlobalCache::namespaced_paths

use std::{
    any::Any,
    collections::{HashMap, HashSet},
    sync::{Arc, LazyLock, RwLock},
};

use crate::fused_rw::FusedRw;

type Item = Arc<FusedRw<Option<Arc<dyn Any + Send + Sync>>>>;

static CACHE: LazyLock<RwLock<HashMap<String, Item>>> =
    LazyLock::new(|| RwLock::new(HashMap::new()));

/// The shared, global cache, supporting dynamic typing. See the [module-level docs] for more info.
///
/// [module-level docs]: crate::global_cache
pub struct GlobalCache {
    _p: std::marker::PhantomData<[u8]>,
}

impl GlobalCache {
    /// Checks if a value exists in the **global** cache, regardless of type.
    pub fn is_cached(path: impl AsRef<str>) -> bool {
        let Some(entry) = CACHE
            .read()
            .expect("Cache cannot poison")
            .get(path.as_ref())
            .cloned()
        else {
            return false;
        };

        entry.read().is_some()
    }

    /// Checks if a value exists in the **global** cache, regardless of type, asynchronously.
    pub async fn is_cached_async(path: impl AsRef<str>) -> bool {
        let Some(entry) = CACHE
            .read()
            .expect("Cache cannot poison")
            .get(path.as_ref())
            .cloned()
        else {
            return false;
        };

        entry.read_async().await.is_some()
    }

    /// Checks if a value exists in the **global** cache, is initialized, and is of the correct
    /// type.
    pub fn is_cached_as<T: Any + Send + Sync>(path: impl AsRef<str>) -> bool {
        let Some(entry) = CACHE
            .read()
            .expect("Cache cannot poison")
            .get(path.as_ref())
            .cloned()
        else {
            return false;
        };

        entry.read().as_ref().is_some_and(|e| e.is::<T>())
    }

    /// Checks if a value exists in the **global** cache, is initialized, and is of the correct
    /// type. Waits asynchronously.
    pub async fn is_cached_as_async<T: Any + Send + Sync>(path: impl AsRef<str>) -> bool {
        let Some(entry) = CACHE
            .read()
            .expect("Cache cannot poison")
            .get(path.as_ref())
            .cloned()
        else {
            return false;
        };

        entry
            .read_async()
            .await
            .as_ref()
            .is_some_and(|e| e.is::<T>())
    }

    /// Retrieves a value from the **global** cache, if it exists, without trying to downcast it.
    pub fn get_dyn(path: impl AsRef<str>) -> Option<Arc<dyn Any + Send + Sync>> {
        let entry = {
            let guard = CACHE.read().expect("Cache cannot poison");
            let entry = guard.get(path.as_ref())?.clone();
            drop(guard);
            entry
        };

        entry.read().clone()
    }

    /// Retrieves a value from the **global** cache, if it exists, without trying to downcast it,
    /// asynchronously.
    pub async fn get_dyn_async(path: impl AsRef<str>) -> Option<Arc<dyn Any + Send + Sync>> {
        let entry = {
            let guard = CACHE.read().expect("Cache cannot poison");
            let entry = guard.get(path.as_ref())?.clone();
            drop(guard);
            entry
        };

        entry.read_async().await.clone()
    }

    /// Retrieves a value from the **global** cache, if it exists. Also returns [`None`] if the
    /// cached value is of the wrong type.
    ///
    /// If you wish to insert a default value, use [`get_or`] instead.
    ///
    /// This is not suitable for async.
    ///
    /// [`get_or`]: Self::get_or
    pub fn get<T: Any + Send + Sync>(path: impl AsRef<str>) -> Option<Arc<T>> {
        Self::get_dyn(path).and_then(|v| v.downcast().ok())
    }

    /// Retrieves a value from the **global** cache, if it exists, asynchronously. Also returns
    /// [`None`] if the cached value is of the wrong type.
    ///
    /// If you wish to insert a default value, use [`get_or_async`] instead.
    ///
    /// This is not suitable for async.
    ///
    /// [`get_or_async`]: Self::get_or_async
    pub async fn get_async<T: Any + Send + Sync>(path: impl AsRef<str>) -> Option<Arc<T>> {
        Self::get_dyn_async(path)
            .await
            .and_then(|v| v.downcast().ok())
    }

    /// Retrieves a value from the **global** cache or adds `default` if it does not exist.
    /// Also returns [`None`] if the cached value is of the wrong type.
    ///
    /// This eagerly evaluates `default` even if the value already exists in the cache. It is
    /// generally better to use [`get_or_else`] or one of its variants instead.
    ///
    /// [`get_or_else`]: Self::get_or_else
    pub fn get_or<T: Any + Send + Sync>(path: impl AsRef<str>, default: Arc<T>) -> Option<Arc<T>> {
        if let Some(good) = Self::get_dyn(path.as_ref()) {
            return good.downcast().ok();
        }

        let entry = {
            let mut guard = CACHE.write().expect("Cache cannot poison");
            guard
                .entry(path.as_ref().to_string())
                .or_insert_with(|| Arc::new(FusedRw::new(None)))
                .clone()
        };

        if let Some(good) = entry.read().as_ref() {
            good.clone().downcast().ok()
        } else {
            assert!(
                entry.write().replace(default.clone()).is_none(),
                "Cached value should be None"
            );
            Some(default)
        }
    }

    /// Retrieves a value from the **global** cache **asynchronously** or adds `default` if it does
    /// not exist. Also returns [`None`] if the cached value is of the wrong type.
    ///
    /// This eagerly evaluates `default` even if the value already exists in the cache. It is
    /// generally better to use [`get_or_else_async`] or one of its variants instead.
    ///
    /// [`get_or_else_async`]: Self::get_or_else_async
    pub async fn get_or_async<T: Any + Send + Sync>(
        path: impl AsRef<str>,
        default: Arc<T>,
    ) -> Option<Arc<T>> {
        if let Some(good) = Self::get_dyn_async(path.as_ref()).await {
            return good.downcast().ok();
        }

        let entry = {
            let mut guard = CACHE.write().expect("Cache cannot poison");
            guard
                .entry(path.as_ref().to_string())
                .or_insert_with(|| Arc::new(FusedRw::new(None)))
                .clone()
        };

        if let Some(good) = entry.read_async().await.as_ref() {
            good.clone().downcast().ok()
        } else {
            assert!(
                entry.write_async().await.replace(default.clone()).is_none(),
                "Cached value should be None"
            );
            Some(default)
        }
    }

    /// Retrieves a value from the **global** cache or loads it from a closure if it does not exist.
    /// Also returns [`None`] if the cached value is of the wrong type.
    pub fn get_or_else<T: Any + Send + Sync, F: FnOnce() -> Arc<T>>(
        path: impl AsRef<str>,
        f: F,
    ) -> Option<Arc<T>> {
        if let Some(good) = Self::get_dyn(path.as_ref()) {
            return good.downcast().ok();
        }

        let entry = {
            let mut guard = CACHE.write().expect("Cache cannot poison");
            guard
                .entry(path.as_ref().to_string())
                .or_insert_with(|| Arc::new(FusedRw::new(None)))
                .clone()
        };

        if let Some(good) = entry.read().as_ref() {
            good.clone().downcast().ok()
        } else {
            let loaded = f();
            assert!(
                entry.write().replace(loaded.clone()).is_none(),
                "Cached value should be None"
            );
            Some(loaded)
        }
    }

    /// Retrieves a value from the **global** cache or loads it from an *async* closure if it does not
    /// exist. Also returns [`None`] if the cached value is of the wrong type.
    ///
    /// Unlike the non-async variants, this **not** an atomic operation. Your closure may be run more
    /// than once, but only the first run will write to the cache.
    pub async fn get_or_else_async<T: Any + Send + Sync, F: AsyncFnOnce() -> Arc<T>>(
        path: impl AsRef<str>,
        f: F,
    ) -> Option<Arc<T>> {
        if let Some(good) = Self::get_dyn_async(path.as_ref()).await {
            return good.downcast().ok();
        }

        let entry = {
            let mut guard = CACHE.write().expect("Cache cannot poison");
            guard
                .entry(path.as_ref().to_string())
                .or_insert_with(|| Arc::new(FusedRw::new(None)))
                .clone()
        };

        if let Some(good) = entry.read_async().await.as_ref() {
            good.clone().downcast().ok()
        } else {
            let loaded = f().await;
            assert!(
                entry.write_async().await.replace(loaded.clone()).is_none(),
                "Cached value should be None"
            );
            Some(loaded)
        }
    }

    /// Removes a path from the **global** cache, if it exists.
    ///
    /// Any values that have been acquired from the cache will remain valid until they are dropped.
    pub fn uncache(path: impl AsRef<str>) {
        // Don't care about entries; they'll drop eventually
        let mut guard = CACHE.write().expect("Cache cannot poison");
        guard.remove(path.as_ref());
    }

    /// Removes all paths from the **global** cache.
    ///
    /// This is dangerous, as it can cause other crates to lose their dependent values. Any values
    /// that have been acquired from the cache will remain valid until they are dropped.
    ///
    /// If you want a safer alternative, iterate and use [`uncache`].
    ///
    /// [`uncache`]: Self::uncache
    pub fn clear() {
        let mut guard = CACHE.write().expect("Cache cannot poison");
        guard.clear();
    }

    /// Returns all paths starting with `namespace`, stripping the namespace prefix.
    ///
    /// This is only a snapshot, and future insertions and removals will not be reflected. Some
    /// entries may be in the process of being written, but most functions will wait until they
    /// are ready.
    pub fn namespaced_paths(namespace: impl AsRef<str>) -> HashSet<String> {
        let ns = namespace.as_ref();
        let guard = CACHE.read().expect("Cache cannot poison");
        guard
            .iter()
            .filter_map(|(k, v)| k.strip_prefix(ns).map(|s| (s.to_string(), v)))
            .filter(|(_, v)| v.read().is_some())
            .map(|(k, _)| k)
            .collect()
    }

    /// Returns all paths starting with `namespace` **asynchronously**, stripping the namespace
    /// prefix.
    ///
    /// This is only a snapshot, and future insertions and removals will not be reflected. Some
    /// entries may be in the process of being written, but most functions will wait until they
    /// are ready.
    pub async fn namespaced_paths_async(namespace: impl AsRef<str>) -> HashSet<String> {
        let ns = namespace.as_ref();
        let namespaced: Vec<_> = {
            CACHE
                .read()
                .expect("Cache cannot poison")
                .iter()
                .filter_map(|(k, _)| k.strip_prefix(ns))
                .map(|s| s.to_string())
                .collect()
        };

        let mut hs = HashSet::new();
        for k in namespaced {
            let Some(entry) = CACHE.read().expect("Cache cannot poison").get(&k).cloned() else {
                continue;
            };

            if entry.read_async().await.is_some() {
                hs.insert(k);
            }
        }

        hs
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::atomic::AtomicUsize;

    #[test]
    fn simple() {
        let string = GlobalCache::get_or_else("abc", || Arc::new("hello".to_string())).unwrap();
        assert_eq!(*string, "hello");
    }

    #[test]
    fn shared() {
        let one = GlobalCache::get_or_else("123", || {
            println!("Running one");
            Arc::new("hello".to_string())
        })
        .unwrap();
        let two = GlobalCache::get_or_else("123", || {
            println!("Running two");
            Arc::new("hello".to_string())
        })
        .unwrap();

        assert!(Arc::ptr_eq(&one, &two));
    }

    #[test]
    fn simultaneous30() {
        let mut handles = Vec::new();
        const N: usize = 30;
        let barrier = Arc::new(std::sync::Barrier::new(N));
        let runs = Arc::new(AtomicUsize::new(0));
        for _ in 0..N {
            let bar_clone = barrier.clone();
            let runs_clone = runs.clone();
            let handle = std::thread::spawn(move || {
                bar_clone.wait();
                let string = GlobalCache::get_or_else("xyz", || {
                    runs_clone.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                    Arc::new("hello".to_string())
                })
                .unwrap();
                assert_eq!(*string, "hello");
            });
            handles.push(handle);
        }
        for handle in handles {
            handle.join().unwrap();
        }

        assert_eq!(runs.load(std::sync::atomic::Ordering::SeqCst), 1);
    }
}