Bump version + Changelog + Readme

Author: ByteAlex

CHANGELOG.md

@@ -1,3 +1,19 @@
+# v0.2.0
+New/Changed:
+* TTL Backing now uses fewer iterations through the entire list
+* Backings can define a `Meta` type which can be used for improved handling with
+the loader
+* TTL Backing now supports a `TtlMeta` -> Custom duration per entry
+* TTL Backing now supports other nested `CacheBacking`s (i.e. TTL+LRU)
+* New methods: `LoadingCache::with_meta_loader()`, `LoadingCache#set_with_meta`
+
+Breaking:
+* Backings trait changed:
+  1. All methods now return a result
+  2. contains_key takes a mutable self reference
+  3. remove_if returns the removed k/v pairs
+  4. Meta Type added / set signature now has a meta field
+
 # v0.1.2
 New/Changed:
 * Replace SystemTime calls with Instant

Cargo.toml

@@ -2,7 +2,7 @@
 name = "cache_loader_async"
 description = "A thread safe loading cache with async loader functions based on tokio"
 repository = "https://github.com/ZeroTwo-Bot/cache-loader-async-rs"
-version = "0.1.2"
+version = "0.2.0"
 authors = ["Alexander Becker <bytealex@zerotwo.bot>", "Spencer Sharkey <spencer@sf-n.com>"]
 edition = "2018"
 keywords = ["cache", "async"]

README.md

@@ -74,6 +74,36 @@ async fn main() {
 }
 ```
 
+You can also provide a custom TTL per key, if you use the `with_meta_loader` method.
+Below example will override the global 30s ttl with a 10s ttl.
+Yes, it doesn't make sense to override every key, so you should be having conditions there.
+```rust
+async fn main() {
+    let duration: Duration = Duration::from_secs(30);
+    let cache = LoadingCache::with_meta_loader(TtlCacheBacking::new(duration), move |key: String| {
+        async move {
+            Ok(key.to_lowercase())
+                .with_meta(Some(TtlMeta::from(Duration::from_secs(10))))
+        }
+    });
+}
+```
+
+Additionally, the TTL backing allows you to customize the underlying backing. By default, it's using the 
+`HashMapBacking`.
+
+```rust
+async fn main() {
+    let duration: Duration = Duration::from_secs(30);
+    let cache = LoadingCache::with_meta_loader(TtlCacheBacking::with_backing(LruCacheBacking::new(10), duration), move |key: String| {
+        async move {
+            Ok(key.to_lowercase())
+                .with_meta(Some(TtlMeta::from(Duration::from_secs(10))))
+        }
+    });
+}
+```
+
 ## Own Backing
 
 To implement an own cache backing, simply implement the public `CacheBacking` trait from the `backing` mod.
@@ -82,11 +112,14 @@ To implement an own cache backing, simply implement the public `CacheBacking` tr
 pub trait CacheBacking<K, V>
     where K: Eq + Hash + Sized + Clone + Send,
           V: Sized + Clone + Send {
-    fn get(&mut self, key: &K) -> Option<&V>;
-    fn set(&mut self, key: K, value: V) -> Option<V>;
-    fn remove(&mut self, key: &K) -> Option<V>;
-    fn contains_key(&self, key: &K) -> bool;
-    fn remove_if(&mut self, predicate: Box<dyn Fn((&K, &V)) -> bool + Send + 'static>);
-    fn clear(&mut self);
+    type Meta: Clone + Send;
+
+    fn get_mut(&mut self, key: &K) -> Result<Option<&mut V>, BackingError>;
+    fn get(&mut self, key: &K) -> Result<Option<&V>, BackingError>;
+    fn set(&mut self, key: K, value: V, meta: Option<Self::Meta>) -> Result<Option<V>, BackingError>;
+    fn remove(&mut self, key: &K) -> Result<Option<V>, BackingError>;
+    fn contains_key(&mut self, key: &K) -> Result<bool, BackingError>;
+    fn remove_if(&mut self, predicate: Box<dyn Fn((&K, &V)) -> bool + Send + Sync + 'static>) -> Result<Vec<(K, V)>, BackingError>;
+    fn clear(&mut self) -> Result<(), BackingError>;
 }
 ```

src/cache_api.rs

@@ -376,19 +376,40 @@ impl<
     ///
     /// # Arguments
     ///
-    /// * `key` - The key which should be loaded
+    /// * `key` - The key which should be set
+    /// * `value` - The value which should be set
+    /// * `meta` - The meta which should be attached to the key
     ///
     /// # Return Value
     ///
     /// Returns a Result with:
     /// Ok - Previous value of type V wrapped in an Option depending whether there was a previous
     ///      value
     /// Err - Error of type CacheLoadingError
-    pub async fn set(&self, key: K, value: V) -> Result<Option<V>, CacheLoadingError<E>> {
-        self.send_cache_action(CacheAction::Set(key, value, None)).await
+    pub async fn set_with_meta(&self, key: K, value: V, meta: Option<B::Meta>) -> Result<Option<V>, CacheLoadingError<E>> {
+        self.send_cache_action(CacheAction::Set(key, value, meta)).await
             .map(|opt_meta| opt_meta.map(|meta| meta.result))
     }
 
+    /// Sets the value for specified key and bypasses eventual currently ongoing loads
+    /// If a key has been set programmatically, eventual concurrent loads will not change
+    /// the value of the key.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key which should be set
+    /// * `value` - The value which should be set
+    ///
+    /// # Return Value
+    ///
+    /// Returns a Result with:
+    /// Ok - Previous value of type V wrapped in an Option depending whether there was a previous
+    ///      value
+    /// Err - Error of type CacheLoadingError
+    pub async fn set(&self, key: K, value: V) -> Result<Option<V>, CacheLoadingError<E>> {
+        self.set_with_meta(key, value, None).await
+    }
+
     /// Loads the value for the specified key from the cache and returns None if not present
     ///
     /// # Arguments