Struct ComponentController

pub struct ComponentController;

The type corresponding to the ComponentController protocol. 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 send the OnStop event.
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 send the OnStop event. The component manager may wait some period of time after calling Kill() before sending OnStop, 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.

When the component stops, the runner should send an OnStop event instead of just closing the channel, to report the component’s termination status (see below) and (optionally) an exit code. Once the runner has sent OnStop it is free to close ComponentRunner; the component framework will close its end of the channel when it receives this event.

Legacy

Instead of sending OnStop, it is also legal for a runner to close the channel with with an epitaph equal to the termination status, but this is a legacy method for backward compatibility that’s no longer recommended.

Termination status

The termination status indicates the component’s final disposition in the eyes of the runner.

Note that termination status is not synonymous with a component’s exit code. A component’s exit code, which is optional for a runner to report, is an integer that represents the program’s own return code. For example, for ELF components, it is the value returned by main(). The termination status is the runner’s status code for the component’s termination, which may capture failure modes that occur in the context of the runner itself rather than the program.

The following termination statuses 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.

Trait Implementations

impl<___T, ___H> ClientProtocol<___T, ___H> for ComponentController

where ___T: Transport, ___H: ComponentControllerClientHandler<___T>, <OnPublishDiagnostics as Method>::Response: Decode<<___T as Transport>::RecvBuffer>, <OnEscrow as Method>::Response: Decode<<___T as Transport>::RecvBuffer>, <OnStop as Method>::Response: Decode<<___T as Transport>::RecvBuffer>,

fn on_event( handler: &mut ___H, sender: &ClientSender<___T, Self>, ordinal: u64, buffer: ___T::RecvBuffer, )

Handles a received client event with the given handler.

impl Debug for ComponentController

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

Formats the value using the given formatter.

impl<___T, ___H> ServerProtocol<___T, ___H> for ComponentController

where ___T: Transport, ___H: ComponentControllerServerHandler<___T>,

fn on_one_way( handler: &mut ___H, sender: &ServerSender<___T, Self>, ordinal: u64, buffer: ___T::RecvBuffer, )

Handles a received server one-way message with the given handler.

fn on_two_way( handler: &mut ___H, sender: &ServerSender<___T, Self>, ordinal: u64, buffer: ___T::RecvBuffer, responder: Responder, )

Handles a received server two-way message with the given handler.

impl TakeFrom<ComponentController> for ComponentControllerMarker

fn take_from(from: &ComponentController) -> Self

Converts from the given T, taking any resources that can’t be cloned.

const COPY_OPTIMIZATION: CopyOptimization<Self> = _

An optimization flag that allows the bytes of this type to be copied directly during conversion instead of calling take_from.