base/process/process.h

   1 // Copyright 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_PROCESS_PROCESS_H_
   6 #define BASE_PROCESS_PROCESS_H_
   7
   8 #include "base/base_export.h"
   9 #include "base/basictypes.h"
  10 #include "base/move.h"
  11 #include "base/process/process_handle.h"
  12 #include "base/time/time.h"
  13 #include "build/build_config.h"
  14
  15 #if defined(OS_WIN)
  16 #include "base/win/scoped_handle.h"
  17 #endif
  18
  19 namespace base {
  20
  21 // Provides a move-only encapsulation of a process.
  22 //
  23 // This object is not tied to the lifetime of the underlying process: the
  24 // process may be killed and this object may still around, and it will still
  25 // claim to be valid. The actual behavior in that case is OS dependent like so:
  26 //
  27 // Windows: The underlying ProcessHandle will be valid after the process dies
  28 // and can be used to gather some information about that process, but most
  29 // methods will obviously fail.
  30 //
  31 // POSIX: The underlying PorcessHandle is not guaranteed to remain valid after
  32 // the process dies, and it may be reused by the system, which means that it may
  33 // end up pointing to the wrong process.
  34 class BASE_EXPORT Process {
  35   MOVE_ONLY_TYPE_FOR_CPP_03(Process, RValue)
  36
  37  public:
  38   explicit Process(ProcessHandle handle = kNullProcessHandle);
  39
  40   // Move constructor for C++03 move emulation of this type.
  41   Process(RValue other);
  42
  43   // The destructor does not terminate the process.
  44   ~Process();
  45
  46   // Move operator= for C++03 move emulation of this type.
  47   Process& operator=(RValue other);
  48
  49   // Returns an object for the current process.
  50   static Process Current();
  51
  52   // Returns a Process for the given |pid|.
  53   static Process Open(ProcessId pid);
  54
  55   // Returns a Process for the given |pid|. On Windows the handle is opened
  56   // with more access rights and must only be used by trusted code (can read the
  57   // address space and duplicate handles).
  58   static Process OpenWithExtraPrivileges(ProcessId pid);
  59
  60 #if defined(OS_WIN)
  61   // Returns a Process for the given |pid|, using some |desired_access|.
  62   // See ::OpenProcess documentation for valid |desired_access|.
  63   static Process OpenWithAccess(ProcessId pid, DWORD desired_access);
  64 #endif
  65
  66   // Creates an object from a |handle| owned by someone else.
  67   // Don't use this for new code. It is only intended to ease the migration to
  68   // a strict ownership model.
  69   // TODO(rvargas) crbug.com/417532: Remove this code.
  70   static Process DeprecatedGetProcessFromHandle(ProcessHandle handle);
  71
  72   // Returns true if processes can be backgrounded.
  73   static bool CanBackgroundProcesses();
  74
  75   // Returns true if this objects represents a valid process.
  76   bool IsValid() const;
  77
  78   // Returns a handle for this process. There is no guarantee about when that
  79   // handle becomes invalid because this object retains ownership.
  80   ProcessHandle Handle() const;
  81
  82   // Returns a second object that represents this process.
  83   Process Duplicate() const;
  84
  85   // Get the PID for this process.
  86   ProcessId Pid() const;
  87
  88   // Returns true if this process is the current process.
  89   bool is_current() const;
  90
  91   // Close the process handle. This will not terminate the process.
  92   void Close();
  93
  94   // Terminates the process with extreme prejudice. The given |exit_code| will
  95   // be the exit code of the process. If |wait| is true, this method will wait
  96   // for up to one minute for the process to actually terminate.
  97   // Returns true if the process terminates within the allowed time.
  98   // NOTE: On POSIX |exit_code| is ignored.
  99   bool Terminate(int exit_code, bool wait) const;
 100
 101   // Waits for the process to exit. Returns true on success.
 102   // On POSIX, if the process has been signaled then |exit_code| is set to -1.
 103   // On Linux this must be a child process, however on Mac and Windows it can be
 104   // any process.
 105   // NOTE: |exit_code| is optional, nullptr can be passed if the exit code is
 106   // not required.
 107   bool WaitForExit(int* exit_code);
 108
 109   // Same as WaitForExit() but only waits for up to |timeout|.
 110   // NOTE: |exit_code| is optional, nullptr can be passed if the exit code
 111   // is not required.
 112   bool WaitForExitWithTimeout(TimeDelta timeout, int* exit_code);
 113
 114 #if defined(OS_MACOSX)
 115   // The Mac needs a Mach port in order to manipulate a process's priority,
 116   // and there's no good way to get that from base given the pid. These Mac
 117   // variants of the IsProcessBackgrounded and SetProcessBackgrounded API take
 118   // the Mach port for this reason. See crbug.com/460102
 119   //
 120   // A process is backgrounded when its priority is lower than normal.
 121   // Return true if the process with mach port |task_port| is backgrounded,
 122   // false otherwise.
 123   bool IsProcessBackgrounded(mach_port_t task_port) const;
 124
 125   // Set the process with the specified mach port as backgrounded. If value is
 126   // true, the priority of the process will be lowered. If value is false, the
 127   // priority of the process will be made "normal" - equivalent to default
 128   // process priority. Returns true if the priority was changed, false
 129   // otherwise.
 130   bool SetProcessBackgrounded(mach_port_t task_port, bool value);
 131 #else
 132   // A process is backgrounded when it's priority is lower than normal.
 133   // Return true if this process is backgrounded, false otherwise.
 134   bool IsProcessBackgrounded() const;
 135
 136   // Set a process as backgrounded. If value is true, the priority of the
 137   // process will be lowered. If value is false, the priority of the process
 138   // will be made "normal" - equivalent to default process priority.
 139   // Returns true if the priority was changed, false otherwise.
 140   bool SetProcessBackgrounded(bool value);
 141 #endif  // defined(OS_MACOSX)
 142   // Returns an integer representing the priority of a process. The meaning
 143   // of this value is OS dependent.
 144   int GetPriority() const;
 145
 146  private:
 147 #if defined(OS_WIN)
 148   bool is_current_process_;
 149   win::ScopedHandle process_;
 150 #else
 151   ProcessHandle process_;
 152 #endif
 153 };
 154
 155 }  // namespace base
 156
 157 #endif  // BASE_PROCESS_PROCESS_H_