Enum fidl_fuchsia_component_runner::ComponentControllerRequest

pub enum ComponentControllerRequest {
    Stop {
        control_handle: ComponentControllerControlHandle,
    },
    Kill {
        control_handle: ComponentControllerControlHandle,
    },
}

A protocol for binding and controlling the lifetime of a component instance started using ComponentRunner.Start(). The component manager is the intended direct client of this protocol.

When the controlled component instance terminates or becomes inaccessible for any reason, the server closes the connection with an epitaph.

LIFECYCLE

A component may exist in one of two states: Started, or Stopped. The component is Started from the time ComponentRunner.Start() is called until the ComponentRunner closes the ComponentController handle. The component then transitions to Stopped.

Component manager uses ComponentController to terminate a component in two steps:

1. Component manager calls Stop() to indicate that the ComponentRunner should stop a component’s execution and close this connection with an epitaph.
2. If after some time the ComponentController is not closed, component manager calls Kill() to indicate that the ComponentRunner must halt a component’s execution immediately, and then close this connection with an epitaph. The component manager may wait some period of time after calling Kill() before closing the ComponentController channel, but makes no guarantees it will wait or for how long.

Component manager first waits for the ComponentController to close, and then tears down the namespace it hosts for the stopped component. Component manager may call Kill() without first having called Stop().

Before stopping, a component can optionally use OnEscrow to store some state in the framework, to receive those state again the next time it is started.

EPITAPH

This protocol sends a FIDL epitaph to indicate that the component instance has been terminated. The component runner is expected to clean up all resources attributed to the component before closing the connection.

The following epitaphs may be sent by the server on error:

• ZX_OK: The component exited successfully, typically because the component was asked to stop or it decided independently to exit.
• INVALID_ARGUMENTS:
  • start_info.resolved_url is not supported by this runner;
  • start_info contains missing or invalid arguments.
• INSTANCE_CANNOT_START: The runner could not start the component. For example, a critical part of the program could not be found or loaded, or the referenced binary was invalid for this runner.
• RESOURCE_UNAVAILABLE: The component could not be launched due to lack of resources.
• INTERNAL: An unexpected internal runner error was encountered.
• INSTANCE_DIED: The component instance was started but subsequently terminated with an error.
• Other status codes (e.g. ZX_ERR_PEER_CLOSED) may indicate a failure of the component runner itself. The component manager may respond to such failures by terminating the component runner’s job to ensure system stability.

Variants

Stop

Request to stop the component instance.

After stopping the component instance, the server should close this connection with an epitaph. After the connection closes, component manager considers this component instance to be Stopped and the component’s namespace will be torn down.

Fields

control_handle: ComponentControllerControlHandle

Kill

Stop this component instance immediately.

The ComponentRunner must immediately kill the component instance, and then close this connection with an epitaph. After the connection closes, component manager considers this component instance to be Stopped and the component’s namespace will be torn down.

In some cases Kill() may be issued before Stop(), but that is not guaranteed.

Fields

control_handle: ComponentControllerControlHandle

Implementations

impl ComponentControllerRequest

pub fn into_stop(self) -> Option<ComponentControllerControlHandle>

pub fn into_kill(self) -> Option<ComponentControllerControlHandle>

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

Name of the method defined in FIDL

Trait Implementations

impl Debug for ComponentControllerRequest

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

Formats the value using the given formatter.