sys-cpu 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2c9b0550fea7a97f78cb37062e8f347d1b945e53a2a885f2c4fa8cdd02e0dc5
-  data.tar.gz: 6b4c3525653fd1a186078a533826795e3d2b168c2649d48fe549de33ca021edb
+  metadata.gz: 56f093dfd8f11c6ed9da97cc8020e687a76001dabef4596299041e6b875a2d3c
+  data.tar.gz: ac4b1d0ef5430c4d5078d9f4cbf12320f2900beab58d815202b32191209631ed
 SHA512:
-  metadata.gz: c3efb6d399e22fff8380ec6d581c3997707bab5f99a7bbe001a86a058427e348066fce271348c9451f567bf6ffa7a9f2cf247de94ae82cd258d5ea6fa3d4bb9c
-  data.tar.gz: 337fe45c0fe0463320c910aee118cf3496f71b9b4be7965d79204a109b12d273746f47afa50deb96519ec4118a3058e2aba00d912810bf065abee5e5fc8e0678
+  metadata.gz: 24a439eec1f866b22d52bd75665f284e8cd27351f474708b85f14900a3a77f4b5563b2961a3a5df7853fe10542048b7ff5c70eff1def7848da7eefa2964f28a2
+  data.tar.gz: e366fd2da77cf922abd384bb16e1c6bff84d4e3c11dc69d1732065971f80a2b5484db0cef28ae0d490492d4efb6173dea77a24b746302273eea7cf52d761716d

data/CHANGES.md

@@ -1,3 +1,12 @@
+## 1.3.0 - 24-Mar-2026
+* Added the cpu_usage method.
+
+## 1.2.0 - 17-Feb-2026
+* The win32ole gem is now a dependency since Ruby 4.x no longer bundles it.
+* The freq method was updated for BSD platforms on aarch64. It now defaults
+  to the hardclock timer value as a best guess.
+* The architecture method now recognizes ARM64 on Windows.
+
 ## 1.1.0 - 9-Jun-2024
 * Removed Solaris support.
 * Added DragonflyBSD support.

data/README.md

@@ -72,7 +72,7 @@ https://github.com/djberg96/sys-cpu
 Apache-2.0
 
 ## Copyright
-(C) 2003-2024 Daniel J. Berger, All Rights Reserved
+(C) 2003-2026 Daniel J. Berger, All Rights Reserved
 
 ## Warranty
 This package is provided "as is" and without any express or

data/Rakefile

@@ -44,6 +44,9 @@ end
 RuboCop::RakeTask.new
 
 desc "Run the test suite"
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = false
+  t.rspec_opts = '-f documentation -w'
+end
 
 task :default => :spec

data/lib/sys/cpu.rb

@@ -10,7 +10,7 @@ module Sys
   # This class is reopened for each of the supported platforms/operating systems.
   class CPU
     # The version of the sys-cpu gem.
-    VERSION = '1.1.0'
+    VERSION = '1.3.0'
 
     private_class_method :new
   end

data/lib/sys/darwin/sys/cpu.rb

@@ -43,7 +43,7 @@ module Sys
     CPU_ARCH_ABI64     = 0x01000000
     CPU_TYPE_X86       = 7
     CPU_TYPE_X86_64    = (CPU_TYPE_X86 | CPU_ARCH_ABI64)
-    CPU_TYPE_ARM		   = 12
+    CPU_TYPE_ARM       = 12
     CPU_TYPE_SPARC     = 14
     CPU_TYPE_POWERPC   = 18
     CPU_TYPE_POWERPC64 = CPU_TYPE_POWERPC | CPU_ARCH_ABI64
@@ -74,6 +74,7 @@ module Sys
     private_class_method :getloadavg
     private_class_method :sysconf
 
+    # Private wrapper class for struct clockinfo
     class ClockInfo < FFI::Struct
       layout(
         :hz, :int,
@@ -189,7 +190,7 @@ module Sys
         (optr.read_long * clock[:hz]) / 1_000_000
       else
         if sysctlbyname('hw.cpufrequency', optr, size, nil, 0) < 0
-          raise Error, 'sysctlbyname failed on hw.cpufrequency' if result < 0
+          raise Error, 'sysctlbyname failed on hw.cpufrequency'
         end
         optr.read_long / 1_000_000
       end
@@ -207,5 +208,119 @@ module Sys
 
       loadavg.get_array_of_double(0, 3)
     end
+
+    # Returns CPU usage as a percentage.
+    #
+    # If +sample_time+ is positive, samples CPU times and calculates an average
+    # over that interval. You can also specify +samples+ to average multiple
+    # consecutive measurements.
+    #
+    # If +sample_time+ is 0 (default), uses a 1-second sample window by default.
+    # Default value for +samples+ is 2 (averages two measurements).
+    #
+    HOST_CPU_LOAD_INFO = 3
+    HOST_CPU_LOAD_INFO_COUNT = 4
+
+    private_constant :HOST_CPU_LOAD_INFO, :HOST_CPU_LOAD_INFO_COUNT
+
+    attach_function :mach_host_self, [], :uint
+    attach_function :host_statistics, %i[uint int pointer pointer], :int
+
+    private_class_method :mach_host_self, :host_statistics
+
+    # Returns the current CPU usage as a percentage, averaged over a sampling interval.
+    #
+    # By default, this method samples CPU usage over a 1-second interval and averages two measurements.
+    # You can customize the interval and number of samples by passing the +sample_time+ (in seconds)
+    # and +samples+ keyword arguments. For example, +cpu_usage(sample_time: 0.5, samples: 4)+ will take four
+    # samples, each 0.5 seconds apart, and return the average CPU usage over that period.
+    #
+    # Passing nil, 0, or a negative value for either argument falls back to the defaults (1.0 seconds
+    # and 2 samples) to keep behavior consistent across platforms.
+    #
+    # Returns a Float (percentage), rounded to one decimal place, or nil if CPU usage cannot be determined.
+    #
+    # Example usage:
+    #   Sys::CPU.cpu_usage                              #=> 12.3
+    #   Sys::CPU.cpu_usage(sample_time: 2, samples: 3)  #=> 10.7
+    #   Sys::CPU.cpu_usage(sample_time: 0, samples: 0)  #=> 12.3   # zeros fall back to defaults
+    #
+    def self.cpu_usage(sample_time: 1.0, samples: 2)
+      sample_time = 1.0 if sample_time.nil? || sample_time <= 0
+      samples = 2 if samples.nil? || samples <= 0
+
+      usages = []
+
+      samples.times do
+        t1 = current_ticks
+        sleep(sample_time)
+        t2 = current_ticks
+        next unless t1 && t2
+
+        if (u = usage_between_ticks(t1, t2))
+          usages << u
+        end
+      end
+
+      return nil if usages.empty?
+
+      (usages.sum / usages.size.to_f).round(1)
+    rescue StandardError
+      nil
+    end
+
+    def self.current_ticks
+      cpu_ticks_sysctl || cpu_ticks_host
+    end
+
+    private_class_method :current_ticks
+
+    def self.usage_between_ticks(t1, t2)
+      diff = t2.map.with_index { |v, i| v - t1[i] }
+      total = diff.sum
+      return nil if total <= 0
+
+      # host_statistics returns [user, system, idle, nice]
+      idle = diff[2] || 0
+      (1.0 - (idle.to_f / total)) * 100
+    end
+
+    private_class_method :usage_between_ticks
+
+    def self.cpu_ticks_sysctl
+      cp_time = proc { |ptr|
+        len = 5
+        size = FFI::MemoryPointer.new(:size_t)
+        size.write_ulong(ptr.size)
+
+        if sysctlbyname('kern.cp_time', ptr, size, nil, 0) < 0
+          raise Error, 'sysctlbyname failed'
+        end
+
+        ptr.read_array_of_ulong(len)
+      }
+
+      cp_time.call(FFI::MemoryPointer.new(:ulong, 5))
+    rescue StandardError
+      nil
+    end
+
+    private_class_method :cpu_ticks_sysctl
+
+    def self.cpu_ticks_host
+      host = mach_host_self
+      info = FFI::MemoryPointer.new(:uint, HOST_CPU_LOAD_INFO_COUNT)
+      count = FFI::MemoryPointer.new(:uint)
+      count.write_uint(HOST_CPU_LOAD_INFO_COUNT)
+
+      kr = host_statistics(host, HOST_CPU_LOAD_INFO, info, count)
+      return nil unless kr == 0
+
+      info.read_array_of_uint(HOST_CPU_LOAD_INFO_COUNT)
+    rescue StandardError
+      nil
+    end
+
+    private_class_method :cpu_ticks_host
   end
 end

data/lib/sys/linux/sys/cpu.rb

@@ -10,7 +10,10 @@ module Sys
 
   cpu_file  = '/proc/cpuinfo'
   cpu_hash  = {}
+
+  # rubocop:disable Style/MutableConstant
   CPU_ARRAY = []
+  # rubocop:enable Style/MutableConstant
 
   private_constant :CPU_ARRAY
 
@@ -97,8 +100,15 @@ module Sys
 
     # Returns a string indicating the CPU model.
     #
+    # Some systems may use slightly different keys in /proc/cpuinfo, so
+    # we fall back to other common names and ensure we always return a
+    # String.
     def self.model
-      CPU_ARRAY.first['model_name']
+      CPU_ARRAY.first['model_name'] ||
+        CPU_ARRAY.first['model'] ||
+        CPU_ARRAY.first['cpu'] ||
+        CPU_ARRAY.first['processor'] ||
+        ''.dup
     end
 
     # Returns an integer indicating the speed of the CPU.
@@ -107,6 +117,62 @@ module Sys
       CPU_ARRAY.first['cpu_mhz'].to_f.round
     end
 
+    # Returns the current CPU usage as a percentage, averaged over a sampling interval.
+    #
+    # By default, this method samples CPU usage over a 1-second interval and averages two measurements.
+    # You can customize the interval and number of samples by passing the +sample_time+ (in seconds)
+    # and +samples+ keyword arguments. For example, +cpu_usage(sample_time: 0.5, samples: 4)+ will take four
+    # samples, each 0.5 seconds apart,
+    # and return the average CPU usage over that period.
+    #
+    # Passing nil, 0, or a negative value for either argument falls back to the defaults (1.0 seconds and
+    # 2 samples) for cross-platform consistency.
+    #
+    # Returns a Float (percentage), rounded to one decimal place, or nil if CPU usage cannot be determined.
+    #
+    # Example usage:
+    #   Sys::CPU.cpu_usage                              #=> 12.3
+    #   Sys::CPU.cpu_usage(sample_time: 2, samples: 3)  #=> 10.7
+    #   Sys::CPU.cpu_usage(sample_time: 0, samples: 0)  #=> 12.3   # zeros fall back to defaults
+    #
+    def self.cpu_usage(sample_time: 1.0, samples: 2)
+      sample_time = 1.0 if sample_time.nil? || sample_time <= 0
+      samples = 2 if samples.nil? || samples <= 0
+
+      usages = []
+
+      samples.times do
+        stats1 = cpu_stats
+        sleep(sample_time)
+        stats2 = cpu_stats
+
+        total_diff = 0.0
+        idle_diff = 0.0
+
+        keys = stats1.key?('cpu') ? ['cpu'] : stats1.keys
+        keys.each do |key|
+          arr1 = stats1[key]
+          arr2 = stats2[key]
+          next unless arr1 && arr2
+          t1 = arr1.sum
+          t2 = arr2.sum
+          total = t2 - t1
+          idle = (arr2[3] || 0) - (arr1[3] || 0)
+          total_diff += total
+          idle_diff += idle
+        end
+
+        if total_diff > 0
+          usages << ((1.0 - (idle_diff / total_diff)) * 100)
+        end
+      end
+
+      return nil if usages.empty?
+      (usages.sum / usages.size.to_f).round(1)
+    rescue StandardError
+      nil
+    end
+
     # Create singleton methods for each of the attributes.
     #
     def self.method_missing(id, arg = 0)
@@ -165,7 +231,9 @@ module Sys
           next
         end
 
-        vals = array[1..-1].map{ |e| e.to_i / 100 } # 100 jiffies/sec.
+        # Keep raw jiffies counts (do not scale by hz) so deltas over short
+        # intervals still produce meaningful values.
+        vals = array[1..-1].map{ |e| e.to_i }
         hash[array[0]] = vals
       end
 

data/lib/sys/unix/sys/cpu.rb

@@ -19,10 +19,11 @@ module Sys
     HW_MODEL        = 2  # Specific machine model
     HW_NCPU         = 3  # Number of CPU's
     HW_CPU_FREQ     = 15 # CPU frequency
+    HOST_OS         = RbConfig::CONFIG['host_os']
 
     private_constant :CTL_HW, :HW_MACHINE, :HW_MODEL, :HW_NCPU, :HW_CPU_FREQ
 
-    if RbConfig::CONFIG['host_os'] =~ /bsd|dragonfly/
+    if HOST_OS =~ /bsd|dragonfly/
       HW_MACHINE_ARCH = 11 # Machine architecture
     else
       HW_MACHINE_ARCH = 12 # Machine architecture
@@ -92,6 +93,7 @@ module Sys
       # Do nothing, not supported on this platform.
     end
 
+    # Private wrapper class for the procinfo struct
     class ProcInfo < FFI::Struct
       layout(
         :pi_state, :int,
@@ -101,6 +103,8 @@ module Sys
       )
     end
 
+    private_constant :ProcInfo
+
     # Returns the cpu's architecture. On most systems this will be identical
     # to the CPU.machine method. On OpenBSD it will be identical to the CPU.model
     # method.
@@ -238,6 +242,16 @@ module Sys
 
     # Returns an integer indicating the speed of the CPU.
     #
+    # Note that for BSD systems running on an aarch64 cpu this method
+    # will default to a hardclock timer value rather than the actual
+    # CPU frequency. This will typically be 1000 (or 100 on VM's).
+    #--
+    # If there's a better way please let me know. In my experiments locally
+    # stuff like dev.cpu.0 did NOT have the information that you might
+    # expect to find there, so we cannot rely on that either. In my defense,
+    # stuff like lscpu or dmesg did not have the freq information either,
+    # not on my aarch64 VM anyway.
+    #
     def self.freq
       if respond_to?(:sysctlbyname, true)
         optr = FFI::MemoryPointer.new(:long)
@@ -245,8 +259,12 @@ module Sys
 
         size.write_long(optr.size)
 
-        if RbConfig::CONFIG['host_os'] =~ /bsd|dragonfly/i
-          name = 'hw.clockrate'
+        if HOST_OS =~ /bsd|dragonfly/i
+          if architecture =~ /aarch/i
+            name = 'kern.hz'
+          else
+            name = 'hw.clockrate'
+          end
         else
           name = 'hw.cpufrequency'
         end
@@ -291,6 +309,52 @@ module Sys
       loadavg.get_array_of_double(0, 3)
     end
 
+    # Returns CPU usage as a percentage, averaged over a sampling interval.
+    #
+    # By default, samples CPU times twice, 1 second apart. Arguments are keyword-based
+    # (+sample_time:+, +samples:+). Passing nil, 0, or a negative value for either
+    # falls back to these defaults for cross-platform consistency.
+    #
+    def self.cpu_usage(sample_time: 1.0, samples: 2)
+      cp_time = proc { |ptr|
+        len = 5
+        size = FFI::MemoryPointer.new(:size_t)
+        size.write_ulong(ptr.size)
+
+        if sysctlbyname('kern.cp_time', ptr, size, nil, 0) < 0
+          raise Error, 'sysctlbyname failed'
+        end
+
+        ptr.read_array_of_ulong(len)
+      }
+
+      sample_time = 1.0 if sample_time.nil? || sample_time <= 0
+      samples = 2 if samples.nil? || samples <= 0
+
+      usages = []
+
+      samples.times do
+        t1 = cp_time.call(FFI::MemoryPointer.new(:ulong, 5))
+        sleep(sample_time)
+        t2 = cp_time.call(FFI::MemoryPointer.new(:ulong, 5))
+
+        total1 = t1.sum
+        total2 = t2.sum
+        idle1 = t1[4] || 0
+        idle2 = t2[4] || 0
+
+        total_diff = total2 - total1
+        idle_diff = idle2 - idle1
+
+        usages << ((1.0 - (idle_diff.to_f / total_diff)) * 100) if total_diff > 0
+      end
+
+      return nil if usages.empty?
+      (usages.sum / usages.size.to_f).round(1)
+    rescue StandardError
+      nil
+    end
+
     # Returns the floating point processor type.
     #
     # Not supported on all platforms.

data/lib/sys/windows/sys/cpu.rb

@@ -117,6 +117,46 @@ module Sys
       end
     end
 
+    # Returns CPU usage as a percentage, averaged over multiple samples.
+    #
+    # The +sample_time+ keyword specifies the interval (in seconds) between samples.
+    # The +samples+ keyword specifies how many samples to take and average.
+    # The +cpu_num+ keyword selects which CPU to query (0 for total).
+    # The +host+ keyword specifies the target machine (defaults to local).
+    #
+    #--
+    # This method uses the _Total Win32_PerfFormattedData_PerfOS_Processor instance
+    # (unless a specific +cpu_num+ is requested) to better match Task Manager's total view.
+    #
+    # Note: Task Manager reports total CPU usage across all cores. Win32_Processor.LoadPercentage
+    # is per-processor (usually per physical socket), so it can differ from Task Manager if it falls back.
+    #
+    def self.cpu_usage(sample_time: 1.0, samples: 2, cpu_num: 0, host: Socket.gethostname)
+      sample_time = 1.0 if sample_time.nil? || sample_time <= 0
+      samples = 2 if samples.nil? || samples <= 0
+      cpu_num = cpu_num.to_i if cpu_num.respond_to?(:to_i)
+      instance = cpu_num == 0 ? '_Total' : cpu_num.to_s
+      cs = BASE_CS + "//#{host}/root/cimv2:Win32_PerfFormattedData_PerfOS_Processor='#{instance}'"
+
+      usages = []
+
+      samples.times do
+        begin
+          wmi = WIN32OLE.connect(cs)
+        rescue WIN32OLERuntimeError
+          usages << load_avg(cpu_num, host)
+        else
+          result = wmi.PercentProcessorTime
+          usages << result.to_i if result
+        end
+        sleep(sample_time)
+      end
+
+      usages.compact!
+      return nil if usages.empty?
+      (usages.sum / usages.size.to_f).round(1)
+    end
+
     # Returns a string indicating the cpu model, e.g. Intel Pentium 4.
     #
     def self.model(host = Socket.gethostname)
@@ -390,6 +430,8 @@ module Sys
           'IA64'
         when 9
           'x64'
+        when 12
+          'ARM64'
       end
     end
 

data/spec/sys_cpu_bsd_spec.rb

@@ -8,14 +8,14 @@
 require 'sys/cpu'
 require 'spec_helper'
 
-RSpec.describe Sys::CPU, :bsd => true do
+RSpec.describe Sys::CPU, :bsd do
   example 'architecture method basic functionality' do
     expect(described_class).to respond_to(:architecture)
     expect{ described_class.architecture }.not_to raise_error
   end
 
   example 'architecture method returns a sane value' do
-    expect(described_class.architecture).to be_kind_of(String)
+    expect(described_class.architecture).to be_a(String)
     expect(described_class.architecture.size).to be > 0
   end
 
@@ -29,7 +29,7 @@ RSpec.describe Sys::CPU, :bsd => true do
   end
 
   example 'freq method returns expected value' do
-    expect(described_class.freq).to be_kind_of(Integer)
+    expect(described_class.freq).to be_a(Integer)
     expect(described_class.freq).to be > 0
   end
 
@@ -43,22 +43,42 @@ RSpec.describe Sys::CPU, :bsd => true do
   end
 
   example 'load_avg returns the expected results' do
-    expect(described_class.load_avg).to be_kind_of(Array)
+    expect(described_class.load_avg).to be_a(Array)
     expect(described_class.load_avg.length).to eq(3)
-    expect(described_class.load_avg[0]).to be_kind_of(Float)
+    expect(described_class.load_avg[0]).to be_a(Float)
   end
 
   example 'load_avg does not accept any arguments' do
     expect{ described_class.load_avg(0) }.to raise_error(ArgumentError)
   end
 
+  example 'cpu_usage works as expected' do
+    expect(described_class).to respond_to(:cpu_usage)
+    expect{ described_class.cpu_usage }.not_to raise_error
+    expect{ described_class.cpu_usage(sample_time: 0.1) }.not_to raise_error
+    expect(described_class.cpu_usage).to be_a(Numeric).or be_nil
+  end
+
+  example 'cpu_usage falls back on non-positive values' do
+    expect{ described_class.cpu_usage(sample_time: 0, samples: 0) }.not_to raise_error
+    expect{ described_class.cpu_usage(sample_time: -0.5, samples: -1) }.not_to raise_error
+    expect(described_class.cpu_usage(sample_time: 0, samples: 0)).to be_a(Numeric).or be_nil
+  end
+
+  example 'cpu_usage sampling produces a valid range' do
+    result = described_class.cpu_usage(sample_time: 0.1)
+    expect(result).to be_a(Numeric).or be_nil
+    expect(result).to be >= 0 if result
+    expect(result).to be <= 100 if result
+  end
+
   example 'machine method basic functionality' do
     expect(described_class).to respond_to(:machine)
     expect{ described_class.machine }.not_to raise_error
   end
 
   example 'machine method returns sane value' do
-    expect(described_class.machine).to be_kind_of(String)
+    expect(described_class.machine).to be_a(String)
     expect(described_class.machine.size).to be > 0
   end
 
@@ -72,7 +92,7 @@ RSpec.describe Sys::CPU, :bsd => true do
   end
 
   example 'model method returns sane value' do
-    expect(described_class.model).to be_kind_of(String)
+    expect(described_class.model).to be_a(String)
     expect(described_class.model.length).to be > 0
   end
 
@@ -86,7 +106,7 @@ RSpec.describe Sys::CPU, :bsd => true do
   end
 
   example 'num_cpu method returns expected value' do
-    expect(described_class.num_cpu).to be_kind_of(Integer)
+    expect(described_class.num_cpu).to be_a(Integer)
     expect(described_class.num_cpu).to be > 0
   end
 
@@ -94,8 +114,8 @@ RSpec.describe Sys::CPU, :bsd => true do
     expect{ described_class.num_cpu(0) }.to raise_error(ArgumentError)
   end
 
-  context "ffi methods and constants are private" do
-    example "ffi constants are private" do
+  context 'ffi methods and constants are private' do
+    example 'ffi constants are private' do
       constants = described_class.constants
       expect(constants).not_to include(:CTL_HW)
       expect(constants).not_to include(:CPU_TYPE_X86)
@@ -104,13 +124,13 @@ RSpec.describe Sys::CPU, :bsd => true do
       expect(constants).not_to include(:ClockInfo)
     end
 
-    example "ffi core methods are private" do
+    example 'ffi core methods are private' do
       methods = described_class.methods(false)
       expect(methods).not_to include(:attach_function)
       expect(methods).not_to include(:bitmask)
     end
 
-    example "ffi attached methods are private" do
+    example 'ffi attached methods are private' do
       methods = described_class.methods(false)
       expect(methods).not_to include(:sysctl)
       expect(methods).not_to include(:sysctlbyname)

data/spec/sys_cpu_hpux_spec.rb

@@ -9,30 +9,30 @@
 require 'sys/cpu'
 require 'spec_helper'
 
-RSpec.describe Sys::CPU, :hpux => true do
+RSpec.describe Sys::CPU, :hpux do
   example 'cpu_freq' do
     expect(described_class).to respond_to(:freq)
     expect{ described_class.freq }.not_to raise_error
     expect{ described_class.freq(0) }.not_to raise_error
-    expect(described_class.freq).to be_kind_of(Integer)
+    expect(described_class.freq).to be_a(Integer)
   end
 
   example 'num_cpu' do
     expect(described_class).to respond_to(:num_cpu)
     expect{ described_class.num_cpu }.not_to raise_error
-    expect(described_class.num_cpu).to be_kind_of(Integer)
+    expect(described_class.num_cpu).to be_a(Integer)
   end
 
   example 'num_active_cpu' do
     expect(described_class).to respond_to(:num_active_cpu)
     expect{ described_class.num_active_cpu }.not_to raise_error
-    expect(described_class.num_active_cpu).to be_kind_of(Integer)
+    expect(described_class.num_active_cpu).to be_a(Integer)
   end
 
   example 'cpu_architecture' do
     expect(described_class).to respond_to(:architecture)
     expect{ described_class.architecture }.not_to raise_error
-    expect(described_class.architecture).to be_kind_of(String)
+    expect(described_class.architecture).to be_a(String)
   end
 
   example 'load_avg basic sanity check' do
@@ -47,9 +47,29 @@ RSpec.describe Sys::CPU, :hpux => true do
   end
 
   example 'load_avg expected results' do
-    expect(described_class.load_avg).to be_kind_of(Array)
-    expect(described_class.load_avg(0)).to be_kind_of(Array)
+    expect(described_class.load_avg).to be_a(Array)
+    expect(described_class.load_avg(0)).to be_a(Array)
     expect(described_class.load_avg.length).to eq(3)
     expect(described_class.load_avg(0).length).to eq(3)
   end
+
+  example 'cpu_usage works as expected' do
+    expect(described_class).to respond_to(:cpu_usage)
+    expect{ described_class.cpu_usage }.not_to raise_error
+    expect{ described_class.cpu_usage(sample_time: 0.1) }.not_to raise_error
+    expect(described_class.cpu_usage).to be_a(Numeric).or be_nil
+  end
+
+  example 'cpu_usage falls back on non-positive values' do
+    expect{ described_class.cpu_usage(sample_time: 0, samples: 0) }.not_to raise_error
+    expect{ described_class.cpu_usage(sample_time: -1, samples: -1) }.not_to raise_error
+    expect(described_class.cpu_usage(sample_time: 0, samples: 0)).to be_a(Numeric).or be_nil
+  end
+
+  example 'cpu_usage sampling produces a valid range' do
+    result = described_class.cpu_usage(sample_time: 0.1)
+    expect(result).to be_a(Numeric).or be_nil
+    expect(result).to be >= 0 if result
+    expect(result).to be <= 100 if result
+  end
 end

data/spec/sys_cpu_linux_spec.rb

@@ -9,7 +9,7 @@
 require 'sys/cpu'
 require 'spec_helper'
 
-RSpec.describe Sys::CPU, :linux => true do
+RSpec.describe Sys::CPU, :linux do
   example 'dynamic methods are defined as expected' do
     expect do
       described_class.processors do |cs|
@@ -25,28 +25,47 @@ RSpec.describe Sys::CPU, :linux => true do
 
   example 'cpu_stats works as expected' do
     expect{ described_class.cpu_stats }.not_to raise_error
-    expect(described_class.cpu_stats).to be_kind_of(Hash)
+    expect(described_class.cpu_stats).to be_a(Hash)
     expect(described_class.cpu_stats['cpu0'].length).to be >= 4
   end
 
   example 'architecture works as expected' do
     expect{ described_class.architecture }.not_to raise_error
-    expect(described_class.architecture).to be_kind_of(String)
+    expect(described_class.architecture).to be_a(String)
   end
 
   example 'model works as expected' do
     expect{ described_class.model }.not_to raise_error
-    expect(described_class.model).to be_kind_of(String)
+    expect(described_class.model).to be_a(String)
   end
 
   example 'freq works as expected' do
     expect{ described_class.freq }.not_to raise_error
-    expect(described_class.freq).to be_kind_of(Numeric)
+    expect(described_class.freq).to be_a(Numeric)
   end
 
   example 'num_cpu works as expected' do
     expect{ described_class.num_cpu }.not_to raise_error
-    expect(described_class.num_cpu).to be_kind_of(Numeric)
+    expect(described_class.num_cpu).to be_a(Numeric)
+  end
+
+  example 'cpu_usage works as expected' do
+    expect{ described_class.cpu_usage }.not_to raise_error
+    expect(described_class.cpu_usage).to be_a(Numeric)
+  end
+
+  example 'cpu_usage falls back on non-positive values' do
+    expect{ described_class.cpu_usage(sample_time: 0, samples: 0) }.not_to raise_error
+    expect{ described_class.cpu_usage(sample_time: -1, samples: -2) }.not_to raise_error
+    expect(described_class.cpu_usage(sample_time: 0, samples: 0)).to be_a(Numeric)
+  end
+
+  example 'cpu_usage sampling produces a valid range' do
+    # Sampled usage should be a number between 0 and 100.
+    result = described_class.cpu_usage(sample_time: 0.1)
+    expect(result).to be_a(Numeric)
+    expect(result).to be >= 0
+    expect(result).to be <= 100
   end
 
   example 'bogus methods are not picked up by method_missing' do

data/spec/sys_cpu_shared.rb

@@ -11,7 +11,7 @@ require 'rspec'
 
 RSpec.shared_examples Sys::CPU do
   example 'version number is set to the expected value' do
-    expect(Sys::CPU::VERSION).to eq('1.1.0')
+    expect(Sys::CPU::VERSION).to eq('1.3.0')
   end
 
   example 'version number is frozen' do

data/spec/sys_cpu_windows_spec.rb

@@ -10,20 +10,20 @@ require 'spec_helper'
 require 'sys/cpu'
 require 'socket'
 
-RSpec.describe Sys::CPU, :windows => true do
+RSpec.describe Sys::CPU, :windows do
   let(:host) { Socket.gethostname }
 
   example 'architecture' do
     expect(described_class).to respond_to(:architecture)
     expect{ described_class.architecture }.not_to raise_error
     expect{ described_class.architecture(host) }.not_to raise_error
-    expect(described_class.architecture).to be_kind_of(String)
+    expect(described_class.architecture).to be_a(String)
   end
 
   example 'freq basic functionality' do
     expect(described_class).to respond_to(:freq)
     expect{ described_class.freq }.not_to raise_error
-    expect(described_class.freq).to be_kind_of(Integer)
+    expect(described_class.freq).to be_a(Integer)
   end
 
   example 'freq with arguments' do
@@ -35,28 +35,49 @@ RSpec.describe Sys::CPU, :windows => true do
     expect(described_class).to respond_to(:model)
     expect{ described_class.model }.not_to raise_error
     expect{ described_class.model(host) }.not_to raise_error
-    expect(described_class.model).to be_kind_of(String)
+    expect(described_class.model).to be_a(String)
   end
 
   example 'num_cpu' do
     expect(described_class).to respond_to(:num_cpu)
     expect{ described_class.num_cpu }.not_to raise_error
     expect{ described_class.num_cpu(host) }.not_to raise_error
-    expect(described_class.num_cpu).to be_kind_of(Integer)
+    expect(described_class.num_cpu).to be_a(Integer)
   end
 
   example 'cpu_type' do
     expect(described_class).to respond_to(:cpu_type)
     expect{ described_class.cpu_type }.not_to raise_error
     expect{ described_class.cpu_type(host) }.not_to raise_error
-    expect(described_class.cpu_type).to be_kind_of(String)
+    expect(described_class.cpu_type).to be_a(String)
   end
 
   example 'load_avg' do
     expect(described_class).to respond_to(:load_avg)
     expect{ described_class.load_avg }.not_to raise_error
     expect{ described_class.load_avg(0, host) }.not_to raise_error
-    expect(described_class.load_avg).to be_kind_of(Integer).or be_kind_of(NilClass)
+    expect(described_class.load_avg).to be_a(Integer).or be_a(NilClass)
+  end
+
+  example 'cpu_usage works as expected' do
+    expect(described_class).to respond_to(:cpu_usage)
+    expect{ described_class.cpu_usage }.not_to raise_error
+    expect{ described_class.cpu_usage(sample_time: 0.1, samples: 0, host: host) }.not_to raise_error
+    expect(described_class.cpu_usage).to be_a(Numeric).or be_a(NilClass)
+  end
+
+  example 'cpu_usage falls back on non-positive values' do
+    expect{ described_class.cpu_usage(sample_time: 0, samples: 0, host: host) }.not_to raise_error
+    expect{ described_class.cpu_usage(sample_time: -1, samples: -1, host: host) }.not_to raise_error
+    expect(described_class.cpu_usage(sample_time: 0, samples: 0, host: host)).to be_a(Numeric).or be_a(NilClass)
+  end
+
+  example 'cpu_usage sampling produces a valid range' do
+    # Sampled usage should be a number between 0 and 100.
+    result = described_class.cpu_usage(sample_time: 0.1)
+    expect(result).to be_a(Numeric).or be_nil
+    expect(result).to be >= 0 if result
+    expect(result).to be <= 100 if result
   end
 
   example 'processors' do

data/sys-cpu.gemspec

@@ -2,7 +2,7 @@ require 'rubygems'
 
 Gem::Specification.new do |spec|
   spec.name       = 'sys-cpu'
-  spec.version    = '1.1.0'
+  spec.version    = '1.3.0'
   spec.author     = 'Daniel J. Berger'
   spec.email      = 'djberg96@gmail.com'
   spec.license    = 'Apache-2.0'
@@ -17,6 +17,11 @@ Gem::Specification.new do |spec|
   # and Linux was worth the tradeoff of not having to create 3 separate gems.
   spec.add_dependency('ffi', '~> 1.1')
 
+  if Gem.win_platform?
+    spec.platform = Gem::Platform.new(['universal', 'mingw32'])
+    spec.add_dependency('win32ole')
+  end
+
   spec.add_development_dependency('rake')
   spec.add_development_dependency('rubocop')
   spec.add_development_dependency('rspec', '~> 3.9')
@@ -30,7 +35,8 @@ Gem::Specification.new do |spec|
     'source_code_uri'       => 'https://github.com/djberg96/sys-cpu',
     'wiki_uri'              => 'https://github.com/djberg96/sys-cpu/wiki',
     'rubygems_mfa_required' => 'true',
-    'github_repo'           => 'https://github.com/djberg96/sys-cpu'
+    'github_repo'           => 'https://github.com/djberg96/sys-cpu',
+    'funding_uri'           => 'https://github.com/sponsors/djberg96'
   }
 
   spec.description = <<-EOF

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: sys-cpu
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Daniel J. Berger
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -35,7 +34,7 @@ cert_chain:
   ORVCZpRuCPpmC8qmqxUnARDArzucjaclkxjLWvCVHeFa9UP7K3Nl9oTjJNv+7/jM
   WZs4eecIcUc4tKdHxcAJ0MO/Dkqq7hGaiHpwKY76wQ1+8xAh
   -----END CERTIFICATE-----
-date: 2024-06-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -157,7 +156,7 @@ metadata:
   wiki_uri: https://github.com/djberg96/sys-cpu/wiki
   rubygems_mfa_required: 'true'
   github_repo: https://github.com/djberg96/sys-cpu
-post_install_message:
+  funding_uri: https://github.com/sponsors/djberg96
 rdoc_options: []
 require_paths:
 - lib
@@ -172,8 +171,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A Ruby interface for providing CPU information
 test_files: