Package oshi.software.os

Class OSProcess

java.lang.Object
oshi.software.os.OSProcess
@NotThreadSafe
public class OSProcess
extends java.lang.Object
A process is an instance of a computer program that is being executed. It contains the program code and its current activity. Depending on the operating system (OS), a process may be made up of multiple threads of execution that execute instructions concurrently.

Thread safe if both threads only use getters, or if setter usage is externally synchronized.

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  OSProcess.State
    Process Execution States

  • Constructor Summary

    Constructors 
    Constructor Description
    OSProcess​(OperatingSystem operatingSystem)
    Constructor for OSProcess.
    OSProcess​(OperatingSystem operatingSystem, int processID)
    Constructor for OSProcess given a Process ID.

  • Method Summary

    Modifier and Type Method Description
    double calculateCpuPercent()
    Deprecated.
    Use getProcessCpuLoadCumulative().
    int getBitness()
    Attempts to get the bitness (32 or 64) of the process.
    long getBytesRead()
    Getter for the field bytesRead.
    long getBytesWritten()
    Getter for the field bytesWritten.
    java.lang.String getCommandLine()
    Getter for the field commandLine.
    java.lang.String getCurrentWorkingDirectory()
    Getter for the field currentWorkingDirectory.
    java.lang.String getGroup()
    Getter for the field group.
    java.lang.String getGroupID()
    Getter for the field groupID.
    long getKernelTime()
    Getter for the field kernelTime.
    java.lang.String getName()
    Getter for the field name.
    long getOpenFiles()
    Sets the number of open file handles (or network connections) that belongs to the process On FreeBSD and Solaris, this value is only populated if information for a single process id is requested.
    int getParentProcessID()
    Getter for the field parentProcessID.
    java.lang.String getPath()
    Getter for the field path.
    int getPriority()
    Getter for the field priority.
    double getProcessCpuLoadBetweenTicks​(OSProcess priorSnapshot)
    Gets CPU usage of this process since a previous snapshot of the same process, provided as a parameter.
    double getProcessCpuLoadCumulative()
    Gets cumulative CPU usage of this process.
    int getProcessID()
    Getter for the field processID.
    long getResidentSetSize()
    Getter for the field residentSetSize.
    long getStartTime()
    Getter for the field startTime.
    OSProcess.State getState()
    Getter for the field state.
    int getThreadCount()
    Getter for the field threadCount.
    long getUpTime()
    Getter for the field upTime.
    java.lang.String getUser()
    Getter for the field user.
    java.lang.String getUserID()
    Getter for the field userID.
    long getUserTime()
    Getter for the field userTime.
    long getVirtualSize()
    Getter for the field virtualSize.
    void setBitness​(int bitness)
    Setter for the field bitness.
    void setBytesRead​(long bytesRead)
    Set the number of bytes the process has read from disk.
    void setBytesWritten​(long bytesWritten)
    Set the number of bytes the process has written to disk.
    void setCommandLine​(java.lang.String commandLine)
    Sets the process command line.
    void setCurrentWorkingDirectory​(java.lang.String currentWorkingDirectory)
    Sets the process current working directory
    void setGroup​(java.lang.String group)
    Sets the group.
    void setGroupID​(java.lang.String groupID)
    Sets the Group ID.
    void setKernelTime​(long kernelTime)
    Set the number of milliseconds the process has executed in kernel mode.
    void setName​(java.lang.String name)
    Set the name of the process.
    void setOpenFiles​(long count)
    Sets the number of open file handles (or network connections) that belongs to the process
    void setParentProcessID​(int parentProcessID)
    Set the parentProcessID.
    void setPath​(java.lang.String path)
    Set the full path of the executing process.
    void setPriority​(int priority)
    Set the priority of this process.
    void setProcessID​(int processID)
    Set the processID.
    void setResidentSetSize​(long residentSetSize)
    Set the Resident Set Size (RSS).
    void setStartTime​(long startTime)
    Set the start time of the process in number of milliseconds since January 1, 1970.
    void setState​(OSProcess.State state)
    Set the execution state of the process.
    void setThreadCount​(int threadCount)
    Set the number of threads in this process.
    void setUpTime​(long upTime)
    Set the number of milliseconds since the process started.
    void setUser​(java.lang.String user)
    Sets the user.
    void setUserID​(java.lang.String userID)
    Sets the User ID.
    void setUserTime​(long userTime)
    Set the number of milliseconds the process has executed in user mode.
    void setVirtualSize​(long virtualSize)
    Set the Virtual Memory Size (VSZ).
    java.lang.String toString()  
    boolean updateAttributes()
    Attempts to updates all process attributes.
    boolean updateAttributes​(boolean slowFields)
    Attempts to updates all process attributes.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • OSProcess

      public OSProcess​(OperatingSystem operatingSystem)

      Constructor for OSProcess.

      Parameters:
      operatingSystem - a OperatingSystem instance

    • OSProcess

      public OSProcess​(OperatingSystem operatingSystem, int processID) throws java.lang.InstantiationException

      Constructor for OSProcess given a Process ID. Instantiates an object with current statistics for that process ID, and is equivalent to OperatingSystem.getProcess(int).

      If a process with that ID does not exist, this constructor will throw an InstantiationException.

      Parameters:
      operatingSystem - a OperatingSystem instance
      processID - process ID
      Throws:
      java.lang.InstantiationException - If a process by that ID does not exist.

  • Method Details

    • updateAttributes

      public boolean updateAttributes()
      Attempts to updates all process attributes. Returns false if the update fails, which will occur if the process no longer exists.
      Returns:
      True if the update was successful, false if the update failed

    • updateAttributes

      public boolean updateAttributes​(boolean slowFields)
      Attempts to updates all process attributes. Returns false if the update fails, which will occur if the process no longer exists.
      Parameters:
      slowFields - If false, skip fields that are slow to retrieve (e.g., group information on Windows, open files on Unix and Linux). If true, include all fields, regardless of how long it takes to retrieve the data.
      Returns:
      True if the update was successful, false if the update failed

    • getName

      public java.lang.String getName()

      Getter for the field name.

      Returns:
      Returns the name of the process.

    • getPath

      public java.lang.String getPath()

      Getter for the field path.

      Returns:
      Returns the full path of the executing process.

    • getCommandLine

      public java.lang.String getCommandLine()

      Getter for the field commandLine.

      Returns:
      Returns the process command line. The format of this string is platform-dependent and may require the end user to parse the result. On Linux and macOS systems, the string is null-character-delimited, to permit the end user to parse the executable and arguments if desired. Further, the macOS variant may include environment variables which the end user may wish to exclude from display. On Solaris, the string is truncated to 80 characters.

    • getCurrentWorkingDirectory

      public java.lang.String getCurrentWorkingDirectory()

      Getter for the field currentWorkingDirectory.

      Returns:
      Returns the process current working directory. On Windows, this value is only populated for the current process.

    • getUser

      public java.lang.String getUser()

      Getter for the field user.

      Returns:
      Returns the user name. On Windows systems, also returns the domain prepended to the username.

    • getUserID

      public java.lang.String getUserID()

      Getter for the field userID.

      Returns:
      Returns the userID. On Windows systems, returns the Security ID (SID)

    • getGroup

      public java.lang.String getGroup()

      Getter for the field group.

      Returns:
      Returns the group. On Windows systems, populating this value for processes other than the current user requires administrative privileges (and still may fail for some system processes) and can incur significant latency. When successful, returns a the default primary group with access to this process, corresponding to the SID in getGroupID().

    • getGroupID

      public java.lang.String getGroupID()

      Getter for the field groupID.

      Returns:
      Returns the groupID. On Windows systems, populating this value for processes other than the current user requires administrative privileges (and still may fail for some system processes) and can incur significant latency. When successful, returns the default primary group SID with access to this process, corresponding to the name in getGroup().

    • getState

      public OSProcess.State getState()

      Getter for the field state.

      Returns:
      Returns the execution state of the process.

    • getProcessID

      public int getProcessID()

      Getter for the field processID.

      Returns:
      Returns the processID.

    • getParentProcessID

      public int getParentProcessID()

      Getter for the field parentProcessID.

      Returns:
      Returns the parentProcessID, if any; 0 otherwise.

    • getThreadCount

      public int getThreadCount()

      Getter for the field threadCount.

      Returns:
      Returns the number of threads in this process.

    • getPriority

      public int getPriority()

      Getter for the field priority.

      Returns:
      Returns the priority of this process. For Linux and Unix, priority is a value in the range -20 to 19 (20 on some systems). The default priority is 0; lower priorities cause more favorable scheduling. For Windows, priority values can range from 0 (lowest priority) to 31 (highest priority). macOS has 128 priority levels, ranging from 0 (lowest priority) to 127 (highest priority). They are divided into several major bands: 0 through 51 are the normal levels; the default priority is 31. 52 through 79 are the highest priority regular threads; 80 through 95 are for kernel mode threads; and 96 through 127 correspond to real-time threads, which are treated differently than other threads by the scheduler.

    • getVirtualSize

      public long getVirtualSize()

      Getter for the field virtualSize.

      Returns:
      Returns the Virtual Memory Size (VSZ). It includes all memory that the process can access, including memory that is swapped out and memory that is from shared libraries.

    • getResidentSetSize

      public long getResidentSetSize()

      Getter for the field residentSetSize.

      Returns:
      Returns the Resident Set Size (RSS). On Windows, returns the Private Working Set size. It is used to show how much memory is allocated to that process and is in RAM. It does not include memory that is swapped out. It does include memory from shared libraries as long as the pages from those libraries are actually in memory. It does include all stack and heap memory.

    • getKernelTime

      public long getKernelTime()

      Getter for the field kernelTime.

      Returns:
      Returns the number of milliseconds the process has executed in kernel/system mode.

    • getUserTime

      public long getUserTime()

      Getter for the field userTime.

      Returns:
      Returns the number of milliseconds the process has executed in user mode.

    • getUpTime

      public long getUpTime()

      Getter for the field upTime.

      Returns:
      Returns the number of milliseconds since the process started.

    • getStartTime

      public long getStartTime()

      Getter for the field startTime.

      Returns:
      Returns the start time of the process in number of milliseconds since January 1, 1970.

    • getBytesRead

      public long getBytesRead()

      Getter for the field bytesRead.

      Returns:
      Returns the number of bytes the process has read from disk.

    • getBytesWritten

      public long getBytesWritten()

      Getter for the field bytesWritten.

      Returns:
      Returns the number of bytes the process has written to disk.

    • setName

      public void setName​(java.lang.String name)
      Set the name of the process.
      Parameters:
      name - process name

    • setPath

      public void setPath​(java.lang.String path)
      Set the full path of the executing process.
      Parameters:
      path - process path

    • setCommandLine

      public void setCommandLine​(java.lang.String commandLine)
      Sets the process command line.
      Parameters:
      commandLine - The commandLine to set.

    • setCurrentWorkingDirectory

      public void setCurrentWorkingDirectory​(java.lang.String currentWorkingDirectory)
      Sets the process current working directory
      Parameters:
      currentWorkingDirectory - The currentWorkingDirectory to set.

    • setUser

      public void setUser​(java.lang.String user)
      Sets the user.
      Parameters:
      user - The user to set.

    • setUserID

      public void setUserID​(java.lang.String userID)
      Sets the User ID.
      Parameters:
      userID - The userID to set.

    • setGroup

      public void setGroup​(java.lang.String group)
      Sets the group.
      Parameters:
      group - The group to set.

    • setGroupID

      public void setGroupID​(java.lang.String groupID)
      Sets the Group ID.
      Parameters:
      groupID - The groupID to set.

    • setState

      public void setState​(OSProcess.State state)
      Set the execution state of the process.
      Parameters:
      state - execution state

    • setProcessID

      public void setProcessID​(int processID)
      Set the processID.
      Parameters:
      processID - process ID

    • setParentProcessID

      public void setParentProcessID​(int parentProcessID)
      Set the parentProcessID.
      Parameters:
      parentProcessID - parent process ID

    • setThreadCount

      public void setThreadCount​(int threadCount)
      Set the number of threads in this process.
      Parameters:
      threadCount - number of threads

    • setPriority

      public void setPriority​(int priority)
      Set the priority of this process. For Linux, priority is a value in the range -20 to 19 (20 on some systems). The default priority is 0; lower priorities cause more favorable scheduling. For Windows, priority values can range from 0 (lowest priority) to 31 (highest priority). Mac OS X has 128 priority levels, ranging from 0 (lowest priority) to 127 (highest priority). They are divided into several major bands: 0 through 51 are the normal levels; the default priority is 31. 52 through 79 are the highest priority regular threads; 80 through 95 are for kernel mode threads; and 96 through 127 correspond to real-time threads, which are treated differently than other threads by the scheduler.
      Parameters:
      priority - priority

    • setVirtualSize

      public void setVirtualSize​(long virtualSize)
      Set the Virtual Memory Size (VSZ). It includes all memory that the process can access, including memory that is swapped out and memory that is from shared libraries.
      Parameters:
      virtualSize - virtual size

    • setResidentSetSize

      public void setResidentSetSize​(long residentSetSize)
      Set the Resident Set Size (RSS). It is used to show how much memory is allocated to that process and is in RAM. It does not include memory that is swapped out. It does include memory from shared libraries as long as the pages from those libraries are actually in memory. It does include all stack and heap memory.
      Parameters:
      residentSetSize - resident set size

    • setKernelTime

      public void setKernelTime​(long kernelTime)
      Set the number of milliseconds the process has executed in kernel mode.
      Parameters:
      kernelTime - kernel time

    • setUserTime

      public void setUserTime​(long userTime)
      Set the number of milliseconds the process has executed in user mode.
      Parameters:
      userTime - user time

    • setStartTime

      public void setStartTime​(long startTime)
      Set the start time of the process in number of milliseconds since January 1, 1970.
      Parameters:
      startTime - start time

    • setUpTime

      public void setUpTime​(long upTime)
      Set the number of milliseconds since the process started.
      Parameters:
      upTime - up time

    • setBytesRead

      public void setBytesRead​(long bytesRead)
      Set the number of bytes the process has read from disk.
      Parameters:
      bytesRead - number of bytes read

    • setBytesWritten

      public void setBytesWritten​(long bytesWritten)
      Set the number of bytes the process has written to disk.
      Parameters:
      bytesWritten - number of bytes written

    • setOpenFiles

      public void setOpenFiles​(long count)
      Sets the number of open file handles (or network connections) that belongs to the process
      Parameters:
      count - The number of handles

    • getOpenFiles

      public long getOpenFiles()
      Sets the number of open file handles (or network connections) that belongs to the process On FreeBSD and Solaris, this value is only populated if information for a single process id is requested.
      Returns:
      open files or -1 if unknown or not supported

    • calculateCpuPercent

      @Deprecated public double calculateCpuPercent()
      Deprecated.
      Use getProcessCpuLoadCumulative().
      Calculates cumulative CPU usage of this process.
      Returns:
      The proportion of up time that the process was executing in kernel or user mode.

    • getProcessCpuLoadCumulative

      public double getProcessCpuLoadCumulative()
      Gets cumulative CPU usage of this process.

      This calculation sums CPU ticks across all processors and may exceed 100% for multi-threaded processes. This is consistent with the cumulative CPU presented by the "top" command on Linux/Unix machines.

      Returns:
      The proportion of up time that the process was executing in kernel or user mode.

    • getProcessCpuLoadBetweenTicks

      public double getProcessCpuLoadBetweenTicks​(OSProcess priorSnapshot)
      Gets CPU usage of this process since a previous snapshot of the same process, provided as a parameter.

      This calculation sums CPU ticks across all processors and may exceed 100% for multi-threaded processes. This is consistent with process usage calulations on Linux/Unix machines, but should be divided by the number of logical processors to match the value displayed by the Windows Task Manager.

      The accuracy of this calculation is dependent on both the number of threads on which the process is executing, and the precision of the Operating System's tick counters. A polling interval of at least a few seconds is recommended.

      Parameters:
      priorSnapshot - An OSProcess object containing statistics for this same process collected at a prior point in time. May be null.
      Returns:
      If the prior snapshot is for the same process at a prior point in time, the proportion of elapsed up time between the current process snapshot and the previous one that the process was executing in kernel or user mode. Returns cumulative load otherwise.

    • getBitness

      public int getBitness()
      Attempts to get the bitness (32 or 64) of the process.
      Returns:
      The bitness, if able to be determined, 0 otherwise.

    • setBitness

      public void setBitness​(int bitness)

      Setter for the field bitness.

      Parameters:
      bitness - The bitness to set.

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object