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