[PATCH 0/2] futex: extend the futex(2) and futex(7) manpages for TP futexes

[PATCH 0/2] futex: extend the futex(2) and futex(7) manpages for TP futexes

[Waiman Long]

This patchset includes changes to the futex(2) and futex(7) manpages
to add descriptions for the new throughput-optimized (TP) futexes
that can be used to implement userspace mutexes.

This patchset includes a place holder (4.X) for the exact version that
the new TP futexes code is merged. That will be changed later on when 
it is known.

Waiman Long (2):
  futex.2: Add description about the FUTEX_LOCK/FUTEX_UNLOCK operations
  futex.7: Add description about the FUTEX_LOCK/FUTEX_UNLOCK operations

 man2/futex.2 |   49 +++++++++++++++++++++++++++++++++++++++++++++++++
 man7/futex.7 |   22 ++++++++++++++++++++++
 2 files changed, 71 insertions(+), 0 deletions(-)

--
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

[PATCH 1/2] futex.2: Add description about the FUTEX_LOCK/FUTEX_UNLOCK operations

[Waiman Long]

The FUTEX_LOCK and FUTEX_UNLOCK operation pair is for supporting the
new throughput-optimized futexes. The futex(2) manpage is extended
to include description about the operations.

Signed-off-by: Waiman Long <Waiman.Long-ZPxbGqLxI0U@public.gmane.org>
---
 man2/futex.2 |   49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 49 insertions(+), 0 deletions(-)

diff --git a/man2/futex.2 b/man2/futex.2
index 5b0083e..6cf67cc 100644
--- a/man2/futex.2
+++ b/man2/futex.2
@@ -816,6 +816,55 @@ arguments are ignored.
 .\"
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .\"
+.TP
+.BR FUTEX_LOCK " (since Linux 4.X)"
+This operation is used for the locking part of contended userspace mutexes.
+The waiter will attempt to steal the lock once at the beginning of the system
+call. If it can't get the lock, it will be put into the waiting queue of
+a seralization kernel mutex. Once it becomes the owner of the mutex,
+it will spin on the futex owner while it is running until the owner releases
+the futex. The spinning is done without sleeping as long as the futex owner
+is running and the waiter hasn't run out its scheduling time slice.
+The same is true for those waiting within the serialization mutex.
+As a result, the unlock-to-lock latency is reduced leading to faster
+performance.
+
+As long as the serialization mutex owner is running, it won't cause
+the futex owner to release the futex by using the
+.BR FUTEX_UNLOCK
+operation. So more lock stealings can go on in userspace leading to
+better performance. When the mutex owner is sleeping, the futex owner will
+have to call into the kernel to wake up the mutex owner and release the futex.
+
+One consequence of this design is lock starvation as the kernel waiter has
+no guarantee that it will ever get the lock. This is counteracted by a
+lock hand-off mechanism where the futex owner is forced to call into
+the kernel to explicitly transfer the lock ownership to the mutex owner
+when the latter has waited too long without getting the futex.
+
+The
+.IR val ,
+.I uaddr2
+and
+.I val3
+arguments are ignored.
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
+.TP
+.BR FUTEX_UNLOCK " (since Linux 4.X)"
+This operation is used for the unlocking part of contended userspace mutexes.
+This call is only needed when the serialization mutex owner is sleeping
+or lock hand-off is activated. In this case, the sleeping waiter is woken
+up and the futex is either released or its ownership transferred to the
+mutex owner.
+
+All the arugments except
+.I uaddr
+are ignored.
+.\"
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.\"
 .SS Priority-inheritance futexes
 Linux supports priority-inheritance (PI) futexes in order to handle
 priority-inversion problems that can be encountered with
-- 
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

[PATCH 2/2] futex.7: Add description about the FUTEX_LOCK/FUTEX_UNLOCK operations

[Waiman Long]

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 <Waiman.Long-ZPxbGqLxI0U@public.gmane.org>
---
 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