[lkml]   [2018]   [Oct]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Patch in this message
Subject[PATCH] sched/completions/Documentation: add recommendation for dynamic and ONSTACK completion
 To prevent dynamic completion objects from being de-allocated while still
in use a recommendation to embed them in long lived data structs is added.
Further a note for the on-stack case is added that emphasizes the limited
scope and recommending dynamic allocation if scope limitations are not
clearly understood.

Signed-off-by: Nicholas Mc Guire <>

Patch is aginast 4.19-rc8 -tip (Oct 16 2018)

Documentation/scheduler/completion.txt | 13 ++++++++++---
1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.txt
index 91a11a6..6e8b0d1 100644
--- a/Documentation/scheduler/completion.txt
+++ b/Documentation/scheduler/completion.txt
@@ -70,8 +70,13 @@ Good, intuitive naming (as always) helps code readability. Naming a completion
Initializing completions:

-Initialization of dynamically allocated completion objects, often embedded in
-other structures, is done via a call to init_completion():
+Dynamically allocated completion objects should preferably be embedded in data
+structures that are assured for the life-time of the function/driver to prevent
+a race with async complete() calls from occurring - notably for the timeout or
+killable variants of wait_for_completion() it must be assured that de-allocation
+does not happen until all related activities (complete() or reinit_completion())
+have taken place. Initializing of dynamically allocated completion objects is done
+via a call to init_completion():


@@ -99,7 +104,9 @@ 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.

When a completion is declared as a local variable within a function,
-then the initialization should always use:
+then the initialization should always use DECLARE_COMPLETION_ONSTACK()
+explicitly to make it clear that limited scope had been considered and
+is intentional - if unsure use dynamically allocated completion objects.


 \ /
  Last update: 2018-10-16 15:53    [W:0.036 / U:0.788 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site