check the `addr` argument for PWQ_WAIT is aligned to an integer.

[~madcoder/pwqr.git] / Documentation / pwqr.adoc

diff --git a/Documentation/pwqr.adoc b/Documentation/pwqr.adoc
index 067b2ae..1942097 100644 (file)
--- 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