[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@xxxxxxx>
---
 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