kino 0.5.0 → 0.7.0

data/lib/kino/ractor_supervisor.rb

@@ -5,7 +5,12 @@ module Kino
   # Spawns worker ractors and keeps them alive. One supervisor thread per
   # ractor: it blocks in Ractor#value, and a crash (anything that kills the
   # ractor, Exception from app code included) wakes it to 500 the in-flight
-  # requests and respawn. Clean exits (queue drained) end supervision.
+  # requests and respawn. Clean exits (queue drained at shutdown, or the
+  # worker retired by the pool scaler) end supervision.
+  #
+  # Also the :ractor-mode pool behind PoolScaler: `grow` adds a worker,
+  # `retire` sends one home, `groups` lists the ones that may be retired,
+  # and `active_count` is what the control plane reports.
   class RactorSupervisor
     def initialize(server_id, app, workers:, threads:, batch: 1, hooks: nil, on_worker_exit: nil)
       @server_id = server_id
@@ -21,6 +26,12 @@ module Kino
       @worker_slots = {}
       @slot_to_worker = {}
       @replaced = {}
+      # Worker index => true while its ractor runs, and => true once the
+      # scaler asked it to leave. Retired workers hand their slots back to
+      # the bank for the next worker to take over.
+      @live = {}
+      @retiring = {}
+      @bank = SlotBank.new(server_id)
       # The first replacement's index; `replace` increments before using it,
       # so this starts one below the first free index (@workers).
       @next_worker_index = @workers - 1
@@ -28,6 +39,7 @@ module Kino
 
     def start
       @supervisor_threads = Array.new(@workers) { |index| supervise(index) }
+      report_active
       self
     end
 
@@ -52,6 +64,61 @@ module Kino
       @lock.synchronize { @supervisor_threads.dup }.each(&:join)
     end
 
+    # Ractors cannot be force-killed; their clients were already freed by
+    # abort_all_inflight. A stuck ractor leaks until process exit.
+    def kill_stragglers
+      Log.error("shutdown deadline passed with stuck ractor workers") unless done?
+    end
+
+    # Workers that are staying: the live ones minus those the quarantine
+    # monitor abandoned as wedged (their replacements count instead) and
+    # minus those already told to leave. A retiring worker leaves the
+    # count at once, not when its ractor finally exits, so the scaler
+    # never sees a stale surplus and retires past its floor.
+    def active_count
+      @lock.synchronize do
+        @live.count { |index, _| !@replaced.key?(index) && !@retiring.key?(index) }
+      end
+    end
+
+    # Worker index => slot ids for every worker the scaler may retire:
+    # live, not already leaving, not quarantined, and past its spawn (a
+    # worker marked live whose supervisor thread has not assigned slots
+    # yet is not listed until it has).
+    def groups
+      @lock.synchronize do
+        @live.keys
+          .reject { |index| @retiring.key?(index) || @replaced.key?(index) || !@worker_slots.key?(index) }
+          .to_h { |index| [index, @worker_slots[index].dup] }
+      end
+    end
+
+    # Add one supervised worker; returns its index.
+    def grow
+      new_index = @lock.synchronize { @next_worker_index += 1 }
+      thread = supervise(new_index)
+      @lock.synchronize { @supervisor_threads << thread }
+      report_active
+      new_index
+    end
+
+    # Send a worker home. Its slots stop receiving work now; the worker
+    # finishes what it holds, leaves at its next idle tick, and its slots
+    # come back to the free list once the ractor has exited. Returns
+    # false when there is no such live worker to retire.
+    def retire(worker_index)
+      slot_ids = @lock.synchronize do
+        next nil unless @live.key?(worker_index) && !@retiring.key?(worker_index)
+
+        @retiring[worker_index] = true
+        @worker_slots[worker_index]
+      end
+      return false unless slot_ids
+
+      slot_ids.each { |id| Native.retire_slot(@server_id, id) }
+      true
+    end
+
     # Replace the ractor owning slot `worker_id`: spawn a fresh supervised
     # ractor, then quarantine the old ractor's slots. The old supervisor
     # thread stays blocked in ractor.value on the wedged ractor (it and the
@@ -90,6 +157,9 @@ module Kino
     private
 
     def supervise(index)
+      # Live from the moment it is asked for, not from when its thread gets
+      # around to spawning: `grow` reports the count right after this.
+      @lock.synchronize { @live[index] = true }
       Thread.new do
         Thread.current.name = "supervisor-#{index}"
         crashes = 0
@@ -97,8 +167,9 @@ module Kino
           ractor, worker_ids = spawn_worker(index)
           begin
             ractor.value # blocks until the ractor terminates
-            HookFire.fire(@on_worker_exit, "on_worker_exit", index, nil) # clean exit: queue drained
-            break        # clean exit: queue closed, workers drained
+            HookFire.fire(@on_worker_exit, "on_worker_exit", index, nil) # clean exit: drained or retired
+            exited(index, worker_ids)
+            break
           rescue Ractor::Error => e
             # The ractor died mid-flight. Anything it was serving will never
             # be answered by Ruby: 500 those clients NOW (not when GC gets
@@ -106,11 +177,17 @@ module Kino
             worker_ids.each { |id| Native.abort_inflight(@server_id, id) }
             cause = (e.respond_to?(:cause) && e.cause) ? e.cause : e
             HookFire.fire(@on_worker_exit, "on_worker_exit", index, cause)
-            break if draining?
+            if draining?
+              exited(index, nil)
+              break
+            end
 
             crashes += 1
             Native.record_respawn(@server_id)
             Log.error("worker-#{index} crashed (#{cause.class}: #{cause.message}); respawning")
+            # A crashed worker that was on its way out respawns on fresh
+            # slots like any other; the scaler retires it again when idle.
+            @lock.synchronize { @retiring.delete(index) }
             # Policy (crash recovery): unlimited respawn
             # keeps the server up under rare crashes but turns a
             # crash-on-every-request bug into a busy loop. A circuit breaker
@@ -121,11 +198,10 @@ module Kino
       end
     end
 
-    # Fresh ractor + fresh native slots. Slots are never reused across
-    # respawns: stale interrupt kicks and dead weak refs go down with the
-    # old slot.
+    # Fresh ractor on slots from the bank: fresh ones, or ones a retired
+    # worker handed back.
     def spawn_worker(worker_index)
-      worker_ids = Array.new(@threads) { Native.register_worker(@server_id) }
+      worker_ids = Array.new(@threads) { @bank.claim }
       @lock.synchronize do
         @worker_slots[worker_index] = worker_ids
         worker_ids.each { |id| @slot_to_worker[id] = worker_index }
@@ -147,6 +223,24 @@ module Kino
       [ractor, worker_ids]
     end
 
+    # Bookkeeping for a supervisor thread that is done: the worker is no
+    # longer live, a retired worker's slots go back to the bank, and the
+    # thread leaves the join set so a long-lived elastic pool does not
+    # accumulate dead threads.
+    def exited(index, worker_ids)
+      retired = @lock.synchronize do
+        @live.delete(index)
+        @supervisor_threads.delete(Thread.current)
+        @retiring.delete(index)
+      end
+      @bank.release(worker_ids) if retired && worker_ids
+      report_active
+    end
+
+    def report_active
+      Native.set_active_workers(@server_id, active_count)
+    end
+
     def draining?
       @lock.synchronize { @draining }
     end

data/lib/kino/server.rb

@@ -68,6 +68,16 @@ module Kino
       @bind = settings[:bind]
       @requested_port = settings[:port]
       @workers = Integer(settings[:workers])
+      # The pool ceiling; equal to the floor for a fixed pool.
+      @max_workers = settings[:max_workers].nil? ? @workers : Integer(settings[:max_workers])
+      if @max_workers < @workers
+        raise ArgumentError, "max_workers (#{@max_workers}) must be at least workers (#{@workers})"
+      end
+      @scale_down_after = settings[:scale_down_after].nil? ? 30.0 : Float(settings[:scale_down_after])
+      raise ArgumentError, "scale_down_after must be positive" unless @scale_down_after.positive?
+      if !settings[:scale_down_after].nil? && !elastic?
+        Log.warn("scale_down_after has no effect unless max_workers is above workers")
+      end
       @on_error = validate_hook(settings[:on_error], :on_error)
       @after_worker_boot = validate_hook(settings[:after_worker_boot], :after_worker_boot)
       @after_request_complete = validate_hook(settings[:after_request_complete], :after_request_complete)
@@ -81,8 +91,9 @@ module Kino
         # The access log's GC and allocation figures come from the VM's
         # process-wide counters, so they are measured only where one
         # request at a time can own them: the GVL serializes :threaded
-        # mode, and a single ractor has nothing to race.
-        access_timing: !!settings[:log_requests] && (@mode == :threaded || @workers == 1)
+        # mode, and a single ractor (a pool that can never grow past one)
+        # has nothing to race.
+        access_timing: !!settings[:log_requests] && (@mode == :threaded || @max_workers == 1)
       )
       # Default threads per mode: 1 in :ractor (threads inside a ractor
       # share its lock; a measured +17% on fast handlers; raise `workers`
@@ -109,6 +120,7 @@ module Kino
       if @tls && unix?
         raise ArgumentError, "TLS is not supported on a unix socket bind; terminate TLS at the proxy in front"
       end
+      @http2 = settings.fetch(:http2, true) ? true : false
       @pidfile = settings[:pidfile]
       @control_bind = settings[:control_bind]&.to_s
       @control_token = settings[:control_token]&.to_s
@@ -125,10 +137,10 @@ module Kino
         else
           @workers * @threads
         end
-      @worker_threads = []
-      @worker_threads_lock = Mutex.new
       @supervisor = nil
+      @threaded_pool = nil
       @quarantine_monitor = nil
+      @pool_scaler = nil
       @started = false
     end
 
@@ -155,8 +167,10 @@ module Kino
           io_threads: @io_threads,
           tokio_threads: @tokio_threads,
           tls_cert: @tls&.fetch(:cert), tls_key: @tls&.fetch(:key),
+          http2: @http2,
           lanes: @lanes, log_requests: @log_requests,
-          mode: @mode.to_s, workers: @workers, threads: @threads, batch: @batch,
+          mode: @mode.to_s, workers: @workers, max_workers: @max_workers,
+          threads: @threads, batch: @batch,
           control_bind: @control_bind, control_token: @control_token
         )
         booted = true
@@ -167,12 +181,15 @@ module Kino
       # lifetime so in-flight buffers survive even a worker ractor crash.
       @pin_keeper = Native.pin_keeper(@id)
       if @mode == :ractor
+        warn_scheduler_cap
         @supervisor = RactorSupervisor.new(@id, @app, workers: @workers, threads: @threads,
           batch: @batch, hooks: @worker_hooks, on_worker_exit: @on_worker_exit).start
       else
-        @worker_threads = (@workers * @threads).times.map { spawn_worker_thread }
+        @threaded_pool = ThreadedPool.new(@id, @app, threads: @threads, batch: @batch,
+          hooks: @worker_hooks, on_worker_exit: @on_worker_exit).start(@workers)
       end
       start_quarantine_monitor if @quarantine_timeout_ms
+      start_pool_scaler if elastic?
       Native.control_ready(@id)
       HookFire.fire(@after_boot, "after_boot")
       @started = true
@@ -190,6 +207,7 @@ module Kino
     def shutdown(timeout: nil)
       return unless @started
 
+      @pool_scaler&.stop
       @quarantine_monitor&.stop
       deadline = monotonic_now + (timeout || @shutdown_timeout)
       Native.stop_accepting(@id)
@@ -222,7 +240,6 @@ module Kino
       # The runtime is gone, so hyper has dropped every pinned buffer;
       # the keeper (and the strings it marked) may now be collected.
       @pin_keeper = nil
-      @worker_threads.clear
       @started = false
       remove_pidfile if @pidfile
       nil
@@ -231,7 +248,7 @@ module Kino
     # Block until every worker has exited (i.e. until shutdown).
     # @return [void]
     def wait
-      @supervisor ? @supervisor.join : @worker_threads.each(&:join)
+      pool.join
     end
 
     # Production entry point: build the server and {#run} it. The `kino`
@@ -296,19 +313,22 @@ module Kino
     #   lanes mode) once started
     def stats
       base = {
-        mode: @mode, lanes: @lanes, workers: @workers, threads: @threads,
-        batch: @batch, respawns: 0
+        mode: @mode, lanes: @lanes, workers: @workers, max_workers: @max_workers,
+        threads: @threads, batch: @batch, respawns: 0,
+        active_workers: @workers, scale_ups: 0, scale_downs: 0
       }
       return base unless @started
 
       queued, in_flight, served, rejected, timeouts, respawns, lane_depths = Native.server_stats(@id)
       base.merge!(queued:, in_flight:, served:, rejected:, timeouts:, respawns:)
       base[:lane_depths] = lane_depths if lane_depths
+      active_workers, _max_workers, scale_ups, scale_downs = Native.pool_stats(@id)
+      base.merge!(active_workers:, scale_ups:, scale_downs:)
       rows = Native.worker_stats(@id)
-      base[:worker_status] = rows.map do |index, served, in_flight, busy_ms, quarantined|
-        {index:, served:, in_flight:, busy_ms:, quarantined:}
+      base[:worker_status] = rows.map do |index, served, in_flight, busy_ms, quarantined, retired|
+        {index:, served:, in_flight:, busy_ms:, quarantined:, retired:}
       end
-      base[:quarantined] = rows.count { |_index, _served, _in_flight, _busy_ms, quarantined| quarantined }
+      base[:quarantined] = rows.count { |row| row[4] }
       count, sum_seconds = Native.queue_time(@id)
       base[:queue_time] = {count:, sum_seconds:}
       base
@@ -316,63 +336,38 @@ module Kino
 
     private
 
-    # Register a fresh dispatch slot and run a worker thread on it; returns
-    # the thread. Used at boot and by the quarantine replacer.
-    def spawn_worker_thread
-      worker_id = Native.register_worker(@id)
-      Thread.new do
-        # Named so log lines from inside say which worker spoke.
-        Thread.current.name = "worker-#{worker_id}"
-        error = nil
-        begin
-          Worker.run(@id, worker_id, @app, @batch, @worker_hooks)
-        rescue Exception => e # rubocop:disable Lint/RescueException -- a hard crash in a threaded worker thread
-          error = e
-          raise
-        ensure
-          HookFire.fire(@on_worker_exit, "on_worker_exit", worker_id, error)
-        end
-      end
+    # The worker pool this mode runs: the ractor supervisor, or the
+    # threaded pool. Both spawn, retire, replace and join workers behind
+    # the same methods.
+    def pool
+      @supervisor || @threaded_pool
     end
 
-    # Track a replacement thread spawned outside the initial pool assignment
-    # (the quarantine replacer) so shutdown's join/done?/kill sweeps see it.
-    def track_replacement_thread(thread)
-      @worker_threads_lock.synchronize { @worker_threads << thread }
+    # Both pools are quarantine replacers: replace(worker_id) spawns a
+    # replacement worker, then quarantines the wedged slot.
+    def start_quarantine_monitor
+      @quarantine_monitor = QuarantineMonitor.new(
+        server_id: @id, timeout_ms: @quarantine_timeout_ms,
+        max: @quarantine_max, replacer: pool
+      ).start
     end
 
-    # @private
-    # The :threaded-mode quarantine replacer: spawns a replacement worker
-    # thread, quarantines the wedged slot, then tracks the new thread so
-    # shutdown's join/done?/kill sweeps see it. Built from bound Method
-    # objects instead of a server reference, so it drives the server
-    # through those methods without send or instance_variable_get.
-    class ThreadedReplacer
-      def initialize(server_id:, spawner:, tracker:)
-        @server_id = server_id
-        @spawner = spawner
-        @tracker = tracker
-      end
+    # Ruby's M:N scheduler runs non-main ractors' Ruby code on at most
+    # RUBY_MAX_CPU native threads (default 8). Workers past that cap share
+    # timeslices instead of adding parallelism, and a fresh ractor can wait
+    # seconds for its first one while the others are CPU-bound.
+    def warn_scheduler_cap
+      cap = Integer(ENV.fetch("RUBY_MAX_CPU", "8"), exception: false) || 8
+      return if @max_workers <= cap
 
-      def replace(worker_id)
-        thread = @spawner.call # spawn FIRST (may raise ThreadError)
-        Native.quarantine_slot(@server_id, worker_id) # quarantine after success
-        @tracker.call(thread)
-        true
-      end
+      Log.warn("#{@max_workers} ractor workers exceed RUBY_MAX_CPU=#{cap}: only #{cap} can run " \
+        "Ruby code at once; set RUBY_MAX_CPU=#{@max_workers} for CPU-bound apps")
     end
-    private_constant :ThreadedReplacer
 
-    # A replacer.replace(worker_id) spawns a replacement worker, then
-    # quarantines the wedged slot, mode-appropriately. In :ractor the
-    # supervisor is the replacer; in :threaded a small object over
-    # spawn_worker_thread.
-    def start_quarantine_monitor
-      replacer = @supervisor || ThreadedReplacer.new(server_id: @id, spawner: method(:spawn_worker_thread),
-        tracker: method(:track_replacement_thread))
-      @quarantine_monitor = QuarantineMonitor.new(
-        server_id: @id, timeout_ms: @quarantine_timeout_ms,
-        max: @quarantine_max, replacer: replacer
+    def start_pool_scaler
+      @pool_scaler = PoolScaler.new(
+        server_id: @id, pool: pool, floor: @workers, ceiling: @max_workers,
+        scale_down_after: @scale_down_after
       ).start
     end
 
@@ -398,6 +393,11 @@ module Kino
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    # A pool that can grow: the ceiling is above the floor.
+    def elastic?
+      @max_workers > @workers
+    end
+
     # Default connection cap: most of the process open-file limit. A
     # connection flood's failure mode is descriptor exhaustion, and in
     # :ractor/:threaded mode the app's own sockets and files share this
@@ -472,34 +472,15 @@ module Kino
     end
 
     def join_workers(deadline)
-      if @supervisor
-        @supervisor.shutdown([deadline - monotonic_now, 0].max)
-      else
-        threads = @worker_threads_lock.synchronize { @worker_threads.dup }
-        threads.each do |thread|
-          thread.join([deadline - monotonic_now, 0.01].max)
-        end
-      end
+      pool.shutdown([deadline - monotonic_now, 0].max)
     end
 
     def workers_done?
-      if @supervisor
-        @supervisor.done?
-      else
-        threads = @worker_threads_lock.synchronize { @worker_threads.dup }
-        threads.none?(&:alive?)
-      end
+      pool.done?
     end
 
     def kill_stragglers
-      if @supervisor
-        # Ractors cannot be force-killed; their clients were already freed
-        # by abort_all_inflight. The stuck ractor leaks until process exit.
-        Log.error("shutdown deadline passed with stuck ractor workers") unless @supervisor.done?
-      else
-        threads = @worker_threads_lock.synchronize { @worker_threads.dup }
-        threads.each { |thread| thread.kill if thread.alive? }
-      end
+      pool.kill_stragglers
     end
 
     # Policy (mode resolution): when is an app safe for ractor

data/lib/kino/slot_bank.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kino
+  # @private
+  # Dispatch slots for a worker pool: fresh ones from the native registry,
+  # or ones that retired workers handed back, reset for their next
+  # occupant. The native side never removes a slot, so recycling is what
+  # keeps the slot table from growing as an elastic pool breathes. Only
+  # cleanly exited workers return slots; a crashed worker's slots are
+  # abandoned (stale interrupt kicks and dead weak refs go down with
+  # them).
+  class SlotBank
+    def initialize(server_id)
+      @server_id = server_id
+      @free = []
+      @lock = Mutex.new
+    end
+
+    def claim
+      id = @lock.synchronize { @free.pop }
+      return Native.register_worker(@server_id) unless id
+
+      Native.reset_slot(@server_id, id)
+      id
+    end
+
+    def release(ids)
+      @lock.synchronize { @free.concat(ids) }
+    end
+  end
+end

data/lib/kino/templates/kino.rb.tt

@@ -20,6 +20,11 @@
 # PEM strings also work).
 # tls cert: "config/certs/server.pem", key: "config/certs/server.key"
 
+# HTTP/2 is on by default: negotiated via ALPN on TLS binds, and served
+# to prior-knowledge (h2c) clients on plaintext. Everything else keeps
+# getting HTTP/1.1. Set false to serve HTTP/1 only.
+# http2 false
+
 ## Topology
 
 # How many workers to run. Each worker handles requests independently;
@@ -35,6 +40,21 @@
 # `workers` instead.
 # threads 1
 
+## Elastic pool (experimental)
+#
+# Let the pool grow past `workers` under load and shrink back when
+# idle: one worker is added every 100 ms while requests wait in the
+# queue, and a worker above `workers` retires after `scale_down_after`
+# seconds idle. Helps apps that wait on databases or other services;
+# pure CPU work gains nothing past the core count. Unset (the default)
+# keeps the pool fixed. In :ractor mode, Ruby runs at most RUBY_MAX_CPU
+# (default 8) ractors' Ruby code at once; set that variable to match
+# `max_workers` on bigger boxes.
+# max_workers 32
+
+# Seconds an extra worker must sit idle before it is retired.
+# scale_down_after 30
+
 ## Dispatch mode
 #
 # :auto     - picks :ractor when your app supports it, else :threaded.