puma 7.0.4 → 8.0.0

data/lib/puma/cluster.rb

@@ -23,7 +23,7 @@ module Puma
       @next_check = Time.now
 
       @worker_max = [] # keeps track of 'max' stat values
-      @phased_restart = false
+      @pending_phased_restart = false
     end
 
     # Returns the list of cluster worker handles.
@@ -87,7 +87,7 @@ module Puma
         end
 
         debug "Spawned worker: #{pid}"
-        @workers << WorkerHandle.new(idx, pid, @phase, @options)
+        @workers.insert(idx, WorkerHandle.new(idx, pid, @phase, @options))
       end
 
       if @options[:fork_worker] && all_workers_in_phase?
@@ -186,7 +186,7 @@ module Puma
         # we need to phase any workers out (which will restart
         # in the right phase).
         #
-        w = @workers.find { |x| x.phase != @phase }
+        w = @workers.find { |x| x.phase < @phase }
 
         if w
           if refork
@@ -221,12 +221,11 @@ module Puma
         pipes[:wakeup] = @wakeup
       end
 
-      server = start_server if preload?
       new_worker = Worker.new index: index,
                               master: master,
                               launcher: @launcher,
                               pipes: pipes,
-                              server: server
+                              app: (app if preload?)
       new_worker.run
     end
 
@@ -238,7 +237,7 @@ module Puma
     def phased_restart(refork = false)
       return false if @options[:preload_app] && !refork
 
-      @phased_restart = refork ? :refork : true
+      @pending_phased_restart = refork ? :refork : true
       wakeup!
 
       true
@@ -456,11 +455,11 @@ module Puma
               break
             end
 
-            if @phased_restart
-              start_phased_restart(@phased_restart == :refork)
+            if @pending_phased_restart
+              start_phased_restart(@pending_phased_restart == :refork)
 
-              in_phased_restart = @phased_restart
-              @phased_restart = false
+              in_phased_restart = @pending_phased_restart
+              @pending_phased_restart = false
 
               workers_not_booted = @options[:workers]
               # worker 0 is not restarted on refork
@@ -583,7 +582,9 @@ module Puma
           #    `Process.wait2(-1)` from detecting a terminated process: https://bugs.ruby-lang.org/issues/19837.
           # 2. When `fork_worker` is enabled, some worker may not be direct children,
           #    but grand children.  Because of this they won't be reaped by `Process.wait2(-1)`.
-          if reaped_children.delete(w.pid) || Process.wait(w.pid, Process::WNOHANG)
+          if (status = reaped_children.delete(w.pid) || Process.wait2(w.pid, Process::WNOHANG)&.last)
+            w.process_status = status
+            @config.run_hooks(:after_worker_shutdown, w, @log_writer)
             true
           else
             w.term if w.term?

data/lib/puma/cluster_accept_loop_delay.rb

@@ -20,48 +20,47 @@ module Puma
   # already https://github.com/puma/puma/pull/3678/files/2736ebddb3fc8528e5150b5913fba251c37a8bf7#diff-a95f46e7ce116caddc9b9a9aa81004246d5210d5da5f4df90a818c780630166bL251-L291
   #
   # With the introduction of true keepalive support, there are two ways a request can come in:
-  # - A new request from a new client comes into the socket and it must be "accept"-d
+  # - A new request from a new client comes into the socket and it must be "accept"-ed
   # - A keepalive request is served and the connection is retained. Another request is then accepted
   #
   # Ideally the server handles requests in the order they come in, and ideally it doesn't accept more requests than it can handle.
   # These goals are contradictory, because when the server is at maximum capacity due to keepalive connections, it could mean we
   # block all new requests, even if those came in before the new request on the older keepalive connection.
   #
-  # ## Distribute CPU resources across all workers
+  # ## Goal: Distribute CPU resources across all workers
   #
   # - This issue was opened https://github.com/puma/puma/issues/2078
   #
-  # There are several entangled issues and it's not exactly clear the root cause, but the observable outcome
+  # There are several entangled issues and it's not exactly clear what the root cause is, but the observable outcome
   # was that performance was better with a small sleep, and that eventually became the default.
   #
   # An attempt to describe why this works is here: https://github.com/puma/puma/issues/2078#issuecomment-3287032470.
   #
   # Summarizing: The delay is for tuning the rate at which "accept" is called on the socket.
-  # Puma works by calling "accept" nonblock on the socket in a loop. When there are multiple workers,
-  # (processes) then they will "race" to accept a request at roughly the same rate. However if one
+  # Puma works by calling "accept" nonblock on the socket in a loop. When there are multiple workers
+  # (processes), they will "race" to accept a request at roughly the same rate. However, if one
   # worker has all threads busy processing requests, then accepting a new request might "steal" it from
   # a less busy worker. If a worker has no work to do, it should loop as fast as possible.
   #
-  # ## Solution(s): Distribute requests across workers at start
+  # ## Solution: Distribute requests across workers at start
   #
   # For now, both goals are framed as "load balancing" across workers (processes) and achieved through
   # the same mechanism of sleeping longer to delay busier workers. Rather than the prior Puma 6.x
-  # and earlier behavior of using a binary on/off sleep value, we increase it an amound proportional
-  # to the load the server is under. Capping the maximum delay to the scenario where all threads are busy
+  # and earlier behavior of using a binary on/off sleep value, we increase it an amount proportional
+  # to the load the server is under, capping the maximum delay to the scenario where all threads are busy
   # and the todo list has reached a multiplier of the maximum number of threads.
   #
   # Private: API may change unexpectedly
   class ClusterAcceptLoopDelay
-    attr_reader :max_threads, :max_delay
+    attr_reader :max_delay
 
-    # Initialize happens once, `call` happens often. Push global calculations here
+    # Initialize happens once, `call` happens often. Perform global calculations here.
     def initialize(
-        # Number of workers in the cluster
-        workers: ,
-        # Maximum delay in seconds i.e. 0.005 is 5 microseconds
-        max_delay: # In seconds i.e. 0.005 is 5 microseconds
-
-      )
+      # Number of workers in the cluster
+      workers: ,
+      # Maximum delay in seconds i.e. 0.005 is 5 milliseconds
+      max_delay:
+    )
       @on = max_delay > 0 && workers >= 2
       @max_delay = max_delay.to_f
 
@@ -76,12 +75,12 @@ module Puma
     # We want the extreme values of this delay to be known (minimum and maximum) as well as
     # a predictable curve between the two. i.e. no step functions or hard cliffs.
     #
-    # Return value is always numeric. Returns 0 if there should be no delay
+    # Return value is always numeric. Returns 0 if there should be no delay.
     def calculate(
       # Number of threads working right now, plus number of requests in the todo list
       busy_threads_plus_todo:,
       # Maximum number of threads in the pool, note that the busy threads (alone) may go over this value at times
-      # if the pool needs to be reaped. The busy thread plus todo count may go over this value by a large amount
+      # if the pool needs to be reaped. The busy thread plus todo count may go over this value by a large amount.
       max_threads:
     )
       max_value = @overload_multiplier * max_threads

data/lib/puma/configuration.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'socket'
+require 'uri'
+
 require_relative 'plugin'
 require_relative 'const'
 require_relative 'dsl'
@@ -131,14 +134,16 @@ module Puma
 
     DEFAULTS = {
       auto_trim_time: 30,
-      binds: ['tcp://0.0.0.0:9292'.freeze],
-      fiber_per_request: !!ENV.fetch("PUMA_FIBER_PER_REQUEST", false),
+      binds: ['tcp://[::]:9292'.freeze],
       debug: false,
-      enable_keep_alives: true,
       early_hints: nil,
+      enable_keep_alives: true,
       environment: 'development'.freeze,
+      fiber_per_request: !!ENV.fetch("PUMA_FIBER_PER_REQUEST", false),
       # Number of seconds to wait until we get the first data for the request.
       first_data_timeout: 30,
+      force_shutdown_after: -1,
+      http_content_length_limit: nil,
       # Number of seconds to wait until the next request before shutting down.
       idle_timeout: nil,
       io_selector_backend: :auto,
@@ -147,6 +152,7 @@ module Puma
       # Limits how many requests a keep alive connection can make.
       # The connection will be closed after it reaches `max_keep_alive`
       # requests.
+      max_io_threads: 0,
       max_keep_alive: 999,
       max_threads: Puma.mri? ? 5 : 16,
       min_threads: 0,
@@ -155,15 +161,16 @@ module Puma
       out_of_band: [],
       # Number of seconds for another request within a persistent session.
       persistent_timeout: 65, # PUMA_PERSISTENT_TIMEOUT
+      prune_bundler: false,
       queue_requests: true,
       rackup: 'config.ru'.freeze,
       raise_exception_on_sigterm: true,
       reaping_time: 1,
       remote_address: :socket,
-      silence_single_worker_warning: false,
       silence_fork_callback_warning: false,
+      silence_single_worker_warning: false,
       tag: File.basename(Dir.getwd),
-      tcp_host: '0.0.0.0'.freeze,
+      tcp_host: '::'.freeze,
       tcp_port: 9292,
       wait_for_less_busy_worker: 0.005,
       worker_boot_timeout: 60,
@@ -172,11 +179,10 @@ module Puma
       worker_shutdown_timeout: 30,
       worker_timeout: 60,
       workers: 0,
-      http_content_length_limit: nil
     }
 
     def initialize(user_options={}, default_options = {}, env = ENV, &block)
-      default_options = self.puma_default_options(env).merge(default_options)
+      default_options = self.puma_default_options(env).merge(events: Events.new).merge(default_options)
 
       @_options    = UserFileDefaultOptions.new(user_options, default_options)
       @plugins     = PluginLoader.new
@@ -196,7 +202,7 @@ module Puma
       @clamped = false
     end
 
-    attr_reader :plugins, :events, :hooks
+    attr_reader :plugins, :events, :hooks, :_options
 
     def options
       raise NotClampedError, "ensure clamp is called before accessing options" unless @clamped
@@ -229,6 +235,8 @@ module Puma
 
     def puma_default_options(env = ENV)
       defaults = DEFAULTS.dup
+      defaults[:tcp_host] = self.class.default_tcp_host
+      defaults[:binds] = [self.class.default_tcp_bind]
       puma_options_from_env(env).each { |k,v| defaults[k] = v if v }
       defaults
     end
@@ -237,18 +245,14 @@ module Puma
       min = env['PUMA_MIN_THREADS'] || env['MIN_THREADS']
       max = env['PUMA_MAX_THREADS'] || env['MAX_THREADS']
       persistent_timeout = env['PUMA_PERSISTENT_TIMEOUT']
-      workers = if env['WEB_CONCURRENCY'] == 'auto'
-        require_processor_counter
-        ::Concurrent.available_processor_count
-      else
-        env['WEB_CONCURRENCY']
-      end
+      workers_env = env['WEB_CONCURRENCY']
+      workers = workers_env && workers_env.strip != "" ? parse_workers(workers_env.strip) : nil
 
       {
         min_threads: min && min != "" && Integer(min),
         max_threads: max && max != "" && Integer(max),
         persistent_timeout: persistent_timeout && persistent_timeout != "" && Integer(persistent_timeout),
-        workers: workers && workers != "" && Integer(workers),
+        workers: workers,
         environment: env['APP_ENV'] || env['RACK_ENV'] || env['RAILS_ENV'],
       }
     end
@@ -280,8 +284,10 @@ module Puma
     # This also calls load if it hasn't been called yet.
     def clamp
       load unless @loaded
+      run_mode_hooks
       set_conditional_default_options
       @_options.finalize_values
+      rewrite_unavailable_ipv6_binds!
       @clamped = true
       warn_hooks
       options
@@ -360,6 +366,23 @@ module Puma
       options.final_options
     end
 
+    def self.default_tcp_host
+      ipv6_interface_available? ? Const::UNSPECIFIED_IPV6 : Const::UNSPECIFIED_IPV4
+    end
+
+    def self.default_tcp_bind(port = DEFAULTS[:tcp_port])
+      URI::Generic.build(scheme: 'tcp', host: default_tcp_host, port: Integer(port)).to_s
+    end
+
+    def self.ipv6_interface_available?
+      Socket.getifaddrs.any? do |ifaddr|
+        addr = ifaddr.addr
+        addr&.ipv6? && !addr&.ipv6_loopback?
+      end
+    rescue StandardError
+      false
+    end
+
     def self.temp_path
       require 'tmpdir'
 
@@ -375,16 +398,52 @@ module Puma
 
     private
 
+    def rewrite_unavailable_ipv6_binds!
+      return if self.class.ipv6_interface_available?
+
+      tried_ipv6_bind = false
+      bind_schemes = ['tcp', 'ssl']
+
+      @_options[:binds] = Array(@_options[:binds]).map do |bind|
+        uri = URI.parse(bind)
+        next bind unless bind_schemes.include?(uri.scheme)
+
+        host = uri.host&.delete_prefix('[')&.delete_suffix(']')
+        next bind unless host&.include?(':')
+
+        tried_ipv6_bind = true
+        next bind unless host == Const::UNSPECIFIED_IPV6
+
+        uri.host = Const::UNSPECIFIED_IPV4
+        uri.to_s
+      rescue URI::InvalidURIError
+        bind
+      end
+
+      warn "WARNING: IPv6 bind requested but no non-loopback IPv6 interface was detected" if tried_ipv6_bind
+    end
+
     def require_processor_counter
       require 'concurrent/utility/processor_counter'
     rescue LoadError
       warn <<~MESSAGE
-        WEB_CONCURRENCY=auto requires the "concurrent-ruby" gem to be installed.
+        WEB_CONCURRENCY=auto or workers(:auto) requires the "concurrent-ruby" gem to be installed.
         Please add "concurrent-ruby" to your Gemfile.
       MESSAGE
       raise
     end
 
+    def parse_workers(value)
+      if value == :auto || value == 'auto'
+        require_processor_counter
+        Integer(::Concurrent.available_processor_count)
+      else
+        Integer(value)
+      end
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "workers must be an Integer or :auto"
+    end
+
     # Load and use the normal Rack builder if we can, otherwise
     # fallback to our minimal version.
     def rack_builder
@@ -425,6 +484,17 @@ module Puma
       rack_app
     end
 
+    def run_mode_hooks
+      workers_before = @_options[:workers]
+      key = workers_before > 0 ? :cluster : :single
+
+      @_options.all_of(key).each(&:call)
+
+      unless @_options[:workers] == workers_before
+        raise "cannot change the number of workers inside a #{key} configuration hook"
+      end
+    end
+
     def set_conditional_default_options
       @_options.default_options[:preload_app] = !@_options[:prune_bundler] &&
         (@_options[:workers] > 1) && Puma.forkable?

data/lib/puma/const.rb

@@ -100,8 +100,8 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "7.0.4"
-    CODE_NAME = "Romantic Warrior"
+    PUMA_VERSION = VERSION = "8.0.0"
+    CODE_NAME = "Into the Arena"
 
     PUMA_SERVER_STRING = ["puma", PUMA_VERSION, CODE_NAME].join(" ").freeze
 

data/lib/puma/control_cli.rb

@@ -16,7 +16,7 @@ module Puma
       'gc'       => nil,
       'gc-stats' => nil,
       'halt'              => 'SIGQUIT',
-      'info'              => 'SIGINFO',
+      'info'              => Puma.backtrace_signal,
       'phased-restart'    => 'SIGUSR1',
       'refork'            => 'SIGURG',
       'reload-worker-directory' => nil,

data/lib/puma/detect.rb

@@ -35,6 +35,13 @@ module Puma
     IS_WINDOWS
   end
 
+  BACKTRACE_SIGNAL =
+    if Signal.list.key?("INFO")
+      "SIGINFO"
+    elsif Signal.list.key?("PWR")
+      "SIGPWR"
+    end
+
   # @version 5.0.0
   def self.mri?
     IS_MRI
@@ -44,4 +51,8 @@ module Puma
   def self.forkable?
     HAS_FORK
   end
+
+  def self.backtrace_signal
+    BACKTRACE_SIGNAL
+  end
 end

data/lib/puma/dsl.rb

@@ -155,7 +155,7 @@ module Puma
     end
 
     def default_host
-      @options[:default_host] || Configuration::DEFAULTS[:tcp_host]
+      @options[:default_host] || Configuration.default_tcp_host
     end
 
     def inject(&blk)
@@ -216,6 +216,8 @@ module Puma
     #   activate_control_app 'unix:///var/run/pumactl.sock', { auth_token: '12345' }
     # @example
     #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true }
+    # @example
+    #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true, data_only: true}
     #
     def activate_control_app(url="auto", opts={})
       if url == "auto"
@@ -240,6 +242,7 @@ module Puma
 
       @options[:control_auth_token] = auth_token
       @options[:control_url_umask] = opts[:umask] if opts[:umask]
+      @options[:control_data_only] = opts[:data_only] if opts[:data_only]
     end
 
     # Load additional configuration from a file.
@@ -257,7 +260,8 @@ module Puma
     # accepted protocols. Multiple urls can be bound to, calling +bind+ does
     # not overwrite previous bindings.
     #
-    # The default is "tcp://0.0.0.0:9292".
+    # The default is "tcp://[::]:9292" when IPv6 interfaces are available,
+    # otherwise "tcp://0.0.0.0:9292".
     #
     # You can use query parameters within the url to specify options:
     #
@@ -276,7 +280,7 @@ module Puma
     # @example SSL cert for mutual TLS (mTLS)
     #   bind 'ssl://127.0.0.1:9292?key=key.key&cert=cert.pem&ca=ca.pem&verify_mode=force_peer'
     # @example Disable optimization for low latency
-    #   bind 'tcp://0.0.0.0:9292?low_latency=false'
+    #   bind 'tcp://[::]:9292?low_latency=false'
     # @example Socket permissions
     #   bind 'unix:///var/run/puma.sock?umask=0111'
     #
@@ -346,7 +350,7 @@ module Puma
 
     # Define how long persistent connections can be idle before Puma closes them.
     #
-    # The default is 20 seconds.
+    # The default is 65 seconds.
     #
     # @example
     #   persistent_timeout 30
@@ -592,6 +596,29 @@ module Puma
       @options[:max_threads] = max
     end
 
+    # Configure the max number of IO threads.
+    #
+    # When request handlers know the current requests will no longer use a significant amount
+    # of CPU, they can mark the current request as IO bound using <tt>env["puma.mark_as_io_bound"]</tt>.
+    #
+    # Threads marked as IO bound are allowed to go over the max thread limit.
+    #
+    # @example
+    #   threads 5
+    #   max_io_threads 5
+    #
+    # The above example allows for 5 regular threads and 5 IO threads to process requests concurrently.
+    # Any IO thread over the limit is counted as a regular thread, hence the above configuration also
+    # allows for 3 regular threads and 7 IO threads for example.
+    def max_io_threads(max)
+      max = Integer(max)
+      if max < 0
+        raise "The maximum number of IO threads (#{max}) must be a positive number"
+      end
+
+      @options[:max_io_threads] = max
+    end
+
     # Instead of using +bind+ and manually constructing a URI like:
     #
     #    bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'
@@ -656,7 +683,8 @@ module Puma
       @options[:state] = path.to_s
     end
 
-    # Use +permission+ to restrict permissions for the state file.
+    # Use +permission+ to restrict permissions for the state file.  By convention,
+    # +permission+ is an octal number (e.g. `0640` or `0o640`).
     #
     # @example
     #   state_permission 0600
@@ -665,21 +693,27 @@ module Puma
       @options[:state_permission] = permission
     end
 
-    # How many worker processes to run.  Typically this is set to
-    # the number of available cores.
+    # How many worker processes to run. Typically this is set to the number of
+    # available cores.
     #
     # The default is the value of the environment variable +WEB_CONCURRENCY+ if
-    # set, otherwise 0.
+    # set, otherwise 0. Passing +:auto+ will set the value to
+    # +Concurrent.available_processor_count+ (requires the concurrent-ruby gem).
+    # On some platforms (e.g. under CPU quotas) this may be fractional, and Puma
+    # will round down. If it rounds down to 0, Puma will run in single mode and
+    # cluster-only hooks like +before_worker_boot+ will not execute.
+    # If you rely on cluster-only hooks, set an explicit worker count.
     #
-    # @note Cluster mode only.
+    # A value of 0 or nil means run in single mode.
     #
     # @example
     #   workers 2
+    #   workers :auto
     #
     # @see Puma::Cluster
     #
     def workers(count)
-      @options[:workers] = count.to_i
+      @options[:workers] = count.nil? ? 0 : @config.send(:parse_workers, count)
     end
 
     # Disable warning message when running in cluster mode with a single worker.
@@ -717,6 +751,44 @@ module Puma
       @options[:silence_fork_callback_warning] = true
     end
 
+    # Code to run only in single mode.
+    # Runs after all config files are loaded.
+    #
+    # This can be called multiple times.
+    #
+    # @note Single mode only.
+    #
+    # @example
+    #   single do
+    #     silence_fork_callback_warning
+    #   end
+    #
+    def single(&block)
+      raise ArgumentError, "A block must be provided to `single`" unless block
+
+      @options[:single] ||= []
+      @options[:single] << block
+    end
+
+    # Code to run only in cluster mode.
+    # Runs after all config files are loaded.
+    #
+    # This can be called multiple times.
+    #
+    # @note Cluster mode only.
+    #
+    # @example
+    #   cluster do
+    #     prune_bundler
+    #   end
+    #
+    def cluster(&block)
+      raise ArgumentError, "A block must be provided to `cluster`" unless block
+
+      @options[:cluster] ||= []
+      @options[:cluster] << block
+    end
+
     # Code to run immediately before master process
     # forks workers (once on boot). These hooks can block if necessary
     # to wait for background operations unknown to Puma to finish before
@@ -818,6 +890,20 @@ module Puma
 
     alias_method :after_worker_boot, :after_worker_fork
 
+    # Code to run in the master right after a worker has stopped. The worker's
+    # index and Process::Status are passed as arguments.
+    #
+    # @note Cluster mode only.
+    #
+    # @example
+    #   after_worker_shutdown do |worker_handle|
+    #     puts 'Worker crashed' unless worker_handle.process_status.success?
+    #   end
+    #
+    def after_worker_shutdown(&block)
+      process_hook :after_worker_shutdown, nil, block, cluster_only: true
+    end
+
     # Code to run after puma is booted (works for both single and cluster modes).
     #
     # @example
@@ -980,6 +1066,7 @@ module Puma
     # The default is +true+ if your app uses more than 1 worker.
     #
     # @note Cluster mode only.
+    # @note When using `fork_worker`, this only applies to worker 0.
     #
     # @example
     #   preload_app!
@@ -1015,6 +1102,7 @@ module Puma
     # new Bundler context and thus can float around as the release
     # dictates.
     #
+    # @note Cluster mode only.
     # @note This is incompatible with +preload_app!+.
     # @note This is only supported for RubyGems 2.2+
     #
@@ -1120,7 +1208,7 @@ module Puma
 
     # Change the default worker timeout for booting.
     #
-    # The default is the value of `worker_timeout`.
+    # The default is 60 seconds.
     #
     # @note Cluster mode only.
     #
@@ -1202,18 +1290,27 @@ module Puma
     # threads will be written to $stdout. This can help figure
     # out why shutdown is hanging.
     #
-    def shutdown_debug(val=true)
-      @options[:shutdown_debug] = val
+    # If `on_force` is true, the backtraces will be written only
+    # when the shutdown is forced i.e. not graceful.
+    #
+    # @see force_shutdown_after
+    def shutdown_debug(val = true, on_force: false)
+      @options[:shutdown_debug] = val && on_force ? :on_force : val
     end
 
-
-    # Attempts to route traffic to less-busy workers by causing them to delay
-    # listening on the socket, allowing workers which are not processing any
+    # Maximum delay of worker accept loop.
+    #
+    # Attempts to route traffic to less-busy workers by causing a busy worker to delay
+    # listening on the socket, allowing workers which are not processing as many
     # requests to pick up new requests first.
     #
     # The default is 0.005 seconds.
     #
-    # Only works on MRI. For all other interpreters, this setting does nothing.
+    # To turn off this feature, set the value to 0.
+    #
+    # @note Cluster mode with >= 2 workers only.
+    #
+    # @note Interpreters with forking support only.
     #
     # @see Puma::Server#handle_servers
     # @see Puma::ThreadPool#wait_for_less_busy_worker
@@ -1357,7 +1454,7 @@ module Puma
     #
     # The default is +:auto+.
     #
-    # @see https://github.com/socketry/nio4r/blob/master/lib/nio/selector.rb
+    # @see https://github.com/socketry/nio4r/blob/main/lib/nio/selector.rb
     #
     def io_selector_backend(backend)
       @options[:io_selector_backend] = backend.to_sym