From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754179AbbLOQCy (ORCPT ); Tue, 15 Dec 2015 11:02:54 -0500 Received: from mail-wm0-f43.google.com ([74.125.82.43]:33065 "EHLO mail-wm0-f43.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753682AbbLOQCw (ORCPT ); Tue, 15 Dec 2015 11:02:52 -0500 Message-ID: <567039A5.9050109@gmail.com> Date: Tue, 15 Dec 2015 17:02:45 +0100 From: "Michael Kerrisk (man-pages)" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.7.0 MIME-Version: 1.0 To: Torvald Riegel CC: mtk.manpages@gmail.com, Thomas Gleixner , Darren Hart , lkml , libc-alpha , linux-man , "Carlos O'Donell" , Roland McGrath , Davidlohr Bueso , Jakub Jelinek , Ingo Molnar , bill o gallmeister , bert hubert , Jan Kiszka , Eric Dumazet , Arnd Bergmann , Rusty Russell , Heinrich Schuchardt , Andy Lutomirski , Daniel Wagner , Anton Blanchard , Steven Rostedt , Rich Felker , Jonathan Wakely , Mike Frysinger Subject: Re: futex(3) man page, final draft for pre-release review References: <56701916.4090203@gmail.com> <1450193693.27311.115.camel@localhost.localdomain> In-Reply-To: <1450193693.27311.115.camel@localhost.localdomain> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hello Torvald, On 12/15/2015 04:34 PM, Torvald Riegel wrote: > On Tue, 2015-12-15 at 14:43 +0100, Michael Kerrisk (man-pages) wrote: >> Hello all, >> >> After much too long a time, the revised futex man page *will* >> go out in the next man pages release (it has been merged >> into master). >> >> There are various places where the page could still be improved, >> but it is much better (and more than 5 times longer) than the >> existing page. > > This looks good to me; I just saw minor things (see below). Thank you > for all the work you put into this (and to everybody who contributed)! Hey Torvald, you were one of the biggest contributors, so, thanks! >> When executing a futex operation that requests to block a thread, >> the kernel will block only if the futex word has the value that >> the calling thread supplied (as one of the arguments of the >> futex() call) as the expected value of the futex word. The load‐ >> ing of the futex word's value, the comparison of that value with >> the expected value, and the actual blocking will happen atomi‐ >> >> FIXME: for next line, it would be good to have an explanation of >> "totally ordered" somewhere around here. >> >> cally and totally ordered with respect to concurrently executing >> futex operations on the same futex word. Thus, the futex word is >> used to connect the synchronization in user space with the imple‐ >> mentation of blocking by the kernel. Analogously to an atomic >> compare-and-exchange operation that potentially changes shared >> memory, blocking via a futex is an atomic compare-and-block oper‐ >> ation. > > Maybe -- should we just say that it refers to the mathematical notion of > a total order (or, technically, a strict total order in this case)? I added a sentence along those lines. > Though I would hope that everyone using futexes is roughly aware of the > differences between partial and total orders. >> FUTEX_TRYLOCK_PI (since Linux 2.6.18) >> This operation tries to acquire the futex at uaddr. It is > > s/futex/lock/ to make it consistent with FUTEX_LOCK. Done. >> invoked when a user-space atomic acquire did not succeed >> because the futex word was not 0. >> >> >> FIXME(Next sentence) The wording "The trylock in kernel" below >> needs clarification. Suggestions? >> >> The trylock in kernel might succeed because the futex word >> contains stale state (FUTEX_WAITERS and/or >> FUTEX_OWNER_DIED). This can happen when the owner of the >> futex died. User space cannot handle this condition in a >> race-free manner, but the kernel can fix this up and >> acquire the futex. >> >> The uaddr2, val, timeout, and val3 arguments are ignored. > > What about "The acquisition of the lock might suceed if performed by the > kernel in cases when the futex word contains stale state...". Sounds good to me. Changed. >> FUTEX_WAIT_REQUEUE_PI (since Linux 2.6.31) >> Wait on a non-PI futex at uaddr and potentially be >> requeued (via a FUTEX_CMP_REQUEUE_PI operation in another >> task) onto a PI futex at uaddr2. The wait operation on >> uaddr is the same as for FUTEX_WAIT. >> >> The waiter can be removed from the wait on uaddr without >> requeueing on uaddr2 via a FUTEX_WAKE operation in another >> task. In this case, the FUTEX_WAIT_REQUEUE_PI operation >> returns with the error EWOULDBLOCK. > > This should be EAGAIN, I suppose, or the enumeration of errors should > include EWOULDBLOCK. Changed. BTW, under ERRORS there is already this text: Note: on Linux, the symbolic names EAGAIN and EWOULDBLOCK (both of which appear in different parts of the kernel futex code) have the same value. Thanks for the comments, Torvald! Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Michael Kerrisk (man-pages)" Subject: Re: futex(3) man page, final draft for pre-release review Date: Tue, 15 Dec 2015 17:02:45 +0100 Message-ID: <567039A5.9050109@gmail.com> References: <56701916.4090203@gmail.com> <1450193693.27311.115.camel@localhost.localdomain> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: QUOTED-PRINTABLE Return-path: In-Reply-To: <1450193693.27311.115.camel-bi+AKbBUZKY6gyzm1THtWbp2dZbC/Bob@public.gmane.org> Sender: linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org To: Torvald Riegel Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, Thomas Gleixner , Darren Hart , lkml , libc-alpha , linux-man , Carlos O'Donell , Roland McGrath , Davidlohr Bueso , Jakub Jelinek , Ingo Molnar , bill o gallmeister , bert hubert , Jan Kiszka , Eric Dumazet , Arnd Bergmann , Rusty Russell , Heinrich Schuchardt , Andy Lutomirski , Daniel Wagner , Anton Blanchard , Steven Rostedt , Rich Felker , Jonathan Wakely List-Id: linux-man@vger.kernel.org Hello Torvald, On 12/15/2015 04:34 PM, Torvald Riegel wrote: > On Tue, 2015-12-15 at 14:43 +0100, Michael Kerrisk (man-pages) wrote: >> Hello all, >> >> After much too long a time, the revised futex man page *will* >> go out in the next man pages release (it has been merged >> into master). >> >> There are various places where the page could still be improved, >> but it is much better (and more than 5 times longer) than the >> existing page. >=20 > This looks good to me; I just saw minor things (see below). Thank yo= u > for all the work you put into this (and to everybody who contributed)= ! Hey Torvald, you were one of the biggest contributors, so, thanks! >> When executing a futex operation that requests to block a thr= ead, >> the kernel will block only if the futex word has the value = that >> the calling thread supplied (as one of the arguments of= the >> futex() call) as the expected value of the futex word. The l= oad=E2=80=90 >> ing of the futex word's value, the comparison of that value = with >> the expected value, and the actual blocking will happen at= omi=E2=80=90 >> >> FIXME: for next line, it would be good to have an explanation of >> "totally ordered" somewhere around here. >> >> cally and totally ordered with respect to concurrently execu= ting >> futex operations on the same futex word. Thus, the futex wor= d is >> used to connect the synchronization in user space with the im= ple=E2=80=90 >> mentation of blocking by the kernel. Analogously to an at= omic >> compare-and-exchange operation that potentially changes sh= ared >> memory, blocking via a futex is an atomic compare-and-block o= per=E2=80=90 >> ation. >=20 > Maybe -- should we just say that it refers to the mathematical notion= of > a total order (or, technically, a strict total order in this case)? I added a sentence along those lines. > Though I would hope that everyone using futexes is roughly aware of t= he > differences between partial and total orders. >> FUTEX_TRYLOCK_PI (since Linux 2.6.18) >> This operation tries to acquire the futex at uaddr. I= t is >=20 > s/futex/lock/ to make it consistent with FUTEX_LOCK. Done. >> invoked when a user-space atomic acquire did not suc= ceed >> because the futex word was not 0. >> >> >> FIXME(Next sentence) The wording "The trylock in kernel" below=20 >> needs clarification. Suggestions? >> >> The trylock in kernel might succeed because the futex = word >> contains stale state (FUTEX_WAITERS an= d/or >> FUTEX_OWNER_DIED). This can happen when the owner of= the >> futex died. User space cannot handle this condition i= n a >> race-free manner, but the kernel can fix this up= and >> acquire the futex. >> >> The uaddr2, val, timeout, and val3 arguments are ignor= ed. >=20 > What about "The acquisition of the lock might suceed if performed by = the > kernel in cases when the futex word contains stale state...". Sounds good to me. Changed. >> FUTEX_WAIT_REQUEUE_PI (since Linux 2.6.31) >> Wait on a non-PI futex at uaddr and potentiall= y be >> requeued (via a FUTEX_CMP_REQUEUE_PI operation in ano= ther >> task) onto a PI futex at uaddr2. The wait operatio= n on >> uaddr is the same as for FUTEX_WAIT. >> >> The waiter can be removed from the wait on uaddr wit= hout >> requeueing on uaddr2 via a FUTEX_WAKE operation in ano= ther >> task. In this case, the FUTEX_WAIT_REQUEUE_PI opera= tion >> returns with the error EWOULDBLOCK. >=20 > This should be EAGAIN, I suppose, or the enumeration of errors should > include EWOULDBLOCK. Changed. BTW, under ERRORS there is already this text: Note: on Linux, the symbolic names EAGAIN and EWOULDBLOC= K (both of which appear in different parts of the kerne= l futex code) have the same value. Thanks for the comments, Torvald! Cheers, Michael --=20 Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org More majordomo info at http://vger.kernel.org/majordomo-info.html