From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933824AbcI3V2Y (ORCPT ); Fri, 30 Sep 2016 17:28:24 -0400 Received: from g2t2355.austin.hpe.com ([15.233.44.28]:45262 "EHLO g2t2355.austin.hpe.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933715AbcI3V16 (ORCPT ); Fri, 30 Sep 2016 17:27:58 -0400 From: Waiman Long To: mtk.manpages@gmail.com Cc: linux-man@vger.kernel.org, linux-kernel@vger.kernel.org, Thomas Gleixner , Ingo Molnar , Peter Zijlstra , Jonathan Corbet , Davidlohr Bueso , Mike Galbraith , Jason Low , Scott J Norton , Douglas Hatch , Waiman Long Subject: [PATCH 2/2] futex.7: Add description about the FUTEX_LOCK/FUTEX_UNLOCK operations Date: Fri, 30 Sep 2016 17:27:44 -0400 Message-Id: <1475270864-51787-3-git-send-email-Waiman.Long@hpe.com> X-Mailer: git-send-email 1.7.1 In-Reply-To: <1475270864-51787-1-git-send-email-Waiman.Long@hpe.com> References: <1475270864-51787-1-git-send-email-Waiman.Long@hpe.com> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org The FUTEX_LOCK and FUTEX_UNLOCK operation pair is for supporting the new throughput-optimized futexes. The futex(7) manpage is extended to include description about the operations. Signed-off-by: Waiman Long --- man7/futex.7 | 22 ++++++++++++++++++++++ 1 files changed, 22 insertions(+), 0 deletions(-) diff --git a/man7/futex.7 b/man7/futex.7 index 8312c6b..6adf3a2 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -78,6 +78,22 @@ This is done using the .B FUTEX_WAIT operation. .PP +For implementing just userspace mutexes, a faster +.B FUTEX_LOCK +and +.B FUTEX_UNLOCK +operation pair can be used instead for SMP systems that support atomic +compare and exchange instruction. +To acquire a mutex, atomically compare and exchange the futex from 0 to +the task's thread ID as returned by the +.BR gettid (2) +system call. If that fails, call into kernel using the +.B FUTEX_LOCK +operation. To release a mutex, atomically compare and exchange the futex +from the thread ID to 0. If that fails, call into kernel using the +.B FUTEX_UNLOCK +operation. +.PP The .BR futex (2) system call can optionally be passed a timeout specifying how long @@ -94,6 +110,11 @@ The same holds for asynchronous futex waiting. Initial futex support was merged in Linux 2.5.7 but with different semantics from those described above. Current semantics are available from Linux 2.5.40 onward. +The +.B FUTEX_LOCK +and +.B FUTEX_UNLOCK +operation pair support was merged in Linux 4.X. .SH NOTES .PP To reiterate, bare futexes are not intended as an easy-to-use @@ -116,6 +137,7 @@ primitives; it is by no means the only one. .BR clone (2), .BR futex (2), .BR get_robust_list (2), +.BR gettid (2), .BR set_robust_list (2), .BR set_tid_address (2), .BR pthreads (7) -- 1.7.1 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Waiman Long Subject: [PATCH 2/2] futex.7: Add description about the FUTEX_LOCK/FUTEX_UNLOCK operations Date: Fri, 30 Sep 2016 17:27:44 -0400 Message-ID: <1475270864-51787-3-git-send-email-Waiman.Long@hpe.com> References: <1475270864-51787-1-git-send-email-Waiman.Long@hpe.com> Return-path: In-Reply-To: <1475270864-51787-1-git-send-email-Waiman.Long-ZPxbGqLxI0U@public.gmane.org> Sender: linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org To: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org Cc: linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, Thomas Gleixner , Ingo Molnar , Peter Zijlstra , Jonathan Corbet , Davidlohr Bueso , Mike Galbraith , Jason Low , Scott J Norton , Douglas Hatch , Waiman Long List-Id: linux-man@vger.kernel.org The FUTEX_LOCK and FUTEX_UNLOCK operation pair is for supporting the new throughput-optimized futexes. The futex(7) manpage is extended to include description about the operations. Signed-off-by: Waiman Long --- man7/futex.7 | 22 ++++++++++++++++++++++ 1 files changed, 22 insertions(+), 0 deletions(-) diff --git a/man7/futex.7 b/man7/futex.7 index 8312c6b..6adf3a2 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -78,6 +78,22 @@ This is done using the .B FUTEX_WAIT operation. .PP +For implementing just userspace mutexes, a faster +.B FUTEX_LOCK +and +.B FUTEX_UNLOCK +operation pair can be used instead for SMP systems that support atomic +compare and exchange instruction. +To acquire a mutex, atomically compare and exchange the futex from 0 to +the task's thread ID as returned by the +.BR gettid (2) +system call. If that fails, call into kernel using the +.B FUTEX_LOCK +operation. To release a mutex, atomically compare and exchange the futex +from the thread ID to 0. If that fails, call into kernel using the +.B FUTEX_UNLOCK +operation. +.PP The .BR futex (2) system call can optionally be passed a timeout specifying how long @@ -94,6 +110,11 @@ The same holds for asynchronous futex waiting. Initial futex support was merged in Linux 2.5.7 but with different semantics from those described above. Current semantics are available from Linux 2.5.40 onward. +The +.B FUTEX_LOCK +and +.B FUTEX_UNLOCK +operation pair support was merged in Linux 4.X. .SH NOTES .PP To reiterate, bare futexes are not intended as an easy-to-use @@ -116,6 +137,7 @@ primitives; it is by no means the only one. .BR clone (2), .BR futex (2), .BR get_robust_list (2), +.BR gettid (2), .BR set_robust_list (2), .BR set_tid_address (2), .BR pthreads (7) -- 1.7.1 -- 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