Project: /_project.yaml Book: /_book.yaml
Defined in fuchsia.sys2/realm.fidl
A protocol used by a component instance to manage its own realm, such as for binding to its children.
The component manager provides this service to components that use /svc/fuchsia.sys2.Realm
.
Binds to a child component instance, causing it to start running if it is not already. When this function successfully returns, child
is running and exposed_dir
is bound to a directory that contains the capabilities which the child exposed to its realm via ComponentDecl.exposes
(specified via “expose” declarations in the component’s manifest).
exposed_dir
is a valid channel as long as child
is running. child
will remain running until it either stops on its own, or DestroyChild
causes the child instance to be destroyed.
For example, if the child exposes a service /svc/example.Echo
then exposed_dir
will contain that service at that path.
NOTE: BindChild
does not support pipelining with CreateChild
. If BindChild
is called on an instance before CreateChild
successfully returns, it may return INSTANCE_NOT_FOUND
.
Errors:
INVALID_ARGUMENTS
: child
is not a valid child reference. -INSTANCE_NOT_FOUND
: child
does not exist.INSTANCE_CANNOT_START
: child
was not running and there was an error starting it.INSTANCE_CANNOT_RESOLVE
: child
's component declaration failed to resolve.Creates a child component instance dynamically. When this function returns successfully, the instance exists, but it may not be running.
Errors:
INVALID_ARGUMENTS
: collection
is not a valid reference or child
is not a valid declaration.COLLECTION_NOT_FOUND
: collection
does not exist.INSTANCE_ALREADY_EXISTS
: decl.name
already exists in collection
.NO_SPACE
: Could not allocate storage for the new instance.Destroys a dynamically-created component instance. When this function returns, the client should assume the instance no longer exists. However, some cleanup (such as stopping the component instance or freeing its storage) may be performed in the background after the function returns.
Errors:
INVALID_ARGUMENTS
: child
is not a valid reference or does not refer to a dynamic instance.INSTANCE_NOT_FOUND
: child
does not exist.COLLECTION_NOT_FOUND
: collection
does not exist.Returns an iterator that lists all instances in a collection.
NOTE: The results are not guaranteed to be consistent. Instances may be created or destroyed while the iterator is live, but those changes won't be observed by the iterator after this method returns.
Errors:
INVALID_ARGUMENTS
: collection
is not a valid reference.COLLECTION_NOT_FOUND
: collection
does not exist.Defined in fuchsia.sys2/realm.fidl
A protocol to iterate over the list of children in a realm.
Advance the iterator and return the next batch of children.
Returns a vector of ChildRef
. Returns an empty vector when there are no more children.
Defined in fuchsia.sys2/component_resolver.fidl
An interface for resolving a URL to a component.
This interface is implemented by components that provide support for loading components with a particular URL scheme. For example, the Fuchsia package component resolver exposes a service with this interface to resolve component URLs using the “fuchsia-pkg://” scheme.
To use a resolver to resolve URLs within your realm, register it in your realm's manifest. (TODO: explain in more detail)
Note: The component manager is the only intended direct client of this interface.
Resolves a component with the given URL.
component_url
is the unescaped URL of the component to resolve.
If successful, returns ZX_OK
and information about the component that was resolved.
On failure, returns null info
and...
ZX_ERR_INVALID_ARGS
: The component's URL was malformed.ZX_ERR_NOT_FOUND
: The component does not exist.ZX_ERR_UNAVAILABLE
: The resolver was unable to retrieve or parse the component's resources.Defined in fuchsia.sys2/component_runner.fidl
An interface for running components.
This interface is implemented by components that provide an execution environment for running particular classes of programs. For example, the Dart virtual machine exposes a service with this interface to run Dart programs.
To specify the runner needed to run your component, set the “runner_url” property in your component's manifest.
Note: The component manager is the only intended direct client of this interface.
Starts running a new component instance described by start_info
.
The caller of this method takes responsibility for binding client connections and controlling the lifetime of the newly started component instance through the requested controller
.
Defined in fuchsia.sys2/component_runner.fidl
An interface for binding client connections and controlling the lifetime of a component instance started using ComponentRunner.Start()
.
When the controlled component instance terminates or becomes inaccessible for any reason, the server invokes OnEpitaph()
and closes its endpoint of the controller interface.
LIFECYCLE
A component may exist in one of two states, Started or Stopped. The component is Started from time ComponentRunner.Start()
is called until the ComponentRunner closes the ComponentController handle. The component then transitions to Stopped.
Stop()
is called to indicate a ComponentRunner should end a component‘s execution. Kill()
indicates that a runner must halt a component’s execution immediately and close the ComponentController's server end. After the ComponentController is closed the component manager can tear down the namespace it hosts for the stopped component. The component manager may call Kill()
without first having called Stop()
.
EPITAPH
This interface uses a FIDL epitaph to indicate that the controller component instance has terminated and to describe its final disposition.
The following epitaph status codes have particular significance:
ZX_OK
: The component instance was successfully terminated in response to Stop()
and its runtime resources have been fully released.ZX_ERR_UNAVAILABLE
: The runner was unable to start the component instance. e.g. The runner could not retrieve the component's assets.ERR_COMPONENT_DIED
: The component instance was started but subsequently terminated unexpectedly.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.
Requests the runner to stop the controlled component instance.
After stopping the component instance, the server should report an epitaph then close its endpoint of the controller interface.
Stop this component immediately. This ComponentRunner must immediately kill the component instance, set an epitaph set on the channel, and close the channel. After the channel closes, the component instance will be considered by the component manager to be Stopped and the component's namespace will be torn down.
Kill() may have been preceeded by Stop(), but that is not guaranteed.
Defined in fuchsia.sys2/system_controller.fidl
An interface implemented by ComponentManager that requests the ComponentManager stop all components and exit.
Stop all components, return an empty result, close this protocol's channel, and exit ComponentManager. If this is the root ComponentManager is exited we expect the system will reboot.
Defined in fuchsia.sys2/work_scheduler.fidl
Framework service: API for scheduling and canceling work. Each component instance can access work items that it has scheduled (but not others' scheduled work items). Work items are scheduled roughly at the specified time and frequency; the service implementation may specify its notion of roughly, and may provide a configuration API to tune this notion.
Each scheduled work item is identified by a client-provided WorkId
. Each scheduled work item has a WorkId
that is unique with respect to scheduled work items belonging to the same component instance.
Schedule a new work item identified by work_id
. The work item is to be scheduled roughly at the time corresponding to work_request.start
. When work_request.period
is specified, reschedule work roughly every work_request.period
until the the work item is canceled.
Cancel the scheduled work item specified by work_id
.
Defined in fuchsia.sys2/work_scheduler.fidl
Component-exposed service: Work scheduler connects to this service to invoke scheduled work item callbacks. The service implementation is responsible for invoking the code that corresponds to the scheduled work item identified by work_id
.
Note: The intent of exposing this service is to expose it to the WorkScheduler
service provider (i.e., the framework) and no one else.
Defined in fuchsia.sys2/work_scheduler.fidl
Framework service: Administrative API for controlling parameters of the WorkScheduler
framework service. So long as there are work items with deadlines in the next batch_period
, the WorkScheduler
will sleep for batch_period
, then wake up and immediately dispatch a batch of work items: all those with past deadlines. It will repeat this process until no work items would be scheduled in the next batch_period
, at which point it will go to sleep until the next deadline. This strategy ensures that each work item is dispatched approximately within batch_period
of its deadline.
Get the current period between WorkScheduler
attempts to dispatch a batch of work. batch_period
is a non-negative 64-bit integer in the range [0, 2^63-1], representing a number of nanoseconds between dispatching batches of work.
Set the current period between WorkScheduler
attempts to batch and dispatch a batch of work. batch_period
is a non-negative 64-bit integer in the range [0, 2^63-1], representing a number of nanoseconds between dispatching batches of work.
Defined in fuchsia.sys2/relative_refs.fidl
A reference to a component’s containing realm, i.e. the parent component.
Defined in fuchsia.sys2/relative_refs.fidl
A reference to the component itself.
Defined in fuchsia.sys2/relative_refs.fidl
A reference to one of the component's child instances.
Defined in fuchsia.sys2/relative_refs.fidl
A reference to one of the component's collections.
Defined in fuchsia.sys2/relative_refs.fidl
A reference to one of the component's storage sections.
Defined in fuchsia.sys2/relative_refs.fidl
A reference to the component framework itself.
Defined in fuchsia.sys2/moniker.fidl
A moniker encodes the relationship between two component instances that exist in the component instance tree at runtime.
To understand this better, consider two component instances labeled “A” and “B” that are both children of a component instance labeled “P”.
At runtime, when “B” requests a service from “A” through a channel established by the component manager, the component manager may provide “A” with a moniker that encodes “B's” identity relative to “A” itself. The moniker‘s encoded value describes the directed path to traverse from “A” (the moniker’s origin) to “B” (the moniker's referent), passing through “P” (their common ancestor).
generated
generated
generated
generated
Defined in fuchsia.sys2/component_namespace.fidl
A namespace specifies the set of directories that a component instance receives at start-up. Each component instance‘s namespace is tailored to provide access to a set of files and services that are appropriate to that component instance’s role in the system (its sandbox).
By convention, a component's namespace typically contains some or all of the following directories:
Each mount point must be unique and non-overlapping. For example, [“/foo”, “/foo/bar”] is invalid.
generated
generated
generated
generated
generated
Type: uint32
Defined in fuchsia.sys2/child_decl.fidl
Type: uint32
Defined in fuchsia.sys2/collection_decl.fidl
The durability of component instances created in a collection.
Type: uint32
Defined in fuchsia.sys2/storage_decl.fidl
The type of storage offered by this component.
Type: uint32
Defined in fuchsia.sys2/error.fidl
Standard error codes for component framework protocols.
Defined in fuchsia.sys2/child_decl.fidl
Statically declares a child component instance.
Must be non-empty, unique among all siblings, and contain only the following characters: [a-z0-9-_.].
Must be non-empty and a well-formed URL.
Defined in fuchsia.sys2/collection_decl.fidl
Statically declares a component instance collection.
Defined in fuchsia.sys2/component_decl.fidl
A component declaration.
This information is typically encoded in the component manifest (.cm file) if it has one or may be generated at runtime by a component resolver for those that don't.
The component manager provides the contents of this dictionary to the component runner when executing the program. Each component runner can freely define the contents of this dictionary as needed.
The system's default runner understands the following entries:
“binary”: string The path of the executable relative to the root of the package. Typically an ELF binary.
“args”: vector of strings The command-line arguments to provide to the executable at runtime.
“env”: dictionary of strings The environment variables to provide to the executable at runtime.
Other runners may define different entries.
The used capabilities must be unique and non-overlapping.
The exposed capabilities must be unique and non-overlapping.
The offered capabilities must be unique and non-overlapping.
Defined in fuchsia.sys2/expose_decl.fidl
Declares a service exposed to a component's containing realm, such as a service exposed by the component or one of its children at runtime.
To learn more about services, see: https://fuchsia.dev/fuchsia-src/glossary#service
Must be an absolute path starting with /.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/expose_decl.fidl
Declares a legacy service exposed to a component's containing realm, such as a legacy service exposed by the component or one of its children at runtime.
A legacy service is a service with a single instance, provided by a single FIDL protocol.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/expose_decl.fidl
Declares a directory exposed to a component's containing realm, such as a directory exposed by the component or one of its children at runtime.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/expose_decl.fidl
Declares a runner exposed to a component's containing realm, such as a runner exposed by the component or one of its children at runtime.
Defined in fuchsia.sys2/offer_decl.fidl
Declares a service offered by a component to one of its children, which may have been offered by the component's containing realm, the component itself, or one of its other children.
To learn more about services, see: https://fuchsia.dev/fuchsia-src/glossary#service
Must be an absolute path starting with /.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/offer_decl.fidl
Declares a legacy service offered by a component to one of its children, which may have been offered by the component's containing realm, the component itself, or one of its other children.
A legacy service is a service with a single instance, provided by a single FIDL protocol.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/offer_decl.fidl
Declares a directory offered by a component to one of its children, which may have been offered by the component's containing realm, the component itself, or one of its other children.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/offer_decl.fidl
Declares a storage capability offered by a component to one of its children, such as meta storage offered by the component's containing realm or cache storage offered by the component itself.
Defined in fuchsia.sys2/offer_decl.fidl
Declares a runner offered by a component to one of its children, which may have been offered by the component's containing realm, the component itself, or one of its other children.
Defined in fuchsia.sys2/runner_decl.fidl
Declares a runner capability backed by a service.
Defined in fuchsia.sys2/storage_decl.fidl
Declares a storage capability backed by a directory from which data, cache, or meta storage can be offered.
Defined in fuchsia.sys2/use_decl.fidl
Declares a service used by a component, which was offered to the component's environment.
To learn more about services, see: https://fuchsia.dev/fuchsia-src/glossary#service
Must be an absolute path starting with /.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/use_decl.fidl
Declares a legacy service used by a component, which was offered to the component's environment.
A legacy service is a service with a single instance, provided by a single FIDL protocol.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/use_decl.fidl
Declares a directory used by a component, which was offered to the component's environment.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/use_decl.fidl
Declares storage used by a component, which was offered to the component's environment.
Must be an absolute path starting with /.
Defined in fuchsia.sys2/use_decl.fidl
Declares a runner used by a component, which was offered to the component's environment.
Defined in fuchsia.sys2/component.fidl
A component is a unit of executable software.
This object provides the component‘s declaration, access to its package’s content, and relevant metadata.
This is null if the component is not represented as a package. In that case, it is the runner‘s responsibility to load the component’s resource from the resolved_url
. This mechanism is used for web applications.
Defined in fuchsia.sys2/component_runner.fidl
Parameters for starting a new component instance.
Defined in fuchsia.sys2/package.fidl
A package is a signed collection of immutable files.
This object provides access to a package's content and relevant metadata.
Defined in fuchsia.sys2/work_scheduler.fidl
Parameters for a new piece of work to be scheduled.
generated
generated
generated
generated
generated
generated
generated
generated
generated
Defined in fuchsia.sys2/expose_decl.fidl
Declares a capability exposed to either a component's containing realm or to the framework. For example, a legacy service exposed by the component at runtime.
Defined in fuchsia.sys2/offer_decl.fidl
Declares a capability offered by a component to one of its children, which may have been offered by the component's containing realm, the component itself, or one of its other children.
Defined in fuchsia.sys2/relative_refs.fidl
A reference to a capability source or destination relative to this component.
Defined in fuchsia.sys2/use_decl.fidl
Declares a capability used by a component, which was offered to the component's environment.
Defined in fuchsia.sys2/work_scheduler.fidl
Different ways to specify when to schedule a work item for the first time.