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 <hof...@osadl.org>
---
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():
init_completion(&dynamic_object->done);
@@ -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.
DECLARE_COMPLETION_ONSTACK(setup_done)
--
2.1.4
