maxprocs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2d7c7f470760666f2720e464ba8ed42f8dc50af36b51c57b651cc2db22dd0b36
+  data.tar.gz: be7f37e10296aa00a6cbebdc707a3078bdb1bd65cd0826da27d91378a67463d6
+SHA512:
+  metadata.gz: 680234708f8bb39980e712d8476d1e08adfc8e6801cb49c917b42a9adda2fca00041aafafb37f91a4d479f292816faceeea9f0e433c5f76131de488830b6e7a8
+  data.tar.gz: 94ee3bd32395c3c943f6495ab4883aa54d427a512a70166010a13425a89292ce9250f5804c311d9ed4c99ff7aaa695f7814c26e759174d2fe233f335bf98d899

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-19
+
+- Initial release
+

data/README.md

@@ -0,0 +1,103 @@
+# maxprocs-ruby [![CI](https://github.com/moznion/maxprocs-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/moznion/maxprocs-ruby/actions/workflows/ci.yml)
+
+A lightweight Ruby gem that detects CPU quota from Linux cgroups and returns the appropriate number of processors.
+
+This is a Ruby equivalent of Go's [uber-go/automaxprocs](https://github.com/uber-go/automaxprocs).
+
+## Problem
+
+Ruby's `Etc.nprocessors` does not consider cgroup CPU quota - it returns the host's CPU count. In container environments (e.g., Docker/Kubernetes), the actual available CPU count differs from the host's CPU count.
+
+For example, this causes Puma/Sidekiq worker counts to be excessive, leading to CPU throttling.
+
+```ruby
+# On a 64-core host with 2 CPU limit container
+Etc.nprocessors # => 64 (host CPUs, not what you want)
+Maxprocs.count # => 2  (container limit, what you want)
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'maxprocs'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install maxprocs
+```
+
+## Synopsis
+
+```ruby
+require 'maxprocs'
+
+# Get CPU count considering cgroup quota (Integer)
+Maxprocs.count # => 2
+
+# Get raw quota value (Float or nil)
+Maxprocs.quota # => 2.5 (nil if unlimited)
+
+# Check if CPU is limited
+Maxprocs.limited? # => true/false
+
+# Get cgroup version
+Maxprocs.cgroup_version # => :v1, :v2, or :none
+
+# Clear cache (for testing)
+Maxprocs.reset!
+
+# Rounding options
+Maxprocs.count(round: :floor) # => 2
+Maxprocs.count(round: :ceil) # => 3
+```
+
+## API Reference
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `Maxprocs.count(round:)` | `Integer` | CPU count (minimum 1). `round: :floor` (default) or `:ceil` |
+| `Maxprocs.quota` | `Float` or `nil` | Raw quota value, `nil` if unlimited |
+| `Maxprocs.limited?` | `Boolean` | `true` if CPU quota is set |
+| `Maxprocs.cgroup_version` | `Symbol` | `:v1`, `:v2`, or `:none` |
+| `Maxprocs.reset!` | `void` | Clear cached values |
+
+Use `maxprocs` when you only need cgroup-aware CPU count detection and want to minimize dependencies.
+
+## Limitations
+
+- On macOS/Windows, always falls back to `Etc.nprocessors`
+- cpu.shares not supported: Only `cpu.cfs_quota_us`/`cpu.max` are read (shares are relative weights, not absolute limits)
+- Direct cgroup only: Does not traverse parent cgroups
+- Some platforms return -1: Some environments may return unlimited quota
+
+## Requirements
+
+- Ruby 3.2+
+
+## Development
+
+```bash
+bundle install
+bundle exec rake
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/moznion/maxprocs-ruby.
+
+## Related Projects
+
+- [uber-go/automaxprocs](https://github.com/uber-go/automaxprocs) - Go implementation (inspiration for this gem)
+- [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) - Full-featured concurrency library with cgroup support
+- [Go 1.25 GOMAXPROCS](https://github.com/golang/go/issues/73193) - Native Go runtime cgroup support
+

data/lib/maxprocs/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Maxprocs
+  VERSION = "0.1.0" #: String
+end

data/lib/maxprocs.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "etc"
+require_relative "maxprocs/version"
+
+# Maxprocs detects CPU quota from Linux cgroups and returns the appropriate
+# number of processors for container environments.
+module Maxprocs
+  CGROUP_FILE_PATH = "/proc/self/cgroup"
+  CGROUP_V1_QUOTA_PATH = "/sys/fs/cgroup/cpu/cpu.cfs_quota_us"
+  CGROUP_V1_PERIOD_PATH = "/sys/fs/cgroup/cpu/cpu.cfs_period_us"
+  CGROUP_V2_CONTROLLERS_PATH = "/sys/fs/cgroup/cgroup.controllers"
+  CGROUP_V2_CPU_MAX_PATH = "/sys/fs/cgroup/cpu.max"
+
+  @mutex = Mutex.new # Thread-safe memoization using a mutex
+  @quota_cache = nil
+  @version_cache = nil
+  @initialized = false
+
+  class << self
+    # Returns the number of CPUs available, considering cgroup quota.
+    #
+    # @rbs round: Symbol -- :floor (default) or :ceil for rounding method
+    # @rbs return: Integer -- the number of CPUs (minimum 1)
+    def count(round: :floor)
+      q = quota
+      return Etc.nprocessors if q.nil?
+
+      result = case round
+      when :ceil
+        q.ceil
+      else
+        q.floor
+      end
+
+      [result, 1].max
+    end
+
+    # Returns the raw CPU quota as a float.
+    #
+    # @rbs return: Float? -- the quota (e.g., 2.5 for 2.5 CPUs), or nil if unlimited
+    def quota
+      ensure_initialized
+      @quota_cache
+    end
+
+    # Returns whether CPU is limited by cgroup.
+    #
+    # @rbs return: bool -- true if CPU quota is set
+    def limited?
+      !quota.nil?
+    end
+
+    # Returns the detected cgroup version.
+    #
+    # @rbs return: Symbol -- :v1, :v2, or :none
+    def cgroup_version
+      ensure_initialized
+      @version_cache
+    end
+
+    # Clears the cached values. Useful for testing.
+    #
+    # @rbs return: void
+    def reset!
+      @mutex.synchronize do
+        @quota_cache = nil
+        @version_cache = nil
+        @initialized = false
+      end
+    end
+
+    private
+
+    # @rbs return: void
+    def ensure_initialized
+      return if @initialized
+
+      @mutex.synchronize do
+        return if @initialized
+
+        @version_cache = detect_cgroup_version
+        @quota_cache = read_quota
+        @initialized = true
+      end
+    end
+
+    # @rbs return: Symbol
+    def detect_cgroup_version
+      return :none unless File.exist?(CGROUP_FILE_PATH)
+
+      # Check for cgroup v2 first
+      if File.exist?(CGROUP_V2_CONTROLLERS_PATH)
+        return :v2
+      end
+
+      if File.exist?(CGROUP_V1_QUOTA_PATH)
+        return :v1
+      end
+
+      :none
+    end
+
+    # @rbs return: Float?
+    def read_quota
+      case @version_cache
+      when :v2
+        read_quota_v2
+      when :v1
+        read_quota_v1
+      end
+    rescue Errno::ENOENT, Errno::EACCES, Errno::EINVAL
+      # File doesn't exist, permission denied, or invalid - fallback to unlimited
+      nil
+    end
+
+    # @rbs return: Float?
+    def read_quota_v1
+      quota = File.read(CGROUP_V1_QUOTA_PATH).strip.to_i
+      return nil if quota == -1 # -1 means unlimited
+
+      period = File.read(CGROUP_V1_PERIOD_PATH).strip.to_i
+      return nil if period <= 0
+
+      quota.to_f / period
+    end
+
+    # @rbs return: Float?
+    def read_quota_v2
+      content = File.read(CGROUP_V2_CPU_MAX_PATH).strip
+      parts = content.split
+
+      max_str = parts[0]
+      return nil if max_str == "max" # "max" means unlimited
+
+      period_str = parts[1]
+      return nil if period_str.nil?
+
+      max = max_str.to_f
+      period = period_str.to_f
+      return nil if period <= 0
+
+      max / period
+    end
+  end
+end

data/sig/generated/maxprocs/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/maxprocs/version.rb with RBS::Inline
+
+module Maxprocs
+  VERSION: String
+end

data/sig/generated/maxprocs.rbs

@@ -0,0 +1,56 @@
+# Generated from lib/maxprocs.rb with RBS::Inline
+
+# Maxprocs detects CPU quota from Linux cgroups and returns the appropriate
+# number of processors for container environments.
+module Maxprocs
+  CGROUP_FILE_PATH: ::String
+
+  CGROUP_V1_QUOTA_PATH: ::String
+
+  CGROUP_V1_PERIOD_PATH: ::String
+
+  CGROUP_V2_CONTROLLERS_PATH: ::String
+
+  CGROUP_V2_CPU_MAX_PATH: ::String
+
+  # Returns the number of CPUs available, considering cgroup quota.
+  #
+  # @rbs round: Symbol -- :floor (default) or :ceil for rounding method
+  # @rbs return: Integer -- the number of CPUs (minimum 1)
+  def self.count: (?round: Symbol) -> Integer
+
+  # Returns the raw CPU quota as a float.
+  #
+  # @rbs return: Float? -- the quota (e.g., 2.5 for 2.5 CPUs), or nil if unlimited
+  def self.quota: () -> Float?
+
+  # Returns whether CPU is limited by cgroup.
+  #
+  # @rbs return: bool -- true if CPU quota is set
+  def self.limited?: () -> bool
+
+  # Returns the detected cgroup version.
+  #
+  # @rbs return: Symbol -- :v1, :v2, or :none
+  def self.cgroup_version: () -> Symbol
+
+  # Clears the cached values. Useful for testing.
+  #
+  # @rbs return: void
+  def self.reset!: () -> void
+
+  # @rbs return: void
+  private def self.ensure_initialized: () -> void
+
+  # @rbs return: Symbol
+  private def self.detect_cgroup_version: () -> Symbol
+
+  # @rbs return: Float?
+  private def self.read_quota: () -> Float?
+
+  # @rbs return: Float?
+  private def self.read_quota_v1: () -> Float?
+
+  # @rbs return: Float?
+  private def self.read_quota_v2: () -> Float?
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: maxprocs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- moznion
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.52'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.52'
+- !ruby/object:Gem::Dependency
+  name: rbs-inline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: steep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+description: |
+  A lightweight Ruby gem that detects CPU quota from Linux cgroups (v1 and v2)
+  and returns the appropriate number of processors for container environments.
+  This is a Ruby equivalent of Go's uber-go/automaxprocs.
+email:
+- moznion@mail.moznion.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/maxprocs.rb
+- lib/maxprocs/version.rb
+- sig/generated/maxprocs.rbs
+- sig/generated/maxprocs/version.rbs
+homepage: https://github.com/moznion/maxprocs-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/moznion/maxprocs-ruby
+  source_code_uri: https://github.com/moznion/maxprocs-ruby
+  changelog_uri: https://github.com/moznion/maxprocs-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Detect CPU quota from Linux cgroups for container environments
+test_files: []