1# Thread
2
3## NAME
4
5thread - runnable / computation entity
6
7## SYNOPSIS
8
9TODO
10
11## DESCRIPTION
12
13The thread object is the construct that represents a time-shared CPU execution
14context. Thread objects live associated to a particular
15[Process Object](process.md) which provides the memory and the handles to other
16objects necessary for I/O and computation.
17
18### Lifetime
19Threads are created by calling `zx_thread_create()`, but only start executing
20when either `zx_thread_start()` or `zx_process_start()` are called. Both syscalls
21take as an argument the entrypoint of the initial routine to execute.
22
23The thread passed to `zx_process_start()` should be the first thread to start execution
24on a process.
25
26A thread terminates execution:
27+ by calling `zx_thread_exit()`
28+ by calling `zx_vmar_unmap_handle_close_thread_exit()`
29+ by calling `zx_futex_wake_handle_close_thread_exit()`
30+ when the parent process terminates
31+ by calling `zx_task_kill()` with the thread's handle
32+ after generating an exception for which there is no handler or the handler
33decides to terminate the thread.
34
35Returning from the entrypoint routine does not terminate execution. The last
36action of the entrypoint should be to call `zx_thread_exit()` or one of the
37above mentioned `_exit()` variants.
38
39Closing the last handle to a thread does not terminate execution. In order to
40forcefully kill a thread for which there is no available handle, use
41`zx_object_get_child()` to obtain a handle to the thread. This method is strongly
42discouraged. Killing a thread that is executing might leave the process in a
43corrupt state.
44
45Fuchsia native threads are always *detached*. That is, there is no *join()* operation
46needed to do a clean termination. However, some runtimes above the kernel, such as
47C11 or POSIX might require threads to be joined.
48
49## SYSCALLS
50
51+ [thread_create](../syscalls/thread_create.md) - create a new thread within a process
52+ [thread_exit](../syscalls/thread_exit.md) - exit the current thread
53+ [thread_read_state](../syscalls/thread_read_state.md) - read register state from a thread
54+ [thread_start](../syscalls/thread_start.md) - cause a new thread to start executing
55+ [thread_write_state](../syscalls/thread_write_state.md) - modify register state of a thread
56
57<br>
58
59+ [task_bind_exception_port](../syscalls/task_bind_exception_port.md) - attach an exception
60port to a task
61+ [task_kill](../syscalls/task_kill.md) - cause a task to stop running
62