From 74f58a643b3c6e5498a4bbb4334aeb0fe14642e2 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Tue, 3 Mar 2015 07:16:45 +0100 Subject: [PATCH] futex.2: Explicitly mark FIXMEs added by Torvald Riegel Mainly so I can keep track of who said what should be fixed/checked Signed-off-by: Michael Kerrisk --- man2/futex.2 | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/man2/futex.2 b/man2/futex.2 index ea1a4f56e..d8eb82344 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -253,7 +253,8 @@ and .I val3 are ignored. -.\" XXX I think we should remove this. Or maybe adapt to a different example. +.\" FIXME(Torvald) I think we should remove this. Or maybe adapt to a +.\" different example. .\" For .\" .BR futex (7), .\" this call is executed if decrementing the count gave a negative value @@ -270,8 +271,8 @@ are ignored. .\" Strictly speaking, since Linux 2.5.x This operation wakes at most .I val -.\" XXX I believe FUTEX_WAIT_BITSET waiters, for example, could also be woken -.\" (therefore, make it e.g. instead of i.e.)? +.\" FIXME(Torvald) I believe FUTEX_WAIT_BITSET waiters, for example, +.\" could also be woken (therefore, make it e.g. instead of i.e.)? of the waiters that are waiting (e.g., inside .BR FUTEX_WAIT ) on the futex word at the address @@ -293,7 +294,8 @@ and .I val3 are ignored. -.\" XXX I think we should remove this. Or maybe adapt to a different example. +.\" FIXME(Torvald) I think we should remove this. Or maybe adapt to +.\" a different example. .\" For .\" .BR futex (7), .\" this is executed if incrementing the count showed that there were waiters, @@ -330,7 +332,7 @@ and .I val3 are ignored. -.\" FIXME We never define "upped". Maybe just remove that sentence? +.\" FIXME(Torvald) We never define "upped". Maybe just remove that sentence? To prevent race conditions, the caller should test if the futex has been upped after .B FUTEX_FD @@ -347,9 +349,9 @@ from Linux 2.6.26 onward. .TP .BR FUTEX_REQUEUE " (since Linux 2.6.0)" .\" Strictly speaking: from Linux 2.5.70 -.\" FIXME Is there some indication that it is broken in general, or is this -.\" comment implicitly speaking about the condvar (?) use case? If the latter -.\" we might want to weaken the advice a little. +.\" FIXME(Torvald) Is there some indication that it is broken in general, +.\" or is this comment implicitly speaking about the condvar (?) use case? +.\" If the latter we might want to weaken the advice a little. .IR "Avoid using this operation" . It is broken for its intended purpose. Use @@ -391,8 +393,8 @@ argument specifies an upper limit on the number of waiters that are requeued to the futex at .IR uaddr2 . -.\" FIXME Is this correct? Or is just the decision which threads to wake or -.\" requeue part of the atomic operation? +.\" FIXME(Torvald) Is this correct? Or is just the decision which +.\" threads to wake or requeue part of the atomic operation? The load from .I uaddr is an atomic memory access (i.e., using atomic machine instructions of the @@ -443,8 +445,8 @@ operation equivalent to .\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721 .\" Author: Jakub Jelinek .\" Date: Tue Sep 6 15:16:25 2005 -0700 -.\" FIXME The glibc condvar implementation is currently being revised (e.g., -.\" to not use an internal lock anymore). +.\" FIXME(Torvald) The glibc condvar implementation is currently being revised +.\" (e.g., to not use an internal lock anymore). .\" It is probably more future-proof to remove this paragraph. This operation was added to support some user-space use cases where more than one futex must be handled at the same time. @@ -892,8 +894,8 @@ This operation tries to acquire the futex at .\" the difference(s) between FUTEX_LOCK_PI and FUTEX_TRYLOCK_PI. .\" Can someone propose something? .\" -.\" FIXME Additionally, we claim above that just FUTEX_WAITERS is never an -.\" allowed state. +.\" FIXME(Torvald) Additionally, we claim above that just FUTEX_WAITERS +.\" is never an allowed state. It deals with the situation where the TID value at .I uaddr is 0, but the @@ -1469,9 +1471,9 @@ This system call is Linux-specific. .SH NOTES Glibc does not provide a wrapper for this system call; call it using .BR syscall (2). -.\" TODO FIXME Above, we cite this section and claim it contains details on -.\" the synchronization semantics; add the C11 equivalents here (or whatever -.\" we find consensus for). +.\" TODO FIXME(Torvald) Above, we cite this section and claim it contains +.\" details on the synchronization semantics; add the C11 equivalents +.\" here (or whatever we find consensus for). .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .\" @@ -1705,7 +1707,6 @@ Futex example library, futex-*.tar.bz2 at .\" .\" FIXME Are there any other resources that should be listed .\" in the SEE ALSO section? -.\" FIXME We should probably refer to the glibc code here, in particular the -.\" glibc-internal futex wrapper functions that are WIP, and the -.\" generic pthread_mutex_t and perhaps condvar implementations. - +.\" FIXME(Torvald) We should probably refer to the glibc code here, in +.\" particular the glibc-internal futex wrapper functions that are WIP, +.\" and the generic pthread_mutex_t and perhaps condvar implementations.