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