From 916e92f2f5c5c0e9275d92ac63b245cf5c778d17 Mon Sep 17 00:00:00 2001 From: Matilda Smeds Date: Fri, 18 Aug 2023 15:45:41 +0200 Subject: [PATCH 1/4] Semaphore example for limiting access to a file --- tokio/src/sync/semaphore.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs index cb770215488..d4cade74c8d 100644 --- a/tokio/src/sync/semaphore.rs +++ b/tokio/src/sync/semaphore.rs @@ -73,6 +73,21 @@ use std::sync::Arc; /// } /// ``` /// +/// Limit access to a file: +/// ``` +/// use std::io::{Result, Write}; +/// use std::fs::File; +/// +/// static PERMITS: Semaphore = Semaphore::const_new(100); +/// +/// async fn write_to_file(message: &[u8]) -> Result<()> { +/// let _permit = PERMITS.acquire().await.unwrap(); +/// let mut buffer = File::create("example.txt")?; +/// buffer.write_all(message)?; +/// Ok(()) +/// } +/// ``` +/// /// [`PollSemaphore`]: https://docs.rs/tokio-util/latest/tokio_util/sync/struct.PollSemaphore.html /// [`Semaphore::acquire_owned`]: crate::sync::Semaphore::acquire_owned #[derive(Debug)] From 157a7446ea93dc78dff4c71f9322ad074758437f Mon Sep 17 00:00:00 2001 From: Matilda Smeds Date: Sat, 19 Aug 2023 12:51:22 +0200 Subject: [PATCH 2/4] Use non-blocking File implementation Co-authored-by: Alice Ryhl --- tokio/src/sync/semaphore.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs index d4cade74c8d..553906037d0 100644 --- a/tokio/src/sync/semaphore.rs +++ b/tokio/src/sync/semaphore.rs @@ -76,7 +76,7 @@ use std::sync::Arc; /// Limit access to a file: /// ``` /// use std::io::{Result, Write}; -/// use std::fs::File; +/// use tokio::fs::File; /// /// static PERMITS: Semaphore = Semaphore::const_new(100); /// From 9d1f07941415b2c3ca4fc74c912836928b84bf93 Mon Sep 17 00:00:00 2001 From: Matilda Smeds Date: Sat, 19 Aug 2023 13:02:55 +0200 Subject: [PATCH 3/4] Use async methods in example --- tokio/src/sync/semaphore.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs index 553906037d0..515b7cbd407 100644 --- a/tokio/src/sync/semaphore.rs +++ b/tokio/src/sync/semaphore.rs @@ -75,15 +75,17 @@ use std::sync::Arc; /// /// Limit access to a file: /// ``` -/// use std::io::{Result, Write}; +/// use std::io::Result; /// use tokio::fs::File; +/// use tokio::sync::Semaphore; +/// use tokio::io::AsyncWriteExt; /// /// static PERMITS: Semaphore = Semaphore::const_new(100); /// /// async fn write_to_file(message: &[u8]) -> Result<()> { /// let _permit = PERMITS.acquire().await.unwrap(); -/// let mut buffer = File::create("example.txt")?; -/// buffer.write_all(message)?; +/// let mut buffer = File::create("example.txt").await?; +/// buffer.write_all(message).await?; /// Ok(()) /// } /// ``` From 89f28eb2ef7e71d8edddc3c91f802f9cfa169ede Mon Sep 17 00:00:00 2001 From: Matilda Smeds Date: Sat, 19 Aug 2023 13:23:25 +0200 Subject: [PATCH 4/4] Explain the example --- tokio/src/sync/semaphore.rs | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs index 515b7cbd407..30936762ddb 100644 --- a/tokio/src/sync/semaphore.rs +++ b/tokio/src/sync/semaphore.rs @@ -73,7 +73,19 @@ use std::sync::Arc; /// } /// ``` /// -/// Limit access to a file: +/// Limit the number of simultaneously opened files in your program. +/// +/// Most operating systems have limits on the number of open file +/// handles. Even in systems without explicit limits, resource constraints +/// implicitly set an upper bound on the number of open files. If your +/// program attempts to open a large number of files and exceeds this +/// limit, it will result in an error. +/// +/// This example uses a Semaphore with 100 permits. By acquiring a permit from +/// the Semaphore before accessing a file, you ensure that your program opens +/// no more than 100 files at a time. When trying to open the 101st +/// file, the program will wait until a permit becomes available before +/// proceeding to open another file. /// ``` /// use std::io::Result; /// use tokio::fs::File; @@ -86,7 +98,7 @@ use std::sync::Arc; /// let _permit = PERMITS.acquire().await.unwrap(); /// let mut buffer = File::create("example.txt").await?; /// buffer.write_all(message).await?; -/// Ok(()) +/// Ok(()) // Permit goes out of scope here, and is available again for acquisition /// } /// ``` ///