1# zx_futex_requeue
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7futex_requeue - Wake some number of threads waiting on a futex, and move more waiters to another wait queue.
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_futex_requeue(const zx_futex_t* value_ptr,
17                             uint32_t wake_count,
18                             zx_futex_t current_value,
19                             const zx_futex_t* requeue_ptr,
20                             uint32_t requeue_count,
21                             zx_handle_t new_requeue_owner);
22```
23
24## DESCRIPTION
25
26Requeuing is a generalization of waking. First, the kernel verifies
27that the value in *current_value* matches the value of the futex at
28*value_ptr*, and if not reports **ZX_ERR_BAD_STATE**. After waking *wake_count*
29threads, *requeue_count* threads are moved from the original futex's
30wait queue to the wait queue corresponding to *requeue_ptr*, another
31futex.
32
33This requeueing behavior may be used to avoid thundering herds on wake.
34
35## OWNERSHIP
36
37A requeue operation targets two futexes, the _wake futex_ and the _requeue
38futex_.  The ownership implications for each are discussed separately.
39Generally, if the call fails for any reason, no changes to ownership for either
40futex are made.
41
42See *Ownership and Priority Inheritance* in [futex](../objects/futex.md) for
43details.
44
45### Effects on the _wake futex_ target
46
47A successful call to `zx_futex_requeue()` results in the owner of the futex being
48set to nothing, regardless of the wake count.  In order to transfer ownership of
49a futex, use the [`zx_futex_requeue_single_owner()`] variant instead.
50[`zx_futex_requeue_single_owner()`] will attempt to wake exactly one thread from the
51futex wait queue.  If there is at least one thread to wake, the owner of the futex will be
52set to the thread which was woken.  Otherwise, the futex
53will have no owner.
54
55### Effects on the _requeue futex_ target
56
57A successful call to `zx_futex_requeue()` or [`zx_futex_requeue_single_owner()`]
58results in the owner of the futex being set to the thread referenced by the
59*new_requeue_owner* handle, or to nothing if *new_requeue_owner* is
60**ZX_HANDLE_INVALID**.
61
62## RIGHTS
63
64<!-- Updated by update-docs-from-abigen, do not edit. -->
65
66None.
67
68## RETURN VALUE
69
70`zx_futex_requeue()` returns **ZX_OK** on success.
71
72## ERRORS
73
74**ZX_ERR_INVALID_ARGS**  One of the following is true:
75+ Either *value_ptr* or *requeue_ptr* is not a valid userspace pointer
76+ Either *value_ptr* or *requeue_ptr* is not aligned to a `sizeof(zx_futex_t)` boundary.
77+ *value_ptr* is the same futex as *requeue_ptr*
78+ *new_requeue_owner* is currently a member of the waiters for either *value_ptr* or *requeue_ptr*
79
80**ZX_ERR_BAD_HANDLE**  *new_requeue_owner* is not **ZX_HANDLE_INVALID**, and not a valid handle.
81**ZX_ERR_WRONG_TYPE**  *new_requeue_owner* is a valid handle, but is not a handle to a thread.
82**ZX_ERR_BAD_STATE**  *current_value* does not match the value at *value_ptr*.
83
84## SEE ALSO
85
86 - [futex objects](../objects/futex.md)
87 - [`zx_futex_requeue_single_owner()`]
88 - [`zx_futex_wait()`]
89 - [`zx_futex_wake()`]
90
91<!-- References updated by update-docs-from-abigen, do not edit. -->
92
93[`zx_futex_requeue_single_owner()`]: futex_requeue_single_owner.md
94[`zx_futex_wait()`]: futex_wait.md
95[`zx_futex_wake()`]: futex_wake.md
96