puma 3.11.1 → 6.6.0

data/lib/puma/thread_pool.rb

@@ -1,8 +1,21 @@
+# frozen_string_literal: true
+
 require 'thread'
 
+require_relative 'io_buffer'
+
 module Puma
-  # A simple thread pool management object.
+  # Internal Docs for A simple thread pool management object.
+  #
+  # Each Puma "worker" has a thread pool to process requests.
   #
+  # First a connection to a client is made in `Puma::Server`. It is wrapped in a
+  # `Puma::Client` instance and then passed to the `Puma::Reactor` to ensure
+  # the whole request is buffered into memory. Once the request is ready, it is passed into
+  # a thread pool via the `Puma::ThreadPool#<<` operator where it is stored in a `@todo` array.
+  #
+  # Each thread in the pool has an internal loop where it pulls a request from the `@todo` array
+  # and processes it.
   class ThreadPool
     class ForceShutdown < RuntimeError
     end
@@ -18,7 +31,7 @@ module Puma
     # The block passed is the work that will be performed in each
     # thread.
     #
-    def initialize(min, max, *extra, &block)
+    def initialize(name, options = {}, &block)
       @not_empty = ConditionVariable.new
       @not_full = ConditionVariable.new
       @mutex = Mutex.new
@@ -28,14 +41,25 @@ module Puma
       @spawned = 0
       @waiting = 0
 
-      @min = Integer(min)
-      @max = Integer(max)
+      @name = name
+      @min = Integer(options[:min_threads])
+      @max = Integer(options[:max_threads])
+      # Not an 'exposed' option, options[:pool_shutdown_grace_time] is used in CI
+      # to shorten @shutdown_grace_time from SHUTDOWN_GRACE_TIME. Parallel CI
+      # makes stubbing constants difficult.
+      @shutdown_grace_time = Float(options[:pool_shutdown_grace_time] || SHUTDOWN_GRACE_TIME)
       @block = block
-      @extra = extra
+      @out_of_band = options[:out_of_band]
+      @clean_thread_locals = options[:clean_thread_locals]
+      @before_thread_start = options[:before_thread_start]
+      @before_thread_exit = options[:before_thread_exit]
+      @reaping_time = options[:reaping_time]
+      @auto_trim_time = options[:auto_trim_time]
 
       @shutdown = false
 
       @trim_requested = 0
+      @out_of_band_pending = false
 
       @workers = []
 
@@ -43,25 +67,51 @@ module Puma
       @reaper = nil
 
       @mutex.synchronize do
-        @min.times { spawn_thread }
+        @min.times do
+          spawn_thread
+          @not_full.wait(@mutex)
+        end
       end
 
-      @clean_thread_locals = false
+      @force_shutdown = false
+      @shutdown_mutex = Mutex.new
     end
 
-    attr_reader :spawned, :trim_requested
-    attr_accessor :clean_thread_locals
+    attr_reader :spawned, :trim_requested, :waiting
 
     def self.clean_thread_locals
-      Thread.current.keys.each do |key| # rubocop: disable Performance/HashEachMethods
+      Thread.current.keys.each do |key| # rubocop: disable Style/HashEachMethods
         Thread.current[key] = nil unless key == :__recursive_key__
       end
     end
 
+    # generate stats hash so as not to perform multiple locks
+    # @return [Hash] hash containing stat info from ThreadPool
+    def stats
+      with_mutex do
+        { backlog: @todo.size,
+          running: @spawned,
+          pool_capacity: @waiting + (@max - @spawned),
+          busy_threads: @spawned - @waiting + @todo.size
+        }
+      end
+    end
+
     # How many objects have yet to be processed by the pool?
     #
     def backlog
-      @mutex.synchronize { @todo.size }
+      with_mutex { @todo.size }
+    end
+
+    # @!attribute [r] pool_capacity
+    def pool_capacity
+      waiting + (@max - spawned)
+    end
+
+    # @!attribute [r] busy_threads
+    # @version 5.0.0
+    def busy_threads
+      with_mutex { @spawned - @waiting + @todo.size }
     end
 
     # :nodoc:
@@ -71,62 +121,54 @@ module Puma
     def spawn_thread
       @spawned += 1
 
+      trigger_before_thread_start_hooks
       th = Thread.new(@spawned) do |spawned|
-        # Thread name is new in Ruby 2.3
-        Thread.current.name = 'puma %03i' % spawned if Thread.current.respond_to?(:name=)
+        Puma.set_thread_name '%s tp %03i' % [@name, spawned]
         todo  = @todo
         block = @block
         mutex = @mutex
         not_empty = @not_empty
         not_full = @not_full
 
-        extra = @extra.map { |i| i.new }
-
         while true
           work = nil
 
-          continue = true
-
           mutex.synchronize do
             while todo.empty?
               if @trim_requested > 0
                 @trim_requested -= 1
-                continue = false
+                @spawned -= 1
+                @workers.delete th
                 not_full.signal
-                break
-              end
-
-              if @shutdown
-                continue = false
-                break
+                trigger_before_thread_exit_hooks
+                Thread.exit
               end
 
               @waiting += 1
+              if @out_of_band_pending && trigger_out_of_band_hook
+                @out_of_band_pending = false
+              end
               not_full.signal
-              not_empty.wait mutex
-              @waiting -= 1
+              begin
+                not_empty.wait mutex
+              ensure
+                @waiting -= 1
+              end
             end
 
-            work = todo.shift if continue
+            work = todo.shift
           end
 
-          break unless continue
-
           if @clean_thread_locals
             ThreadPool.clean_thread_locals
           end
 
           begin
-            block.call(work, *extra)
+            @out_of_band_pending = true if block.call(work)
           rescue Exception => e
             STDERR.puts "Error reached top of thread-pool: #{e.message} (#{e.class})"
           end
         end
-
-        mutex.synchronize do
-          @spawned -= 1
-          @workers.delete th
-        end
       end
 
       @workers << th
@@ -136,9 +178,62 @@ module Puma
 
     private :spawn_thread
 
+    def trigger_before_thread_start_hooks
+      return unless @before_thread_start&.any?
+
+      @before_thread_start.each do |b|
+        begin
+          b.call
+        rescue Exception => e
+          STDERR.puts "WARNING before_thread_start hook failed with exception (#{e.class}) #{e.message}"
+        end
+      end
+      nil
+    end
+
+    private :trigger_before_thread_start_hooks
+
+    def trigger_before_thread_exit_hooks
+      return unless @before_thread_exit&.any?
+
+      @before_thread_exit.each do |b|
+        begin
+          b.call
+        rescue Exception => e
+          STDERR.puts "WARNING before_thread_exit hook failed with exception (#{e.class}) #{e.message}"
+        end
+      end
+      nil
+    end
+
+    private :trigger_before_thread_exit_hooks
+
+    # @version 5.0.0
+    def trigger_out_of_band_hook
+      return false unless @out_of_band&.any?
+
+      # we execute on idle hook when all threads are free
+      return false unless @spawned == @waiting
+
+      @out_of_band.each(&:call)
+      true
+    rescue Exception => e
+      STDERR.puts "Exception calling out_of_band_hook: #{e.message} (#{e.class})"
+      true
+    end
+
+    private :trigger_out_of_band_hook
+
+    # @version 5.0.0
+    def with_mutex(&block)
+      @mutex.owned? ?
+        yield :
+        @mutex.synchronize(&block)
+    end
+
     # Add +work+ to the todo list for a Thread to pickup and process.
     def <<(work)
-      @mutex.synchronize do
+      with_mutex do
         if @shutdown
           raise "Unable to add work while shutting down"
         end
@@ -153,29 +248,77 @@ module Puma
       end
     end
 
+    # This method is used by `Puma::Server` to let the server know when
+    # the thread pool can pull more requests from the socket and
+    # pass to the reactor.
+    #
+    # The general idea is that the thread pool can only work on a fixed
+    # number of requests at the same time. If it is already processing that
+    # number of requests then it is at capacity. If another Puma process has
+    # spare capacity, then the request can be left on the socket so the other
+    # worker can pick it up and process it.
+    #
+    # For example: if there are 5 threads, but only 4 working on
+    # requests, this method will not wait and the `Puma::Server`
+    # can pull a request right away.
+    #
+    # If there are 5 threads and all 5 of them are busy, then it will
+    # pause here, and wait until the `not_full` condition variable is
+    # signaled, usually this indicates that a request has been processed.
+    #
+    # It's important to note that even though the server might accept another
+    # request, it might not be added to the `@todo` array right away.
+    # For example if a slow client has only sent a header, but not a body
+    # then the `@todo` array would stay the same size as the reactor works
+    # to try to buffer the request. In that scenario the next call to this
+    # method would not block and another request would be added into the reactor
+    # by the server. This would continue until a fully buffered request
+    # makes it through the reactor and can then be processed by the thread pool.
     def wait_until_not_full
-      @mutex.synchronize do
+      with_mutex do
         while true
           return if @shutdown
-          return if @waiting > 0
 
           # If we can still spin up new threads and there
-          # is work queued, then accept more work until we would
+          # is work queued that cannot be handled by waiting
+          # threads, then accept more work until we would
           # spin up the max number of threads.
-          return if @todo.size < @max - @spawned
+          return if busy_threads < @max
 
           @not_full.wait @mutex
         end
       end
     end
 
-    # If too many threads are in the pool, tell one to finish go ahead
+    # @version 5.0.0
+    def wait_for_less_busy_worker(delay_s)
+      return unless delay_s && delay_s > 0
+
+      # Ruby MRI does GVL, this can result
+      # in processing contention when multiple threads
+      # (requests) are running concurrently
+      return unless Puma.mri?
+
+      with_mutex do
+        return if @shutdown
+
+        # do not delay, if we are not busy
+        return unless busy_threads > 0
+
+        # this will be signaled once a request finishes,
+        # which can happen earlier than delay
+        @not_full.wait @mutex, delay_s
+      end
+    end
+
+    # If there are any free threads in the pool, tell one to go ahead
     # and exit. If +force+ is true, then a trim request is requested
     # even if all threads are being utilized.
     #
     def trim(force=false)
-      @mutex.synchronize do
-        if (force or @waiting > 0) and @spawned - @trim_requested > @min
+      with_mutex do
+        free = @waiting - @todo.size
+        if (force or free > 0) and @spawned - @trim_requested > @min
           @trim_requested += 1
           @not_empty.signal
         end
@@ -185,7 +328,7 @@ module Puma
     # If there are dead threads in the pool make them go away while decreasing
     # spawned counter so that new healthy threads could be created again.
     def reap
-      @mutex.synchronize do
+      with_mutex do
         dead_workers = @workers.reject(&:alive?)
 
         dead_workers.each do |worker|
@@ -199,10 +342,12 @@ module Puma
       end
     end
 
-    class AutoTrim
-      def initialize(pool, timeout)
+    class Automaton
+      def initialize(pool, timeout, thread_name, message)
         @pool = pool
         @timeout = timeout
+        @thread_name = thread_name
+        @message = message
         @running = false
       end
 
@@ -210,8 +355,9 @@ module Puma
         @running = true
 
         @thread = Thread.new do
+          Puma.set_thread_name @thread_name
           while @running
-            @pool.trim
+            @pool.public_send(@message)
             sleep @timeout
           end
         end
@@ -223,50 +369,43 @@ module Puma
       end
     end
 
-    def auto_trim!(timeout=30)
-      @auto_trim = AutoTrim.new(self, timeout)
+    def auto_trim!(timeout=@auto_trim_time)
+      @auto_trim = Automaton.new(self, timeout, "#{@name} tp trim", :trim)
       @auto_trim.start!
     end
 
-    class Reaper
-      def initialize(pool, timeout)
-        @pool = pool
-        @timeout = timeout
-        @running = false
-      end
-
-      def start!
-        @running = true
-
-        @thread = Thread.new do
-          while @running
-            @pool.reap
-            sleep @timeout
-          end
-        end
-      end
-
-      def stop
-        @running = false
-        @thread.wakeup
-      end
+    def auto_reap!(timeout=@reaping_time)
+      @reaper = Automaton.new(self, timeout, "#{@name} tp reap", :reap)
+      @reaper.start!
     end
 
-    def auto_reap!(timeout=5)
-      @reaper = Reaper.new(self, timeout)
-      @reaper.start!
+    # Allows ThreadPool::ForceShutdown to be raised within the
+    # provided block if the thread is forced to shutdown during execution.
+    def with_force_shutdown
+      t = Thread.current
+      @shutdown_mutex.synchronize do
+        raise ForceShutdown if @force_shutdown
+        t[:with_force_shutdown] = true
+      end
+      yield
+    ensure
+      t[:with_force_shutdown] = false
     end
 
     # Tell all threads in the pool to exit and wait for them to finish.
+    # Wait +timeout+ seconds then raise +ForceShutdown+ in remaining threads.
+    # Next, wait an extra +@shutdown_grace_time+ seconds then force-kill remaining
+    # threads. Finally, wait 1 second for remaining threads to exit.
     #
     def shutdown(timeout=-1)
-      threads = @mutex.synchronize do
+      threads = with_mutex do
         @shutdown = true
+        @trim_requested = @spawned
         @not_empty.broadcast
         @not_full.broadcast
 
-        @auto_trim.stop if @auto_trim
-        @reaper.stop if @reaper
+        @auto_trim&.stop
+        @reaper&.stop
         # dup workers so that we join them all safely
         @workers.dup
       end
@@ -275,27 +414,29 @@ module Puma
         # Wait for threads to finish without force shutdown.
         threads.each(&:join)
       else
-        # Wait for threads to finish after n attempts (+timeout+).
-        # If threads are still running, it will forcefully kill them.
-        timeout.times do
-          threads.delete_if do |t|
-            t.join 1
-          end
-
-          if threads.empty?
-            break
-          else
-            sleep 1
+        join = ->(inner_timeout) do
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          threads.reject! do |t|
+            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+            t.join inner_timeout - elapsed
           end
         end
 
-        threads.each do |t|
-          t.raise ForceShutdown
-        end
+        # Wait +timeout+ seconds for threads to finish.
+        join.call(timeout)
 
-        threads.each do |t|
-          t.join SHUTDOWN_GRACE_TIME
+        # If threads are still running, raise ForceShutdown and wait to finish.
+        @shutdown_mutex.synchronize do
+          @force_shutdown = true
+          threads.each do |t|
+            t.raise ForceShutdown if t[:with_force_shutdown]
+          end
         end
+        join.call(@shutdown_grace_time)
+
+        # If threads are _still_ running, forcefully kill them and wait to finish.
+        threads.each(&:kill)
+        join.call(1)
       end
 
       @spawned = 0

data/lib/puma/util.rb

@@ -1,10 +1,6 @@
-major, minor, patch = RUBY_VERSION.split('.').map { |v| v.to_i }
+# frozen_string_literal: true
 
-if major == 1 && minor == 9 && patch == 3 && RUBY_PATCHLEVEL < 125
-  require 'puma/rack/backports/uri/common_193'
-else
-  require 'uri/common'
-end
+require 'uri/common'
 
 module Puma
   module Util
@@ -14,18 +10,34 @@ module Puma
       IO.pipe
     end
 
-    # Unescapes a URI escaped string with +encoding+. +encoding+ will be the
-    # target encoding of the string returned, and it defaults to UTF-8
+    # An instance method on Thread has been provided to address https://bugs.ruby-lang.org/issues/13632,
+    # which currently affects some older versions of Ruby: 2.2.7 2.2.8 2.2.9 2.2.10 2.3.4 2.4.1
+    # Additional context: https://github.com/puma/puma/pull/1345
+    def purge_interrupt_queue
+      Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+    end
+
+    # Escapes and unescapes a URI escaped string with
+    # +encoding+. +encoding+ will be the target encoding of the string
+    # returned, and it defaults to UTF-8
     if defined?(::Encoding)
+      def escape(s, encoding = Encoding::UTF_8)
+        URI.encode_www_form_component(s, encoding)
+      end
+
       def unescape(s, encoding = Encoding::UTF_8)
         URI.decode_www_form_component(s, encoding)
       end
     else
+      def escape(s, encoding = nil)
+        URI.encode_www_form_component(s, encoding)
+      end
+
       def unescape(s, encoding = nil)
         URI.decode_www_form_component(s, encoding)
       end
     end
-    module_function :unescape
+    module_function :unescape, :escape
 
     DEFAULT_SEP = /[&;] */n
 
@@ -54,7 +66,7 @@ module Puma
         end
       end
 
-      return params
+      params
     end
 
     # A case-insensitive Hash that preserves the original case of a
@@ -76,6 +88,7 @@ module Puma
         end
       end
 
+      # @!attribute [r] to_hash
       def to_hash
         hash = {}
         each { |k,v| hash[k] = v }

data/lib/puma.rb

@@ -1,15 +1,78 @@
+# frozen_string_literal: true
+
 # Standard libraries
 require 'socket'
 require 'tempfile'
-require 'time'
-require 'etc'
 require 'uri'
 require 'stringio'
 
 require 'thread'
 
+# use require, see https://github.com/puma/puma/pull/2381
+require 'puma/puma_http11'
+
+require_relative 'puma/detect'
+require_relative 'puma/json_serialization'
+
 module Puma
-  autoload :Const, 'puma/const'
-  autoload :Server, 'puma/server'
-  autoload :Launcher, 'puma/launcher'
+  # when Puma is loaded via `Puma::CLI`, all files are loaded via
+  # `require_relative`.  The below are for non-standard loading
+  autoload :Const,     "#{__dir__}/puma/const"
+  autoload :Server,    "#{__dir__}/puma/server"
+  autoload :Launcher,  "#{__dir__}/puma/launcher"
+  autoload :LogWriter, "#{__dir__}/puma/log_writer"
+
+  # at present, MiniSSL::Engine is only defined in extension code (puma_http11),
+  # not in minissl.rb
+  HAS_SSL = const_defined?(:MiniSSL, false) && MiniSSL.const_defined?(:Engine, false)
+
+  HAS_UNIX_SOCKET = Object.const_defined?(:UNIXSocket) && !IS_WINDOWS
+
+  if HAS_SSL
+    require_relative 'puma/minissl'
+  else
+    module MiniSSL
+      # this class is defined so that it exists when Puma is compiled
+      # without ssl support, as Server and Reactor use it in rescue statements.
+      class SSLError < StandardError ; end
+    end
+  end
+
+  def self.ssl?
+    HAS_SSL
+  end
+
+  def self.abstract_unix_socket?
+    @abstract_unix ||=
+      if HAS_UNIX_SOCKET
+        begin
+          ::UNIXServer.new("\0puma.temp.unix").close
+          true
+        rescue ArgumentError  # darwin
+          false
+        end
+      else
+        false
+      end
+  end
+
+  # @!attribute [rw] stats_object=
+  def self.stats_object=(val)
+    @get_stats = val
+  end
+
+  # @!attribute [rw] stats_object
+  def self.stats
+    Puma::JSONSerialization.generate @get_stats.stats
+  end
+
+  # @!attribute [r] stats_hash
+  # @version 5.0.0
+  def self.stats_hash
+    @get_stats.stats
+  end
+
+  def self.set_thread_name(name)
+    Thread.current.name = "puma #{name}"
+  end
 end