doc: Add examples to Semaphore

[oguzbilgener]

Motivation

Closes #3795

Add examples to Semaphore and its methods. All doctests pass. Let me know if you find anything too verbose or confusing.

[Darksonn]

Thanks for taking the time to do this!

I think generally the examples are more complicated than they need to be. You don't have to show off every feature of a method in its example, and if you feel the need to add { ... } blocks inside the example, it should probably be two examples.

Also, don't be afraid of duplicating the same example several times. The for loop example from the beginning could absolutely make sense to have on several different methods throughout the documentation.

[Darksonn]

I think an example of the const_new method would be nice. It could be very short:

static SEM: Semaphore = Semaphore::const_new(10);

[oguzbilgener]

@Darksonn Thank you for the quick feedback! I updated all of them to simplify as you suggested.

[Darksonn]

This seems better now. 👍

[udoprog]

style nits, rest looks great to me now as well. cheers!

[oguzbilgener]

@udoprog Thank you for the review!

[Darksonn]

I'm pretty sure these are my last comments.

[Darksonn]

This example isn't great. You wouldn't use try_acquire_owned like this.

[oguzbilgener]

The only realistic example I could think of that doesn't involve writing a poll method is something like this. Do you have any feedback?

use std::sync::Arc;
use tokio::sync::Semaphore;
use tokio_stream::{self as stream, StreamExt};

#[tokio::main]
async fn main() {
    // Simulate a stream of incoming requests from some I/O resource
    let mut requests = stream::iter(1u32..=20);
    // Allow up to 4 concurrent operations
    let semaphore = Arc::new(Semaphore::new(4));
    let mut join_handles = Vec::new();

    while let Some(id) = requests.next().await {
        match Arc::clone(&semaphore).try_acquire_owned() {
            Ok(permit) => {
                join_handles.push(tokio::spawn(async move {
                    perform_operation(id).await;
                    // Hold the permit until our operation is over.
                    drop(permit);
                }));
            }
            Err(TryAcquireError::NoPermits) => {
                // We're busy, we can respond immediately to tell the client to try again later.
            }
            Err(TryAcquireError::Closed) => {
                unreachable!() // no one calls `semaphore.close()`
            }
        }
    }

    for handle in join_handles {
        let _ = handle.await;
    }
}

async fn perform_operation(_id: u32) {
    tokio::time::sleep(Duration::from_nanos(1)).await
}

[Darksonn]

Maybe just do the same thing as the example on try_acquire. It's a lot simpler even if it doesn't show off the move-to-new-task feature.

[oguzbilgener]

Done, thank you for the review.

[Darksonn]

Same here.