man9: Add man page for kern_yield() and friends

[mhorne]

Summary

It is simple and will be referenced by mi_switch(9).

[markj]

share/man/man9/kern_yield.9

72

Maybe note that it's really mostly meant to be used by threads doing a lot of work in the kernel, which don't readily preempt each other (see preempt_thresh) and thus rely on each other to yield the CPU. The function effectively checks whether it's been a long time (relative to the scheduling quantum) since the thread yielded voluntarily and thus might be hogging a CPU.

89

It's also a good idea to release locks before yielding, when possible.

[kib]

Two notes about priorities

1. the kernel implements involuntary switching, so a thread hogging CPU should have special properties comparing to other threads that are starved.
2. yielding does not guarantee that the yielding thread is removed from CPU, see note 1.

Explaining these two connected points in more details would be a useful service to the reader, IMO.

Also, the priority requested by kern_prio() is sticky until thread returns to usermode, which might be a surprise, AFAIR.

[mhorne]

In D38182#867832, @kib wrote:

Two notes about priorities

1. the kernel implements involuntary switching, so a thread hogging CPU should have special properties comparing to other threads that are starved.
2. yielding does not guarantee that the yielding thread is removed from CPU, see note 1.

Explaining these two connected points in more details would be a useful service to the reader, IMO.

I think I understand these points, but to be clear you are mainly referring to interactivity score in ULE? As in, threads with a low voluntary sleep count could be categorized as non-interactive, and scheduled with lower priority than interactive timesharing threads. Therefore, the yielding thread may end up being the highest priority thread on the CPU's runqueues, and would be picked to continue running.

Also, the priority requested by kern_prio() is sticky until thread returns to usermode, which might be a surprise, AFAIR.

[mhorne]

Handle review comments, mainly by expanding USAGE NOTES.

[kib]

share/man/man9/kern_yield.9

95

I do not think this statement is true

[mhorne]

share/man/man9/kern_yield.9

95

Remarkably, with the default tuning of kern.sched.preempt_thresh, it is.

sched_shouldpreempt() contains the logic. I did overlook one case, which is that interactive or better threads will preempt non-interactive (batch) threads running on remote CPUs.

Nonetheless I will relax the language here slightly.

[mhorne]

Slight tweaks to the first paragraph in USAGE NOTES.