Enum WakeAlarmsRequest

pub enum WakeAlarmsRequest {
    SetAndWait {
        deadline: BootInstant,
        mode: SetMode,
        alarm_id: String,
        responder: WakeAlarmsSetAndWaitResponder,
    },
    Cancel {
        alarm_id: String,
        control_handle: WakeAlarmsControlHandle,
    },
    Set {
        notifier: ClientEnd<NotifierMarker>,
        deadline: BootInstant,
        mode: SetMode,
        alarm_id: String,
        responder: WakeAlarmsSetResponder,
    },
    SetAndWaitUtc {
        deadline: InstantUtc,
        mode: SetMode,
        alarm_id: String,
        responder: WakeAlarmsSetAndWaitUtcResponder,
    },
    #[non_exhaustive]
    _UnknownMethod {
        ordinal: u64,
        control_handle: WakeAlarmsControlHandle,
        method_type: MethodType,
    },
}

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.

Variants

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.

Return value

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

The call to SetAndWait returns when the alarm fires, an error occurs, or the alarm is canceled. This return style is required for some clients, such as Starnix, which rely on FIDL response tallying to guide their power management strategy.

As an example, under Starnix, a response to this request will cause a Starnix container to be unsuspended (“woken up”). This is a critical behavior for suspend correctness under Starnix. Using the [Notifier] approach would side-step this mechanism and result in incorrect wake behavior under Starnix.

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.
• [INVALID_ARGS]: a parameter provided by the user is not valid, such as an empty alarm_id.

Fields

deadline: BootInstant

mode: SetMode

alarm_id: String

responder: WakeAlarmsSetAndWaitResponder

Cancel

Cancels the alarm specified by alarm_id.

Providing an alarm_id for an alarm that is not scheduled is a no-op.

Fields

alarm_id: String

control_handle: WakeAlarmsControlHandle

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.
• [INVALID_ARGS]: a parameter provided by the user is not valid, such as an empty alarm_id.

Fields

notifier: ClientEnd<NotifierMarker>

deadline: BootInstant

mode: SetMode

alarm_id: String

responder: WakeAlarmsSetResponder

SetAndWaitUtc

Similar to [SetAndWait], except the alarm is scheduled on the UTC timeline.

Refer to [SetAndWait] documentation for the functionality details, and especially see the section “Return value” for the return value subtleties.

Fields

deadline: InstantUtc

mode: SetMode

alarm_id: String

responder: WakeAlarmsSetAndWaitUtcResponder

_UnknownMethod

An interaction was received which does not match any known method.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

ordinal: u64

Ordinal of the method that was called.

control_handle: WakeAlarmsControlHandle

method_type: MethodType

Implementations

impl WakeAlarmsRequest

pub fn into_set_and_wait( self, ) -> Option<(BootInstant, SetMode, String, WakeAlarmsSetAndWaitResponder)>

pub fn into_cancel(self) -> Option<(String, WakeAlarmsControlHandle)>

pub fn into_set( self, ) -> Option<(ClientEnd<NotifierMarker>, BootInstant, SetMode, String, WakeAlarmsSetResponder)>

pub fn into_set_and_wait_utc( self, ) -> Option<(InstantUtc, SetMode, String, WakeAlarmsSetAndWaitUtcResponder)>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for WakeAlarmsRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.