+
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
`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