kino 0.5.0 → 0.7.0

data/ext/kino/src/pin.rs

@@ -22,6 +22,10 @@
 //! GVL held), release is a single atomic store from whatever tokio
 //! thread drops the buffer, and the mark hook only loads atomics, so
 //! no path takes a lock. A full slab degrades to the copy path.
+//!
+//! The slab is also how env_strings.rs roots its cached env strings (a
+//! second slab, marked through its own keeper), for the same reason: no
+//! GC registration API may be called from parallel ractors.
 
 use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 use std::sync::Arc;
@@ -50,8 +54,9 @@ extern "C" {
     fn rb_str_tmp_frozen_acquire(orig: rb_sys::VALUE) -> rb_sys::VALUE;
 }
 
-/// GC roots for in-flight response buffers. Slot value 0 = empty (a
-/// VALUE of 0 is Qfalse, which can never be a pinned string).
+/// A fixed slab of atomic VALUE slots, each a pinning GC root while it
+/// is non-zero. Slot value 0 = empty (a VALUE of 0 is Qfalse, which can
+/// never be a rooted string).
 pub struct PinSlab {
     slots: Box<[AtomicU64]>,
     /// Rotating claim cursor: keeps the free-slot scan O(1) amortized.
@@ -59,15 +64,21 @@ pub struct PinSlab {
 }
 
 impl PinSlab {
+    /// A slab for one server's in-flight response buffers.
     pub fn new() -> Self {
+        Self::with_capacity(SLAB_CAPACITY)
+    }
+
+    pub fn with_capacity(capacity: usize) -> Self {
         PinSlab {
-            slots: (0..SLAB_CAPACITY).map(|_| AtomicU64::new(0)).collect(),
+            slots: (0..capacity).map(|_| AtomicU64::new(0)).collect(),
             cursor: AtomicUsize::new(0),
         }
     }
 
-    /// Root `value`; None when the slab is full (caller copies instead).
-    fn insert(&self, value: rb_sys::VALUE) -> Option<usize> {
+    /// Root `value`; None when the slab is full (the caller falls back to
+    /// a copy, or to an uncached string).
+    pub(crate) fn insert(&self, value: rb_sys::VALUE) -> Option<usize> {
         let start = self.cursor.fetch_add(1, Ordering::Relaxed);
         for offset in 0..self.slots.len() {
             let index = (start + offset) % self.slots.len();
@@ -83,7 +94,7 @@ impl PinSlab {
 
     /// Drop the root. Called from tokio threads: a plain atomic store,
     /// no Ruby API. The string stays alive until the next GC sweep.
-    fn release(&self, index: usize) {
+    pub(crate) fn release(&self, index: usize) {
         self.slots[index].store(0, Ordering::SeqCst);
     }
 
@@ -113,9 +124,10 @@ impl PinSlab {
     }
 }
 
-/// The GC-visible face of a server's PinSlab: `Kino::Server` holds one
-/// for its lifetime (surviving worker-ractor crashes), and Ruby's GC
-/// marks every pinned string through it.
+/// The GC-visible face of a PinSlab: Ruby's GC marks every rooted string
+/// through it. `Kino::Server` holds one for its response-buffer slab for
+/// the server's lifetime (surviving worker-ractor crashes); env_strings
+/// registers one for its cache slab as an immortal root at init.
 #[derive(magnus::TypedData)]
 #[magnus(class = "Kino::Native::PinKeeper", free_immediately, mark)]
 pub struct PinKeeper(pub Arc<PinSlab>);

data/ext/kino/src/queue.rs

@@ -25,6 +25,21 @@ pub const TICK: Duration = Duration::from_millis(50);
 /// the difference and doesn't need to.
 type Taken = Option<BoxedCtx>;
 
+/// What a take does when its bounded wait times out: keep waiting (None),
+/// or end the loop because the pool scaler retired this slot. A retired
+/// lane worker first empties its own lane, one item per timeout: the
+/// dispatcher stopped feeding it when the flag went up (see
+/// registry::WorkerSlot::retire for the ordering), so whatever is
+/// still there is the last of it, and nothing already assigned is
+/// orphaned. Only reached with the queue momentarily empty, so the fast
+/// path pays nothing for it.
+fn after_timeout(slot: &WorkerSlot) -> Option<Taken> {
+    if !slot.retired.load(Ordering::SeqCst) {
+        return None;
+    }
+    Some(slot.lane_rx.as_ref().and_then(|rx| rx.try_recv().ok()))
+}
+
 /// Block until one request arrives (GVL released, interruptible).
 /// No busy-poll before parking, deliberately: the wake-per-request futex
 /// cost is real (~20% of cycles at saturation, per perf), but a measured
@@ -46,7 +61,7 @@ fn block_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Result<Taken, Err
             let taken =
                 gvl::interruptible(&slot.interrupted, || match req_rx.recv_timeout(TICK) {
                     Ok(ctx) => Some(Some(ctx)),
-                    Err(flume::RecvTimeoutError::Timeout) => None,
+                    Err(flume::RecvTimeoutError::Timeout) => after_timeout(slot),
                     Err(flume::RecvTimeoutError::Disconnected) => Some(None),
                 })?;
             Ok(taken.flatten())
@@ -93,8 +108,10 @@ fn lane_take(server: &ServerInner, slot: &Arc<WorkerSlot>) -> Result<Taken, Erro
         match lane_rx.recv_timeout(TICK) {
             Ok(ctx) => Some(Some(ctx)),
             // Periodic steal so a backlog behind a slow sibling can't
-            // outlive a tick.
-            Err(flume::RecvTimeoutError::Timeout) => steal().map(Some),
+            // outlive a tick; a retired worker leaves instead.
+            Err(flume::RecvTimeoutError::Timeout) => {
+                after_timeout(slot).or_else(|| steal().map(Some))
+            }
             Err(flume::RecvTimeoutError::Disconnected) => Some(None),
         }
     });
@@ -138,54 +155,73 @@ fn admit(
     Ok(env)
 }
 
-type Checkout = (Arc<ServerInner>, Arc<WorkerSlot>, BoxedCtx);
+/// Per-worker native handle: the registry lookup and slot resolution are
+/// paid once at worker boot instead of on every take. Created inside the
+/// worker thread/ractor that uses it (like Request handles), so ownership
+/// is correct by construction. Holds the server weakly: after teardown the
+/// upgrade fails, which is the same clean shutdown signal the per-take
+/// registry lookup used to give.
+#[magnus::wrap(class = "Kino::Native::Worker", free_immediately)]
+pub struct Worker {
+    server: std::sync::Weak<ServerInner>,
+    slot: Arc<WorkerSlot>,
+}
 
-fn checkout(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<Option<Checkout>, Error> {
+/// Resolve a (server, worker) pair into a Worker handle; nil when the
+/// server is already gone (the caller treats that as shutdown).
+pub fn worker(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<Option<Worker>, Error> {
     let Some(server) = registry::try_get(server_id) else {
-        return Ok(None); // server torn down → clean shutdown signal
+        return Ok(None);
     };
     let slot = server.slot(ruby, worker_id)?;
+    Ok(Some(Worker {
+        server: Arc::downgrade(&server),
+        slot,
+    }))
+}
 
-    // The previous batch is fully answered once the worker comes back.
-    slot.current.lock().clear();
-    slot.in_flight.store(0, Ordering::Relaxed);
-    slot.interrupted.store(false, Ordering::SeqCst);
+impl Worker {
+    fn checkout(&self) -> Result<Option<(Arc<ServerInner>, BoxedCtx)>, Error> {
+        let Some(server) = self.server.upgrade() else {
+            return Ok(None); // server torn down → clean shutdown signal
+        };
 
-    Ok(block_take(&server, &slot)?.map(|ctx| (server, slot, ctx)))
-}
+        // The previous batch is fully answered once the worker comes back.
+        self.slot.current.lock().clear();
+        self.slot.in_flight.store(0, Ordering::Relaxed);
+        self.slot.interrupted.store(false, Ordering::SeqCst);
 
-/// Take one request; returns its env Hash (request handle inside under
-/// "kino.request") or nil on shutdown. The batch-of-one hot path: no
-/// arrays allocated at all.
-pub fn take_one(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<Option<RHash>, Error> {
-    match checkout(ruby, server_id, worker_id)? {
-        Some((server, slot, ctx)) => Ok(Some(admit(ruby, &server, &slot, ctx)?)),
-        None => Ok(None),
+        Ok(block_take(&server, &self.slot)?.map(|ctx| (server, ctx)))
     }
-}
 
-/// Take up to `max` requests: block for the first, drain the rest
-/// non-blocking (they only batch when the queue is already deep).
-/// Returns nil on shutdown; otherwise an Array of env Hashes.
-pub fn take_batch(
-    ruby: &Ruby,
-    server_id: u64,
-    worker_id: usize,
-    max: usize,
-) -> Result<Option<RArray>, Error> {
-    let Some((server, slot, first)) = checkout(ruby, server_id, worker_id)? else {
-        return Ok(None);
-    };
+    /// Take one request; returns its env Hash (request handle inside under
+    /// "kino.request") or nil on shutdown. The batch-of-one hot path: no
+    /// arrays allocated at all.
+    pub fn take_one(ruby: &Ruby, rb_self: &Worker) -> Result<Option<RHash>, Error> {
+        match rb_self.checkout()? {
+            Some((server, ctx)) => Ok(Some(admit(ruby, &server, &rb_self.slot, ctx)?)),
+            None => Ok(None),
+        }
+    }
+
+    /// Take up to `max` requests: block for the first, drain the rest
+    /// non-blocking (they only batch when the queue is already deep).
+    /// Returns nil on shutdown; otherwise an Array of env Hashes.
+    pub fn take_batch(ruby: &Ruby, rb_self: &Worker, max: usize) -> Result<Option<RArray>, Error> {
+        let Some((server, first)) = rb_self.checkout()? else {
+            return Ok(None);
+        };
 
-    let batch = ruby.ary_new_capa(max.max(1));
-    batch.push(admit(ruby, &server, &slot, first)?)?;
-    for _ in 1..max {
-        match server.req_rx.try_recv() {
-            Ok(ctx) => batch.push(admit(ruby, &server, &slot, ctx)?)?,
-            Err(_) => break,
+        let batch = ruby.ary_new_capa(max.max(1));
+        batch.push(admit(ruby, &server, &rb_self.slot, first)?)?;
+        for _ in 1..max {
+            match server.req_rx.try_recv() {
+                Ok(ctx) => batch.push(admit(ruby, &server, &rb_self.slot, ctx)?)?,
+                Err(_) => break,
+            }
         }
+        Ok(Some(batch))
     }
-    Ok(Some(batch))
 }
 
 /// The fused hot path: answer `request` (complete response in one shot)
@@ -194,28 +230,104 @@ pub fn take_batch(
 pub fn respond_and_take_one(
     ruby: &Ruby,
     request: &Request,
-    server_id: u64,
-    worker_id: usize,
+    worker: magnus::typed_data::Obj<Worker>,
     status: u16,
     headers: RHash,
     body: RString,
 ) -> Result<Option<RHash>, Error> {
     crate::request::respond_simple(ruby, request, status, headers, body)?;
-    take_one(ruby, server_id, worker_id)
+    Worker::take_one(ruby, &worker)
 }
 
 /// Batch variant of the fused call.
-#[allow(clippy::too_many_arguments)]
 pub fn respond_and_take(
     ruby: &Ruby,
     request: &Request,
-    server_id: u64,
-    worker_id: usize,
+    worker: magnus::typed_data::Obj<Worker>,
     max: usize,
     status: u16,
     headers: RHash,
     body: RString,
 ) -> Result<Option<RArray>, Error> {
     crate::request::respond_simple(ruby, request, status, headers, body)?;
-    take_batch(ruby, server_id, worker_id, max)
+    Worker::take_batch(ruby, &worker, max)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::registry::test_server;
+    use crate::request::test_ctx;
+
+    #[test]
+    fn a_take_keeps_waiting_after_a_timeout_unless_the_slot_is_retired() {
+        let server = test_server(false, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+
+        assert!(after_timeout(&slot).is_none());
+    }
+
+    #[test]
+    fn a_retired_shared_queue_worker_ends_its_loop_at_the_next_timeout() {
+        let server = test_server(false, 4);
+        server.register_worker();
+        server.slots.read()[0].retire();
+        let slot = server.slots.read()[0].clone();
+
+        assert!(matches!(after_timeout(&slot), Some(None)));
+    }
+
+    #[test]
+    fn a_retired_lane_worker_drains_its_own_lane_before_leaving() {
+        let server = test_server(true, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+        slot.lane_tx
+            .lock()
+            .as_ref()
+            .expect("lane open")
+            .send(test_ctx())
+            .expect("lane has room");
+        server.slots.read()[0].retire();
+
+        // One item still assigned to this lane: serve it, not orphan it.
+        assert!(matches!(after_timeout(&slot), Some(Some(_))));
+        // Lane empty now: leave.
+        assert!(matches!(after_timeout(&slot), Some(None)));
+    }
+
+    #[test]
+    fn a_retired_lane_worker_drains_every_item_one_per_timeout() {
+        let server = test_server(true, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+        for _ in 0..3 {
+            slot.lane_tx
+                .lock()
+                .as_ref()
+                .expect("lane open")
+                .send(test_ctx())
+                .expect("lane has room");
+        }
+        server.slots.read()[0].retire();
+
+        for _ in 0..3 {
+            assert!(matches!(after_timeout(&slot), Some(Some(_))));
+        }
+        assert!(matches!(after_timeout(&slot), Some(None)));
+    }
+
+    #[test]
+    fn a_reset_slot_keeps_waiting_again() {
+        let server = test_server(false, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+        slot.retire();
+        assert!(matches!(after_timeout(&slot), Some(None)));
+
+        slot.reset();
+
+        assert!(after_timeout(&slot).is_none());
+    }
 }

data/ext/kino/src/registry.rs

@@ -21,7 +21,11 @@ pub const STATE_DRAINING: u8 = 2;
 /// "ractor" or "threaded", never "auto".
 pub struct Topology {
     pub mode: String,
+    /// The pool floor: the configured worker count.
     pub workers: usize,
+    /// The pool ceiling: equal to `workers` for a fixed pool. HTTP/2
+    /// admission (SETTINGS_MAX_CONCURRENT_STREAMS) is advertised from it.
+    pub max_workers: usize,
     pub threads: usize,
     pub batch: usize,
 }
@@ -113,8 +117,18 @@ pub struct ServerInner {
     pub respawns: AtomicU64,
     /// Replacements spawned by the quarantine monitor (Relaxed, advisory).
     pub quarantine_replacements: AtomicU64,
+    /// Workers staying in the pool (a worker told to retire no longer
+    /// counts), reported by the Ruby pool as it grows and shrinks; starts
+    /// at the floor. Relaxed, advisory.
+    pub active_workers: AtomicUsize,
+    /// Pool scaler events (Relaxed, advisory).
+    pub scale_ups: AtomicU64,
+    pub scale_downs: AtomicU64,
     pub topology: Topology,
     pub https: bool,
+    /// HTTP/2 serving (ALPN over TLS, prior-knowledge h2c on plaintext);
+    /// false pins every connection to HTTP/1.
+    pub http2: bool,
     /// The socket file of a `unix://` bind, removed at shutdown.
     pub unix_path: Option<std::path::PathBuf>,
     /// Native access log sink (None unless log_requests is on).
@@ -155,6 +169,11 @@ pub struct WorkerSlot {
     /// Set by the quarantine monitor when this slot is abandoned as wedged:
     /// excluded from wedge detection, and its busy_ms is reported as 0.
     pub quarantined: std::sync::atomic::AtomicBool,
+    /// Set by the pool scaler to send this slot's worker home: the lane
+    /// dispatcher skips it, and the take loop ends at its next idle tick
+    /// (a request already taken finishes first). Cleared by `reset` when
+    /// the slot is handed to a new worker.
+    pub retired: std::sync::atomic::AtomicBool,
 }
 
 /// Per-lane depth cap: small, so a slow handler can only ever delay this
@@ -248,8 +267,35 @@ impl WorkerSlot {
             in_flight: AtomicUsize::new(0),
             last_started_ms: AtomicU64::new(0),
             quarantined: std::sync::atomic::AtomicBool::new(false),
+            retired: std::sync::atomic::AtomicBool::new(false),
         }
     }
+
+    /// Send this slot's worker home once it is idle. The flag is raised
+    /// under the lane lock, the same lock the lane dispatcher holds while
+    /// it checks the flag and sends: any dispatch that saw "not retired"
+    /// has landed in the lane before the worker can see the flag and
+    /// drain, so no request is orphaned.
+    pub fn retire(&self) {
+        let _lane = self.lane_tx.lock();
+        self.retired.store(true, Ordering::SeqCst);
+    }
+
+    /// Return a retired slot to its fresh state so a new worker can take
+    /// it over (slots are never removed; recycling keeps the registry
+    /// from growing with every scale-up). The lane channel stays, the new
+    /// occupant simply starts taking from it; the quarantine mark stays
+    /// too, a quarantined slot is never handed out.
+    pub fn reset(&self) {
+        let _lane = self.lane_tx.lock();
+        self.current.lock().clear();
+        self.retired.store(false, Ordering::SeqCst);
+        self.parked.store(false, Ordering::SeqCst);
+        self.interrupted.store(false, Ordering::SeqCst);
+        self.served.store(0, Ordering::Relaxed);
+        self.in_flight.store(0, Ordering::Relaxed);
+        self.last_started_ms.store(0, Ordering::Relaxed);
+    }
 }
 
 static REGISTRY: OnceLock<RwLock<HashMap<u64, Arc<ServerInner>>>> = OnceLock::new();
@@ -347,13 +393,18 @@ pub fn test_server(lanes: bool, queue_depth: usize) -> Arc<ServerInner> {
         state: std::sync::atomic::AtomicU8::new(STATE_BOOTING),
         respawns: AtomicU64::new(0),
         quarantine_replacements: AtomicU64::new(0),
+        active_workers: AtomicUsize::new(0),
+        scale_ups: AtomicU64::new(0),
+        scale_downs: AtomicU64::new(0),
         topology: Topology {
             mode: "threaded".to_string(),
             workers: 0,
+            max_workers: 0,
             threads: 0,
             batch: 1,
         },
         https: false,
+        http2: true,
         unix_path: None,
         access_log: None,
         lanes,
@@ -487,6 +538,18 @@ mod tests {
         assert_eq!(server.topology.batch, 1);
     }
 
+    #[test]
+    fn pool_counters_start_at_the_configured_floor() {
+        let server = test_server(false, 4);
+        assert_eq!(
+            server.active_workers.load(Ordering::Relaxed),
+            server.topology.workers
+        );
+        assert_eq!(server.topology.max_workers, server.topology.workers);
+        assert_eq!(server.scale_ups.load(Ordering::Relaxed), 0);
+        assert_eq!(server.scale_downs.load(Ordering::Relaxed), 0);
+    }
+
     #[test]
     fn fresh_slot_has_zeroed_per_worker_sensors() {
         let server = test_server(false, 4);
@@ -506,6 +569,88 @@ mod tests {
         assert_eq!(server.quarantine_replacements.load(Ordering::Relaxed), 0);
     }
 
+    #[test]
+    fn fresh_slot_is_not_retired() {
+        let server = test_server(false, 4);
+        server.register_worker();
+        assert!(!server.slots.read()[0].retired.load(Ordering::Relaxed));
+    }
+
+    #[test]
+    fn retire_then_reset_returns_a_slot_to_its_fresh_state() {
+        let server = test_server(true, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+        slot.parked.store(true, Ordering::Relaxed);
+        slot.interrupted.store(true, Ordering::Relaxed);
+        slot.served.store(5, Ordering::Relaxed);
+        slot.in_flight.store(1, Ordering::Relaxed);
+        slot.last_started_ms.store(9, Ordering::Relaxed);
+        slot.current.lock().push(std::sync::Weak::new());
+
+        slot.retire();
+        assert!(slot.retired.load(Ordering::Relaxed));
+
+        slot.reset();
+        assert!(!slot.retired.load(Ordering::Relaxed));
+        assert!(!slot.parked.load(Ordering::Relaxed));
+        assert!(!slot.interrupted.load(Ordering::Relaxed));
+        assert_eq!(slot.served.load(Ordering::Relaxed), 0);
+        assert_eq!(slot.in_flight.load(Ordering::Relaxed), 0);
+        assert_eq!(slot.last_started_ms.load(Ordering::Relaxed), 0);
+        assert!(slot.current.lock().is_empty());
+        // The lane survives reuse: the next occupant takes from it.
+        assert!(slot.lane_tx.lock().is_some());
+    }
+
+    #[test]
+    fn reset_keeps_a_quarantine_mark() {
+        let server = test_server(false, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+        slot.quarantined.store(true, Ordering::Relaxed);
+
+        slot.retire();
+        slot.reset();
+
+        // A wedged slot stays flagged even if it ever came back around.
+        assert!(slot.quarantined.load(Ordering::Relaxed));
+    }
+
+    #[test]
+    fn retire_releases_the_lane_lock() {
+        let server = test_server(true, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+
+        slot.retire();
+
+        assert!(slot.lane_tx.try_lock().is_some());
+    }
+
+    #[test]
+    fn retire_waits_for_a_dispatcher_holding_the_lane_lock() {
+        let server = test_server(true, 4);
+        server.register_worker();
+        let slot = server.slots.read()[0].clone();
+
+        // A dispatcher that has already read "not retired" and is sending.
+        let sending = slot.lane_tx.lock();
+        let retiring = std::thread::spawn({
+            let slot = slot.clone();
+            move || slot.retire()
+        });
+        std::thread::sleep(Duration::from_millis(30));
+        assert!(
+            !slot.retired.load(Ordering::SeqCst),
+            "the flag must not go up under a dispatcher's lock"
+        );
+
+        drop(sending);
+        retiring.join().expect("retire thread");
+        assert!(slot.retired.load(Ordering::SeqCst));
+    }
+
     #[test]
     fn queue_histogram_buckets_by_wait() {
         let h = QueueHistogram::new();