1# zx_timer_set
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7timer_set - start a timer
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_timer_set(zx_handle_t handle,
17                         zx_time_t deadline,
18                         zx_duration_t slack);
19```
20
21## DESCRIPTION
22
23`zx_timer_set()` starts a one-shot timer that will fire when
24*deadline* passes. If a previous call to `zx_timer_set()` was
25pending, the previous timer is canceled and
26**ZX_TIMER_SIGNALED** is de-asserted as needed.
27
28The *deadline* parameter specifies a deadline with respect to
29**ZX_CLOCK_MONOTONIC**. To wait for a relative interval,
30use [`zx_deadline_after()`] returned value in *deadline*.
31
32To fire the timer immediately pass a *deadline* less than or equal to **0**.
33
34When the timer fires it asserts **ZX_TIMER_SIGNALED**. To de-assert this
35signal call [`zx_timer_cancel()`] or `zx_timer_set()` again.
36
37The *slack* parameter specifies a range from *deadline* - *slack* to
38*deadline* + *slack* during which the timer is allowed to fire. The system
39uses this parameter as a hint to coalesce nearby timers.
40
41The precise coalescing behavior is controlled by the *options* parameter
42specified when the timer was created. **ZX_TIMER_SLACK_EARLY** allows only
43firing in the *deadline* - *slack* interval and **ZX_TIMER_SLACK_LATE**
44allows only firing in the *deadline* + *slack* interval. The default
45option value of 0 is **ZX_TIMER_SLACK_CENTER** and allows both early and
46late firing with an effective interval of *deadline* - *slack* to
47*deadline* + *slack*
48
49## RIGHTS
50
51<!-- Updated by update-docs-from-abigen, do not edit. -->
52
53*handle* must be of type **ZX_OBJ_TYPE_TIMER** and have **ZX_RIGHT_WRITE**.
54
55## RETURN VALUE
56
57`zx_timer_set()` returns **ZX_OK** on success.
58In the event of failure, a negative error value is returned.
59
60
61## ERRORS
62
63**ZX_ERR_BAD_HANDLE**  *handle* is not a valid handle.
64
65**ZX_ERR_ACCESS_DENIED**  *handle* lacks the right **ZX_RIGHT_WRITE**.
66
67**ZX_ERR_OUT_OF_RANGE**  *slack* is negative.
68
69## SEE ALSO
70
71 - [`zx_deadline_after()`]
72 - [`zx_timer_cancel()`]
73 - [`zx_timer_create()`]
74
75<!-- References updated by update-docs-from-abigen, do not edit. -->
76
77[`zx_deadline_after()`]: deadline_after.md
78[`zx_timer_cancel()`]: timer_cancel.md
79[`zx_timer_create()`]: timer_create.md
80