From: Nicholas Mc Guire <hofrat@osadl.org>
To: mingo@kernel.org
Cc: john.garry@huawei.com, tglx@linutronix.de, hpa@zytor.com,
peterz@infradead.org, torvalds@linux-foundation.org,
linux-kernel@vger.kernel.org,
Nicholas Mc Guire <hofrat@osadl.org>
Subject: [PATCH] sched/completions/Documentation: add recommendation for dynamic and ONSTACK completion
Date: Tue, 16 Oct 2018 15:45:39 +0200 [thread overview]
Message-ID: <1539697539-24055-1-git-send-email-hofrat@osadl.org> (raw)
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@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
next reply other threads:[~2018-10-16 13:52 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-10-16 13:45 Nicholas Mc Guire [this message]
2018-10-17 9:10 ` [tip:sched/core] sched/completions/Documentation: Add recommendation for dynamic and ONSTACK completions tip-bot for Nicholas Mc Guire
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1539697539-24055-1-git-send-email-hofrat@osadl.org \
--to=hofrat@osadl.org \
--cc=hpa@zytor.com \
--cc=john.garry@huawei.com \
--cc=linux-kernel@vger.kernel.org \
--cc=mingo@kernel.org \
--cc=peterz@infradead.org \
--cc=tglx@linutronix.de \
--cc=torvalds@linux-foundation.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).