Struct ServiceFs 

pub struct ServiceFs<ServiceObjTy: ServiceObjTrait> { /* private fields */ }

A filesystem which connects clients to services.

This type implements the Stream trait and will yield the values returned from calling Service::connect on the services it hosts.

This can be used to, for example, yield streams of channels, request streams, futures to run, or any other value that should be processed as the result of a request.

Implementations

impl<'a, Output: 'a> ServiceFs<ServiceObjLocal<'a, Output>>

pub fn new_local() -> Self

Create a new ServiceFs that is singlethreaded-only and does not require services to implement Send.

impl<'a, Output: 'a> ServiceFs<ServiceObj<'a, Output>>

pub fn new() -> Self

Create a new ServiceFs that is multithreaded-capable and requires services to implement Send.

impl<ServiceObjTy: ServiceObjTrait> ServiceFs<ServiceObjTy>

pub fn root_dir(&mut self) -> ServiceFsDir<'_, ServiceObjTy>

Get a reference to the root directory as a ServiceFsDir.

This can be useful when writing code which hosts some set of services on a directory and wants to be agnostic to whether that directory is the root ServiceFs or a subdirectory.

Such a function can take an &mut ServiceFsDir<...> as an argument, allowing callers to provide either a subdirectory or fs.root_dir().

pub fn add_service_connector<F, P>(&mut self, service: F) -> &mut Self

where F: FnMut(ServerEnd<P>) -> ServiceObjTy::Output, P: DiscoverableProtocolMarker, FidlServiceServerConnector<F, P, ServiceObjTy::Output>: Into<ServiceObjTy>,

Adds a service connector to the directory.

let mut fs = ServiceFs::new_local();
fs
    .add_service_connector(|server_end: ServerEnd<EchoMarker>| {
        connect_channel_to_protocol::<EchoMarker>(
            server_end.into_channel(),
        )
    })
    .add_service_connector(|server_end: ServerEnd<CustomMarker>| {
        connect_channel_to_protocol::<CustomMarker>(
            server_end.into_channel(),
        )
    })
    .take_and_serve_directory_handle()?;

The FIDL service will be hosted at the name provided by the [Discoverable] annotation in the FIDL source.

Panics

Panics if any node has already been added with the discoverable protocol name.

pub fn add_service_at( &mut self, name: impl TryInto<Name, Error: Debug>, service: impl Into<ServiceObjTy>, ) -> &mut Self

Adds a service to the directory with the given name.

Panics

Panics if name is not a valid fuchsia.io [Name], or if any node has already been added with the given name.

pub fn add_fidl_service<F, RS>(&mut self, service: F) -> &mut Self

where F: FnMut(RS) -> ServiceObjTy::Output, RS: RequestStream, RS::Protocol: DiscoverableProtocolMarker, FidlService<F, RS, ServiceObjTy::Output>: Into<ServiceObjTy>,

Adds a FIDL service to the directory.

service is a closure that accepts a RequestStream. Each service being served must return an instance of the same type (ServiceObjTy::Output). This is necessary in order to multiplex multiple services over the same dispatcher code. The typical way to do this is to create an enum with variants for each service you want to serve.

enum MyServices {
    EchoServer(EchoRequestStream),
    CustomServer(CustomRequestStream),
    // ...
}

The constructor for a variant of the MyServices enum can be passed as the service parameter.

let mut fs = ServiceFs::new_local();
fs
    .add_fidl_service(MyServices::EchoServer)
    .add_fidl_service(MyServices::CustomServer)
    .take_and_serve_directory_handle()?;

ServiceFs can now be treated as a Stream of type MyServices.

const MAX_CONCURRENT: usize = 10_000;
fs.for_each_concurrent(MAX_CONCURRENT, |request: MyServices| {
    match request {
        MyServices::EchoServer(request) => handle_echo(request),
        MyServices::CustomServer(request) => handle_custom(request),
    }
}).await;

The FIDL service will be hosted at the name provided by the [Discoverable] annotation in the FIDL source.

Panics

Panics if any node has already been added with the discoverable protocol name.

pub fn add_fidl_service_at<F, RS>( &mut self, name: impl TryInto<Name, Error: Debug>, service: F, ) -> &mut Self

where F: FnMut(RS) -> ServiceObjTy::Output, RS: RequestStream, RS::Protocol: DiscoverableProtocolMarker, FidlService<F, RS, ServiceObjTy::Output>: Into<ServiceObjTy>,

Adds a FIDL service to the directory with the given name.

See add_fidl_service for details.

Panics

Panics if name is not a valid fuchsia.io [Name], or if any node has already been added with the given name.

pub fn add_fidl_service_instance<F, SR>( &mut self, instance: impl TryInto<Name, Error: Debug>, service: F, ) -> &mut Self

where F: Fn(SR) -> ServiceObjTy::Output + Clone, SR: ServiceRequest, FidlServiceMember<F, SR, ServiceObjTy::Output>: Into<ServiceObjTy>,

Adds a named instance of a FIDL service to the directory.

The FIDL service will be hosted at [SERVICE_NAME]/[instance]/ where SERVICE_NAME is constructed from the FIDL library path and the name of the FIDL service.

Example

For the following FIDL definition,

library lib.foo;

service Bar {
  ...
}

The SERVICE_NAME of FIDL Service Bar would be lib.foo.Bar.

Panics

Panics if instance is not a valid fuchsia.io [Name], or if an entry has already been added that conflicts with the service or instance directory structure.

pub fn add_fidl_service_instance_at<F, SR>( &mut self, name: impl TryInto<Name, Error: Debug>, instance: impl TryInto<Name, Error: Debug>, service: F, ) -> &mut Self

where F: Fn(SR) -> ServiceObjTy::Output + Clone, SR: ServiceRequest, FidlServiceMember<F, SR, ServiceObjTy::Output>: Into<ServiceObjTy>,

Adds a named instance of a FIDL service to the directory with the given name.

The FIDL service will be hosted at [name]/[instance]/.

Panics

Panics if name or instance is not a valid fuchsia.io [Name], or if an entry has already been added that conflicts with the service or instance directory structure.

pub fn add_proxy_service<P: DiscoverableProtocolMarker, O>( &mut self, ) -> &mut Self

where ServiceObjTy: From<Proxy<P, O>> + ServiceObjTrait<Output = O>,

Adds a service that proxies requests to the current environment.

The FIDL service will be hosted at the name provided by the [Discoverable] annotation in the FIDL source.

Panics

Panics if any node has already been added with the discoverable protocol name.

pub fn add_proxy_service_to<P: DiscoverableProtocolMarker, O>( &mut self, directory_request: Arc<ClientEnd<DirectoryMarker>>, ) -> &mut Self

where ServiceObjTy: From<ProxyTo<P, O>> + ServiceObjTrait<Output = O>,

Adds a service that proxies requests to the given component.

The FIDL service will be hosted at the name provided by the [Discoverable] annotation in the FIDL source.

Panics

Panics if any node has already been added with the discoverable protocol name.

pub fn add_vmo_file_at( &mut self, name: impl TryInto<Name, Error: Debug>, vmo: Vmo, ) -> &mut Self

Adds a VMO file to the directory with the given name.

The vmo should have content size set as required.

Panics

Panics if name is not a valid fuchsia.io [Name], or if any node has already been added with the given name.

pub fn add_entry_at( &mut self, name: impl TryInto<Name, Error: Debug>, entry: Arc<dyn DirectoryEntry>, ) -> &mut Self

Adds an entry to the directory with the given name.

Panics

Panics if name is not a valid fuchsia.io [Name], or if any node has already been added with the given name.

pub fn dir( &mut self, name: impl TryInto<Name, Error: Debug>, ) -> ServiceFsDir<'_, ServiceObjTy>

Returns a reference to the subdirectory with the given name, creating one if none exists.

Panics

Panics if name is not a valid fuchsia.io [Name], or if an entry has already been added with the given name and it is not a directory.

pub fn add_remote( &mut self, name: impl TryInto<Name, Error: Debug>, proxy: DirectoryProxy, ) -> &mut Self

Adds a new remote directory served over the given DirectoryProxy.

Panics

Panics if name is not a valid fuchsia.io [Name], or if any node has already been added with the given name.

pub fn add_fidl_next_protocol<P, H>( &mut self, create_handler: impl Fn(Server<P, Channel>) -> H + Send + Sync + Clone + 'static, ) -> &mut Self

where P: Discoverable + DispatchServerMessage<H, Channel>, H: Send + Sync + 'static,

Adds a FIDL protocol to the directory.

The FIDL protocol will be hosted at the name provided by the Discoverable annotation in the FIDL source.

Panics

Panics if any node has already been added with the discoverable protocol name.

pub fn add_fidl_next_service_instance<S, H>( &mut self, instance_name: impl TryInto<Name, Error: Debug>, handler: H, ) -> &mut Self

where S: DiscoverableService + DispatchServiceHandler<H, Channel> + 'static, H: Send + Sync + 'static,

Adds a FIDL service to the directory.

The FIDL service will be hosted at the name provided by the Discoverable annotation in the FIDL source under [instance_name].

Panics

Panics if instance_name is not a valid fuchsia.io [Name], or if an entry has already been added that conflicts with the service or instance directory structure.

pub fn add_fidl_next_service_instance_at<S, H>( &mut self, name: impl TryInto<Name, Error: Debug>, instance_name: impl TryInto<Name, Error: Debug>, handler: H, ) -> &mut Self

where S: DiscoverableService + DispatchServiceHandler<H, Channel> + 'static, H: Send + Sync + 'static,

Adds a FIDL service to the directory with a custom service name.

The FIDL service will be hosted at [name]/[instance_name]/.

Panics

Panics if name or instance_name is not a valid fuchsia.io [Name], or if an entry has already been added that conflicts with the service or instance directory structure.

pub fn create_protocol_connector<O>( &mut self, ) -> Result<ProtocolConnector, Error>

where ServiceObjTy: ServiceObjTrait<Output = O>,

Creates a protocol connector that can access the capabilities exposed by this ServiceFs.

impl<ServiceObjTy: ServiceObjTrait> ServiceFs<ServiceObjTy>

pub fn take_and_serve_directory_handle(&mut self) -> Result<&mut Self, Error>

Removes the DirectoryRequest startup handle for the current component and connects it to this ServiceFs as a client.

Multiple calls to this function from the same component will result in Err(MissingStartupHandle).

pub fn serve_connection( &mut self, chan: ServerEnd<DirectoryMarker>, ) -> Result<&mut Self, Error>

Add a channel to serve this ServiceFs filesystem on. The ServiceFs will continue to be provided over previously added channels, including the one added if take_and_serve_directory_handle was called.

pub fn until_stalled( self, debounce_interval: MonotonicDuration, ) -> StallableServiceFs<ServiceObjTy>

TODO(https://fxbug.dev/326626515): this is an experimental method to run a FIDL directory connection until stalled, with the purpose to cleanly stop a component. We’ll expect to revisit how this works to generalize to all connections later. Try not to use this function for other purposes.

Normally the ServiceFs stream will block until all connections are closed. In order to escrow the outgoing directory server endpoint, you may use this function to get a StallableServiceFs that detects when no new requests hit the outgoing directory for debounce_interval, and all hosted protocols and other VFS connections to finish, then yield back the outgoing directory handle.

The ServiceFs stream yields [ServiceObjTy::Output], which could be an enum of FIDL connection requests in a typical component. By contrast, StallableServiceFs yields an enum of either the request, or the unbound outgoing directory endpoint, allowing you to escrow it back to component_manager before exiting the component.

Trait Implementations

impl<ServiceObjTy: ServiceObjTrait> Stream for ServiceFs<ServiceObjTy>

type Item = <ServiceObjTy as ServiceObjTrait>::Output

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<'pin, ServiceObjTy: ServiceObjTrait> Unpin for ServiceFs<ServiceObjTy>

where PinnedFieldsOf<__ServiceFs<'pin, ServiceObjTy>>: Unpin,