X-Git-Url: http://git.madism.org/?p=~madcoder%2Fpwqr.git;a=blobdiff_plain;f=Documentation%2Fpwqr.adoc;h=0c04746773a8f32d6c3c9510fb18f12a30726108;hp=067b2aec896d2a75cee235562ea9776508b01306;hb=170387f1b2fdd96e6271d658161926086a9c2586;hpb=b29ccbcc4ab80bc7e7b2131349459cc9e96d49ef

diff --git a/Documentation/pwqr.adoc b/Documentation/pwqr.adoc
index 067b2ae..0c04746 100644
--- a/Documentation/pwqr.adoc
+++ b/Documentation/pwqr.adoc
@@ -30,7 +30,8 @@ quarantined::
 +
 This state avoids waking a thread to force userland to "park" the thread, this
 is racy, make the scheduler work for nothing useful.  Though if `PWQR_WAKE` is
-called, quarantined threads are woken but with a `EDQUOT` errno set.
+called, quarantined threads are woken but with a `EDQUOT` errno set, and only
+one by one, no matter how wakes have been asked.
 +
 This state actually has only one impact: when `PWQR_WAKE` is called for more
 than one threads, for example 4, and that userland knows that there is 5
@@ -226,13 +227,27 @@ Valid values for the `op` argument are:
 
 `PWQR_WAKE`::
 	Tries to wake `val` threads from the pool. This is done according to
-	the current concurrency level not to overcommit. On success, the
-	number of woken threads is returned, it can be 0.
+	the current concurrency level not to overcommit. On success, a hint of
+	the number of woken threads is returned, it can be 0.
++
+This is only a hint of the number of threads woken up for two reasons. First,
+the kernel could really have woken up a thread, but when it becomes scheduled,
+it could *then* decide that it would overcommit (because some other thread
+unblocked inbetween for example), and block it again.
++
+But it can also lie in the other direction: userland is supposed to account
+for waiting threads. So when we're overcommiting and userland want a waiting
+thread to be unblocked, we actually say we woke none, but still unblock one
+(the famous quarantined threads we talk about above). This allow the userland
+counter of waiting threads to decrease, but we know the thread won't be usable
+so we return 0.
 
 `PWQR_WAKE_OC`::
 	Tries to wake `val` threads from the pool. This is done bypassing the
 	current concurrency level (`OC` stands for `OVERCOMMIT`). On success,
-	the number of woken threads is returned, it can be 0.
+	the number of woken threads is returned, it can be 0, but it's the
+	real count that has been (or will soon be) woken up. If it's less than
+	required, it's because there aren't enough parked threads.
 
 `PWQR_WAIT`::
 	Puts the thread to wait for a future `PWQR_WAKE` command. If this