1# zx_task_suspend
2
3This function replaces [task_suspend](task_suspend.md). When all callers are
4updated, **task_suspend** will be deleted and this function will be renamed
5**task_suspend**.
6
7## NAME
8
9task_suspend_token - suspend the given task. Currently only thread handles may
10be suspended.
11
12## SYNOPSIS
13
14```
15#include <zircon/syscalls.h>
16
17void zx_task_suspend_token(zx_handle_t task, zx_handle_t* suspend_token);
18
19```
20
21## DESCRIPTION
22
23**task_suspend_token**() causes the requested task to suspend execution. Task
24suspension is not synchronous and the task might not be suspended before the
25call returns. The task will be suspended soon after **task_suspend_token**() is
26invoked, unless it is currently blocked in the kernel, in which case it will
27suspend after being unblocked.
28
29Invoking **task_kill**() on a task that is suspended will successfully kill
30the task.
31
32## RESUMING
33
34The allow the task to resume, close the suspend token handle. The task will
35remain suspended as long as there are any open suspend tokens. Like suspending,
36resuming is asynchronous so the thread may not be in a running state when the
37[handle_close](handle_close.md) call returns, even if no other suspend tokens
38are open.
39
40## RIGHTS
41
42TODO(ZX-2399)
43
44## RETURN VALUE
45
46**task_suspend**() returns **ZX_OK** on success.
47In the event of failure, a negative error value is returned.
48
49## ERRORS
50
51**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
52
53**ZX_ERR_WRONG_TYPE** *handle* is not a thread handle.
54
55**ZX_ERR_INVALID_ARGS**  *suspend_token*  was an invalid pointer.
56
57**ZX_ERR_BAD_STATE**  The task is not in a state where suspending is possible.
58
59## LIMITATIONS
60
61Currently only thread handles are supported.
62