1# zx_futex_requeue 2 3## NAME 4 5futex_requeue - Wake some number of threads waiting on a futex, and 6move more waiters to another wait queue. 7 8## SYNOPSIS 9 10``` 11#include <zircon/syscalls.h> 12 13zx_status_t zx_futex_requeue(const zx_futex_t* value_ptr, uint32_t wake_count, 14 int current_value, const zx_futex_t* requeue_ptr, 15 uint32_t requeue_count); 16``` 17 18## DESCRIPTION 19 20Requeuing is a generalization of waking. First, the kernel verifies 21that the value in `current_value` matches the value of the futex at 22`value_ptr`, and if not reports *ZX_ERR_BAD_STATE*. After waking `wake_count` 23threads, `requeue_count` threads are moved from the original futex's 24wait queue to the wait queue corresponding to `requeue_ptr`, another 25futex. 26 27This requeueing behavior may be used to avoid thundering herds on wake. 28 29## RIGHTS 30 31TODO(ZX-2399) 32 33## RETURN VALUE 34 35**futex_requeue**() returns **ZX_OK** on success. 36 37## ERRORS 38 39**ZX_ERR_INVALID_ARGS** *value_ptr* isn't a valid userspace pointer, or 40*value_ptr* is the same futex as *requeue_ptr*, or 41*value_ptr* or *requeue_ptr* is not aligned, or 42*requeue_ptr* is NULL but *requeue_count* is positive. 43 44**ZX_ERR_BAD_STATE** *current_value* does not match the value at *value_ptr*. 45 46## SEE ALSO 47 48[futex_wait](futex_wait.md), 49[futex_wake](futex_wake.md). 50