HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
FUTEX_CMP_REQUEUE(2const)FUTEX_CMP_REQUEUE(2const)FUTEX_CMP_REQUEUE - compare a futex, wake some waiters, and requeue others
Standard C library (libc,-lc)
#include <linux/futex.h>/* Definition ofFUTEX_*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>long syscall(SYS_futex, uint32_t *uaddr, FUTEX_CMP_REQUEUE,uint32_tval, uint32_tval2, uint32_t *uaddr2,uint32_tval3);
This operation first checks whether the locationuaddr still contains the valueval3. If not, the operation fails with the errorEAGAIN. Otherwise, the operation wakes up a maximum ofval waiters that are waiting on the futex atuaddr. If there are more thanval waiters, then the remaining waiters are removed from the wait queue of the source futex atuaddr and added to the wait queue of the target futex atuaddr2. Theval2 argument specifies an upper limit on the number of waiters that are requeued to the futex atuaddr2. The load fromuaddr is an atomic memory access (i.e., using atomic machine instructions of the respective architecture). This load, the comparison withval3, and the requeueing of any waiters are performed atomically and totally ordered with respect to other operations on the same futex word. Typical values to specify forval are 0 or 1. (Specifyingval asINT_MAXis not useful, because it would make theFUTEX_CMP_REQUEUE operation equivalent toFUTEX_WAKE(2const).) The limit value specified viaval2 is typically either 1 orINT_MAX. (Specifyingval2 as 0 is not useful, because it would make theFUTEX_CMP_REQUEUEoperation equivalent toFUTEX_WAKE(2const).) TheFUTEX_CMP_REQUEUEoperation was added as a replacement for the earlierFUTEX_REQUEUE(2const). The difference is that the check of the value atuaddr can be used to ensure that requeueing happens only under certain conditions, which allows race conditions to be avoided in certain use cases. BothFUTEX_REQUEUE(2const) andFUTEX_CMP_REQUEUEcan be used to avoid "thundering herd" wake-ups that could occur when usingFUTEX_WAKE(2const) in cases where all of the waiters that are woken need to acquire another futex. Consider the following scenario, where multiple waiter threads are waiting on B, a wait queue implemented using a futex: lock(A) while (!check_value(V)) { unlock(A); block_on(B); lock(A); }; unlock(A); If a waker thread usedFUTEX_WAKE(2const), then all waiters waiting on B would be woken up, and they would all try to acquire lock A. However, waking all of the threads in this manner would be pointless because all except one of the threads would immediately block on lock A again. By contrast, a requeue operation wakes just one waiter and moves the other waiters to lock A, and when the woken waiter unlocks A then the next waiter can proceed.On error, -1 is returned, anderrno is set to indicate the error. On success,FUTEX_CMP_REQUEUEreturns the total number of waiters that were woken up or requeued to the futex for the futex word atuaddr2. If this value is greater thanval, then the difference is the number of waiters requeued to the futex for the futex word atuaddr2.
Seefutex(2).EAGAINThe value pointed to byuaddr is not equal to the expected valueval3.EFAULTuaddr2 did not point to a valid user-space address.EINVALuaddr2 does not point to a valid object—that is, the address is not four-byte-aligned.EINVALThe kernel detected an inconsistency between the user-space state atuaddr and the kernel state—that is, it detected a waiter which waits inFUTEX_LOCK_PI(2const) orFUTEX_LOCK_PI2(2const) onuaddr.
Linux.
Linux 2.6.7.
futex(2)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-30FUTEX_CMP_REQUEUE(2const)Pages that refer to this page:futex(2), FUTEX_CMP_REQUEUE_PI(2const), FUTEX_REQUEUE(2const)
Copyright and license for this manual page
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |