<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Completions - “wait for completion” barrier APIs — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="membarrier() System Call" href="membarrier.html" />
<link rel="prev" title="Scheduler" href="index.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2 current"><a class="reference internal" href="../subsystem-apis.html#core-subsystems">Core subsystems</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../core-api/index.html">Core API Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../driver-api/index.html">Driver implementer’s API guide</a></li>
<li class="toctree-l3"><a class="reference internal" href="../mm/index.html">Memory Management Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../power/index.html">Power Management</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">Scheduler</a></li>
<li class="toctree-l3"><a class="reference internal" href="../timers/index.html">Timers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#human-interfaces">Human interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/scheduler/completion.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="language-selection">
English
<ul>
<li><a href="../translations/zh_CN/scheduler/completion.html">Chinese (Simplified)</a></li>
</ul>
</div>
<section id="completions-wait-for-completion-barrier-apis">
<h1>Completions - “wait for completion” barrier APIs<a class="headerlink" href="#completions-wait-for-completion-barrier-apis" title="Link to this heading">¶</a></h1>
<section id="introduction">
<h2>Introduction:<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<p>If you have one or more threads that must wait for some kernel activity
to have reached a point or a specific state, completions can provide a
race-free solution to this problem. Semantically they are somewhat like a
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">pthread_barrier()</span></code> and have similar use-cases.</p>
<p>Completions are a code synchronization mechanism which is preferable to any
misuse of locks/semaphores and busy-loops. Any time you think of using
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">yield()</span></code> or some quirky msleep(1) loop to allow something else to proceed,
you probably want to look into using one of the wait_for_completion*()
calls and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> instead.</p>
<p>The advantage of using completions is that they have a well defined, focused
purpose which makes it very easy to see the intent of the code, but they
also result in more efficient code as all threads can continue execution
until the result is actually needed, and both the waiting and the signalling
is highly efficient using low level scheduler sleep/wakeup facilities.</p>
<p>Completions are built on top of the waitqueue and wakeup infrastructure of
the Linux scheduler. The event the threads on the waitqueue are waiting for
is reduced to a simple flag in ‘<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">completion</span></code>’, appropriately called “done”.</p>
<p>As completions are scheduling related, the code can be found in
kernel/sched/completion.c.</p>
</section>
<section id="usage">
<h2>Usage:<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h2>
<p>There are three main parts to using completions:</p>
<blockquote>
<div><ul class="simple">
<li><p>the initialization of the ‘<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">completion</span></code>’ synchronization object</p></li>
<li><p>the waiting part through a call to one of the variants of <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code>,</p></li>
<li><p>the signaling side through a call to <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> or <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete_all()</span></code>.</p></li>
</ul>
</div></blockquote>
<p>There are also some helper functions for checking the state of completions.
Note that while initialization must happen first, the waiting and signaling
part can happen in any order. I.e. it’s entirely normal for a thread
to have marked a completion as ‘done’ before another thread checks whether
it has to wait for it.</p>
<p>To use completions you need to #include <linux/completion.h> and
create a static or dynamic variable of type ‘<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">completion</span></code>’,
which has only two fields:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct completion {
unsigned int done;
struct swait_queue_head wait;
};
</pre></div>
</div>
<p>This provides the ->wait waitqueue to place tasks on for waiting (if any), and
the ->done completion flag for indicating whether it’s completed or not.</p>
<p>Completions should be named to refer to the event that is being synchronized on.
A good example is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>wait_for_completion(&early_console_added);
complete(&early_console_added);
</pre></div>
</div>
<p>Good, intuitive naming (as always) helps code readability. Naming a completion
‘complete’ is not helpful unless the purpose is super obvious...</p>
</section>
<section id="initializing-completions">
<h2>Initializing completions:<a class="headerlink" href="#initializing-completions" title="Link to this heading">¶</a></h2>
<p>Dynamically allocated completion objects should preferably be embedded in data
structures that are assured to be alive for the life-time of the function/driver,
to prevent races with asynchronous <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> calls from occurring.</p>
<p>Particular care should be taken when using the <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">_timeout()</span></code> or <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">_killable()</span></code>/<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">_interruptible()</span></code>
variants of <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code>, as it must be assured that memory de-allocation
does not happen until all related activities (<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> or <a class="reference internal" href="../driver-api/basics.html#c.reinit_completion" title="reinit_completion"><code class="xref c c-func docutils literal notranslate"><span class="pre">reinit_completion()</span></code></a>)
have taken place, even if these wait functions return prematurely due to a timeout
or a signal triggering.</p>
<p>Initializing of dynamically allocated completion objects is done via a call to
<a class="reference internal" href="../driver-api/basics.html#c.init_completion" title="init_completion"><code class="xref c c-func docutils literal notranslate"><span class="pre">init_completion()</span></code></a>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>init_completion(&dynamic_object->done);
</pre></div>
</div>
<p>In this call we initialize the waitqueue and set ->done to 0, i.e. “not completed”
or “not done”.</p>
<p>The re-initialization function, <a class="reference internal" href="../driver-api/basics.html#c.reinit_completion" title="reinit_completion"><code class="xref c c-func docutils literal notranslate"><span class="pre">reinit_completion()</span></code></a>, simply resets the
->done field to 0 (“not done”), without touching the waitqueue.
Callers of this function must make sure that there are no racy
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code> calls going on in parallel.</p>
<p>Calling <a class="reference internal" href="../driver-api/basics.html#c.init_completion" title="init_completion"><code class="xref c c-func docutils literal notranslate"><span class="pre">init_completion()</span></code></a> on the same completion object twice is
most likely a bug as it re-initializes the queue to an empty queue and
enqueued tasks could get “lost” - use <a class="reference internal" href="../driver-api/basics.html#c.reinit_completion" title="reinit_completion"><code class="xref c c-func docutils literal notranslate"><span class="pre">reinit_completion()</span></code></a> in that case,
but be aware of other races.</p>
<p>For static declaration and initialization, macros are available.</p>
<p>For static (or global) declarations in file scope you can use
<a class="reference internal" href="../driver-api/basics.html#c.DECLARE_COMPLETION" title="DECLARE_COMPLETION"><code class="xref c c-func docutils literal notranslate"><span class="pre">DECLARE_COMPLETION()</span></code></a>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>static DECLARE_COMPLETION(setup_done);
DECLARE_COMPLETION(setup_done);
</pre></div>
</div>
<p>Note that in this case the completion is boot time (or module load time)
initialized to ‘not done’ and doesn’t require an <a class="reference internal" href="../driver-api/basics.html#c.init_completion" title="init_completion"><code class="xref c c-func docutils literal notranslate"><span class="pre">init_completion()</span></code></a> call.</p>
<p>When a completion is declared as a local variable within a function,
then the initialization should always use <a class="reference internal" href="../driver-api/basics.html#c.DECLARE_COMPLETION_ONSTACK" title="DECLARE_COMPLETION_ONSTACK"><code class="xref c c-func docutils literal notranslate"><span class="pre">DECLARE_COMPLETION_ONSTACK()</span></code></a>
explicitly, not just to make lockdep happy, but also to make it clear
that limited scope had been considered and is intentional:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>DECLARE_COMPLETION_ONSTACK(setup_done)
</pre></div>
</div>
<p>Note that when using completion objects as local variables you must be
acutely aware of the short life time of the function stack: the function
must not return to a calling context until all activities (such as waiting
threads) have ceased and the completion object is completely unused.</p>
<p>To emphasise this again: in particular when using some of the waiting API variants
with more complex outcomes, such as the timeout or signalling (<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">_timeout()</span></code>,
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">_killable()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">_interruptible()</span></code>) variants, the wait might complete
prematurely while the object might still be in use by another thread - and a return
from the wait_on_completion*() caller function will deallocate the function
stack and cause subtle data corruption if a <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> is done in some
other thread. Simple testing might not trigger these kinds of races.</p>
<p>If unsure, use dynamically allocated completion objects, preferably embedded
in some other long lived object that has a boringly long life time which
exceeds the life time of any helper threads using the completion object,
or has a lock or other synchronization mechanism to make sure <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code>
is not called on a freed object.</p>
<p>A naive <a class="reference internal" href="../driver-api/basics.html#c.DECLARE_COMPLETION" title="DECLARE_COMPLETION"><code class="xref c c-func docutils literal notranslate"><span class="pre">DECLARE_COMPLETION()</span></code></a> on the stack triggers a lockdep warning.</p>
</section>
<section id="waiting-for-completions">
<h2>Waiting for completions:<a class="headerlink" href="#waiting-for-completions" title="Link to this heading">¶</a></h2>
<p>For a thread to wait for some concurrent activity to finish, it
calls <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code> on the initialized completion structure:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>void wait_for_completion(struct completion *done)
</pre></div>
</div>
<p>A typical usage scenario is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CPU#1 CPU#2
struct completion setup_done;
init_completion(&setup_done);
initialize_work(...,&setup_done,...);
/* run non-dependent code */ /* do setup */
wait_for_completion(&setup_done); complete(&setup_done);
</pre></div>
</div>
<p>This is not implying any particular order between <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code> and
the call to <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> - if the call to <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> happened before the call
to <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code> then the waiting side simply will continue
immediately as all dependencies are satisfied; if not, it will block until
completion is signaled by <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code>.</p>
<p>Note that <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code> is calling <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_lock_irq()</span></code>/<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_unlock_irq()</span></code>,
so it can only be called safely when you know that interrupts are enabled.
Calling it from IRQs-off atomic contexts will result in hard-to-detect
spurious enabling of interrupts.</p>
<p>The default behavior is to wait without a timeout and to mark the task as
uninterruptible. <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code> and its variants are only safe
in process context (as they can sleep) but not in atomic context,
interrupt context, with disabled IRQs, or preemption is disabled - see also
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">try_wait_for_completion()</span></code> below for handling completion in atomic/interrupt
context.</p>
<p>As all variants of <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion()</span></code> can (obviously) block for a long
time depending on the nature of the activity they are waiting for, so in
most cases you probably don’t want to call this with held mutexes.</p>
</section>
<section id="wait-for-completion-variants-available">
<h2>wait_for_completion*() variants available:<a class="headerlink" href="#wait-for-completion-variants-available" title="Link to this heading">¶</a></h2>
<p>The below variants all return status and this status should be checked in
most(/all) cases - in cases where the status is deliberately not checked you
probably want to make a note explaining this (e.g. see
arch/arm/kernel/smp.c:<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">__cpu_up()</span></code>).</p>
<p>A common problem that occurs is to have unclean assignment of return types,
so take care to assign return-values to variables of the proper type.</p>
<p>Checking for the specific meaning of return values also has been found
to be quite inaccurate, e.g. constructs like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>if (!wait_for_completion_interruptible_timeout(...))
</pre></div>
</div>
<p>... would execute the same code path for successful completion and for the
interrupted case - which is probably not what you want:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>int wait_for_completion_interruptible(struct completion *done)
</pre></div>
</div>
<p>This function marks the task TASK_INTERRUPTIBLE while it is waiting.
If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>unsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout)
</pre></div>
</div>
<p>The task is marked as TASK_UNINTERRUPTIBLE and will wait at most ‘timeout’
jiffies. If a timeout occurs it returns 0, else the remaining time in
jiffies (but at least 1).</p>
<p>Timeouts are preferably calculated with <a class="reference internal" href="../driver-api/basics.html#c.msecs_to_jiffies" title="msecs_to_jiffies"><code class="xref c c-func docutils literal notranslate"><span class="pre">msecs_to_jiffies()</span></code></a> or <a class="reference internal" href="../driver-api/basics.html#c.usecs_to_jiffies" title="usecs_to_jiffies"><code class="xref c c-func docutils literal notranslate"><span class="pre">usecs_to_jiffies()</span></code></a>,
to make the code largely HZ-invariant.</p>
<p>If the returned timeout value is deliberately ignored a comment should probably explain
why (e.g. see drivers/mfd/wm8350-core.c <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wm8350_read_auxadc()</span></code>):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout)
</pre></div>
</div>
<p>This function passes a timeout in jiffies and marks the task as
TASK_INTERRUPTIBLE. If a signal was received it will return -ERESTARTSYS;
otherwise it returns 0 if the completion timed out, or the remaining time in
jiffies if completion occurred.</p>
<p>Further variants include _killable which uses TASK_KILLABLE as the
designated tasks state and will return -ERESTARTSYS if it is interrupted,
or 0 if completion was achieved. There is a _timeout variant as well:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>long wait_for_completion_killable(struct completion *done)
long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout)
</pre></div>
</div>
<p>The _io variants <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">wait_for_completion_io()</span></code> behave the same as the non-_io
variants, except for accounting waiting time as ‘waiting on IO’, which has
an impact on how the task is accounted in scheduling/IO stats:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>void wait_for_completion_io(struct completion *done)
unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout)
</pre></div>
</div>
</section>
<section id="signaling-completions">
<h2>Signaling completions:<a class="headerlink" href="#signaling-completions" title="Link to this heading">¶</a></h2>
<p>A thread that wants to signal that the conditions for continuation have been
achieved calls <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> to signal exactly one of the waiters that it can
continue:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>void complete(struct completion *done)
</pre></div>
</div>
<p>... or calls <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete_all()</span></code> to signal all current and future waiters:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>void complete_all(struct completion *done)
</pre></div>
</div>
<p>The signaling will work as expected even if completions are signaled before
a thread starts waiting. This is achieved by the waiter “consuming”
(decrementing) the done field of ‘<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">completion</span></code>’. Waiting threads
wakeup order is the same in which they were enqueued (FIFO order).</p>
<p>If <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> is called multiple times then this will allow for that number
of waiters to continue - each call to <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> will simply increment the
done field. Calling <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete_all()</span></code> multiple times is a bug though. Both
<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete_all()</span></code> can be called in IRQ/atomic context safely.</p>
<p>There can only be one thread calling <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> or <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete_all()</span></code> on a
particular ‘<code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">completion</span></code>’ at any time - serialized through the wait
queue spinlock. Any such concurrent calls to <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete()</span></code> or <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">complete_all()</span></code>
probably are a design bug.</p>
<p>Signaling completion from IRQ context is fine as it will appropriately
lock with <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_lock_irqsave()</span></code>/<code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">spin_unlock_irqrestore()</span></code> and it will never
sleep.</p>
</section>
<section id="try-wait-for-completion-completion-done">
<h2>try_wait_for_completion()/completion_done():<a class="headerlink" href="#try-wait-for-completion-completion-done" title="Link to this heading">¶</a></h2>
<p>The <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">try_wait_for_completion()</span></code> function will not put the thread on the wait
queue but rather returns false if it would need to enqueue (block) the thread,
else it consumes one posted completion and returns true:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>bool try_wait_for_completion(struct completion *done)
</pre></div>
</div>
<p>Finally, to check the state of a completion without changing it in any way,
call <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">completion_done()</span></code>, which returns false if there are no posted
completions that were not yet consumed by waiters (implying that there are
waiters) and true otherwise:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>bool completion_done(struct completion *done)
</pre></div>
</div>
<p>Both <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">try_wait_for_completion()</span></code> and <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">completion_done()</span></code> are safe to be called in
IRQ or atomic context.</p>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/scheduler/completion.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>