Query CPU usage statistics for a given time interval using hs.host.cpuUsageTicks and return the results as percentages.

Parameters

`period` - an optional value specifying the time between samples collected for calculating CPU usage statistics.

If `callback` is not provided, this is an optional integer, default 100000, specifying the number of microseconds to block between samples collected. Note that Hammerspoon will block for this period of time during execution of this function.

If `callback` is provided, this is an optional number, default 1.0, specifying the number of seconds between samples collected. Hammerspoon will *not* block during this time period.

`callback` - an optional callback function which will receive the cpu usage statistics in a table, described below, as its sole argument.

Returns

If a callback function is not provided, this function will return a table containing the following:

Individual tables, indexed by the core number, for each CPU core with the following keys in each subtable:

user -- percentage of CPU time occupied by user level processes.

system -- percentage of CPU time occupied by system (kernel) level processes.

active -- For convenience, when you just want the total CPU usage, this is the sum of user, system, and nice.

idle -- percentage of CPU time spent idle

The key `overall` containing the same keys as described above but based upon the average of all cores combined.

The key `n` containing the number of cores detected.

If a callback function is provided, this function will return a placeholder table with the following metamethods:

`hs.host.cpuUsage:finished()` - returns a boolean indicating if the second CPU sample has been collected yet (true) or not (false).

`hs.host.cpuUsage:stop()` - abort the sample collection. The callback function will not be invoked.

The results of the cpu statistics will be submitted as a table, described above, to the callback function.

Notes

If no callback function is provided, Hammerspoon will block (i.e. no other Hammerspoon activity can occur) during execution of this function for `period` microseconds (1 second = 1,000,000 microseconds). The default period is 1/10 of a second. If `period` is too small, it is possible that some of the CPU statistics may result in `nan` (not-a-number).

Returns a table containing the current cpu usage information for the system in ticks since the most recent system boot.

Parameters

None

Returns

A table containing the following:

Individual tables, indexed by the core number, for each CPU core with the following keys in each subtable:

user -- number of ticks the cpu core has spent in user mode since system startup.

system -- number of ticks the cpu core has spent in system mode since system startup.

nice

active -- For convenience, when you just want the total CPU usage, this is the sum of user, system, and nice.

idle -- number of ticks the cpu core has spent idle

The key `overall` containing the same keys as described above but based upon the combined total of all cpu cores for the system.

The key `n` containing the number of cores detected.

Notes

CPU mode ticks are updated during system interrupts and are incremented based upon the mode the CPU is in at the time of the interrupt. By its nature, this is always going to be approximate, and a single call to this function will return the current tick values since the system was last rebooted.

To generate a snapshot of the system's usage "at this moment", you must take two samples and calculate the difference between them. The [hs.host.cpuUsage](#cpuUsage) function is a wrapper which does this for you and returns the cpu usage statistics as a percentage of the total number of ticks which occurred during the sample period you specify when invoking `hs.host.cpuUsage`.

The global unique identifier for a process includes the host name, process ID, and a time stamp, which ensures that the ID is unique for the network. This property generates a new string each time it is invoked, and it uses a counter to guarantee that strings are unique.

This is often used as a file or directory name in conjunction with `hs.host.temporaryDirectory()` when creating temporary files.

A table whose key-value pairs represent the GPUs for the current system. Each key is a string contining the name for an installed GPU and its value is the GPU's VRAM size in MB. If the VRAM size cannot be determined for a specific GPU, its value will be -1.0.

Notes

If your GPU reports -1.0 as the memory size, please submit an issue to the Hammerspoon github repository and include any information that you can which may be relevant, such as: Macintosh model, macOS version, is the GPU built in or a third party expansion card, the GPU model and VRAM as best you can determine (see the System Information application in the Utilities folder and look at the Graphics/Display section) and anything else that you think might be important.

The operating system version as a table containing the major, minor, and patch numbers.

Parameters

None

Returns

The operating system version as a table containing the keys major, minor, and patch corresponding to the version number determined and a key named "exact" or "approximation" depending upon the method used to determine the OS Version information.

Notes

Prior to 10.10 (Yosemite), there was no definitive way to reliably get an exact OS X version number without either mapping it to the Darwin kernel version, mapping it to the AppKitVersionNumber (the recommended method), or parsing the result of NSProcessingInfo's `operatingSystemVersionString` selector, which Apple states is not guaranteed to be reliably parseable.

for OS X versions prior to 10.10, the version number is approximately determined by evaluating the AppKitVersionNumber. For these operating systems, the `approximate` key is defined and set to true, as the exact patch level cannot be definitively determined.

for OS X Versions starting at 10.10 and going forward, an exact value for the version number can be determined with NSProcessingInfo's `operatingSystemVersion` selector and the `exact` key is defined and set to true if this method is used.

According to the OS X Developer documentation, "The operating system version string is human readable, localized, and is appropriate for displaying to the user. This string is not appropriate for parsing."

UUIDs (Universally Unique Identifiers), also known as GUIDs (Globally Unique Identifiers) or IIDs (Interface Identifiers), are 128-bit values. UUIDs created by NSUUID conform to RFC 4122 version 4 and are created with random bytes.