tor-browser

process.h (12243B)

---

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

#ifndef BASE_PROCESS_PROCESS_H_
#define BASE_PROCESS_PROCESS_H_

#include "base/base_export.h"
#include "base/process/process_handle.h"
#include "base/strings/string_piece.h"
#include "base/time/time.h"
#include "build/blink_buildflags.h"
#include "build/build_config.h"
#include "build/chromeos_buildflags.h"

#if BUILDFLAG(IS_WIN)
#include "base/win/scoped_handle.h"
#endif

#if BUILDFLAG(IS_FUCHSIA)
#include <lib/zx/process.h>
#endif

#if BUILDFLAG(IS_APPLE) || BUILDFLAG(IS_CHROMEOS) || BUILDFLAG(IS_WIN)
#include "base/feature_list.h"
#endif  // BUILDFLAG(IS_APPLE) || BUILDFLAG(IS_CHROMEOS) || BUILDFLAG(IS_WIN)

#if BUILDFLAG(IS_APPLE)
#include "base/process/port_provider_mac.h"
#endif  // BUILDFLAG(IS_APPLE)

namespace base {

#if BUILDFLAG(IS_CHROMEOS)
// OneGroupPerRenderer feature places each foreground renderer process into
// its own cgroup. This will cause the scheduler to use the aggregate runtime
// of all threads in the process when deciding on the next thread to schedule.
// It will help guarantee fairness between renderers.
BASE_EXPORT BASE_DECLARE_FEATURE(kOneGroupPerRenderer);

// Set all threads of a background process as backgrounded, which changes the
// thread attributes including c-group, latency sensitivity. But the nice value
// is unchanged, since background process is under the spell of the background
// CPU c-group (via cgroup.procs).
BASE_EXPORT BASE_DECLARE_FEATURE(kSetThreadBgForBgProcess);
#endif

#if BUILDFLAG(IS_WIN)
BASE_EXPORT BASE_DECLARE_FEATURE(kUseEcoQoSForBackgroundProcess);
#endif

// Provides a move-only encapsulation of a process.
//
// This object is not tied to the lifetime of the underlying process: the
// process may be killed and this object may still around, and it will still
// claim to be valid. The actual behavior in that case is OS dependent like so:
//
// Windows: The underlying ProcessHandle will be valid after the process dies
// and can be used to gather some information about that process, but most
// methods will obviously fail.
//
// POSIX: The underlying ProcessHandle is not guaranteed to remain valid after
// the process dies, and it may be reused by the system, which means that it may
// end up pointing to the wrong process.
class BASE_EXPORT Process {
public:
 // On Windows, this takes ownership of |handle|. On POSIX, this does not take
 // ownership of |handle|.
 explicit Process(ProcessHandle handle = kNullProcessHandle);

 Process(Process&& other);

 Process(const Process&) = delete;
 Process& operator=(const Process&) = delete;

 // The destructor does not terminate the process.
 ~Process();

 Process& operator=(Process&& other);

 // Returns an object for the current process.
 static Process Current();

 // Returns a Process for the given |pid|.
 static Process Open(ProcessId pid);

 // Returns a Process for the given |pid|. On Windows the handle is opened
 // with more access rights and must only be used by trusted code (can read the
 // address space and duplicate handles).
 static Process OpenWithExtraPrivileges(ProcessId pid);

#if BUILDFLAG(IS_WIN)
 // Returns a Process for the given |pid|, using some |desired_access|.
 // See ::OpenProcess documentation for valid |desired_access|.
 static Process OpenWithAccess(ProcessId pid, DWORD desired_access);
#endif

 // Returns true if changing the priority of processes through `SetPriority()`
 // is possible.
 static bool CanSetPriority();

 // Terminates the current process immediately with |exit_code|.
 [[noreturn]] static void TerminateCurrentProcessImmediately(int exit_code);

 // Returns true if this objects represents a valid process.
 bool IsValid() const;

 // Returns a handle for this process. There is no guarantee about when that
 // handle becomes invalid because this object retains ownership.
 ProcessHandle Handle() const;

 // Returns a second object that represents this process.
 Process Duplicate() const;

 // Relinquishes ownership of the handle and sets this to kNullProcessHandle.
 // The result may be a pseudo-handle, depending on the OS and value stored in
 // this.
 [[nodiscard]] ProcessHandle Release();

 // Get the PID for this process.
 ProcessId Pid() const;

 // Get the creation time for this process. Since the Pid can be reused after a
 // process dies, it is useful to use both the Pid and the creation time to
 // uniquely identify a process.
 //
 // On Android, works only if |this| is the current process, as security
 // features prevent an application from getting data about other processes,
 // even if they belong to us. Otherwise, returns Time().
 Time CreationTime() const;

 // Returns true if this process is the current process.
 bool is_current() const;

#if BUILDFLAG(IS_CHROMEOS)
 // A unique token generated for each process, this is used to create a unique
 // cgroup for each renderer.
 const std::string& unique_token() const { return unique_token_; }
#endif

 // Close the process handle. This will not terminate the process.
 void Close();

 // Returns true if this process is still running. This is only safe on Windows
 // (and maybe Fuchsia?), because the ProcessHandle will keep the zombie
 // process information available until itself has been released. But on Posix,
 // the OS may reuse the ProcessId.
#if BUILDFLAG(IS_WIN)
 bool IsRunning() const {
   return !WaitForExitWithTimeout(base::TimeDelta(), nullptr);
 }
#endif

 // Terminates the process with extreme prejudice. The given |exit_code| will
 // be the exit code of the process. If |wait| is true, this method will wait
 // for up to one minute for the process to actually terminate.
 // Returns true if the process terminates within the allowed time.
 // NOTE: |exit_code| is only used on OS_WIN.
 bool Terminate(int exit_code, bool wait) const;

#if BUILDFLAG(IS_WIN)
 enum class WaitExitStatus {
   PROCESS_EXITED,
   STOP_EVENT_SIGNALED,
   FAILED,
 };

 // Waits for the process to exit, or the specified |stop_event_handle| to be
 // set. Returns value indicating which event was set. The given |exit_code|
 // will be the exit code of the process.
 WaitExitStatus WaitForExitOrEvent(
     const base::win::ScopedHandle& stop_event_handle,
     int* exit_code) const;
#endif  // BUILDFLAG(IS_WIN)

 // Waits for the process to exit. Returns true on success.
 // On POSIX, if the process has been signaled then |exit_code| is set to -1.
 // On Linux this must be a child process, however on Mac and Windows it can be
 // any process.
 // NOTE: |exit_code| is optional, nullptr can be passed if the exit code is
 // not required.
 bool WaitForExit(int* exit_code) const;

 // Same as WaitForExit() but only waits for up to |timeout|.
 // NOTE: |exit_code| is optional, nullptr can be passed if the exit code
 // is not required.
 bool WaitForExitWithTimeout(TimeDelta timeout, int* exit_code) const;

 // Indicates that the process has exited with the specified |exit_code|.
 // This should be called if process exit is observed outside of this class.
 // (i.e. Not because Terminate or WaitForExit, above, was called.)
 // Note that nothing prevents this being called multiple times for a dead
 // process though that should be avoided.
 void Exited(int exit_code) const;

 // The different priorities that a process can have.
 // TODO(pmonette): Consider merging with base::TaskPriority when the API is
 //                 stable.
 enum class Priority {
   // The process does not contribute to content that is currently important
   // to the user. Lowest priority.
   kBestEffort,

   // The process contributes to content that is visible to the user. High
   // priority.
   kUserVisible,

   // The process contributes to content that is of the utmost importance to
   // the user, like producing audible content, or visible content in the
   // focused window. Highest priority.
   kUserBlocking,
 };

#if BUILDFLAG(IS_MAC) || (BUILDFLAG(IS_IOS) && BUILDFLAG(USE_BLINK))
 // The Mac needs a Mach port in order to manipulate a process's priority,
 // and there's no good way to get that from base given the pid. These Mac
 // variants of the `GetPriority()` and `SetPriority()` API take a port
 // provider for this reason. See crbug.com/460102.

 // Retrieves the priority of the process. Defaults to Priority::kUserBlocking
 // if the priority could not be retrieved, or if `port_provider` is null.
 Priority GetPriority(PortProvider* port_provider) const;

 // Sets the priority of the process process. Returns true if the priority was
 // changed, false otherwise. If `port_provider` is null, this is a no-op and
 // it returns false.
 bool SetPriority(PortProvider* port_provider, Priority priority);
#else
 // Retrieves the priority of the process. Defaults to Priority::kUserBlocking
 // if the priority could not be retrieved.
 Priority GetPriority() const;

 // Sets the priority of the process process. Returns true if the priority was
 // changed, false otherwise.
 bool SetPriority(Priority priority);
#endif  // BUILDFLAG(IS_MAC) || (BUILDFLAG(IS_IOS) && BUILDFLAG(USE_BLINK))

 // Returns an integer representing the priority of a process. The meaning
 // of this value is OS dependent.
 int GetOSPriority() const;

#if BUILDFLAG(IS_CHROMEOS_ASH)
 // Get the PID in its PID namespace.
 // If the process is not in a PID namespace or /proc/<pid>/status does not
 // report NSpid, kNullProcessId is returned.
 ProcessId GetPidInNamespace() const;
#endif

#if BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_CHROMEOS)
 // Returns true if the process has any seccomp policy applied.
 bool IsSeccompSandboxed();
#endif  // BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_CHROMEOS)

#if BUILDFLAG(IS_CHROMEOS)
 // Exposes OneGroupPerRendererEnabled() to unit tests.
 static bool OneGroupPerRendererEnabledForTesting();

 // If OneGroupPerRenderer is enabled, runs at process startup to clean up
 // any stale cgroups that were left behind from any unclean exits of the
 // browser process.
 static void CleanUpStaleProcessStates();

 // Initializes the process's priority. If OneGroupPerRenderer is enabled, it
 // creates a unique cgroup for the process. This should be called before
 // SetPriority(). This is a no-op if the Process is not valid or if it has
 // already been called.
 void InitializePriority();
#endif  // BUILDFLAG(IS_CHROMEOS)

#if BUILDFLAG(IS_APPLE)
 // Sets the priority of the current process to its default value.
 static void SetCurrentTaskDefaultRole();
#endif  // BUILDFLAG(IS_MAC)

private:
#if BUILDFLAG(IS_CHROMEOS)
 // Cleans up process state. If OneGroupPerRenderer is enabled, it cleans up
 // the cgroup created by InitializePriority(). If the process has not
 // fully terminated yet, it will post a background task to try again.
 void CleanUpProcess(int remaining_retries) const;

 // Calls CleanUpProcess() on a background thread.
 void CleanUpProcessAsync() const;

 // Used to call CleanUpProcess() on a background thread because Process is not
 // refcounted.
 static void CleanUpProcessScheduled(Process process, int remaining_retries);
#endif  // BUILDFLAG(IS_CHROMEOS)

#if BUILDFLAG(IS_WIN)
 win::ScopedHandle process_;
#elif BUILDFLAG(IS_FUCHSIA)
 zx::process process_;
#else
 ProcessHandle process_;
#endif

#if BUILDFLAG(IS_WIN) || BUILDFLAG(IS_FUCHSIA)
 bool is_current_process_;
#endif

#if BUILDFLAG(IS_CHROMEOS)
 // A unique token per process not per class instance (`base::Process`). This
 // is similar to the PID of a process but should not be reused after the
 // process's termination. The token will be copied during Duplicate()
 // and move semantics as is the PID/ProcessHandle.
 std::string unique_token_;
#endif
};

#if BUILDFLAG(IS_CHROMEOS)
// Exposed for testing.
// Given the contents of the /proc/<pid>/cgroup file, determine whether the
// process is backgrounded or not.
BASE_EXPORT Process::Priority GetProcessPriorityCGroup(
   const StringPiece& cgroup_contents);
#endif  // BUILDFLAG(IS_CHROMEOS)

}  // namespace base

#endif  // BASE_PROCESS_PROCESS_H_