1# zx_futex_wake_handle_close_thread_exit
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7futex_wake_handle_close_thread_exit - write to futex, wake futex, close handle, exit
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16[[noreturn]] void zx_futex_wake_handle_close_thread_exit(
17    const zx_futex_t* value_ptr,
18    uint32_t wake_count,
19    int32_t new_value,
20    zx_handle_t close_handle);
21```
22
23## DESCRIPTION
24
25`zx_futex_wake_handle_close_thread_exit()` does a sequence of four operations:
261. `atomic_store_explicit(value_ptr, new_value, memory_order_release);`
272. `zx_futex_wake(value_ptr, wake_count);`
283. `zx_handle_close(close_handle);`
294. `zx_thread_exit();`
30
31The expectation is that as soon as the first operation completes,
32other threads may unmap or reuse the memory containing the calling
33thread's own stack.  This is valid for this call, though it would be
34invalid for plain [`zx_futex_wake()`] or any other call.
35
36If any of the operations fail, then the thread takes a trap (as if by `__builtin_trap();`).
37
38## RIGHTS
39
40<!-- Updated by update-docs-from-abigen, do not edit. -->
41
42TODO(ZX-2399)
43
44## RETURN VALUE
45
46`zx_futex_wake_handle_close_thread_exit()` does not return.
47
48## ERRORS
49
50None.
51
52## NOTES
53
54The intended use for this is for a dying thread to alert another thread
55waiting for its completion, close its own thread handle, and exit.
56The thread handle cannot be closed beforehand because closing the last
57handle to a thread kills that thread.  The write to *value_ptr* can't be
58done before this call because any time after the write, a joining thread might
59reuse or deallocate this thread's stack, which may cause issues with calling
60conventions into this function.
61
62This call is used for joinable threads, while
63[`zx_vmar_unmap_handle_close_thread_exit()`]
64is used for detached threads.
65
66## SEE ALSO
67
68 - [futex objects](../objects/futex.md)
69 - [`zx_futex_wake()`]
70 - [`zx_handle_close()`]
71 - [`zx_thread_exit()`]
72 - [`zx_vmar_unmap_handle_close_thread_exit()`]
73
74<!-- References updated by update-docs-from-abigen, do not edit. -->
75
76[`zx_futex_wake()`]: futex_wake.md
77[`zx_handle_close()`]: handle_close.md
78[`zx_thread_exit()`]: thread_exit.md
79[`zx_vmar_unmap_handle_close_thread_exit()`]: vmar_unmap_handle_close_thread_exit.md
80