Package oshi.hardware

Interface CentralProcessor

All Known Implementing Classes:

AbstractCentralProcessor, OpenBsdCentralProcessor

@ThreadSafe
public interface CentralProcessor

This class represents the entire Central Processing Unit (CPU) of a computer system, which may contain one or more physical packages (sockets), one or more physical processors (cores), and one or more logical processors (what the Operating System sees, which may include hyperthreaded cores.)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	CentralProcessor.LogicalProcessor	A class representing a Logical Processor and its replationship to physical processors, physical packages, and logical groupings such as NUMA Nodes and Processor groups, useful for identifying processor topology.
static class	CentralProcessor.PhysicalProcessor	A class representing a Physical Processor (a core) providing per-core statistics that may vary, particularly in hybrid/modular processors.
static class	CentralProcessor.ProcessorCache	A class representing CPU Cache Memory.
static final class	CentralProcessor.ProcessorIdentifier	A class encapsulating ghe CPU's identifier strings ,including name, vendor, stepping, model, and family information (also called the signature of a CPU)
static enum	CentralProcessor.TickType	Index of CPU tick counters in the getSystemCpuLoadTicks() and getProcessorCpuLoadTicks() arrays.

Method Summary

Modifier and Type	Method	Description
long	getContextSwitches()	Get the number of system-wide context switches which have occurred.
long[]	getCurrentFreq()	Attempts to return the current frequency (in Hz), of the logical processors on this CPU.
List<String>	getFeatureFlags()	Returns a list of platform-specific strings which identify CPU Feature Flags.
long	getInterrupts()	Get the number of system-wide interrupts which have occurred.
int	getLogicalProcessorCount()	Get the number of logical CPUs available for processing.
List<CentralProcessor.LogicalProcessor>	getLogicalProcessors()	Returns an UnmodifiableList of the CPU's logical processors.
long	getMaxFreq()	Maximum frequeny (in Hz), of the logical processors on this CPU.
int	getPhysicalPackageCount()	Get the number of packages/sockets in the system.
int	getPhysicalProcessorCount()	Get the number of physical CPUs/cores available for processing.
List<CentralProcessor.PhysicalProcessor>	getPhysicalProcessors()	Returns an UnmodifiableList of the CPU's physical processors.
List<CentralProcessor.ProcessorCache>	getProcessorCaches()	Makes a best-effort attempt to identify the CPU's processor caches.
default double[]	getProcessorCpuLoad(long delay)	This is a convenience method which collects an initial set of ticks using getProcessorCpuLoadTicks() and passes that result to getProcessorCpuLoadBetweenTicks(long[][]) after the specified delay.
double[]	getProcessorCpuLoadBetweenTicks(long[][] oldTicks)	Returns the "recent cpu usage" for all logical processors by counting ticks from getProcessorCpuLoadTicks() between the user-provided value from a previous call.
long[][]	getProcessorCpuLoadTicks()	Get Processor CPU Load tick counters.
CentralProcessor.ProcessorIdentifier	getProcessorIdentifier()	The CPU's identifier strings ,including name, vendor, stepping, model, and family information (also called the signature of a CPU).
default double	getSystemCpuLoad(long delay)	This is a convenience method which collects an initial set of ticks using getSystemCpuLoadTicks() and passes that result to getSystemCpuLoadBetweenTicks(long[]) after the specified delay.
double	getSystemCpuLoadBetweenTicks(long[] oldTicks)	Returns the "recent cpu usage" for the whole system by counting ticks from getSystemCpuLoadTicks() between the user-provided value from a previous call.
long[]	getSystemCpuLoadTicks()	Get System-wide CPU Load tick counters.
double[]	getSystemLoadAverage(int nelem)	Returns the system load average for the number of elements specified, up to 3, representing 1, 5, and 15 minutes.

Method Details

getProcessorIdentifier

CentralProcessor.ProcessorIdentifier getProcessorIdentifier()

The CPU's identifier strings ,including name, vendor, stepping, model, and family information (also called the signature of a CPU).

The Processor Identifier is primarily associated with Intel-based chips. Attempts are made to provide comparable values for other chip manufacturers.

Returns:

a CentralProcessor.ProcessorIdentifier object encapsulating CPU identifier information.

getMaxFreq

long getMaxFreq()

Maximum frequeny (in Hz), of the logical processors on this CPU.

Returns:

The max frequency or -1 if unknown.

getCurrentFreq

long[] getCurrentFreq()

Attempts to return the current frequency (in Hz), of the logical processors on this CPU.

May not be implemented on all Operating Systems.

On Windows, returns an estimate based on the percent of maximum frequency. On Windows systems with more than 64 logical processors, may only return frequencies for the current processor group in the first portion of the array.

Returns:

An array of processor frequencies for each logical processor on the system. Use the getLogicalProcessors() to correlate these frequencies with physical packages and processors.

getLogicalProcessors

List<CentralProcessor.LogicalProcessor> getLogicalProcessors()

Returns an UnmodifiableList of the CPU's logical processors. The list will be sorted in order of increasing NUMA node number, and then processor number. This order is (usually) consistent with other methods providing per-processor results.

On some operating systems with variable numbers of logical processors, the size of this array could change and may not align with other per-processor methods.

Returns:

An UnmodifiabeList of logical processors.

getPhysicalProcessors

List<CentralProcessor.PhysicalProcessor> getPhysicalProcessors()

Returns an UnmodifiableList of the CPU's physical processors. The list will be sorted in order of increasing core ID.

Returns:

An UnmodifiabeList of physical processors.

getProcessorCaches

List<CentralProcessor.ProcessorCache> getProcessorCaches()

Makes a best-effort attempt to identify the CPU's processor caches. For hybrid processors, both performance and efficiency core caches are shown. Only one instance of per-core caches is shown.

Values are unreliable in virtual machines and rely in information made available by the VM or hypervisor. Callers should conduct sanity checking of the returned objects. Not all values are available on all operating systems or architectures.

Not available on Solaris.

Returns:

An UnmodifiabeList of processor caches.

getFeatureFlags

List<String> getFeatureFlags()

Returns a list of platform-specific strings which identify CPU Feature Flags. This string requires user parsing to obtain meaningful information.

Returns:

On Windows, returns a list of values for which the IsProcessorFeaturePresent() function evaluates to true.

On macOS x86, returns relevant sysctl.machdep.feature values. On Apple Silicon, returns relevant sysctl hw.optional.arm.FEAT values.

On Linux, returns the flags and/or features fields from /proc/cpuinfo.

On OpenBSD, FreeBSD, and Solaris, returns dmesg output containing the word Feature.

For unimplemented operating systems, returns an empty list.

getSystemCpuLoadBetweenTicks

double getSystemCpuLoadBetweenTicks(long[] oldTicks)

Returns the "recent cpu usage" for the whole system by counting ticks from getSystemCpuLoadTicks() between the user-provided value from a previous call.

On some operating systems with variable numbers of logical processors, the size of the array returned from a previous call to getSystemCpuLoadTicks() could change and will throw an IllegalArgumentException. Calling code on these operating systems should handle this exception.

Parameters:

oldTicks - A tick array from a previous call to getSystemCpuLoadTicks()

Returns:

CPU load between 0 and 1 (100%)

Throws:

IllegalArgumentException - if the array sizes differ.

getSystemCpuLoadTicks

long[] getSystemCpuLoadTicks()

Get System-wide CPU Load tick counters. Returns an array with eight elements representing milliseconds spent in User (0), Nice (1), System (2), Idle (3), IOwait (4), Hardware interrupts (IRQ) (5), Software interrupts/DPC (SoftIRQ) (6), or Steal (7) states. Use CentralProcessor.TickType.getIndex() to retrieve the appropriate index. By measuring the difference between ticks across a time interval, CPU load over that interval may be calculated.

On some operating systems with variable numbers of logical processors, the size of this array could change and may not align with other per-processor methods.

Note that while tick counters are in units of milliseconds, they may advance in larger increments along with (platform dependent) clock ticks. For example, by default Windows clock ticks are 1/64 of a second (about 15 or 16 milliseconds) and Linux ticks are distribution and configuration dependent but usually 1/100 of a second (10 milliseconds).

Nice and IOWait information is not available on Windows, and IOwait and IRQ information is not available on macOS, so these ticks will always be zero.

To calculate overall Idle time using this method, include both Idle and IOWait ticks. Similarly, IRQ, SoftIRQ, and Steal ticks should be added to the System value to get the total. System ticks also include time executing other virtual hosts (steal).

Returns:

An array of 8 long values representing time spent in User, Nice, System, Idle, IOwait, IRQ, SoftIRQ, and Steal states.

getSystemLoadAverage

double[] getSystemLoadAverage(int nelem)

Returns the system load average for the number of elements specified, up to 3, representing 1, 5, and 15 minutes. The system load average is the sum of the number of runnable entities queued to the available processors and the number of runnable entities running on the available processors averaged over a period of time.

This method is designed to provide a hint about the system load and may be queried frequently.

The way in which the load average is calculated is operating system specific but is typically a damped time-dependent average. Linux includes processes waiting for system resources such as disks, while macOS and Unix consider only processes waiting for CPU.

Windows does not provide a load average. Users may set the configuration property oshi.os.windows.loadaverage to true to start a daemon thread which will provide a similar metric.

The load average may be unavailable on some platforms (e.g., Windows without the above configuration). If the load average is not available, a negative value is returned.

Parameters:

nelem - Number of elements to return.

Returns:

an array of the system load averages for 1, 5, and 15 minutes with the size of the array specified by nelem; or negative values if not available.

getSystemCpuLoad

default double getSystemCpuLoad(long delay)

This is a convenience method which collects an initial set of ticks using getSystemCpuLoadTicks() and passes that result to getSystemCpuLoadBetweenTicks(long[]) after the specified delay.

Parameters:

delay - Milliseconds to wait.

Returns:

value between 0 and 1 (100%) that represents the cpu usage in the provided time period.

getProcessorCpuLoad

default double[] getProcessorCpuLoad(long delay)

This is a convenience method which collects an initial set of ticks using getProcessorCpuLoadTicks() and passes that result to getProcessorCpuLoadBetweenTicks(long[][]) after the specified delay.

On some operating systems with variable numbers of logical processors, the size of the array returned from the two calls could change and will throw an IllegalArgumentException. Calling code on these operating systems should handle this exception.

Parameters:

delay - Milliseconds to wait.

Returns:

array of CPU load between 0 and 1 (100%) for each logical processor, for the provided time period.

Throws:

IllegalArgumentException - if the array sizes differ between calls.

getProcessorCpuLoadBetweenTicks

double[] getProcessorCpuLoadBetweenTicks(long[][] oldTicks)

Returns the "recent cpu usage" for all logical processors by counting ticks from getProcessorCpuLoadTicks() between the user-provided value from a previous call.

On some operating systems with variable numbers of logical processors, the size of the array returned from the two calls could change and will throw an IllegalArgumentException. Calling code on these operating systems should handle this exception.

Parameters:

oldTicks - A tick array from a previous call to getProcessorCpuLoadTicks()

Returns:

array of CPU load between 0 and 1 (100%) for each logical processor

Throws:

IllegalArgumentException - if the array sizes differ between calls.

getProcessorCpuLoadTicks

long[][] getProcessorCpuLoadTicks()

Get Processor CPU Load tick counters. Returns a two dimensional array, with getLogicalProcessorCount() arrays, each containing seven elements representing milliseconds spent in User (0), Nice (1), System (2), Idle (3), IOwait (4), Hardware interrupts (IRQ) (5), Software interrupts/DPC (SoftIRQ) (6), or Steal (7) states. Use CentralProcessor.TickType.getIndex() to retrieve the appropriate index. By measuring the difference between ticks across a time interval, CPU load over that interval may be calculated.

Note that while tick counters are in units of milliseconds, they may advance in larger increments along with (platform dependent) clock ticks. For example, by default Windows clock ticks are 1/64 of a second (about 15 or 16 milliseconds) and Linux ticks are distribution and configuration dependent but usually 1/100 of a second (10 milliseconds).

Nice and IOwait per processor information is not available on Windows, and IOwait and IRQ information is not available on macOS, so these ticks will always be zero.

To calculate overall Idle time using this method, include both Idle and IOWait ticks. Similarly, IRQ, SoftIRQ and Steal ticks should be added to the System value to get the total. System ticks also include time executing other virtual hosts (steal).

Returns:

A 2D array of logicalProcessorCount x 7 long values representing time spent in User, Nice, System, Idle, IOwait, IRQ, SoftIRQ, and Steal states.

getLogicalProcessorCount

int getLogicalProcessorCount()

Get the number of logical CPUs available for processing. This value may be higher than physical CPUs if hyperthreading is enabled.

On some operating systems with variable numbers of logical processors, may return a max value.

Returns:

The number of logical CPUs available.

getPhysicalProcessorCount

int getPhysicalProcessorCount()

Get the number of physical CPUs/cores available for processing.

On some operating systems with variable numbers of physical processors available to the OS, may return a max value.

Returns:

The number of physical CPUs available.

getPhysicalPackageCount

int getPhysicalPackageCount()

Get the number of packages/sockets in the system. A single package may contain multiple cores.

Returns:

The number of physical packages available.

getContextSwitches

long getContextSwitches()

Get the number of system-wide context switches which have occurred.

Not available system-wide on macOS. Process- and Thread-level context switches are available from OSProcess.getContextSwitches() and OSThread.getContextSwitches().

Returns:

The number of context switches, if this information is available; 0 otherwise.

getInterrupts

long getInterrupts()

Get the number of system-wide interrupts which have occurred.

Not available system-wide on macOS.

Returns:

The number of interrupts, if this information is available; 0 otherwise.