€•”Œsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ(/translations/zh_CN/scheduler/completion”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ(/translations/zh_TW/scheduler/completion”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ(/translations/it_IT/scheduler/completion”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ(/translations/ja_JP/scheduler/completion”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ(/translations/ko_KR/scheduler/completion”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ(/translations/pt_BR/scheduler/completion”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ(/translations/sp_SP/scheduler/completion”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ0Completions - "wait for completion" barrier APIs”h]”hŒ4Completions - “wait for completion†barrier APIs”…””}”(hh¼h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhh·h²hh³ŒB/var/lib/git/docbuild/linux/Documentation/scheduler/completion.rst”h´Kubh¶)”}”(hhh]”(h»)”}”(hŒ Introduction:”h]”hŒ Introduction:”…””}”(hhÎh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhhËh²hh³hÊh´KubhŒ paragraph”“”)”}”(hXIf 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]”hXIf 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.”…””}”(hhÞh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KhhËh²hubhÝ)”}”(hXACompletions 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]”hXACompletions 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.”…””}”(hhìh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K hhËh²hubhÝ)”}”(hXrThe 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]”hXrThe 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.”…””}”(hhúh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KhhË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â€.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KhhË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.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KhhËh²hubeh}”(h]”Œ introduction”ah ]”h"]”Œ introduction:”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kubh¶)”}”(hhh]”(h»)”}”(hŒUsage:”h]”hŒUsage:”…””}”(hj/h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj,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:”…””}”(hj=h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K$hj,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”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hŒDthe initialization of the 'struct completion' synchronization object”h]”hÝ)”}”(hjZh]”hŒHthe initialization of the ‘struct completion’ synchronization object”…””}”(hj\h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K&hjXubah}”(h]”h ]”h"]”h$]”h&]”uh1jVhjSubjW)”}”(hŒPthe waiting part through a call to one of the variants of wait_for_completion(),”h]”hÝ)”}”(hjqh]”hŒPthe waiting part through a call to one of the variants of wait_for_completion(),”…””}”(hjsh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K'hjoubah}”(h]”h ]”h"]”h$]”h&]”uh1jVhjSubjW)”}”(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().”…””}”(hjŠh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K(hj†ubah}”(h]”h ]”h"]”h$]”h&]”uh1jVhjSubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jQh³hÊh´K&hjMubah}”(h]”h ]”h"]”h$]”h&]”uh1jKh³hÊh´K&hj,h²hubhÝ)”}”(hX>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]”hXDThere 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.”…””}”(hj¬h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K*hj,h²hubhÝ)”}”(hŒTo use completions you need to #include 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 and create a static or dynamic variable of type ‘struct completion’, which has only two fields:”…””}”(hjºh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K0hj,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; };”…””}”hjÊsbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1jÈh³hÊh´K4hj,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.”…””}”(hjÚh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K9hj,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:”…””}”(hjèh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kdone);”h]”hŒ'init_completion(&dynamic_object->done);”…””}”hjUsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´KWhjh²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â€.”…””}”(hjch²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KYhjh²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.”…””}”(hjqh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K\hjh²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.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kahjh²hubhÝ)”}”(hŒ@For static declaration and initialization, macros are available.”h]”hŒ@For static declaration and initialization, macros are available.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kfhjh²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():”…””}”(hj›h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Khhjh²hubjÉ)”}”(hŒFstatic DECLARE_COMPLETION(setup_done); DECLARE_COMPLETION(setup_done);”h]”hŒFstatic DECLARE_COMPLETION(setup_done); DECLARE_COMPLETION(setup_done);”…””}”hj©sbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´Kkhjh²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.”…””}”(hj·h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Knhjh²hubhÝ)”}”(hX 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]”hX 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:”…””}”(hjÅh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kqhjh²hubjÉ)”}”(hŒ&DECLARE_COMPLETION_ONSTACK(setup_done)”h]”hŒ&DECLARE_COMPLETION_ONSTACK(setup_done)”…””}”hjÓsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´Kvhjh²hubhÝ)”}”(hXNote 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]”hXNote 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.”…””}”(hjáh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kxhjh²hubhÝ)”}”(hX 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]”hX 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.”…””}”(hjïh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K}hjh²hubhÝ)”}”(hXHIf 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]”hXHIf 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.”…””}”(hjýh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K…hjh²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.”…””}”(hj h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K‹hjh²hubeh}”(h]”Œinitializing-completions”ah ]”h"]”Œinitializing completions:”ah$]”h&]”uh1hµhh·h²hh³hÊh´KHubh¶)”}”(hhh]”(h»)”}”(hŒWaiting for completions:”h]”hŒWaiting for completions:”…””}”(hj$h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj!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:”…””}”(hj2h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Khj!h²hubjÉ)”}”(hŒ1void wait_for_completion(struct completion *done)”h]”hŒ1void wait_for_completion(struct completion *done)”…””}”hj@sbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´K“hj!h²hubhÝ)”}”(hŒA typical usage scenario is::”h]”hŒA typical usage scenario is:”…””}”(hjNh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K•hj!h²hubjÉ)”}”(hX 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]”hX 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);”…””}”hj\sbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´K—hj!h²hubhÝ)”}”(hXLThis 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]”hXLThis 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().”…””}”(hjjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K¢hj!h²hubhÝ)”}”(hXNote 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]”hXNote 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.”…””}”(hjxh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K¨hj!h²hubhÝ)”}”(hXrThe 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]”hXrThe 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.”…””}”(hj†h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K­hj!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.”…””}”(hj”h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K´hj!h²hubeh}”(h]”Œwaiting-for-completions”ah ]”h"]”Œwaiting for completions:”ah$]”h&]”uh1hµhh·h²hh³hÊh´KŽubh¶)”}”(hhh]”(h»)”}”(hŒ*wait_for_completion*() variants available:”h]”hŒ*wait_for_completion*() variants available:”…””}”(hj­h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjª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()).”…””}”(hj»h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K¼hjª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.”…””}”(hjÉh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KÁhjª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:”…””}”(hj×h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KÄhjªh²hubjÉ)”}”(hŒ4if (!wait_for_completion_interruptible_timeout(...))”h]”hŒ4if (!wait_for_completion_interruptible_timeout(...))”…””}”hjåsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´KÇhjª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:”…””}”(hjóh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KÉhjªh²hubjÉ)”}”(hŒ>int wait_for_completion_interruptible(struct completion *done)”h]”hŒ>int wait_for_completion_interruptible(struct completion *done)”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´KÌhjª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:”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KÎhjª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)”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´KÑhjª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).”…””}”(hj+h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KÓhjª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.”…””}”(hj9h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´K×hjª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()):”…””}”(hjGh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´KÚhjª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)”…””}”hjUsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´KÝhjª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.”…””}”(hjch²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kßhjª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:”…””}”(hjqh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kähjª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)”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´Kèhjª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:”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Këhjª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)”…””}”hj›sbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´Kïhjªh²hubeh}”(h]”Œ&wait-for-completion-variants-available”ah ]”h"]”Œ*wait_for_completion*() variants available:”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kºubh¶)”}”(hhh]”(h»)”}”(hŒSignaling completions:”h]”hŒSignaling completions:”…””}”(hj´h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj±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:”…””}”(hjÂh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Köhj±h²hubjÉ)”}”(hŒ&void complete(struct completion *done)”h]”hŒ&void complete(struct completion *done)”…””}”hjÐsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´Kúhj±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:”…””}”(hjÞh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Kühj±h²hubjÉ)”}”(hŒ*void complete_all(struct completion *done)”h]”hŒ*void complete_all(struct completion *done)”…””}”hjìsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´Kþhj±h²hubhÝ)”}”(hXThe 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]”hX 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).”…””}”(hjúh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mhj±h²hubhÝ)”}”(hX(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]”hX(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.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mhj±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.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´M hj±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.”…””}”(hj$h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mhj±h²hubeh}”(h]”Œsignaling-completions”ah ]”h"]”Œsignaling completions:”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kôubh¶)”}”(hhh]”(h»)”}”(hŒ,try_wait_for_completion()/completion_done():”h]”hŒ,try_wait_for_completion()/completion_done():”…””}”(hj=h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj:h²hh³hÊh´MubhÝ)”}”(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:”…””}”(hjKh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mhj:h²hubjÉ)”}”(hŒ5bool try_wait_for_completion(struct completion *done)”h]”hŒ5bool try_wait_for_completion(struct completion *done)”…””}”hjYsbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´Mhj: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:”…””}”(hjgh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´Mhj:h²hubjÉ)”}”(hŒ-bool completion_done(struct completion *done)”h]”hŒ-bool completion_done(struct completion *done)”…””}”hjusbah}”(h]”h ]”h"]”h$]”h&]”jØjÙuh1jÈh³hÊh´M"hj: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.”…””}”(hjƒh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÜh³hÊh´M$hj:h²hubeh}”(h]”Œ'try-wait-for-completion-completion-done”ah ]”h"]”Œ,try_wait_for_completion()/completion_done():”ah$]”h&]”uh1hµhh·h²hh³hÊh´Mubeh}”(h]”Œ,completions-wait-for-completion-barrier-apis”ah ]”h"]”Œ0completions - "wait for completion" barrier apis”ah$]”h&]”uh1hµhhh²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&jjjjj§j¤j®j«j7j4j–j“uŒ nametypes”}”(jž‰j)‰j‰j‰j§‰j®‰j7‰j–‰uh}”(j›h·j&hËjj,jjj¤j!j«jªj4j±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.