Skip to contentSkip to conversation

sched/swait: Annotate swait's special use

PATCH In review Davidlohr Bueso 3 participants 3 messages Oct 20, 2017 – Oct 23, 2017

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 sched/swait: Annotate swait's special use

We currently welcome using swait over wait whenever possible because it is a slimmer data structure. However, Linus has made it very clear that he does not want this used, unless under very specific rt scenarios (such as current users).

Update the comments before kernel hipsters start thinking swait is the cool thing to do.

---
 include/linux/swait.h | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)
include/linux/swait.h +16 -11
index 73e97a08d3d0..cf30f5022472 100644
@@ -9,13 +9,16 @@
 /*
  * Simple wait queues
  *
- * While these are very similar to the other/complex wait queues (wait.h) the
- * most important difference is that the simple waitqueue allows for
- * deterministic behaviour -- IOW it has strictly bounded IRQ and lock hold
- * times.
+ * While these are very similar to regular wait queues (wait.h) the most
+ * important difference is that the simple waitqueue allows for deterministic
+ * behaviour -- IOW it has strictly bounded IRQ and lock hold times.
  *
- * In order to make this so, we had to drop a fair number of features of the
- * other waitqueue code; notably:
+ * Mainly, this is accomplished by two things. Firstly not allowing swake_up_all
+ * from IRQ disabled, and dropping the lock upon every wakeup, giving a higher
+ * priority task a chance to run.
+ *
+ * Secondly, we had to drop a fair number of features of the other waitqueue
+ * code; notably:
  *
  *  - mixing INTERRUPTIBLE and UNINTERRUPTIBLE sleeps on the same waitqueue;
  *    all wakeups are TASK_NORMAL in order to avoid O(n) lookups for the right
@@ -24,12 +27,14 @@
  *  - the exclusive mode; because this requires preserving the list order
  *    and this is hard.
  *
- *  - custom wake functions; because you cannot give any guarantees about
- *    random code.
- *
- * As a side effect of this; the data structures are slimmer.
+ *  - custom wake callback functions; because you cannot give any guarantees
+ *    about random code. This also allows swait to be used in RT, such that
+ *    raw spinlock can be used for the swait queue head.
  *
- * One would recommend using this wait queue where possible.
+ * As a side effect of these; the data structures are slimmer albeit more ad-hoc.
+ * For all the above, note that simple wait queues should _only_ be used under
+ * very specific realtime constraints -- it is best to stick with the regular
+ * wait queues in most cases.
  */
 
 struct task_struct;
Signature · 1 line
2.13.6
Acked-by on v1 1/1
#1 lore raw
Quoted 9 lines · Davidlohr Bueso

We currently welcome using swait over wait whenever possible because it is a slimmer data structure. However, Linus has made it very clear that he does not want this used, unless under very specific rt scenarios (such as current users).

Update the comments before kernel hipsters start thinking swait is the cool thing to do.

Thanks, I was busy.

Luis

#2 lore raw

[tip:sched/urgent] sched/swait: Document it clearly that the swait facilities are special and shouldn't be used

In reply to Davidlohr Bueso
sched/swait: Document it clearly that the swait facilities are special and shouldn't be used
Commit-ID:  88796e7e5c457cae72833196cb98e6895dd107e2
Gitweb:     https://git.kernel.org/tip/88796e7e5c457cae72833196cb98e6895dd107e2
Author:     Davidlohr Bueso <[email protected]>
AuthorDate: Fri, 20 Oct 2017 10:13:46 -0700
Committer:  Ingo Molnar <[email protected]>
CommitDate: Mon, 23 Oct 2017 13:59:21 +0200

sched/swait: Document it clearly that the swait facilities are special and shouldn't be used

We currently welcome using swait over wait whenever possible because it is a slimmer data structure. However, Linus has made it very clear that he does not want this used, unless under very specific RT scenarios (such as current users).

Update the comments before kernel hipsters start thinking swait is the cool thing to do.

---
 include/linux/swait.h | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)
include/linux/swait.h +16 -11
index 73e97a0..cf30f502 100644
@@ -9,13 +9,16 @@
 /*
  * Simple wait queues
  *
- * While these are very similar to the other/complex wait queues (wait.h) the
- * most important difference is that the simple waitqueue allows for
- * deterministic behaviour -- IOW it has strictly bounded IRQ and lock hold
- * times.
+ * While these are very similar to regular wait queues (wait.h) the most
+ * important difference is that the simple waitqueue allows for deterministic
+ * behaviour -- IOW it has strictly bounded IRQ and lock hold times.
  *
- * In order to make this so, we had to drop a fair number of features of the
- * other waitqueue code; notably:
+ * Mainly, this is accomplished by two things. Firstly not allowing swake_up_all
+ * from IRQ disabled, and dropping the lock upon every wakeup, giving a higher
+ * priority task a chance to run.
+ *
+ * Secondly, we had to drop a fair number of features of the other waitqueue
+ * code; notably:
  *
  *  - mixing INTERRUPTIBLE and UNINTERRUPTIBLE sleeps on the same waitqueue;
  *    all wakeups are TASK_NORMAL in order to avoid O(n) lookups for the right
@@ -24,12 +27,14 @@
  *  - the exclusive mode; because this requires preserving the list order
  *    and this is hard.
  *
- *  - custom wake functions; because you cannot give any guarantees about
- *    random code.
- *
- * As a side effect of this; the data structures are slimmer.
+ *  - custom wake callback functions; because you cannot give any guarantees
+ *    about random code. This also allows swait to be used in RT, such that
+ *    raw spinlock can be used for the swait queue head.
  *
- * One would recommend using this wait queue where possible.
+ * As a side effect of these; the data structures are slimmer albeit more ad-hoc.
+ * For all the above, note that simple wait queues should _only_ be used under
+ * very specific realtime constraints -- it is best to stick with the regular
+ * wait queues in most cases.
  */
 
 struct task_struct;