1# zx_futex_wait
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7futex_wait - Wait on a futex.
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_wait(const zx_futex_t* value_ptr,
17                          zx_futex_t current_value,
18                          zx_handle_t new_futex_owner,
19                          zx_time_t deadline);
20```
21
22## DESCRIPTION
23
24`zx_futex_wait()` atomically verifies that *value_ptr* still contains the value
25*current_value* and sleeps until the futex is made available by a call to
26`zx_futex_wake`. Optionally, the thread can also be woken up after the
27*deadline* (with respect to **ZX_CLOCK_MONOTONIC**) passes.
28
29## SPURIOUS WAKEUPS
30
31A component that uses futexes should be prepared to handle spurious
32wakeups.  A spurious wakeup is a situation where `zx_futex_wait()`
33returns successfully even though the component did not wake the waiter
34by calling [`zx_futex_wake()`].
35
36Zircon's implementation of futexes currently does not generate
37spurious wakeups itself.  However, commonly-used algorithms that use
38futexes can sometimes generate spurious wakeups.  For example, the
39usual implementation of `mutex_unlock` can potentially produce a
40[`zx_futex_wake()`] call on a memory location after the location has been
41freed and reused for unrelated purposes.
42
43## OWNERSHIP
44
45A successful call to `zx_futex_wait()` results in the owner of the futex being
46set to the thread referenced by the *new_futex_owner* handle, or to nothing if
47*new_futex_owner* is **ZX_HANDLE_INVALID**.
48
49See *Ownership and Priority Inheritance* in [futex](../objects/futex.md) for
50details.
51
52## RIGHTS
53
54<!-- Updated by update-docs-from-abigen, do not edit. -->
55
56None.
57
58## RETURN VALUE
59
60`zx_futex_wait()` returns **ZX_OK** on success.
61
62## ERRORS
63
64**ZX_ERR_INVALID_ARGS**  One of the following is true:
65+ *value_ptr* is not a valid userspace pointer
66+ *value_ptr* is not aligned to a `sizeof(zx_futex_t)` boundary.
67+ *new_futex_owner* is currently a member of the waiters for *value_ptr*.
68
69**ZX_ERR_BAD_HANDLE**  *new_futex_owner* is not **ZX_HANDLE_INVALID**, and not a valid handle.
70**ZX_ERR_WRONG_TYPE**  *new_futex_owner* is a valid handle, but is not a handle to a thread.
71**ZX_ERR_BAD_STATE**  *current_value* does not match the value at *value_ptr*.
72**ZX_ERR_TIMED_OUT**  The thread was not woken before *deadline* passed.
73
74## SEE ALSO
75
76 - [futex objects](../objects/futex.md)
77 - [`zx_futex_requeue()`]
78 - [`zx_futex_wake()`]
79
80<!-- References updated by update-docs-from-abigen, do not edit. -->
81
82[`zx_futex_requeue()`]: futex_requeue.md
83[`zx_futex_wake()`]: futex_wake.md
84