1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
<table class="head">
<tr>
<td class="head-ltitle">KERN_YIELD(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">KERN_YIELD(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">kern_yield</code>,
<code class="Nm">maybe_yield</code>, <code class="Nm">should_yield</code>
— <span class="Nd">functions for yielding execution of the current
thread</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">kern_yield</code>(<var class="Fa" style="white-space: nowrap;">int
prio</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">maybe_yield</code>();</p>
<p class="Pp"><var class="Ft">bool</var>
<br/>
<code class="Fn">should_yield</code>();</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The
<a class="permalink" href="#kern_yield"><code class="Fn" id="kern_yield">kern_yield</code></a>()
function causes the currently running thread to voluntarily, but
unconditionally, surrender its execution to the scheduler. The
<var class="Va">prio</var> argument specifies the scheduling priority to be
assigned before the context switch, which has an influence on when execution
will resume. Note that the requested priority will take effect until the
thread returns to usermode, after which its base user priority will be
restored. Valid values for <var class="Va">prio</var> are any of the
<code class="Dv">PRI_*</code> values defined in
<code class="In"><<a class="In">sys/priority.h</a>></code>, as well as
the following special values:</p>
<dl class="Bl-tag">
<dt id="PRI_USER"><a class="permalink" href="#PRI_USER"><code class="Dv">PRI_USER</code></a></dt>
<dd>Schedule the thread with its base user priority; the value corresponding
to <a class="Xr">setpriority(2)</a> / <a class="Xr">nice(3)</a>.</dd>
<dt id="PRI_UNCHANGED"><a class="permalink" href="#PRI_UNCHANGED"><code class="Dv">PRI_UNCHANGED</code></a></dt>
<dd>Yield the thread without changing its priority.</dd>
</dl>
<p class="Pp" id="should_yield">The
<a class="permalink" href="#should_yield"><code class="Fn">should_yield</code></a>()
function checks if sufficient time has passed since the thread's last
voluntary context switch that yielding would be a useful service to other
threads. It returns <var class="Va">true</var> when this is the case. See
<a class="Sx" href="#USAGE_NOTES">USAGE NOTES</a> for an elaboration of what
this means.</p>
<p class="Pp" id="maybe_yield">The
<a class="permalink" href="#maybe_yield"><code class="Fn">maybe_yield</code></a>()
function is a helper function for the common task of optionally yielding the
processor. Internally,
<code class="Fn">kern_yield</code>(<var class="Fa">PRI_USER</var>) will be
called if <code class="Fn">should_yield</code>() returns
<var class="Va">true</var>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="USAGE_NOTES"><a class="permalink" href="#USAGE_NOTES">USAGE
NOTES</a></h1>
<p class="Pp">Although the kernel supports preemption, this is usually reserved
for high-priority realtime or interrupt threads. Kernel worker threads and
timesharing threads are not guaranteed to preempt each another. Thus,
threads executing in the kernel are expected to behave cooperatively with
respect to other threads in the system. The yield functions are mostly
intended to be used by threads which perform a lot of work inside the
kernel. For example: <code class="Fn">maybe_yield</code>() is called by the
<code class="Dv">vlnru</code> process each time it reclaims a vnode.</p>
<p class="Pp" id="kern_yield~2">The scheduler aims to identify threads which
monopolize the CPU, and will schedule them with decreased priority. Threads
which regularly yield the processor will be given the chance to run more
often. The possibly surprising effect of this is that, depending on the
disposition of other threads on the CPU's runqueue, a call to
<a class="permalink" href="#kern_yield~2"><code class="Fn">kern_yield</code></a>()
does not guarantee that the yielding thread will be taken off the CPU.</p>
<p class="Pp" id="kern_yield~3">With the above considerations in mind, it is
advised that code written using
<a class="permalink" href="#kern_yield~3"><code class="Fn">kern_yield</code></a>()
be measured to confirm that its use has a positive effect on relevant
performance or responsiveness metrics. Switching thread contexts has a
non-zero cost, and thus yielding the processor too eagerly could have a
negative impact on performance.</p>
<p class="Pp">Additionally, since yielding is a cooperative action, it is
advised that the yielding thread release any locks that it may be holding,
when possible. Otherwise, threads which have been given the chance to run
could end up waiting on the yielding thread to release the lock, largely
defeating the purpose of the yield.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">setpriority(2)</a>, <a class="Xr">nice(3)</a>,
<a class="Xr">mi_switch(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This manual page was written by <span class="An">Mitchell
Horne</span>
<<a class="Mt" href="mailto:mhorne@FreeBSD.org">mhorne@FreeBSD.org</a>>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 30, 2023</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
