blob: 5e9a0e1b4eba6111d0e91f99b24d8139f2d56c49 [file] [log] [blame]
// Copyright 2020 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.
library fuchsia.process.lifecycle;
using fuchsia.component.sandbox;
/// A component can implement the Lifecycle protocol to be notified of lifecycle
/// events. It can also store some state in the framework, to be redelivered to
/// the component the next time it is started (a practice called "escrowing").
/// The ELF Runner uses this protocol to communicate lifecycle changes
/// to the component, for more details on how it uses this protocol see:
closed protocol Lifecycle {
/// The process must clean up its state in preparation for termination, and
/// must close the channel hosting the `Lifecycle` protocol when it is
/// ready to be terminated. The process should exit after it completes its
/// cleanup. At the discretion of the system the process may be terminated
/// before it closes the `Lifecycle` channel.
strict Stop();
/// Escrow state shortly before the component exits.
/// When the ELF runner receives this event, it will arrange with the
/// framework to wait until the current execution of the component has
/// finished, then start the component again when the `ZX_CHANNEL_READABLE`
/// signal is observed on `outgoing_dir`.
/// Repeated calls will replace the old escrowed value. This is discouraged.
/// Handles escrowed via `OnEscrow` are always delivered to the next
/// execution of the component.
strict -> OnEscrow(resource table {
/// Escrow the outgoing directory server endpoint. Whenever the
/// component is started again, this will be returned as the
/// `PA_DIRECTORY_REQUEST` processargs entry.
1: outgoing_dir;
/// Escrow some user defined state. Whenever the component is started
/// again, this will be returned as the `PA_ESCROWED_DICTIONARY`
/// processargs entry.
/// The framework will not wait for any signals on these objects.
/// ## Example
/// Let's say a component needs to escrow an event pair that represents
/// the result of some expensive calculation. It can create a
/// dictionary, put the event pair inside with an appropriate key
/// (e.g. `"my_event_pair"`), then check for that entry on startup.
2: escrowed_dictionary client_end:fuchsia.component.sandbox.Dictionary;