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: 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
Entityhandle 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
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
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 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.