Merge pull request #30 from moka-rs/get-or-insert-example

Add examples to the doc for `get_or_insert_with` and `get_or_try_insert_with` methods

.vscode/settings.json

@@ -24,6 +24,7 @@
         "nocapture",
         "peekable",
         "preds",
+        "reqwest",
         "runtimes",
         "rustdoc",
         "rustfmt",

CHANGELOG.md

@@ -4,7 +4,12 @@
 
 ### Fixed
 
-- `usize` overflow on big cache capacity. ([#28][gh-pull-0028])
+- Fix `usize` overflow on big cache capacity. ([#28][gh-pull-0028])
+
+### Added
+
+- Add examples for `get_or_insert_with` and `get_or_try_insert_with`
+  methods to the docs. ([#30][gh-pull-0030])
 
 
 ## Version 0.5.1
@@ -88,6 +93,7 @@
 
 [caffeine-git]: https://github.com/ben-manes/caffeine
 
+[gh-pull-0030]: https://github.com/moka-rs/moka/pull/30/
 [gh-pull-0028]: https://github.com/moka-rs/moka/pull/28/
 [gh-pull-0022]: https://github.com/moka-rs/moka/pull/22/
 [gh-pull-0020]: https://github.com/moka-rs/moka/pull/20/

Cargo.toml

@@ -44,6 +44,7 @@ actix-rt1 = { package = "actix-rt", version = "1", default-features = false }
 async-std = { version = "1", default-features = false, features = ["attributes"] }
 futures = "0.3"
 getrandom = "0.2"
+reqwest = "0.11"
 skeptic = "0.13"
 tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }
 

src/future/cache.rs

@@ -278,6 +278,72 @@ where
     /// key even if the method is concurrently called by many async tasks; only one
     /// of the calls resolves its future, and other calls wait for that future to
     /// complete.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// // Cargo.toml
+    /// //
+    /// // [dependencies]
+    /// // moka = { version = "0.5", features = ["future"] }
+    /// // futures = "0.3"
+    /// // tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }
+    /// use moka::future::Cache;
+    /// use std::sync::Arc;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     const TEN_MIB: usize = 10 * 1024 * 1024; // 10MiB
+    ///     let cache = Cache::new(100);
+    ///
+    ///     // Spawn four async tasks.
+    ///     let tasks: Vec<_> = (0..4_u8)
+    ///         .map(|task_id| {
+    ///             let my_cache = cache.clone();
+    ///             tokio::spawn(async move {
+    ///                 println!("Task {} started.", task_id);
+    ///
+    ///                 // Insert and get the value for key1. Although all four async tasks
+    ///                 // will call `get_or_insert_with` at the same time, the `init` async
+    ///                 // block must be resolved only once.
+    ///                 let value = my_cache
+    ///                     .get_or_insert_with("key1", async {
+    ///                         println!("Task {} inserting a value.", task_id);
+    ///                         Arc::new(vec![0u8; TEN_MIB])
+    ///                     })
+    ///                     .await;
+    ///
+    ///                 // Ensure the value exists now.
+    ///                 assert_eq!(value.len(), TEN_MIB);
+    ///                 assert!(my_cache.get(&"key1").is_some());
+    ///
+    ///                 println!("Task {} got the value. (len: {})", task_id, value.len());
+    ///             })
+    ///         })
+    ///         .collect();
+    ///
+    ///     // Run all tasks concurrently and wait for them to complete.
+    ///     futures::future::join_all(tasks).await;
+    /// }
+    /// ```
+    ///
+    /// **A Sample Result**
+    ///
+    /// - The async black resolved exactly once by task 3.
+    /// - Other tasks were blocked until task 3 inserted the value.
+    ///
+    /// ```console
+    /// Task 0 started.
+    /// Task 3 started.
+    /// Task 1 started.
+    /// Task 2 started.
+    /// Task 3 inserting a value.
+    /// Task 3 got the value. (len: 10485760)
+    /// Task 0 got the value. (len: 10485760)
+    /// Task 1 got the value. (len: 10485760)
+    /// Task 2 got the value. (len: 10485760)
+    /// ```
+    ///
     pub async fn get_or_insert_with(&self, key: K, init: impl Future<Output = V>) -> V {
         let hash = self.base.hash(&key);
         let key = Arc::new(key);
@@ -292,6 +358,83 @@ where
     /// key even if the method is concurrently called by many async tasks; only one
     /// of the calls resolves its future, and other calls wait for that future to
     /// complete.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// // Cargo.toml
+    /// //
+    /// // [dependencies]
+    /// // moka = { version = "0.5", features = ["future"] }
+    /// // futures = "0.3"
+    /// // reqwest = "0.11"
+    /// // tokio = { version = "1", features = ["rt-multi-thread", "macros" ] }
+    /// use moka::future::Cache;
+    ///
+    /// // This async function tries to get HTML from the given URI.
+    /// async fn get_html(
+    ///     task_id: u8,
+    ///     uri: &str,
+    /// ) -> Result<String, Box<dyn std::error::Error + Send + Sync + 'static>> {
+    ///     println!("get_html() called by task {}.", task_id);
+    ///     Ok(reqwest::get(uri).await?.text().await?)
+    /// }
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let cache = Cache::new(100);
+    ///
+    ///     // Spawn four async tasks.
+    ///     let tasks: Vec<_> = (0..4_u8)
+    ///         .map(|task_id| {
+    ///             let my_cache = cache.clone();
+    ///             tokio::spawn(async move {
+    ///                 println!("Task {} started.", task_id);
+    ///
+    ///                 // Try to insert and get the value for key1. Although
+    ///                 // all four async tasks will call `get_or_try_insert_with`
+    ///                 // at the same time, get_html() must be called only once.
+    ///                 let value = my_cache
+    ///                     .get_or_try_insert_with(
+    ///                         "key1",
+    ///                         get_html(task_id, "https://www.rust-lang.org"),
+    ///                     ).await;
+    ///
+    ///                 // Ensure the value exists now.
+    ///                 assert!(value.is_ok());
+    ///                 assert!(my_cache.get(&"key1").is_some());
+    ///
+    ///                 println!(
+    ///                     "Task {} got the value. (len: {})",
+    ///                     task_id,
+    ///                     value.unwrap().len()
+    ///                 );
+    ///             })
+    ///         })
+    ///         .collect();
+    ///
+    ///     // Run all tasks concurrently and wait for them to complete.
+    ///     futures::future::join_all(tasks).await;
+    /// }
+    /// ```
+    ///
+    /// **A Sample Result**
+    ///
+    /// - `get_html()` called exactly once by task 2.
+    /// - Other tasks were blocked until task 2 inserted the value.
+    ///
+    /// ```console
+    /// Task 1 started.
+    /// Task 0 started.
+    /// Task 2 started.
+    /// Task 3 started.
+    /// get_html() called by task 2.
+    /// Task 2 got the value. (len: 19419)
+    /// Task 1 got the value. (len: 19419)
+    /// Task 0 got the value. (len: 19419)
+    /// Task 3 got the value. (len: 19419)
+    /// ```
+    ///
     #[allow(clippy::redundant_allocation)]
     // https://rust-lang.github.io/rust-clippy/master/index.html#redundant_allocation
     // `Arc<Box<dyn ..>>` in the return type creates an extra heap allocation.

src/future/value_initializer.rs

@@ -45,14 +45,14 @@ where
 
         match self.try_insert_waiter(&key, &waiter) {
             None => {
-                // Inserted. Resolve the init future.
+                // Our waiter was inserted. Let's resolve the init future.
                 let value = init.await;
                 *lock = Some(Ok(value.clone()));
                 Initialized(value)
             }
             Some(res) => {
-                // Value already exists. Drop our write lock and wait for a read lock
-                // to become available.
+                // Somebody else's waiter already exists. Drop our write lock and wait
+                // for a read lock to become available.
                 std::mem::drop(lock);
                 match &*res.read().await {
                     Some(Ok(value)) => ReadExisting(value.clone()),
@@ -73,7 +73,7 @@ where
 
         match self.try_insert_waiter(&key, &waiter) {
             None => {
-                // Inserted. Resolve the init future.
+                // Our waiter was inserted. Let's resolve the init future.
                 match init.await {
                     Ok(value) => {
                         *lock = Some(Ok(value.clone()));
@@ -88,8 +88,8 @@ where
                 }
             }
             Some(res) => {
-                // Value already exists. Drop our write lock and wait for a read lock
-                // to become available.
+                // Somebody else's waiter already exists. Drop our write lock and wait
+                // for a read lock to become available.
                 std::mem::drop(lock);
                 match &*res.read().await {
                     Some(Ok(value)) => ReadExisting(value.clone()),

src/sync/cache.rs

@@ -258,6 +258,64 @@ where
     /// key even if the method is concurrently called by many threads; only one of
     /// the calls evaluates its function, and other calls wait for that function to
     /// complete.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use moka::sync::Cache;
+    /// use std::{sync::Arc, thread, time::Duration};
+    ///
+    /// const TEN_MIB: usize = 10 * 1024 * 1024; // 10MiB
+    /// let cache = Cache::new(100);
+    ///
+    /// // Spawn four threads.
+    /// let threads: Vec<_> = (0..4_u8)
+    ///     .map(|task_id| {
+    ///         let my_cache = cache.clone();
+    ///         thread::spawn(move || {
+    ///             println!("Thread {} started.", task_id);
+    ///
+    ///             // Try to insert and get the value for key1. Although all four
+    ///             // threads will call `get_or_insert_with` at the same time, the
+    ///             // `init` closure must be evaluated only once.
+    ///             let value = my_cache.get_or_insert_with("key1", || {
+    ///                 println!("Thread {} inserting a value.", task_id);
+    ///                 Arc::new(vec![0u8; TEN_MIB])
+    ///             });
+    ///
+    ///             // Ensure the value exists now.
+    ///             assert_eq!(value.len(), TEN_MIB);
+    ///             thread::sleep(Duration::from_millis(10));
+    ///             assert!(my_cache.get(&"key1").is_some());
+    ///
+    ///             println!("Thread {} got the value. (len: {})", task_id, value.len());
+    ///         })
+    ///     })
+    ///     .collect();
+    ///
+    /// // Wait all threads to complete.
+    /// threads
+    ///     .into_iter()
+    ///     .for_each(|t| t.join().expect("Thread failed"));
+    /// ```
+    ///
+    /// **Result**
+    ///
+    /// - The `init` closure called exactly once by thread 1.
+    /// - Other threads were blocked until thread 1 inserted the value.
+    ///
+    /// ```console
+    /// Thread 1 started.
+    /// Thread 0 started.
+    /// Thread 3 started.
+    /// Thread 2 started.
+    /// Thread 1 inserting a value.
+    /// Thread 2 got the value. (len: 10485760)
+    /// Thread 1 got the value. (len: 10485760)
+    /// Thread 0 got the value. (len: 10485760)
+    /// Thread 3 got the value. (len: 10485760)
+    /// ```
+    ///
     pub fn get_or_insert_with(&self, key: K, init: impl FnOnce() -> V) -> V {
         let hash = self.base.hash(&key);
         let key = Arc::new(key);
@@ -293,6 +351,76 @@ where
     /// key even if the method is concurrently called by many threads; only one of
     /// the calls evaluates its function, and other calls wait for that function to
     /// complete.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use moka::sync::Cache;
+    /// use std::{path::Path, time::Duration, thread};
+    ///
+    /// /// This function tries to get the file size in bytes.
+    /// fn get_file_size(
+    ///     thread_id: u8,
+    ///     path: impl AsRef<Path>,
+    /// ) -> Result<u64, Box<dyn std::error::Error + Send + Sync + 'static>> {
+    ///     println!("get_file_size() called by thread {}.", thread_id);
+    ///     Ok(std::fs::metadata(path)?.len())
+    /// }
+    ///
+    /// let cache = Cache::new(100);
+    ///
+    /// // Spawn four threads.
+    /// let threads: Vec<_> = (0..4_u8)
+    ///     .map(|thread_id| {
+    ///         let my_cache = cache.clone();
+    ///         thread::spawn(move || {
+    ///             println!("Thread {} started.", thread_id);
+    ///
+    ///             // Try to insert and get the value for key1. Although all four
+    ///             // threads will call `get_or_try_insert_with` at the same time,
+    ///             // get_file_size() must be called only once.
+    ///             let value = my_cache.get_or_try_insert_with(
+    ///                 "key1",
+    ///                 || get_file_size(thread_id, "./Cargo.toml"),
+    ///             );
+    ///
+    ///             // Ensure the value exists now.
+    ///             assert!(value.is_ok());
+    ///             thread::sleep(Duration::from_millis(10));
+    ///             assert!(my_cache.get(&"key1").is_some());
+    ///
+    ///             println!(
+    ///                 "Thread {} got the value. (len: {})",
+    ///                 thread_id,
+    ///                 value.unwrap()
+    ///             );
+    ///         })
+    ///     })
+    ///     .collect();
+    ///
+    /// // Wait all threads to complete.
+    /// threads
+    ///     .into_iter()
+    ///     .for_each(|t| t.join().expect("Thread failed"));
+    /// ```
+    ///
+    /// **Result**
+    ///
+    /// - `get_file_size()` called exactly once by thread 1.
+    /// - Other threads were blocked until thread 1 inserted the value.
+    ///
+    /// ```console
+    /// Thread 1 started.
+    /// Thread 2 started.
+    /// get_file_size() called by thread 1.
+    /// Thread 3 started.
+    /// Thread 0 started.
+    /// Thread 2 got the value. (len: 1466)
+    /// Thread 0 got the value. (len: 1466)
+    /// Thread 1 got the value. (len: 1466)
+    /// Thread 3 got the value. (len: 1466)
+    /// ```
+    ///
     #[allow(clippy::redundant_allocation)]
     // https://rust-lang.github.io/rust-clippy/master/index.html#redundant_allocation
     // `Arc<Box<dyn ..>>` in the return type creates an extra heap allocation.