// 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 uint32 MAX_RESOLVE_NAME_SIZE = 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
/// `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, Layout = "Simple"]
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(string:MAX_RESOLVE_NAME_SIZE name) -> (zx.status status,
                                                   handle<vmo>? executable,
                                                   fuchsia.ldsvc.Loader? ldsvc);
};