fuchsia.time.alarms

APIs for handling wake alarms.

Wake alarms are alarms that can also wake the system in case it is in a low power state. They are used to ensure that a task is performed regardless if a suspend intervenes.

Scheduled alarms do not persist across reboots.

Summary

[WakeAlarms]: Provides scheduling platform-wide wake alarms. These alarms can wake a suspended system if needed. The ability to wake the system must be supported by the platform to obtain the wake behavior.

Added: NEXT

PROTOCOLS

WakeAlarms

Defined in fuchsia.time.alarms/wake_alarms.fidl

[WakeAlarms] provides setting up platform-wide wake alarms.

An alarm is a promise made by the system to the caller of the API to notify the caller that AT LEAST a certain amount of time has expired. The alarm may fire later than the requested amount of time at the discretion of the server implementing this API.

When this notification happens, we say that the wake alarm has "fired".

A "wake" alarm firing also ensures that the system comes back from a reduced power state if needed, so that it can notify the caller.

The general shape of a wake alarm API has three parts:

A specification of when a wake alarm is supposed to fire,
A way to notify the caller of an alarm that fired, and
A way to keep the system awake until both the caller and the callee have completed work associated with the alarm.

Cancel

Cancels the alarm specified by alarm_id.

Providing an alarm_id of an alarm that is not scheduled quietly succeeds.

Request

Name	Type
`alarm_id`	`AlarmId`

SetAndWait

Sets a wake alarm with the provided parameters, and waits for the alarm to fire.

The caller may request multiple alarms concurrently. Re-requesting an alarm that has the same alarm_id as an already scheduled alarm causes that scheduled alarm to be canceled before the same alarm is scheduled again.

The call to SetAndWait returns when the alarm fires, or an error occurs, or the alarm is canceled.

Return value

keep_alive: a handle which prevents system suspend so long as it is held alive.

Protocol Errors

[DROPPED] if the alarm has been canceled by using [Cancel].
[UNSPECIFIED] you are observing a new failure mode which has not been assigned an error code yet. Expect this failure mode to be assigned a more specific error code in future versions of this API. This is not a bug, but an indication that you may need to update the API version.
[INTERNAL] is a bug: an internal fallible call (which is expected to be unlikely to fail) has failed somehow. Please report this for investigation.

Request

Name	Type
`deadline`	`zx/InstantBoot`
`mode`	`SetMode`
`alarm_id`	`AlarmId`

Response

Name	Type
`payload`	`WakeAlarms_SetAndWait_Result`

STRUCTS

WakeAlarms_SetAndWait_Response resource

Defined in fuchsia.time.alarms/wake_alarms.fidl

Field	Type	Description	Default
`keep_alive`	`fuchsia.power.system/LeaseToken`	Used by the caller to ensure a minimum time slice for useful work, before the system may suspend again.	No default

ENUMS

WakeAlarmsError flexible

Type: uint32

Defined in fuchsia.time.alarms/wake_alarms.fidl

WakeAlarmsError describes the error code that can be returned from wake alarm API calls.

Name Value Description

Name	Value	Description
UNSPECIFIED	`1`	Denotes new failure mode which has not been assigned an error code yet. Expect this failure mode to be assigned a more specific error code in the future versions of this API. This is not a bug, but an indication that you may need to update the API version.
DROPPED	`2`	This alarm was canceled, or rescheduled by the API user.
INTERNAL	`3`	The server end encountered an error internal to its code, which should not ever happen in normal operation. Receiving this error means that the server end of the connection has a bug that must be fixed.

UNSPECIFIED

1

Denotes new failure mode which has not been assigned an error code yet.

Expect this failure mode to be assigned a more specific error code in the future versions of this API. This is not a bug, but an indication that you may need to update the API version.

DROPPED

2

This alarm was canceled, or rescheduled by the API user.

INTERNAL

3

The server end encountered an error internal to its code, which should not ever happen in normal operation. Receiving this error means that the server end of the connection has a bug that must be fixed.

UNIONS

SetMode flexible resource

Defined in fuchsia.time.alarms/wake_alarms.fidl

Ordinal	Variant	Type	Description
1	`keep_alive`	`fuchsia.power.system/LeaseToken`	This lease is dropped as immediately after the alarm is scheduled (or an error occurs during scheduling), thus guaranteeing that the alarm is scheduled before the system is suspended.
2	`notify_setup_done`	`handle<event>`	The callee signals this event (with ZX_EVENT_SIGNALED) once the alarm is scheduled. This indicates that the caller can drop any pending wake leases related to this call.

WakeAlarms_SetAndWait_Result strict resource

Defined in fuchsia.time.alarms/wake_alarms.fidl

Ordinal	Variant	Type
1	`response`	`WakeAlarms_SetAndWait_Response`
2	`err`	`WakeAlarmsError`
3	`framework_err`	`internal`

ALIASES

Name	Value	Description
AlarmId	`string`[`128`]