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

diff --git a/Documentation/pwqr.adoc b/Documentation/pwqr.adoc
index 067b2ae..1942097 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
@@ -212,9 +213,8 @@ Valid values for the `op` argument are:
 	value is passed as the `val` argument. The requests returns the old
 	concurrency level on success.
 +
-	A zero or negative value for `val` means 'automatic' and is recomputed
-	as the current number of online CPUs as
-	`sysconf(_SC_NPROCESSORS_ONLN)` would return.
+A zero or negative value for `val` means 'automatic' and is recomputed as the
+current number of online CPUs as `sysconf(_SC_NPROCESSORS_ONLN)` would return.
 
 `PWQR_REGISTER`::
 	Registers the calling thread to be taken into account by the pool
@@ -226,13 +226,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
@@ -243,6 +257,9 @@ If the concurrency level is below the target, then the kernel checks if the
 address `addr` still contains the value `val` (in the fashion of `futex(2)`).
 If it doesn't then the call doesn't block. Else the calling thread is blocked
 until a `PWQR_WAKE` command is received.
++
+`addr` must of course be a pointer to an aligned integer which stores the
+reference ticket in userland.
 
 `PWQR_PARK`::
 	Puts the thread in park mode. Those are spare threads to avoid