The Fuchsia entity model facilitates information interchange by defining a common interface for describing, referencing, accessing, and mutating data objects (entities) which are shared between components (modules, agents, shells) running in the modular framework. It consists of the following major concepts:
Entity handle.Entity: An interface which gives access to a shared data object.EntityProvider: the interface which allows agents to expose entities to the system.EntityResolver: the Fuchsia API for requesting an Entity handle for a given reference.The lifecycle of the data backing an Entity is controlled by the EntityProvider. The lifecycle of the Entity handle is controlled by sessionmgr.
Agents don't create Entity handles directly. Agents connect to the EntityReferenceFactory which provides the agent with an entity reference in exchange for a cookie. The entity reference can then be shared with other modular components which can use their EntityResolver to dereference it into an Entity interface.
Calls on that Entity interface will then be forwarded to the agent, along with the associated cookie.
The agent is thus responsible for storing and providing the entity data, associating it with the correct cookie, and optionally handling requests for mutating the entity data.
Modules can create entities explicitly via their ModuleContext by providing a fuchsia.mem.Buffer and an associated type. The framework manages the lifecycle of such entities by storing them in the story's record. For this reason, when the story is deleted, so is the entity. Agents and modules outside the story can dereference the entity so long as the story still exists.
This section describes the internals of entity resolution.
EntityProviderRunner implements the fuchsia::modular::EntityResolver interface, and is also responsible for creating entity references by implementing the fuchsia::modular::EntityReferenceFactory interface. A single instance of the EntityProviderRunner manages all the entity providers running in the system.
The first step in entity resolution (i.e. the first thing which happens when ResolveEntity is called) is the runner determines whether the entity is provided by an agent or by the modular framework by inspecting the entity reference. The runner then asks an EntityProviderLauncher to launch the appropriate entity provider.
If the entity provider is an agent, an AgentController is passed to the launcher, and the runner keeps the agent controller alive until the client closes the Entity.
Each Entity request has an associated EntityController which the entity runner owns. The EntityController owns the AgentController if the entity provider was an agent, and is responsible for forwarding the entity interface methods to the entity provider.