| // Copyright 2017 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.modular; |
| |
| using fuchsia.sys; |
| |
| /// An agent is a component whose lifecycle is not tied to any Story. |
| /// |
| /// - An agent is a singleton instance. |
| /// - Components can connect to an Agent using the |
| /// fuchsia.modular.ComponentContext capability. |
| /// - An agent vends services to components that connect to it over a |
| /// ServiceProvider. |
| /// - An agent is started when someone wants to connect to it, or when a task it |
| /// has scheduled has triggered. |
| /// |
| /// This FIDL interface should be implemented by a component that is meant to be |
| /// run as an Agent. |
| /// |
| /// When an agent application implements the |Lifecycle| interface, it can |
| /// receive a signal for when it should stop. An agent may be stopped for the |
| /// following reasons: |
| /// |
| /// (1) All |AgentController| connections associated with this agent are closed. |
| /// |
| /// (2) The system wants to optimize for resources. |
| /// |
| /// Once the framework delivers a |Lifecycle.Terminate()|, the agent application |
| /// may exit itself, or is killed by framework after a timeout. |
| /// |
| /// For more info see: |
| /// - fuchsia.modular.AgentContext and fuchsia.modular.ComponentContext for |
| /// capabilities an agent has. |
| /// - fuchsia.modular.Lifecycle for how Components get lifecycle events. |
| [Discoverable] // Created by each agent. |
| interface Agent { |
| /// Called when some component tries to connect to this agent. |requestor_url| |
| /// is the identifier for the component which called |
| /// |ComponentContext.ConnectToAgent()|. The |services| are provided to that |
| /// component. |
| Connect(string requestor_url, request<fuchsia.sys.ServiceProvider> services); |
| |
| /// Called when some task identified by |task_id| is scheduled to run. The task |
| /// was first posted by this Agent using |AgentContext.ScheduleTask()|. The |
| /// return callback is called by this Agent when all work related to this task |
| /// is completed. Note that the framework may call |Lifecycle.Terminate()| |
| /// before RunTask returns. |
| /// |
| /// TODO(alhaad): The current implementation allows the Agent to run a task |
| /// until its callback returns. If the task takes a long time to finish, the |
| /// framework has no way to signal a request for termination other than to shut |
| /// down the entire Agent instance. Instead, we should cap task length with |
| /// strategies like budgets. Also, the Task should likely have its own |
| /// connection that allows for more signalling. |
| RunTask(string task_id) -> (); |
| }; |