main/syscalls/timer_set.md

<!--
Copyright 2023 The Fuchsia Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# zx_timer_set

## Summary

Start a timer.

## Declaration

```c
#include <zircon/syscalls.h>

zx_status_t zx_timer_set(zx_handle_t handle,
                         zx_time_t deadline,
                         zx_duration_t slack);
```

## Description

`zx_timer_set()` starts a one-shot timer that will fire when
*deadline* passes. If a previous call to `zx_timer_set()` was
pending, the previous timer is canceled and
`ZX_TIMER_SIGNALED` is de-asserted as needed.

The *deadline* parameter specifies a deadline with respect to
`ZX_CLOCK_MONOTONIC`. To wait for a relative interval,
use [`zx_deadline_after()`] returned value in *deadline*.

To fire the timer immediately pass a *deadline* less than or equal to `0`.

When the timer fires it asserts `ZX_TIMER_SIGNALED`. To de-assert this
signal call [`zx_timer_cancel()`] or `zx_timer_set()` again.

The *slack* parameter specifies a range from *deadline* - *slack* to
*deadline* + *slack* during which the timer is allowed to fire. The system
uses this parameter as a hint to coalesce nearby timers.

The precise coalescing behavior is controlled by the *options* parameter
specified when the timer was created. `ZX_TIMER_SLACK_EARLY` allows only
firing in the *deadline* - *slack* interval and `ZX_TIMER_SLACK_LATE`
allows only firing in the *deadline* + *slack* interval. The default
option value of 0 is `ZX_TIMER_SLACK_CENTER` and allows both early and
late firing with an effective interval of *deadline* - *slack* to
*deadline* + *slack*

## Rights

*handle* must be of type `ZX_OBJ_TYPE_TIMER` and have `ZX_RIGHT_WRITE`.

## Return value

`zx_timer_set()` returns `ZX_OK` on success.
In the event of failure, a negative error value is returned.

## Errors

`ZX_ERR_BAD_HANDLE`  *handle* is not a valid handle.

`ZX_ERR_ACCESS_DENIED`  *handle* lacks the right `ZX_RIGHT_WRITE`.

`ZX_ERR_OUT_OF_RANGE`  *slack* is negative.

## See also

 - [`zx_deadline_after()`]
 - [`zx_timer_cancel()`]
 - [`zx_timer_create()`]

[`zx_deadline_after()`]: deadline_after.md
[`zx_timer_cancel()`]: timer_cancel.md
[`zx_timer_create()`]: timer_create.md