APIs for scheduling tasks that are robust to suspend.

Introduction

This library provides APIs for scheduling alarms that are able to wake the system from a suspended state. Wake alarms are alarms that can also wake the system in case it is in a low power state.

Scheduled alarms do not persist across reboots.

The primary protocol in this library is fuchsia.time.alarms.WakeAlarms, which allows clients to set, cancel, and wait for wake alarms.

Concepts

• Wake Alarm: An alarm that can wake the system from a low-power state in order to fire.
• Alarm ID: A unique identifier for an alarm within a single FIDL connection.
• Deadline: The time at which the alarm is scheduled to fire, expressed as a zx.InstantBoot.
• Keep-alive: A token that prevents the system from suspending while it is held. This is used to ensure that the system remains awake while the client is processing the alarm.

Usage

To use the WakeAlarms protocol, a client must first connect to the service. Once connected, the client can use the SetAndWait method to schedule an alarm.

The SetAndWait method will return when the alarm fires. If the alarm is canceled before it fires, the method will return a DROPPED error.

To cancel an alarm, the client can use the Cancel method. This method takes an alarm ID and will cause the corresponding SetAndWait call to return with a DROPPED error.

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.
• [Notifier]: Used to notify when a wake alarm fires, when a separate API is more convenient to the end user than the hanging-get approach used in SetAndWait.

PROTOCOLS

Notifier

Defined in fuchsia.time.alarms/wake_alarms.fidl

[Notifier] is used to notify when a wake alarm fires.

A client-end channel of this protocol will be provided to the implementor of [WakeAlarms.Set].

Dropping the server-end will cancel all alarms scheduled with [WakeAlarms.Set] associated with this server instance.

Notify

Notifies when an alarm previously set by [WakeAlarms.Set] fires.

Request

Name	Type
alarm_id	AlarmId
keep_alive	fuchsia.power.system/LeaseToken

NotifyError

Notifies when an alarm previously set by [WakeAlarms.Set] is unable to fire due to an error.

Request

Name	Type
alarm_id	AlarmId
error	WakeAlarmsError

WakeAlarms

Defined in fuchsia.time.alarms/wake_alarms.fidl

Provides a mechanism for scheduling 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 the requested 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 for an alarm that is not scheduled is a no-op.

Request

Name	Type
alarm_id	AlarmId

Set

Sets a wake alarm with the provided parameters.

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.

Return value

This method will return when the alarm is scheduled.

Protocol Errors

• [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
notifier	client_end:Notifier
deadline	zx/InstantBoot
mode	SetMode
alarm_id	AlarmId

Response

Name	Type
payload	WakeAlarms_Set_Result

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 new alarm is scheduled.

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

Return value

• keep_alive: A handle that prevents the system from suspending as long as it is held.

Protocol Errors

• DROPPED: The alarm was canceled by a call to Cancel.
• UNSPECIFIED: A new failure mode has been observed that has not yet been assigned an error code. This indicates that the API version may need to be updated.
• INTERNAL is a server-side 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

WakeAlarms_Set_Response

Defined in fuchsia.time.alarms/wake_alarms.fidl

<EMPTY>

ENUMS

WakeAlarmsError flexible

Type: uint32

Defined in fuchsia.time.alarms/wake_alarms.fidl

Describes the error codes that can be returned from WakeAlarms API calls.

Name	Value	Description
UNSPECIFIED	1	A new failure mode has been observed that has not yet been assigned an error code. This indicates that the API version may need to be updated.
DROPPED	2	The 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

A mode of notification for when an alarm has been scheduled.

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	Description
1	response	WakeAlarms_SetAndWait_Response
2	err	WakeAlarmsError
3	framework_err	internal

WakeAlarms_Set_Result strict

Defined in fuchsia.time.alarms/wake_alarms.fidl

Ordinal	Variant	Type	Description
1	response	WakeAlarms_Set_Response
2	err	WakeAlarmsError
3	framework_err	internal

ALIASES

Name	Value	Description
AlarmId	string[128]	A unique identifier for an alarm. This alias is used to identify alarms within a single WakeAlarms connection. It is the client's responsibility to ensure that the IDs are unique for all active alarms.