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