Semaphore example using an Arc<Semaphore> for semaphore passing

tokio/src/sync/semaphore.rs

@@ -47,7 +47,23 @@ use std::sync::Arc;
 /// }
 /// ```
 ///
-/// Use [`Semaphore::acquire_owned`] to move permits across tasks:
+/// Limit number of incoming requests being handled at the same time, using a task-safe semaphore
+/// via [`Semaphore::acquire_owned`].
+///
+/// Similar to limiting the numer of simultaneous opened files, network handles are a limited resource.
+/// Allowing an unbounded amount of requests to be processed could result in a denial-of-service,
+/// and many other issues.
+///
+/// However, in contrast to the file example, this example uses a non-static, `Arc`-wrapped `Semaphore`
+/// for more fine-grained lifetime and ownership control. The `Arc` allows multiple threads and tasks
+/// to share ownership of the semaphore. Here we create a shallow-copy of the `Arc<Semaphore>` reference
+/// using `clone`. Then we acquire a permit through the `Arc` from the `Semaphore` via [`Semaphore::acquire_owned`],
+/// and move it inside the task. This ensures no non-`'static` variables are referenced from within
+/// said task.
+///
+/// If we leave the scope where the `Arc<Semaphore>` was defined, and references still exist in any
+/// of our tasks to it, the `Semaphore` will continue to exist in a static-like context, until all
+/// `Arc`s have been dropped.
 ///
 /// ```
 /// use std::sync::Arc;