process-metrics 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2822c0b3ad1a6e79d294cc8607359b1a8042818a8b07306c5685064addd4b7fd
-  data.tar.gz: f945a7b3bcf467f696c9823a11ecefa996aae3f7e9d075bcfcd6bba87edd13d1
+  metadata.gz: 86b26a801c95a764b0f98139e25ad1ac12b455b1b44b664722d1ff189bce8be4
+  data.tar.gz: 7591aff04fdbc4e9b6eabdd42ac8bcdf6ffbeea605f812b1d00255a57cba49c5
 SHA512:
-  metadata.gz: 5869ec2e258caad4625fc45f9ee572ebbf9803592f0b8ed1115e80a5f21ad7b36acc3122c9d17aa5c8816c33d76bc4393c3d6620f2ec15f44e065701168ee952
-  data.tar.gz: 7b0a434ceba0c1b0d89297825a5bde80999542e10060e5aa89bafc34e44529e75323ad5de3b3ad792e7bdaee87856e64111ba209026e597203eeed8c6ca3aad9
+  metadata.gz: 1a688f8a4db31df31adbbc5d5513716785ff61047f0b010aba506064d4c981dc5582fe99784eef0d244f877643034325d0996a323cc91e3ee1d6e6caa0e0f8e9
+  data.tar.gz: 72d8c7499461b35deafd4af20ba6c065de44f76d8868971e3ab70795febbb2863df98f9cb06c1e82e94fc1cdc7867275d58e1e03f9aa9ea890d50c5a37cf05bb

data/context/getting-started.md

@@ -112,3 +112,17 @@ sample.utilization
 ```
 
 Both interfaces use the same core-unit scale. A utilization of `0.5` means half of one core on average, while `2.0` means two cores were fully occupied. Utilization is therefore not limited to the range `0.0..1.0`.
+
+## Processor Capacity
+
+Use {ruby Process::Metrics::Processor.count} to get the number of processors available to the current process. On Linux, this takes CPU affinity into account.
+
+Use {ruby Process::Metrics::Processor.quota} to get the available processor capacity as a `Float`. On Linux, it also takes cgroup v2 CPU bandwidth limits into account. On other systems, when no finite quota is configured, or when the quota cannot be determined, it returns {ruby Process::Metrics::Processor.count} as a `Float`.
+
+``` ruby
+Process::Metrics::Processor.count
+# => 8
+
+Process::Metrics::Processor.quota
+# => 1.5
+```

data/lib/process/metrics/processor/linux.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		class Processor
+			# @private
+			module Linux
+				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
+				DEFAULT_CGROUP_PATH = "/proc/self/cgroup"
+				
+				class << self
+					# Read the effective processor quota for the current cgroup.
+					# @parameter cgroup_root [String] The root of the cgroup v2 filesystem.
+					# @parameter cgroup_path [String] The process cgroup membership file.
+					# @returns [Float | Nil] The smallest finite quota in the cgroup hierarchy, if available.
+					def quota(cgroup_root: DEFAULT_CGROUP_ROOT, cgroup_path: DEFAULT_CGROUP_PATH)
+						unless relative_path = current_path(cgroup_path)
+							return nil
+						end
+						
+						root = File.expand_path(cgroup_root)
+						directory = File.expand_path(relative_path.delete_prefix("/"), root)
+						return nil unless directory == root || directory.start_with?("#{root}/")
+						
+						quota = nil
+						
+						loop do
+							if current = read_quota(directory)
+								quota = [quota, current].compact.min
+							end
+							
+							break if directory == root
+							directory = File.dirname(directory)
+						end
+						
+						return quota
+					rescue Errno::EACCES, Errno::EINVAL, Errno::ENOENT, Errno::ENOTDIR, ArgumentError
+						return nil
+					end
+					
+					private
+					
+					def current_path(path)
+						File.foreach(path) do |line|
+							hierarchy, controllers, relative_path = line.strip.split(":", 3)
+							
+							if hierarchy == "0" && controllers == "" && relative_path
+								return relative_path
+							end
+						end
+						
+						return nil
+					end
+					
+					def read_quota(directory)
+						maximum, period = File.read(File.join(directory, "cpu.max")).split
+						return nil if maximum == "max" || !maximum || !period
+						
+						maximum = Integer(maximum)
+						period = Integer(period)
+						return nil unless maximum.positive? && period.positive?
+						
+						return maximum.to_f / period
+					rescue Errno::EACCES, Errno::EINVAL, Errno::ENOENT, Errno::ENOTDIR, ArgumentError
+						return nil
+					end
+				end
+			end
+			
+			# The processor capacity available to the current process.
+			# This takes cgroup v2 CPU bandwidth limits into account, and otherwise returns {count} as a `Float`.
+			# @returns [Float] The available processor capacity in core units.
+			def self.quota
+				count = self.count.to_f
+				
+				if quota = Linux.quota
+					if quota < count
+						return quota
+					end
+				end
+				
+				return count
+			end
+		end
+	end
+end

data/lib/process/metrics/processor.rb

@@ -3,10 +3,26 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
+require "etc"
+
 module Process
 	module Metrics
 		# Computes interval CPU utilization from cumulative process metrics.
 		class Processor
+			# The number of processors available to the current process.
+			# On Linux, this takes the process CPU affinity into account.
+			# @returns [Integer] The number of available processors.
+			def self.count
+				Etc.nprocessors
+			end
+			
+			# The processor capacity available to the current process.
+			# On Linux, this takes cgroup v2 CPU bandwidth limits into account. Otherwise, it returns {count} as a `Float`.
+			# @returns [Float] The available processor capacity in core units.
+			def self.quota
+				return self.count.to_f
+			end
+			
 			# An immutable measurement of process CPU usage over an interval.
 			# @attribute [Integer] The process ID.
 			# @attribute [Float] The elapsed monotonic time in seconds.
@@ -79,3 +95,7 @@ module Process
 		end
 	end
 end
+
+if RUBY_PLATFORM.include?("linux")
+	require_relative "processor/linux"
+end

data/lib/process/metrics/version.rb

@@ -7,6 +7,6 @@
 module Process
 	# @namespace
 	module Metrics
-		VERSION = "0.13.0"
+		VERSION = "0.14.0"
 	end
 end

data/readme.md

@@ -16,6 +16,10 @@ Please see the [project documentation](https://socketry.github.io/process-metric
 
 Please see the [project releases](https://socketry.github.io/process-metrics/releases/index) for all releases.
 
+### v0.14.0
+
+  - Add `Process::Metrics::Processor.count` and `.quota` for affinity-aware processor counts and cgroup v2-aware processor capacity.
+
 ### v0.13.0
 
   - Normalize processor utilization to core units, where `1.0` represents one fully occupied CPU core, and restore Linux reporting.
@@ -56,10 +60,6 @@ Please see the [project releases](https://socketry.github.io/process-metrics/rel
 
   - Be more proactive about returning nil if memory capture failed.
 
-### v0.6.1
-
-  - Handle `Errno::ESRCH: No such process @ io_fillbuf - fd:xxx /proc/xxx/smaps_rollup` by ignoring it.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.14.0
+
+  - Add `Process::Metrics::Processor.count` and `.quota` for affinity-aware processor counts and cgroup v2-aware processor capacity.
+
 ## v0.13.0
 
   - Normalize processor utilization to core units, where `1.0` represents one fully occupied CPU core, and restore Linux reporting.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -89,6 +89,7 @@ files:
 - lib/process/metrics/memory/darwin.rb
 - lib/process/metrics/memory/linux.rb
 - lib/process/metrics/processor.rb
+- lib/process/metrics/processor/linux.rb
 - lib/process/metrics/version.rb
 - license.md
 - readme.md