content / common / child_process.mojom [blame]

// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module content.mojom;

import "ipc/ipc.mojom";
import "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/generic_pending_receiver.mojom";
import "mojo/public/mojom/base/memory_pressure_level.mojom";
import "services/tracing/public/mojom/background_tracing_agent.mojom";
import "services/tracing/public/mojom/system_tracing_service.mojom";

// Information about how logging should be configured.
// Corresponds to logging::LoggingSettings.
[EnableIf=is_chromeos_ash]
struct LoggingSettings {
  uint32 logging_dest;
  handle<platform> log_file_descriptor;
};

// The primordial interface child processes use to push requests to their
// browser-side host object.
interface ChildProcessHost {
  // Pings the parent process, expecting a reply. Used to verify that the
  // process and this interface connection are operational. When a child
  // process is started, it begins a timer (default 15 seconds) and sends this
  // message to the browser. If no reply comes back before time runs out, the
  // process self-terminates. There are no other interesting side effects, nor
  // are there any constraints on what either process can do while this is in
  // flight.
  Ping() => ();

  // Requests that the browser bind |receiver| on behalf of the child process.
  // Whether or not the interface type encapsulated by |receiver| is supported
  // depends on the process type and potentially on the Content embedder.
  BindHostReceiver(mojo_base.mojom.GenericPendingReceiver receiver);
};

// A control interface the browser uses to drive the behavior of all types of
// Content child processes.
interface ChildProcess {
  // Tells the child process that it's safe to shutdown.
  ProcessShutdown();

  // Requests the child process send its Mach task port to the caller.
  [EnableIf=is_apple]
  GetTaskPort() => (handle<platform> task_port);

  // Tells the child process to begin or end IPC message logging.
  [EnableIf=ipc_logging]
  SetIPCLoggingEnabled(bool on);

  // Used to configure triggering for background tracing of child processes.
  GetBackgroundTracingAgentProvider(
      pending_receiver<tracing.mojom.BackgroundTracingAgentProvider> receiver);

  // Used for connecting to the Perfetto system tracing service in the child
  // process. The child process uses |remote| to request the browser process
  // to make the socket connection and pass the connection back to the child.
  // This interface only accesses the producer socket. A child process
  // should never access the consumer socket.
  //
  // Enabled on POSIX platforms except Android: Android child processes connects
  // to the system tracing service directly.
  [EnableIf=is_non_android_posix]
  EnableSystemTracingService(
      pending_remote<tracing.mojom.SystemTracingService> remote);

  // Force the child process to crash immediately (i.e. a hard crash, no
  // cleanup, generating a crash report).
  CrashHungProcess();

  // Requests that the process bind a receiving pipe targeting the service
  // interface named by |receiver|.
  //
  // TODO(crbug.com/40633267): Rename this to |RunService()| once the above method
  // is removed.
  BindServiceInterface(mojo_base.mojom.GenericPendingReceiver receiver);

  // Requests that the process bind a receiving pipe targeting the interface
  // named by |receiver|. Unlike |BindServiceInterface()| this may be used to
  // bind arbitrary interfaces on many different types of child processes.
  // Calls to this method generally end up in
  // |ChildThreadImpl::OnBindReceiver()|.
  //
  // Whether or not the interface type encapsulated by |receiver| is supported
  // depends on the process type and potentially on the Content embedder.
  BindReceiver(mojo_base.mojom.GenericPendingReceiver receiver);

  // Sets the profiling file for the child process.
  // Used for the coverage builds.
  [EnableIf=clang_profiling_inside_sandbox]
  SetProfilingFile(mojo_base.mojom.File file);

  // Write out the accumulated code profiling profile to the configured file.
  // The callback is invoked once the profile has been flushed to disk.
  [EnableIf=clang_profiling_inside_sandbox]
  WriteClangProfilingProfile() => ();

  // Sets the pseudonymization salt in a child process.
  //
  // PRIVACY NOTE: It is important that the `salt` is never persisted anywhere
  // or sent to a server.  Whoever has access to the salt can de-anonymize
  // results of the content::PseudonymizationUtil::PseudonymizeString method.
  SetPseudonymizationSalt(uint32 salt);

  // Reinitializes the child process's logging with the given settings. This
  // is needed on Chrome OS, which switches to a log file in the user's home
  // directory once they log in.
  [EnableIf=is_chromeos_ash]
  ReinitializeLogging(LoggingSettings settings);

  // Notifies a child process of current memory pressure level.
  //
  // OnMemoryPressure is called when the browser process receives OS's
  // memory pressure signals, and also when the browser process triggers
  // user-level memory pressure signals.
  //
  // This method is only for an experimental feature, and may be removed
  // shortly. Other code should not use this method.
  // See https://crbug.com/1393283 for details.
  [EnableIf=is_android]
  OnMemoryPressure(mojo_base.mojom.MemoryPressureLevel memory_pressure_level);

  // Asks the child process to modify its internal settings to bias towards
  // energy efficiency because the embedder is in battery saver mode. The
  // default is `false`.
  SetBatterySaverMode(bool battery_saver_mode_enabled);
};