futex_wake_handle_close_thread_exit - write to futex, wake futex, close handle, exit
#include <magenta/syscalls.h> _Noreturn void mx_futex_wake_handle_close_thread_exit( mx_futex_t* value_ptr, uint32_t wake_count, int new_value, mx_handle_t close_handle);
futex_wake_handle_close_thread_exit() does a sequence of four operations:
atomic_store_explicit(value_ptr, new_value, memory_order_release);
The expectation is that as soon as the first operation completes, other threads may unmap or reuse the memory containing the calling thread's own stack. This is valid for this call, though it would be invalid for plain mx_futex_wake() or any other call.
If any of the operations fail, then the thread takes a trap (as if by
futex_wake_handle_close_thread_exit() does not return.
The intended use for this is for a dying thread to alert another thread waiting for its completion, close its own thread handle, and exit. The thread handle cannot be closed beforehand because closing the last handle to a thread kills that thread. The write to
value_ptr can‘t be done before this call because any time after the write, a joining thread might reuse or deallocate this thread’s stack, which may cause issues with calling conventions into this function.
This call is used for joinable threads, while vmar_unmap_handle_close_thread_exit() is used for detached threads.