€•A“      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ(/translations/zh_CN/scheduler/completion”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/zh_TW/scheduler/completion”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/it_IT/scheduler/completion”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ja_JP/scheduler/completion”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ko_KR/scheduler/completion”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/sp_SP/scheduler/completion”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ0Completions - "wait for completion" barrier APIs”h]”hŒ4Completions - â€œwait for completionâ€ barrier APIs”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒB/var/lib/git/docbuild/linux/Documentation/scheduler/completion.rst”h Kubh¢)”}”(hhh]”(h§)”}”(hŒIntroduction:”h]”hŒIntroduction:”…””}”(hhºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh·hžhhŸh¶h KubhŒ	paragraph”“”)”}”(hX  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
pthread_barrier() and have similar use-cases.”h]”hX  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
pthread_barrier() and have similar use-cases.”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hXA  Completions are a code synchronization mechanism which is preferable to any
misuse of locks/semaphores and busy-loops. Any time you think of using
yield() 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 complete() instead.”h]”hXA  Completions are a code synchronization mechanism which is preferable to any
misuse of locks/semaphores and busy-loops. Any time you think of using
yield() 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 complete() instead.”…””}”(hhØhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hXr  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.”h]”hXr  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.”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hŒç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 'struct completion', appropriately called "done".”h]”hŒï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 â€˜struct completionâ€™, appropriately called â€œdoneâ€.”…””}”(hhôhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hŒZAs completions are scheduling related, the code can be found in
kernel/sched/completion.c.”h]”hŒZAs completions are scheduling related, the code can be found in
kernel/sched/completion.c.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubeh}”(h]”Œintroduction”ah ]”h"]”Œintroduction:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒUsage:”h]”hŒUsage:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h K"ubhÉ)”}”(hŒ0There are three main parts to using completions:”h]”hŒ0There are three main parts to using completions:”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K$hj  hžhubhŒblock_quote”“”)”}”(hŒß- the initialization of the 'struct completion' synchronization object
- the waiting part through a call to one of the variants of wait_for_completion(),
- the signaling side through a call to complete() or complete_all().
”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒDthe initialization of the 'struct completion' synchronization object”h]”hÉ)”}”(hjF  h]”hŒHthe initialization of the â€˜struct completionâ€™ synchronization object”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K&hjD  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jB  hj?  ubjC  )”}”(hŒPthe waiting part through a call to one of the variants of wait_for_completion(),”h]”hÉ)”}”(hj]  h]”hŒPthe waiting part through a call to one of the variants of wait_for_completion(),”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K'hj[  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jB  hj?  ubjC  )”}”(hŒCthe signaling side through a call to complete() or complete_all().
”h]”hÉ)”}”(hŒBthe signaling side through a call to complete() or complete_all().”h]”hŒBthe signaling side through a call to complete() or complete_all().”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K(hjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jB  hj?  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j=  hŸh¶h K&hj9  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j7  hŸh¶h K&hj  hžhubhÉ)”}”(hX>  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.”h]”hXD  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.”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K*hj  hžhubhÉ)”}”(hŒTo use completions you need to #include <linux/completion.h> and
create a static or dynamic variable of type 'struct completion',
which has only two fields::”h]”hŒ To use completions you need to #include <linux/completion.h> and
create a static or dynamic variable of type â€˜struct completionâ€™,
which has only two fields:”…””}”(hj¦  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K0hj  hžhubhŒliteral_block”“”)”}”(hŒWstruct completion {
        unsigned int done;
        struct swait_queue_head wait;
};”h]”hŒWstruct completion {
        unsigned int done;
        struct swait_queue_head wait;
};”…””}”hj¶  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1j´  hŸh¶h K4hj  hžhubhÉ)”}”(hŒ—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.”h]”hŒ™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.”…””}”(hjÆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K9hj  hžhubhÉ)”}”(hŒdCompletions should be named to refer to the event that is being synchronized on.
A good example is::”h]”hŒcCompletions should be named to refer to the event that is being synchronized on.
A good example is:”…””}”(hjÔ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K<hj  hžhubjµ  )”}”(hŒKwait_for_completion(&early_console_added);

complete(&early_console_added);”h]”hŒKwait_for_completion(&early_console_added);

complete(&early_console_added);”…””}”hjâ  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h K?hj  hžhubhÉ)”}”(hŒGood, intuitive naming (as always) helps code readability. Naming a completion
'complete' is not helpful unless the purpose is super obvious...”h]”hŒ“Good, intuitive naming (as always) helps code readability. Naming a completion
â€˜completeâ€™ is not helpful unless the purpose is super obvious...”…””}”(hjð  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KChj  hžhubeh}”(h]”Œusage”ah ]”h"]”Œusage:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K"ubh¢)”}”(hhh]”(h§)”}”(hŒInitializing completions:”h]”hŒInitializing completions:”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KHubhÉ)”}”(hŒä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 complete() calls from occurring.”h]”hŒä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 complete() calls from occurring.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KJhj  hžhubhÉ)”}”(hXh  Particular care should be taken when using the _timeout() or _killable()/_interruptible()
variants of wait_for_completion(), as it must be assured that memory de-allocation
does not happen until all related activities (complete() or reinit_completion())
have taken place, even if these wait functions return prematurely due to a timeout
or a signal triggering.”h]”hXh  Particular care should be taken when using the _timeout() or _killable()/_interruptible()
variants of wait_for_completion(), as it must be assured that memory de-allocation
does not happen until all related activities (complete() or reinit_completion())
have taken place, even if these wait functions return prematurely due to a timeout
or a signal triggering.”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KNhj  hžhubhÉ)”}”(hŒbInitializing of dynamically allocated completion objects is done via a call to
init_completion()::”h]”hŒaInitializing of dynamically allocated completion objects is done via a call to
init_completion():”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KThj  hžhubjµ  )”}”(hŒ'init_completion(&dynamic_object->done);”h]”hŒ'init_completion(&dynamic_object->done);”…””}”hjA  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h KWhj  hžhubhÉ)”}”(hŒaIn this call we initialize the waitqueue and set ->done to 0, i.e. "not completed"
or "not done".”h]”hŒiIn this call we initialize the waitqueue and set ->done to 0, i.e. â€œnot completedâ€
or â€œnot doneâ€.”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KYhj  hžhubhÉ)”}”(hŒ÷The re-initialization function, reinit_completion(), 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
wait_for_completion() calls going on in parallel.”h]”hŒûThe re-initialization function, reinit_completion(), 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
wait_for_completion() calls going on in parallel.”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K\hj  hžhubhÉ)”}”(hŒìCalling init_completion() 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 reinit_completion() in that case,
but be aware of other races.”h]”hŒðCalling init_completion() 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 reinit_completion() in that case,
but be aware of other races.”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kahj  hžhubhÉ)”}”(hŒ@For static declaration and initialization, macros are available.”h]”hŒ@For static declaration and initialization, macros are available.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kfhj  hžhubhÉ)”}”(hŒTFor static (or global) declarations in file scope you can use
DECLARE_COMPLETION()::”h]”hŒSFor static (or global) declarations in file scope you can use
DECLARE_COMPLETION():”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khhj  hžhubjµ  )”}”(hŒFstatic DECLARE_COMPLETION(setup_done);
DECLARE_COMPLETION(setup_done);”h]”hŒFstatic DECLARE_COMPLETION(setup_done);
DECLARE_COMPLETION(setup_done);”…””}”hj•  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h Kkhj  hžhubhÉ)”}”(hŒ‘Note that in this case the completion is boot time (or module load time)
initialized to 'not done' and doesn't require an init_completion() call.”h]”hŒ—Note that in this case the completion is boot time (or module load time)
initialized to â€˜not doneâ€™ and doesnâ€™t require an init_completion() call.”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Knhj  hžhubhÉ)”}”(hX  When a completion is declared as a local variable within a function,
then the initialization should always use DECLARE_COMPLETION_ONSTACK()
explicitly, not just to make lockdep happy, but also to make it clear
that limited scope had been considered and is intentional::”h]”hX  When a completion is declared as a local variable within a function,
then the initialization should always use DECLARE_COMPLETION_ONSTACK()
explicitly, not just to make lockdep happy, but also to make it clear
that limited scope had been considered and is intentional:”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kqhj  hžhubjµ  )”}”(hŒ&DECLARE_COMPLETION_ONSTACK(setup_done)”h]”hŒ&DECLARE_COMPLETION_ONSTACK(setup_done)”…””}”hj¿  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h Kvhj  hžhubhÉ)”}”(hX  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.”h]”hX  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.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kxhj  hžhubhÉ)”}”(hX  To emphasise this again: in particular when using some of the waiting API variants
with more complex outcomes, such as the timeout or signalling (_timeout(),
_killable() and _interruptible()) 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 complete() is done in some
other thread. Simple testing might not trigger these kinds of races.”h]”hX  To emphasise this again: in particular when using some of the waiting API variants
with more complex outcomes, such as the timeout or signalling (_timeout(),
_killable() and _interruptible()) 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 complete() is done in some
other thread. Simple testing might not trigger these kinds of races.”…””}”(hjÛ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K}hj  hžhubhÉ)”}”(hXH  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 complete()
is not called on a freed object.”h]”hXH  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 complete()
is not called on a freed object.”…””}”(hjé  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K…hj  hžhubhÉ)”}”(hŒEA naive DECLARE_COMPLETION() on the stack triggers a lockdep warning.”h]”hŒEA naive DECLARE_COMPLETION() on the stack triggers a lockdep warning.”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K‹hj  hžhubeh}”(h]”Œinitializing-completions”ah ]”h"]”Œinitializing completions:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KHubh¢)”}”(hhh]”(h§)”}”(hŒWaiting for completions:”h]”hŒWaiting for completions:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KŽubhÉ)”}”(hŒ…For a thread to wait for some concurrent activity to finish, it
calls wait_for_completion() on the initialized completion structure::”h]”hŒ„For a thread to wait for some concurrent activity to finish, it
calls wait_for_completion() on the initialized completion structure:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj  hžhubjµ  )”}”(hŒ1void wait_for_completion(struct completion *done)”h]”hŒ1void wait_for_completion(struct completion *done)”…””}”hj,  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h K“hj  hžhubhÉ)”}”(hŒA typical usage scenario is::”h]”hŒA typical usage scenario is:”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K•hj  hžhubjµ  )”}”(hX	  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);”h]”hX	  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);”…””}”hjH  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h K—hj  hžhubhÉ)”}”(hXL  This is not implying any particular order between wait_for_completion() and
the call to complete() - if the call to complete() happened before the call
to wait_for_completion() then the waiting side simply will continue
immediately as all dependencies are satisfied; if not, it will block until
completion is signaled by complete().”h]”hXL  This is not implying any particular order between wait_for_completion() and
the call to complete() - if the call to complete() happened before the call
to wait_for_completion() then the waiting side simply will continue
immediately as all dependencies are satisfied; if not, it will block until
completion is signaled by complete().”…””}”(hjV  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¢hj  hžhubhÉ)”}”(hX   Note that wait_for_completion() is calling spin_lock_irq()/spin_unlock_irq(),
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.”h]”hX   Note that wait_for_completion() is calling spin_lock_irq()/spin_unlock_irq(),
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.”…””}”(hjd  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¨hj  hžhubhÉ)”}”(hXr  The default behavior is to wait without a timeout and to mark the task as
uninterruptible. wait_for_completion() 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
try_wait_for_completion() below for handling completion in atomic/interrupt
context.”h]”hXr  The default behavior is to wait without a timeout and to mark the task as
uninterruptible. wait_for_completion() 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
try_wait_for_completion() below for handling completion in atomic/interrupt
context.”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K­hj  hžhubhÉ)”}”(hŒÕAs all variants of wait_for_completion() 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.”h]”hŒ×As all variants of wait_for_completion() 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.”…””}”(hj€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K´hj  hžhubeh}”(h]”Œwaiting-for-completions”ah ]”h"]”Œwaiting for completions:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KŽubh¢)”}”(hhh]”(h§)”}”(hŒ*wait_for_completion*() variants available:”h]”hŒ*wait_for_completion*() variants available:”…””}”(hj™  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj–  hžhhŸh¶h KºubhÉ)”}”(hŒð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:__cpu_up()).”h]”hŒð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:__cpu_up()).”…””}”(hj§  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¼hj–  hžhubhÉ)”}”(hŒ‘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.”h]”hŒ‘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.”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÁhj–  hžhubhÉ)”}”(hŒuChecking for the specific meaning of return values also has been found
to be quite inaccurate, e.g. constructs like::”h]”hŒtChecking for the specific meaning of return values also has been found
to be quite inaccurate, e.g. constructs like:”…””}”(hjÃ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÄhj–  hžhubjµ  )”}”(hŒ4if (!wait_for_completion_interruptible_timeout(...))”h]”hŒ4if (!wait_for_completion_interruptible_timeout(...))”…””}”hjÑ  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h KÇhj–  hžhubhÉ)”}”(hŒƒ... would execute the same code path for successful completion and for the
interrupted case - which is probably not what you want::”h]”hŒ‚... would execute the same code path for successful completion and for the
interrupted case - which is probably not what you want:”…””}”(hjß  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÉhj–  hžhubjµ  )”}”(hŒ>int wait_for_completion_interruptible(struct completion *done)”h]”hŒ>int wait_for_completion_interruptible(struct completion *done)”…””}”hjí  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h KÌhj–  hžhubhÉ)”}”(hŒ–This function marks the task TASK_INTERRUPTIBLE while it is waiting.
If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise::”h]”hŒ•This function marks the task TASK_INTERRUPTIBLE while it is waiting.
If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise:”…””}”(hjû  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÎhj–  hžhubjµ  )”}”(hŒYunsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout)”h]”hŒYunsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout)”…””}”hj	  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h KÑhj–  hžhubhÉ)”}”(hŒª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).”h]”hŒ®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).”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÓhj–  hžhubhÉ)”}”(hŒxTimeouts are preferably calculated with msecs_to_jiffies() or usecs_to_jiffies(),
to make the code largely HZ-invariant.”h]”hŒxTimeouts are preferably calculated with msecs_to_jiffies() or usecs_to_jiffies(),
to make the code largely HZ-invariant.”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K×hj–  hžhubhÉ)”}”(hŒ—If the returned timeout value is deliberately ignored a comment should probably explain
why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc())::”h]”hŒ–If the returned timeout value is deliberately ignored a comment should probably explain
why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc()):”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÚhj–  hžhubjµ  )”}”(hŒ^long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout)”h]”hŒ^long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout)”…””}”hjA  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h KÝhj–  hžhubhÉ)”}”(hŒö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.”h]”hŒö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.”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kßhj–  hžhubhÉ)”}”(hŒÔ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::”h]”hŒÓ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:”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kähj–  hžhubjµ  )”}”(hŒ”long wait_for_completion_killable(struct completion *done)
long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout)”h]”hŒ”long wait_for_completion_killable(struct completion *done)
long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout)”…””}”hjk  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h Kèhj–  hžhubhÉ)”}”(hŒÓThe _io variants wait_for_completion_io() 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::”h]”hŒÖThe _io variants wait_for_completion_io() 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:”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Këhj–  hžhubjµ  )”}”(hŒ‘void wait_for_completion_io(struct completion *done)
unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout)”h]”hŒ‘void wait_for_completion_io(struct completion *done)
unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout)”…””}”hj‡  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h Kïhj–  hžhubeh}”(h]”Œ&wait-for-completion-variants-available”ah ]”h"]”Œ*wait_for_completion*() variants available:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kºubh¢)”}”(hhh]”(h§)”}”(hŒSignaling completions:”h]”hŒSignaling completions:”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KôubhÉ)”}”(hŒ¢A thread that wants to signal that the conditions for continuation have been
achieved calls complete() to signal exactly one of the waiters that it can
continue::”h]”hŒ¡A thread that wants to signal that the conditions for continuation have been
achieved calls complete() to signal exactly one of the waiters that it can
continue:”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Köhj  hžhubjµ  )”}”(hŒ&void complete(struct completion *done)”h]”hŒ&void complete(struct completion *done)”…””}”hj¼  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h Kúhj  hžhubhÉ)”}”(hŒF... or calls complete_all() to signal all current and future waiters::”h]”hŒE... or calls complete_all() to signal all current and future waiters:”…””}”(hjÊ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kühj  hžhubjµ  )”}”(hŒ*void complete_all(struct completion *done)”h]”hŒ*void complete_all(struct completion *done)”…””}”hjØ  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h Kþhj  hžhubhÉ)”}”(hX  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 'struct completion'. Waiting threads
wakeup order is the same in which they were enqueued (FIFO order).”h]”hX   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 â€˜struct completionâ€™. Waiting threads
wakeup order is the same in which they were enqueued (FIFO order).”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M hj  hžhubhÉ)”}”(hX(  If complete() is called multiple times then this will allow for that number
of waiters to continue - each call to complete() will simply increment the
done field. Calling complete_all() multiple times is a bug though. Both
complete() and complete_all() can be called in IRQ/atomic context safely.”h]”hX(  If complete() is called multiple times then this will allow for that number
of waiters to continue - each call to complete() will simply increment the
done field. Calling complete_all() multiple times is a bug though. Both
complete() and complete_all() can be called in IRQ/atomic context safely.”…””}”(hjô  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj  hžhubhÉ)”}”(hŒôThere can only be one thread calling complete() or complete_all() on a
particular 'struct completion' at any time - serialized through the wait
queue spinlock. Any such concurrent calls to complete() or complete_all()
probably are a design bug.”h]”hŒøThere can only be one thread calling complete() or complete_all() on a
particular â€˜struct completionâ€™ at any time - serialized through the wait
queue spinlock. Any such concurrent calls to complete() or complete_all()
probably are a design bug.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M
hj  hžhubhÉ)”}”(hŒ–Signaling completion from IRQ context is fine as it will appropriately
lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
sleep.”h]”hŒ–Signaling completion from IRQ context is fine as it will appropriately
lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
sleep.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj  hžhubeh}”(h]”Œsignaling-completions”ah ]”h"]”Œsignaling completions:”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kôubh¢)”}”(hhh]”(h§)”}”(hŒ,try_wait_for_completion()/completion_done():”h]”hŒ,try_wait_for_completion()/completion_done():”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj&  hžhhŸh¶h MubhÉ)”}”(hŒÓThe try_wait_for_completion() 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::”h]”hŒÒThe try_wait_for_completion() 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:”…””}”(hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj&  hžhubjµ  )”}”(hŒ5bool try_wait_for_completion(struct completion *done)”h]”hŒ5bool try_wait_for_completion(struct completion *done)”…””}”hjE  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h Mhj&  hžhubhÉ)”}”(hŒ÷Finally, to check the state of a completion without changing it in any way,
call completion_done(), which returns false if there are no posted
completions that were not yet consumed by waiters (implying that there are
waiters) and true otherwise::”h]”hŒöFinally, to check the state of a completion without changing it in any way,
call completion_done(), which returns false if there are no posted
completions that were not yet consumed by waiters (implying that there are
waiters) and true otherwise:”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj&  hžhubjµ  )”}”(hŒ-bool completion_done(struct completion *done)”h]”hŒ-bool completion_done(struct completion *done)”…””}”hja  sbah}”(h]”h ]”h"]”h$]”h&]”jÄ  jÅ  uh1j´  hŸh¶h M"hj&  hžhubhÉ)”}”(hŒdBoth try_wait_for_completion() and completion_done() are safe to be called in
IRQ or atomic context.”h]”hŒdBoth try_wait_for_completion() and completion_done() are safe to be called in
IRQ or atomic context.”…””}”(hjo  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M$hj&  hžhubeh}”(h]”Œ'try-wait-for-completion-completion-done”ah ]”h"]”Œ,try_wait_for_completion()/completion_done():”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Mubeh}”(h]”Œ,completions-wait-for-completion-barrier-apis”ah ]”h"]”Œ0completions - "wait for completion" barrier apis”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j°  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jŠ  j‡  j  j  j  j   j
  j  j“  j  jš  j—  j#  j   j‚  j  uŒ	nametypes”}”(jŠ  ‰j  ‰j  ‰j
  ‰j“  ‰jš  ‰j#  ‰j‚  ‰uh}”(j‡  h£j  h·j   j  j  j  j  j  j—  j–  j   j  j  j&  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.