random-port 0.7.6 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19a3b6d51277760ad0638f741ef63bf1fbc8a4b77663b41569da4c34e251353a
-  data.tar.gz: 96e0c4061b43248cbf091e318b9e6645371a7fd11189a43cd1cadccf23b9704d
+  metadata.gz: dd90fdffc75dd2489cab29b75ddadb118d7399fc51acf86d0c7588cff3656bef
+  data.tar.gz: f8f40a67dd0fd7daf6fd7ad67e9272035a587b96dbaf581777f659a3d1779bd3
 SHA512:
-  metadata.gz: 6ac6711969efbcd97a534391cff9b3bb3e4244a5fe0a4518d7cbb3644a6b849507db8025af1491fac615c1aa9f3edf4db7d7bd9e42faf5619304191c1265afa0
-  data.tar.gz: f01a9a30993fcc100fd5946290a8f8b60d94cb8a19db6ab8b918527ca48086f92cff89723391d99302f79fc264ed9f4d76a2225bfdfa24819e3af51ec8971396
+  metadata.gz: 9b076ebfe2d5b5ec19a2252783e2e1d01050feebb698d5ef1066aefbb230708617fabba95f9a363b3c6dc03204ce8eb7de92d1d902c572374f69d7d1c979e9d5
+  data.tar.gz: c6f56a56d9b510904a982a78ed9e2cab315cdd8d5e21a0587ac3aae10c9da9e1435ebbf1bd888d92a0f34930b3032f99febcaae593268988685ea060ba2db70c

data/Gemfile

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 source 'https://rubygems.org'
 gemspec
 
-gem 'minitest', '~>5.25', require: false
+gem 'minitest', '~>6.0', require: false
+gem 'minitest-mock', '~>5.27', require: false
+gem 'minitest-reporters', '~>1.7', require: false
 gem 'qbash', '~>0.2', require: false
 gem 'rake', '~>13.2', require: false
 gem 'rubocop', '~>1.75', require: false
@@ -15,5 +17,6 @@ gem 'rubocop-performance', '~>1.25', require: false
 gem 'rubocop-rake', '~>0.7', require: false
 gem 'rubocop-rspec', '~> 3.7', require: false
 gem 'simplecov', '~>0.22', require: false
+gem 'simplecov-cobertura', '~>3.0', require: false
 gem 'threads', '~>0.4', require: false
 gem 'yard', '~>0.9', require: false

data/Gemfile.lock

@@ -7,35 +7,47 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    ansi (1.5.0)
     ast (2.4.3)
     backtrace (0.4.1)
-    concurrent-ruby (1.3.5)
+    builder (3.3.0)
+    concurrent-ruby (1.3.6)
     docile (1.4.1)
-    elapsed (0.2.0)
+    elapsed (0.2.2)
       loog (~> 0.6)
       tago (~> 0.1)
-    json (2.15.0)
+    ellipsized (0.3.0)
+    json (2.18.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    loog (0.6.1)
+    loog (0.7.2)
+      ellipsized
       logger (~> 1.0)
-    minitest (5.25.5)
+    minitest (6.0.1)
+      prism (~> 1.5)
+    minitest-mock (5.27.0)
+    minitest-reporters (1.7.1)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.1)
       ast (~> 2.4.1)
       racc
-    prism (1.5.1)
-    qbash (0.4.5)
+    prism (1.8.0)
+    qbash (0.7.2)
       backtrace (> 0)
       elapsed (> 0)
       loog (> 0)
       tago (> 0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
+    rake (13.3.1)
     regexp_parser (2.11.3)
-    rubocop (1.80.2)
+    rexml (3.4.4)
+    rubocop (1.84.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -43,41 +55,44 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.46.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     rubocop-minitest (0.38.2)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
-    rubocop-performance (1.26.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.7.0)
+    rubocop-rspec (3.9.0)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      rubocop (~> 1.81)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
+    simplecov-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    tago (0.2.0)
-    threads (0.4.1)
+    tago (0.7.0)
+    threads (0.5.0)
       backtrace (~> 0)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
-    yard (0.9.37)
+    unicode-emoji (4.2.0)
+    yard (0.9.38)
 
 PLATFORMS
   arm64-darwin-22
@@ -87,7 +102,9 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  minitest (~> 5.25)
+  minitest (~> 6.0)
+  minitest-mock (~> 5.27)
+  minitest-reporters (~> 1.7)
   qbash (~> 0.2)
   rake (~> 13.2)
   random-port!
@@ -97,6 +114,7 @@ DEPENDENCIES
   rubocop-rake (~> 0.7)
   rubocop-rspec (~> 3.7)
   simplecov (~> 0.22)
+  simplecov-cobertura (~> 3.0)
   threads (~> 0.4)
   yard (~> 0.9)
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2018-2025 Yegor Bugayenko
+Copyright (c) 2018-2026 Yegor Bugayenko
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the 'Software'), to deal

data/LICENSES/MIT.txt

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2018-2025 Yegor Bugayenko
+Copyright (c) 2018-2026 Yegor Bugayenko
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the 'Software'), to deal

data/README.md

@@ -9,7 +9,7 @@
 [![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/yegor256/random-port/master/frames)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/random-port/blob/master/LICENSE.txt)
 [![Test Coverage](https://img.shields.io/codecov/c/github/yegor256/random-port.svg)](https://codecov.io/github/yegor256/random-port?branch=master)
-[![Hits-of-Code](https://hitsofcode.com/github/yegor256/random-port)](https://hitsofcode.com/view/github/random-port/mailanes)
+[![Hits-of-Code](https://hitsofcode.com/github/yegor256/random-port)](https://hitsofcode.com/view/github/yegor256/random-port)
 
 It's a simple Ruby gem to get a random TCP port.
 
@@ -52,6 +52,15 @@ RandomPort::Pool::SINGLETON.acquire do |port|
 end
 ```
 
+Or use shortened version, all methods called in `RandomPort`
+will be delegated to `Pool::SINGLETON`:
+
+```ruby
+RandomPort.acquire do |port|
+  # Use it here...
+end
+```
+
 The pool is thread-safe by default.
 You can configure it to be
 not-thread-safe, using optional `sync` argument of the constructor.

data/Rakefile

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 require 'rubygems'
@@ -37,4 +37,5 @@ require 'yard'
 desc 'Build Yard documentation'
 YARD::Rake::YardocTask.new do |t|
   t.files = ['lib/**/*.rb']
+  t.options = ['--fail-on-warning']
 end

data/lib/random-port/module.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-# The module for all classes.
+# Main module that contains all RandomPort classes and utilities.
+#
+# This module provides a simple way to acquire random TCP ports
+# that are guaranteed to be available for use. It includes a Pool
+# class that manages port allocation and ensures thread safety.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2018-2025 Yegor Bugayenko
+# Copyright:: Copyright (c) 2018-2026 Yegor Bugayenko
 # License:: MIT
 module RandomPort
+  extend Forwardable
+
+  def_delegators :'RandomPort::Pool::SINGLETON', :acquire, :release, :count, :size, :empty?
+  module_function :acquire, :release, :count, :size, :empty?
 end

data/lib/random-port/pool.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 require 'monitor'
@@ -8,7 +8,7 @@ require 'socket'
 require 'tago'
 require_relative 'module'
 
-# Pool of TPC ports.
+# Pool of TCP ports.
 #
 # Use it like this:
 #
@@ -17,26 +17,27 @@ require_relative 'module'
 #    # to the pool afterwards.
 #  end
 #
-# You can specify the maximum amount of ports to acquire, using +limit+.
-# If more acquiring requests will arrive, an exception will be raised.
+# You can specify the maximum number of ports to acquire using +limit+.
+# If more acquisition requests arrive, an exception will be raised.
 #
-# The class is thread-safe, by default. You can configure it to be
-# not-thread-safe, using optional +sync+ argument of the constructor,
+# The class is thread-safe by default. You can configure it to be
+# non-thread-safe using the optional +sync+ argument of the constructor,
 # passing <tt>FALSE</tt>.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2018-2025 Yegor Bugayenko
+# Copyright:: Copyright (c) 2018-2026 Yegor Bugayenko
 # License:: MIT
 class RandomPort::Pool
-  # If can't acquire by time out.
+  # Raised when a port cannot be acquired within the timeout period.
   class Timeout < StandardError; end
 
+  # @return [Integer] The maximum number of ports that can be acquired from this pool
   attr_reader :limit
 
-  # Ctor.
-  # @param [Boolean] sync Set it to FALSE if you want this pool to be NOT thread-safe
-  # @param [Integer] limit Set the maximum number of ports in the pool
-  # @param [Integer] start The next port to try
+  # Constructor.
+  # @param [Boolean] sync Set to FALSE if you want this pool to be non-thread-safe
+  # @param [Integer] limit The maximum number of ports that can be acquired from the pool
+  # @param [Integer] start The first port number to try when acquiring
   def initialize(sync: true, limit: 65_536, start: 1025)
     @ports = []
     @sync = sync
@@ -45,27 +46,33 @@ class RandomPort::Pool
     @next = start
   end
 
-  # Application wide pool of ports
+  # Application-wide singleton pool of ports.
   SINGLETON = RandomPort::Pool.new
 
-  # How many ports acquired now?
+  # Returns the number of ports currently acquired from the pool.
+  # @return [Integer] The count of acquired ports
   def count
     @ports.count
   end
   alias size count
 
-  # Is it empty?
+  # Checks if the pool is empty (no ports are currently acquired).
+  # @return [Boolean] TRUE if no ports are acquired, FALSE otherwise
   def empty?
     @ports.empty?
   end
 
-  # Acquire a new random TCP port.
+  # Acquires one or more available TCP ports from the pool.
   #
   # You can specify the number of ports to acquire. If it's more than one,
-  # an array will be returned.
+  # an array will be returned. If a block is given, the port(s) will be
+  # automatically released after the block execution.
   #
-  # You can specify the amount of seconds to wait until a new port
-  # is available.
+  # @param [Integer] total The number of ports to acquire (default: 1)
+  # @param [Integer] timeout The maximum seconds to wait for port availability
+  # @yield [Integer|Array<Integer>] The acquired port(s)
+  # @return [Integer|Array<Integer>] The acquired port(s) if no block given
+  # @raise [Timeout] If ports cannot be acquired within the timeout period
   def acquire(total = 1, timeout: 4)
     start = Time.now
     attempt = 0
@@ -77,7 +84,7 @@ class RandomPort::Pool
           "(#{@ports.size} already occupied) " \
           "for #{total} port(s), after #{attempt} attempts in #{start.ago}"
       end
-      attempt +=  1
+      attempt += 1
       opts = safe { group(total) }
       if opts.nil?
         @next += 1
@@ -96,9 +103,9 @@ class RandomPort::Pool
     end
   end
 
-  # Return it/them back to the pool.
-  # @param [Integer] port TCP port number to release
-  # @return nil
+  # Releases one or more ports back to the pool.
+  # @param [Integer|Array<Integer>] port The TCP port number(s) to release
+  # @return [nil]
   def release(port)
     safe do
       if port.is_a?(Array)
@@ -111,12 +118,12 @@ class RandomPort::Pool
 
   private
 
-  # Take a group of ports, if possible.
-  # @param [Integer] total How many ports to take
-  # @return [Array<Integer>|nil] Ports found or NIL if impossible now
+  # Attempts to acquire a contiguous group of ports.
+  # @param [Integer] total The number of ports to acquire
+  # @return [Array<Integer>|nil] An array of port numbers if successful, nil otherwise
   def group(total)
     return nil if @ports.count + total > @limit
-    opts = Array.new(0, total)
+    opts = Array.new(total, 0)
     begin
       (0..(total - 1)).each do |i|
         port = i.zero? ? @next : opts[i - 1] + 1
@@ -132,12 +139,15 @@ class RandomPort::Pool
     opts
   end
 
-  # Find one possible TCP port or raise exception if this port can't be used.
+  # Verifies that a specific TCP port is available for use.
   #
-  # If port is occupied, this method raises an error (+Errno::EADDRINUSE+).
+  # Attempts to bind to the port on various interfaces to ensure availability.
+  # If the port is occupied, this method raises an error (+Errno::EADDRINUSE+).
   #
-  # @param [Integer] port Suggested port number
-  # @return [Integer] The same port number
+  # @param [Integer] port The port number to verify
+  # @return [Integer] The same port number if available
+  # @raise [Errno::EADDRINUSE] If the port is already in use
+  # @raise [SocketError] If there's a socket-related error
   def take(port)
     ['127.0.0.1', '::1', '0.0.0.0', 'localhost'].each do |host|
       begin
@@ -149,6 +159,9 @@ class RandomPort::Pool
     port
   end
 
+  # Executes a block of code with or without thread synchronization.
+  # @param block The block of code to execute
+  # @return The result of the block execution
   def safe(&block)
     if @sync
       @monitor.synchronize(&block)

data/lib/random-port.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 require_relative 'random-port/module'

data/random-port.gemspec

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SPDX-FileCopyrightText: Copyright (c) 2018-2025 Yegor Bugayenko
+# SPDX-FileCopyrightText: Copyright (c) 2018-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
 require 'English'
@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
   s.required_ruby_version = '>=2.3'
   s.name = 'random-port'
-  s.version = '0.7.6'
+  s.version = '0.8.0'
   s.license = 'MIT'
   s.summary = 'Random TCP port'
   s.description = 'Reserves a random TCP port'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: random-port
 version: !ruby/object:Gem::Version
-  version: 0.7.6
+  version: 0.8.0
 platform: ruby
 authors:
 - Yegor Bugayenko