puma 3.0.0.rc1 → 5.0.0.beta1

data/lib/puma/single.rb

@@ -1,11 +1,22 @@
+# frozen_string_literal: true
+
 require 'puma/runner'
+require 'puma/detect'
+require 'puma/plugin'
 
 module Puma
+  # This class is instantiated by the `Puma::Launcher` and used
+  # to boot and serve a Ruby application when no puma "workers" are needed
+  # i.e. only using "threaded" mode. For example `$ puma -t 1:5`
+  #
+  # At the core of this class is running an instance of `Puma::Server` which
+  # gets created via the `start_server` method from the `Puma::Runner` class
+  # that this inherits from.
   class Single < Runner
     def stats
-      b = @server.backlog
-      r = @server.running
-      %Q!{ "backlog": #{b}, "running": #{r} }!
+      {
+        started_at: @started_at.utc.iso8601
+      }.merge(@server.stats)
     end
 
     def restart
@@ -13,7 +24,7 @@ module Puma
     end
 
     def stop
-      @server.stop false
+      @server.stop(false) if @server
     end
 
     def halt
@@ -23,66 +34,15 @@ module Puma
     def stop_blocked
       log "- Gracefully stopping, waiting for requests to finish"
       @control.stop(true) if @control
-      @server.stop(true)
-    end
-
-    def jruby_daemon?
-      daemon? and Puma.jruby?
-    end
-
-    def jruby_daemon_start
-      require 'puma/jruby_restart'
-      JRubyRestart.daemon_start(@restart_dir, restart_args)
+      @server.stop(true) if @server
     end
 
     def run
-      already_daemon = false
-
-      if jruby_daemon?
-        require 'puma/jruby_restart'
-
-        if JRubyRestart.daemon?
-          # load and bind before redirecting IO so errors show up on stdout/stderr
-          load_and_bind
-        end
-
-        already_daemon = JRubyRestart.daemon_init
-      end
-
       output_header "single"
 
-      if jruby_daemon?
-        if already_daemon
-          JRubyRestart.perm_daemonize
-        else
-          pid = nil
-
-          Signal.trap "SIGUSR2" do
-            log "* Started new process #{pid} as daemon..."
-
-            # Must use exit! so we don't unwind and run the ensures
-            # that will be run by the new child (such as deleting the
-            # pidfile)
-            exit!(true)
-          end
-
-          Signal.trap "SIGCHLD" do
-            log "! Error starting new process as daemon, exiting"
-            exit 1
-          end
-
-          pid = jruby_daemon_start
-          sleep
-        end
-      else
-        if daemon?
-          log "* Daemonizing..."
-          Process.daemon(true)
-          redirect_io
-        end
-
-        load_and_bind
-      end
+      load_and_bind
+
+      Plugins.fire_background
 
       @launcher.write_state
 
@@ -90,10 +50,9 @@ module Puma
 
       @server = server = start_server
 
-      unless daemon?
-        log "Use Ctrl-C to stop"
-        redirect_io
-      end
+
+      log "Use Ctrl-C to stop"
+      redirect_io
 
       @launcher.events.fire_on_booted!
 

data/lib/puma/state_file.rb

@@ -1,11 +1,18 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
 module Puma
   class StateFile
     def initialize
       @options = {}
     end
 
-    def save(path)
-      File.write path, YAML.dump(@options)
+    def save(path, permission = nil)
+      File.open(path, "w") do |file|
+        file.chmod(permission) if permission
+        file.write(YAML.dump(@options))
+      end
     end
 
     def load(path)

data/lib/puma/thread_pool.rb

@@ -1,9 +1,27 @@
+# frozen_string_literal: true
+
 require 'thread'
 
 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 proceses it.
   class ThreadPool
+    class ForceShutdown < RuntimeError
+    end
+
+    # How long, after raising the ForceShutdown of a thread during
+    # forced shutdown mode, to wait for the thread to try and finish
+    # up its work before leaving the thread to die on the vine.
+    SHUTDOWN_GRACE_TIME = 5 # seconds
 
     # Maintain a minimum of +min+ and maximum of +max+ threads
     # in the pool.
@@ -29,6 +47,7 @@ module Puma
       @shutdown = false
 
       @trim_requested = 0
+      @out_of_band_pending = false
 
       @workers = []
 
@@ -36,19 +55,37 @@ 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
     end
 
-    attr_reader :spawned, :trim_requested
+    attr_reader :spawned, :trim_requested, :waiting
     attr_accessor :clean_thread_locals
+    attr_accessor :out_of_band_hook
+
+    def self.clean_thread_locals
+      Thread.current.keys.each do |key| # rubocop: disable Performance/HashEachMethods
+        Thread.current[key] = nil unless key == :__recursive_key__
+      end
+    end
 
     # How many objects have yet to be processed by the pool?
     #
     def backlog
-      @mutex.synchronize { @todo.size }
+      with_mutex { @todo.size }
+    end
+
+    def pool_capacity
+      waiting + (@max - spawned)
+    end
+
+    def busy_threads
+      with_mutex { @spawned - @waiting + @todo.size }
     end
 
     # :nodoc:
@@ -58,7 +95,8 @@ module Puma
     def spawn_thread
       @spawned += 1
 
-      th = Thread.new do
+      th = Thread.new(@spawned) do |spawned|
+        Puma.set_thread_name 'threadpool %03i' % spawned
         todo  = @todo
         block = @block
         mutex = @mutex
@@ -70,48 +108,37 @@ module Puma
         while true
           work = nil
 
-          continue = true
-
           mutex.synchronize do
             while todo.empty?
               if @trim_requested > 0
                 @trim_requested -= 1
-                continue = false
-                break
-              end
-
-              if @shutdown
-                continue = false
-                break
+                @spawned -= 1
+                @workers.delete th
+                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
             end
 
-            work = todo.shift if continue
+            work = todo.shift
           end
 
-          break unless continue
-
           if @clean_thread_locals
-            Thread.current.keys.each do |key|
-              Thread.current[key] = nil unless key == :__recursive_key__
-            end
+            ThreadPool.clean_thread_locals
           end
 
           begin
-            block.call(work, *extra)
-          rescue Exception
+            @out_of_band_pending = true if block.call(work, *extra)
+          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
@@ -121,9 +148,30 @@ module Puma
 
     private :spawn_thread
 
+    def trigger_out_of_band_hook
+      return false unless out_of_band_hook && out_of_band_hook.any?
+
+      # we execute on idle hook when all threads are free
+      return false unless @spawned == @waiting
+
+      out_of_band_hook.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
+
+    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
@@ -138,21 +186,75 @@ 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 bufferend request
+    # makes it through the reactor and can then be processed by the thread pool.
     def wait_until_not_full
-      @mutex.synchronize do
-        until @todo.size - @waiting < @max - @spawned or @shutdown
+      with_mutex do
+        while true
+          return if @shutdown
+
+          # If we can still spin up new threads and there
+          # 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 busy_threads < @max
+
           @not_full.wait @mutex
         end
       end
     end
 
-    # If too many threads are in the pool, tell one to finish go ahead
+    def wait_for_less_busy_worker(delay_s)
+      # Ruby MRI does GVL, this can result
+      # in processing contention when multiple threads
+      # (requests) are running concurrently
+      return unless Puma.mri?
+      return unless delay_s > 0
+
+      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
@@ -162,7 +264,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|
@@ -170,14 +272,18 @@ module Puma
           @spawned -= 1
         end
 
-        @workers -= dead_workers
+        @workers.delete_if do |w|
+          dead_workers.include?(w)
+        end
       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
 
@@ -185,8 +291,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
@@ -198,45 +305,25 @@ module Puma
       end
     end
 
-    def auto_trim!(timeout=5)
-      @auto_trim = AutoTrim.new(self, timeout)
+    def auto_trim!(timeout=30)
+      @auto_trim = Automaton.new(self, timeout, "threadpool trimmer", :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
-    end
-
     def auto_reap!(timeout=5)
-      @reaper = Reaper.new(self, timeout)
+      @reaper = Automaton.new(self, timeout, "threadpool reaper", :reap)
       @reaper.start!
     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 +grace+ seconds then force-kill remaining threads.
+    # Finally, wait +kill_grace+ seconds for remaining threads to exit.
     #
-    def shutdown
-      threads = @mutex.synchronize do
+    def shutdown(timeout=-1)
+      threads = with_mutex do
         @shutdown = true
+        @trim_requested = @spawned
         @not_empty.broadcast
         @not_full.broadcast
 
@@ -246,7 +333,31 @@ module Puma
         @workers.dup
       end
 
-      threads.each(&:join)
+      if timeout == -1
+        # Wait for threads to finish without force shutdown.
+        threads.each(&:join)
+      else
+        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
+
+        # Wait +timeout+ seconds for threads to finish.
+        join.call(timeout)
+
+        # If threads are still running, raise ForceShutdown and wait to finish.
+        threads.each do |t|
+          t.raise ForceShutdown
+        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
       @workers = []