| # Thread |
| |
| ## NAME |
| |
| thread - runnable / computation entity |
| |
| ## SYNOPSIS |
| |
| TODO |
| |
| ## DESCRIPTION |
| |
| The thread object is the construct that represents a time-shared CPU execution |
| context. Thread objects live associated to a particular |
| [Process Object](process.md), which provides the memory and the handles to other |
| objects necessary for I/O and computation. |
| |
| ### Lifetime |
| Threads are created by calling [`zx_thread_create()`], but only start executing |
| when either [`zx_thread_start()`] or [`zx_process_start()`] are called. Both syscalls |
| take as an argument the entrypoint of the initial routine to execute. |
| |
| The thread passed to [`zx_process_start()`] should be the first thread to start execution |
| on a process. |
| |
| A thread terminates execution: |
| + by calling [`zx_thread_exit()`] |
| + by calling [`zx_vmar_unmap_handle_close_thread_exit()`] |
| + by calling [`zx_futex_wake_handle_close_thread_exit()`] |
| + when the parent process terminates |
| + by calling [`zx_task_kill()`] with the thread's handle |
| + after generating an exception for which there is no handler or the handler |
| decides to terminate the thread. |
| |
| Returning from the entrypoint routine does not terminate execution. The last |
| action of the entrypoint should be to call [`zx_thread_exit()`] or one of the |
| above mentioned `_exit()` variants. |
| |
| Closing the last handle to a thread does not terminate execution. In order to |
| forcefully kill a thread for which there is no available handle, use |
| [`zx_object_get_child()`] to obtain a handle to the thread. This method is strongly |
| discouraged. Killing a thread that is executing might leave the process in a |
| corrupt state. |
| |
| Fuchsia native threads are always *detached*. That is, there is no *join()* operation |
| needed to do a clean termination. However, some runtimes above the kernel, such as |
| C11 or POSIX might require threads to be joined. |
| |
| ### Signals |
| Threads provide the following signals: |
| + `ZX_THREAD_TERMINATED` |
| + `ZX_THREAD_SUSPENDED` |
| + `ZX_THREAD_RUNNING` |
| |
| When a thread is started `ZX_THREAD_RUNNING` is asserted. When it is suspended |
| `ZX_THREAD_RUNNING` is deasserted, and `ZX_THREAD_SUSPENDED` is asserted. When |
| the thread is resumed `ZX_THREAD_SUSPENDED` is deasserted and |
| `ZX_THREAD_RUNNING` is asserted. When a thread terminates both |
| `ZX_THREAD_RUNNING` and `ZX_THREAD_SUSPENDED` are deasserted and |
| `ZX_THREAD_TERMINATED` is asserted. |
| |
| Note that signals are OR'd into the state maintained by the |
| [`zx_object_wait_*()`](/reference/syscalls/object_wait_one.md) family of functions thus |
| you may see any combination of requested signals when they return. |
| |
| ## SYSCALLS |
| |
| - [`zx_thread_create()`] - create a new thread within a process |
| - [`zx_thread_exit()`] - exit the current thread |
| - [`zx_thread_read_state()`] - read register state from a thread |
| - [`zx_thread_start()`] - cause a new thread to start executing |
| - [`zx_thread_write_state()`] - modify register state of a thread |
| |
| <br> |
| |
| - [`zx_task_create_exception_channel()`] - listen for task exceptions |
| - [`zx_task_kill()`] - cause a task to stop running |
| |
| [`zx_futex_wake_handle_close_thread_exit()`]: /reference/syscalls/futex_wake_handle_close_thread_exit.md |
| [`zx_object_get_child()`]: /reference/syscalls/object_get_child.md |
| [`zx_process_start()`]: /reference/syscalls/process_start.md |
| [`zx_task_create_exception_channel()`]: /reference/syscalls/task_create_exception_channel.md |
| [`zx_task_kill()`]: /reference/syscalls/task_kill.md |
| [`zx_thread_create()`]: /reference/syscalls/thread_create.md |
| [`zx_thread_exit()`]: /reference/syscalls/thread_exit.md |
| [`zx_thread_read_state()`]: /reference/syscalls/thread_read_state.md |
| [`zx_thread_write_state()`]: /reference/syscalls/thread_write_state.md |
| [`zx_thread_start()`]: /reference/syscalls/thread_start.md |
| [`zx_vmar_unmap_handle_close_thread_exit()`]: /reference/syscalls/vmar_unmap_handle_close_thread_exit.md |