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