[PATCH] sched/completions/Documentation: add recommendation for dynamic and ONSTACK completion

[Nicholas Mc Guire]

 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 <hofrat@xxxxxxxxx>
---

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