From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758693AbbA2W2Y (ORCPT ); Thu, 29 Jan 2015 17:28:24 -0500 Received: from omr2.cc.vt.edu ([198.82.141.100]:41469 "EHLO omr2.cc.vt.edu" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755542AbbA2W2W (ORCPT ); Thu, 29 Jan 2015 17:28:22 -0500 X-Mailer: exmh version 2.8.0 04/21/2012 with nmh-1.6+dev To: Nicholas Mc Guire Cc: Jonathan Corbet , Ingo Molnar , Peter Zijlstra , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH v3] doc: brief user documentation for completion In-Reply-To: Your message of "Thu, 29 Jan 2015 16:55:45 +0100." <1422546945-25645-1-git-send-email-der.herr@hofr.at> From: Valdis.Kletnieks@vt.edu References: <1422546945-25645-1-git-send-email-der.herr@hofr.at> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="==_Exmh_1422570446_1905P"; micalg=pgp-sha1; protocol="application/pgp-signature" Content-Transfer-Encoding: 7bit Date: Thu, 29 Jan 2015 17:27:26 -0500 Message-ID: <22227.1422570446@turing-police.cc.vt.edu> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org --==_Exmh_1422570446_1905P Content-Type: text/plain; charset=us-ascii On Thu, 29 Jan 2015 16:55:45 +0100, Nicholas Mc Guire said: > Signed-off-by: Nicholas Mc Guire > --- > > v3: cleanups and merged review notes from Jonathan Corbet > > patch is against 3.19.0-rc5 -next-20150119 > > Documentation/scheduler/completion.txt | 243 ++++++++++++++++++++++++++++++++ > 1 file changed, 243 insertions(+) > create mode 100644 Documentation/scheduler/completion.txt > > diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.txt > new file mode 100644 > index 0000000..5396656 > --- /dev/null > +++ b/Documentation/scheduler/completion.txt > @@ -0,0 +1,243 @@ Cleaning up the English a bit... I think I found most of the issues... > +misuse of locks. Any time you think of using yield() or some quirky > +msleep(1); loop to allow something else to proceed, you probably wants to s/wants to/want to/ > +To use completions one needs to include and To use completions, you need to.... > +good naming (as always) helps code readability. s/good/Good/ > +The re-initialization function reinit_completions(), simply resets the This needs either an additional comma after function or lose the one. > +For static declaration and initialization macros are available, these are: initialization, macros are available. These are: > +used for static declarations in file scope. Within functions the static > +initialization should always use: > + > + DECLARE_COMPLETION_ONSTACK(setup_done) > + > +suitable for automatic/local variables on the stack and will make lockdep > +happy. This probably needs a big fat warning about making *sure* the completion remains in-scope, and no references remain to on-stack data when the function returns. > +For a thread of execution to wait for some concurrent work to finish, it > +will call wait_for_completion() on the initialized completion structure. s/it will call/it calls/ > +Note 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 hard-irq context will result in hard to detect spurious > +enabling of interrupts. interrupts are enabled. Calling it from ... > +As all variants of wait_for_completion() can (obviously) block for a long > +time, one probably does not want to call this with held locks - see also time, you probably don't want to.... > +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()). Not a doc question - but should these be tagged __must_check to enforce it? > +A common problem that occurred is to have unclean assignment of return types, occurs > +marking the task TASK_INTERRUPTIBLE. If a signal was received while waiting while waiting, > +it will return -ERESTARTSYS and 0 otherwise. > +The _io variants wait_for_completions_io behave the same as the non-_io > +variants, except for accounting waiting time as waiting on IO, which has > +an impact on how scheduling is calculated only. s/only// > +The signaling will work as expected even if completions is signaled before if completions are signaled > +There only can be one thread calling complete() or complete_all() on a > +particular struct completions at any time - serialized through the wait > +queue spinlock. Any such concurrent calls to complete() or complete_all() > +probably are a design bug though. s/though// --==_Exmh_1422570446_1905P Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 Comment: Exmh version 2.5 07/13/2001 iQIVAwUBVMqzzgdmEQWDXROgAQINiBAAlbBNVgrZF0xSnycO/cuAq4yEMATkhdq4 TOxNxOAqQi5C9zrVEjSTvYo5sZrZ1V0IDC6ZjyvjUMRVIhoItCJlg2dygSqNDSY0 ivU4Wn0z7l3/3bYEW5+Ve3tQhncqFfOEKDfqtvglS8ElSmzM/VIyW1u3A1VZ7epP 4YKblCJV0K7F6iW02t5igyOwtTjhrEWL4If1rzMpCK7rjO3GGETovXNHqdulb4zU XacZinZfMj/0jfyUHMqgAZxcCcfjwf1WwnG1OqxnTUhesJxEYKfXew9lQsQYom8m D9y5V4AuvnD6SG7kAIUXJZt1Wiv6R8hAU6HTfPpHrQDvWB6tC6xL0TqQPYOcWTui inwIB0/KIojoGj7YgdDbrIutB70IhkFEy1et+yEWDH8FQQw/YlYT2A5FJgoF2PbF Y8pVN2GEf4sQy/Hx8kU10WDUJdf2nEjM0/ylibe39SxKeU7xgyhn2VSF/NS5MF7u K0DzdkzncEPrHdO/A50n5qT0eVqKIQ2rpceXBnrCiCcrJFY6Z0vZMaiepaxi47Vh 3LSzL2yxD1zYW3aFXSpDuCadJ2lAgKMW9UoCG2IcLEMNMlo1zX3kHXmMYmcSdtqf YnsxQPlU0aankxcYq5tgmZCEXUXKcLxlNZD7nJEzfq00fxIEH+YOrpc1HM+jEJK/ J/wMQI9OUhk= =RHCx -----END PGP SIGNATURE----- --==_Exmh_1422570446_1905P--