// Copyright 2018 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.process;

using fuchsia.ldsvc;
using zx;

/// The maximum size for a name used by `Resolver`.
const MAX_RESOLVE_NAME_SIZE uint32 = 2048;

/// An interface for resolving names to executables and library loaders.
///
/// An executable itself is often not sufficient to create a working process
/// because many executables also load shared libraries. On Fuchsia, there is no
/// global pool of shared libraries. Instead, every process has an associated
/// `fuchsia.ldsvc.Loader`, which provides access to a private pool of shared
/// libraries appropriate for that process.
///
/// This interface provides a protocol for resolving a name into both the
/// `zx.handle:VMO` for the executable and the `fuchsia.ldsvc.Loader` for its
/// associated shared libraries.
///
/// This interface is rarely used directly. Instead, `fdio_spawn` and
/// `fdio_spawn_etc` use this interface internally when they try to run a file
/// with a `#!resolve` directive.
@discoverable
protocol Resolver {
    /// Resolves the given `name` to an `executable` and an shared library
    /// loader.
    ///
    /// If present, the `executable` is suitable for use as the `executable`
    /// property of `LaunchInfo` -- in particular, it will have `ZX_RIGHT_EXECUTE`.
    /// If present, the `ldsvc` is suitable for use as the `PA_LDSVC_LOADER`
    /// handle when launching the process.
    ///
    /// For example, the resolver might locate the given `name` inside a package
    /// and return the executable binary from the package as well as a shared
    /// library loader scoped to that package.
    Resolve(struct {
        name string:MAX_RESOLVE_NAME_SIZE;
    }) -> (resource struct {
        status zx.status;
        executable zx.handle:<VMO, optional>;
        ldsvc client_end:<fuchsia.ldsvc.Loader, optional>;
    });
};