// 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.
@available(added=7)
library fuchsia.process.lifecycle;

using fuchsia.io;
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:
/// https://fuchsia.dev/fuchsia-src/concepts/components/v2/elf_runner#lifecycle
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.
    @available(added=HEAD)
    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 server_end:fuchsia.io.Directory;

        /// 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;
    });
};