From 3a02d34d3a223244d8f880d87936059935313b66 Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Mon, 12 Apr 2021 15:46:42 +0200 Subject: [PATCH] sync: document that Semaphore is fair (#3693) --- tokio/src/sync/semaphore.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs index b4304d60d..af75042be 100644 --- a/tokio/src/sync/semaphore.rs +++ b/tokio/src/sync/semaphore.rs @@ -14,6 +14,13 @@ use std::sync::Arc; /// available, `acquire` (asynchronously) waits until an outstanding permit is /// dropped. At this point, the freed permit is assigned to the caller. /// +/// This `Semaphore` is fair, which means that permits are given out in the order +/// they were requested. This fairness is also applied when `acquire_many` gets +/// involved, so if a call to `acquire_many` at the front of the queue requests +/// more permits than currently available, this can prevent a call to `acquire` +/// from completing, even if the semaphore has enough permits complete the call +/// to `acquire`. +/// /// To use the `Semaphore` in a poll function, you can use the [`PollSemaphore`] /// utility. ///