castrum 0.9.3 → 0.9.6

package/rust/task/runtime.rs

@@ -0,0 +1,220 @@
+// rust/task/runtime.rs — process-wide off-thread task pool.
+//
+// A small, dependency-free, work-sharing pool: one condvar-gated queue and N
+// worker threads. It is deliberately SEPARATE from the rayon global pool
+// (`util/threadpool.rs`), which stays the batch `par_iter` executor — mixing
+// long blocking offloads into rayon would starve batch parallelism.
+//
+// Lifecycle is first-init-wins (`OnceLock` + a `start()` CAS), so the FFI
+// entry, a direct `submit`, and tests all converge on ONE pool per process.
+
+use parking_lot::{Condvar, Mutex};
+use std::collections::VecDeque;
+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::OnceLock;
+use std::time::Duration;
+
+/// Jobs a worker takes per queue-lock acquisition. Amortizes the lock when many
+/// tasks arrive at once (e.g. `Promise.all` over 2 000 items) instead of
+/// re-locking per task.
+const BATCH_POP: usize = 16;
+/// Bounded spin before parking. A job that lands while a worker is between
+/// "queue empty" and "park" is picked up WITHOUT a futex syscall — the common
+/// case for a burst, and pure kernel-time saved.
+const SPIN_ROUNDS: u32 = 64;
+/// Idle park timeout. A bounded wait (instead of an indefinite one) means a
+/// missed wakeup costs at most this much latency and can never wedge a worker.
+const PARK_TIMEOUT: Duration = Duration::from_micros(200);
+
+/// A unit of offloaded work. Owns its input bytes (`'static`, `Send`).
+pub type Job = Box<dyn FnOnce() + Send + 'static>;
+
+/// The process-wide task pool.
+pub struct TaskPool {
+    queue: Mutex<VecDeque<Job>>,
+    cv: Condvar,
+    running: AtomicBool,
+    threads: AtomicU32,
+}
+
+static POOL: OnceLock<TaskPool> = OnceLock::new();
+
+impl TaskPool {
+    fn new() -> Self {
+        Self {
+            queue: Mutex::new(VecDeque::new()),
+            cv: Condvar::new(),
+            running: AtomicBool::new(false),
+            threads: AtomicU32::new(0),
+        }
+    }
+
+    /// Spawn `n` workers. Idempotent: the `running` CAS means only the first
+    /// caller actually spawns, so a concurrent `init` + implicit `submit` race
+    /// cannot double the pool.
+    fn start(&'static self, n: usize) {
+        if self.running.swap(true, Ordering::AcqRel) {
+            return;
+        }
+        let n = n.max(1);
+        self.threads.store(n as u32, Ordering::Release);
+        for i in 0..n {
+            let _ = std::thread::Builder::new()
+                .name(format!("castrum-task-{i}"))
+                .stack_size(512 * 1024)
+                .spawn(move || {
+                    pin_worker(i);
+                    self.worker();
+                });
+        }
+    }
+
+    fn worker(&self) {
+        // Reused across iterations so the batch path adds no per-task allocation.
+        let mut batch: Vec<Job> = Vec::with_capacity(BATCH_POP);
+        let mut spin = 0u32;
+        loop {
+            batch.clear();
+            {
+                let mut q = self.queue.lock();
+                if let Some(first) = q.pop_front() {
+                    batch.push(first);
+                    // Only keep pulling while there is genuinely plenty of work
+                    // left, so one greedy worker cannot starve its idle peers
+                    // (e.g. 8 tasks on an 11-thread pool must fan out 1:1).
+                    if q.len() >= self.threads.load(Ordering::Relaxed) as usize {
+                        for _ in 1..BATCH_POP {
+                            match q.pop_front() {
+                                Some(job) => batch.push(job),
+                                None => break,
+                            }
+                        }
+                    }
+                }
+            }
+            if !batch.is_empty() {
+                spin = 0;
+                for job in batch.drain(..) {
+                    job();
+                }
+                continue;
+            }
+            if !self.running.load(Ordering::Acquire) {
+                // Exit only once the queue is genuinely empty (a submit that
+                // raced the shutdown flag still runs).
+                if self.queue.lock().is_empty() {
+                    break;
+                }
+                continue;
+            }
+            // Empty and running: spin briefly, then park with a short timeout.
+            if spin < SPIN_ROUNDS {
+                spin += 1;
+                std::hint::spin_loop();
+                continue;
+            }
+            spin = 0;
+            let mut q = self.queue.lock();
+            if q.is_empty() && self.running.load(Ordering::Acquire) {
+                self.cv.wait_for(&mut q, PARK_TIMEOUT);
+            }
+        }
+    }
+
+    fn enqueue(&'static self, job: Job) {
+        self.queue.lock().push_back(job);
+        self.cv.notify_one();
+    }
+
+    fn shutdown(&self) {
+        self.running.store(false, Ordering::Release);
+        self.cv.notify_all();
+    }
+}
+
+#[cfg(target_os = "linux")]
+static TASK_CORE_IDS: OnceLock<Option<Vec<core_affinity::CoreId>>> = OnceLock::new();
+
+/// Pin a worker to a dedicated core when `CASTRUM_TASK_PIN_CORES` (or the
+/// shared `CASTRUM_PIN_CORES`) is set. Same rationale as the rayon pool's
+/// pinning: stable cache locality and less scheduler migration, at the cost of
+/// flexibility. Core 0 is skipped so the Bun event-loop thread keeps it.
+#[cfg(target_os = "linux")]
+fn pin_worker(id: usize) {
+    if std::env::var("CASTRUM_TASK_PIN_CORES").is_err()
+        && std::env::var("CASTRUM_PIN_CORES").is_err()
+    {
+        return;
+    }
+    let ids = TASK_CORE_IDS.get_or_init(core_affinity::get_core_ids);
+    if let Some(ids) = ids {
+        if ids.len() > 1 {
+            let idx = 1 + (id % (ids.len() - 1));
+            let _ = core_affinity::set_for_current(ids[idx]);
+        }
+    }
+}
+
+#[cfg(not(target_os = "linux"))]
+fn pin_worker(_id: usize) {}
+
+/// Default worker count: all cores but one (headroom for the Bun event loop),
+/// overridable with `CASTRUM_TASK_THREADS`.
+pub fn default_threads() -> usize {
+    std::env::var("CASTRUM_TASK_THREADS")
+        .ok()
+        .and_then(|v| v.parse::<usize>().ok())
+        .filter(|&n| n > 0)
+        .unwrap_or_else(|| {
+            std::thread::available_parallelism()
+                .map(|n| n.get().saturating_sub(1))
+                .unwrap_or(1)
+                .max(1)
+        })
+}
+
+/// Start the pool with `threads` workers (`None`/`0` → {@link default_threads}).
+///
+/// Returns `0` when this call started the pool and `1` when it was already
+/// running (both are success; the codebase keeps non-zero = error).
+pub fn init(threads: Option<u32>) -> u32 {
+    let p = POOL.get_or_init(TaskPool::new);
+    if p.running.load(Ordering::Acquire) {
+        return 1;
+    }
+    let n = threads
+        .filter(|&t| t > 0)
+        .map(|t| t as usize)
+        .unwrap_or_else(default_threads);
+    p.start(n);
+    0
+}
+
+/// Enqueue `job`, auto-starting the pool on first use. Always accepted in v1
+/// (the queue is unbounded; admission/backpressure is a later milestone).
+pub fn submit<F>(job: F) -> bool
+where
+    F: FnOnce() + Send + 'static,
+{
+    let p = POOL.get_or_init(TaskPool::new);
+    if !p.running.load(Ordering::Acquire) {
+        let n = default_threads();
+        p.start(n);
+    }
+    p.enqueue(Box::new(job));
+    true
+}
+
+/// Configured worker count (0 before the pool starts).
+pub fn threads() -> u32 {
+    POOL.get_or_init(TaskPool::new)
+        .threads
+        .load(Ordering::Acquire)
+}
+
+/// Stop accepting and let idle workers exit. In-flight jobs still complete.
+pub fn shutdown() {
+    if let Some(p) = POOL.get() {
+        p.shutdown();
+    }
+}

package/rust/task/tests.rs

@@ -0,0 +1,231 @@
+// rust/task/tests.rs — pool / ring / cancellation / panic / doorbell tests.
+//
+// These touch PROCESS-WIDE state (one pool + one ring per process), so they are
+// serialized by a test mutex rather than relying on the default parallel test
+// threads.
+
+use parking_lot::Mutex;
+use std::sync::atomic::{AtomicU32, Ordering};
+
+use super::completion::{self, Completion};
+use super::ops::{
+    self, OP_GZIP_COMPRESS, OP_GZIP_DECOMPRESS, OP_TEST_PANIC, STATUS_CANCELLED, STATUS_ERROR,
+    STATUS_OK,
+};
+use super::runtime;
+
+/// Serializes tests that share the global ring/pool/cancel set.
+static LOCK: Mutex<()> = Mutex::new(());
+
+fn parse(buf: &[u8], written: usize) -> Vec<(u64, u32, Vec<u8>)> {
+    let mut out = Vec::new();
+    if written < 4 {
+        return out;
+    }
+    let count = u32::from_le_bytes([buf[0], buf[1], buf[2], buf[3]]) as usize;
+    let mut off = 4usize;
+    for _ in 0..count {
+        if off + 16 > written {
+            break;
+        }
+        let id = u64::from_le_bytes(buf[off..off + 8].try_into().unwrap());
+        let status = u32::from_le_bytes(buf[off + 8..off + 12].try_into().unwrap());
+        let len = u32::from_le_bytes(buf[off + 12..off + 16].try_into().unwrap()) as usize;
+        off += 16;
+        if off + len > written {
+            break;
+        }
+        out.push((id, status, buf[off..off + len].to_vec()));
+        off += len;
+    }
+    out
+}
+
+/// Drain everything pending into a right-sized buffer (one grow retry).
+fn drain_all() -> Vec<(u64, u32, Vec<u8>)> {
+    let mut buf = vec![0u8; 1 << 16];
+    loop {
+        let w = completion::drain(&mut buf);
+        if w == 0 {
+            return Vec::new();
+        }
+        if w > buf.len() {
+            buf = vec![0u8; w];
+            continue;
+        }
+        return parse(&buf, w);
+    }
+}
+
+/// Poll until `id` completes (10 s guard) and return `(status, body)`.
+fn wait_for(id: u64) -> (u32, Vec<u8>) {
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(10);
+    loop {
+        for (rid, status, body) in drain_all() {
+            if rid == id {
+                return (status, body);
+            }
+        }
+        assert!(
+            std::time::Instant::now() < deadline,
+            "task {id} never completed"
+        );
+        std::thread::sleep(std::time::Duration::from_millis(2));
+    }
+}
+
+fn gzip_args(payload: &[u8]) -> Vec<u8> {
+    let compressed = crate::payload::compress::gzip_compress_bytes(payload, 6).unwrap();
+    let mut args = Vec::with_capacity(4 + compressed.len());
+    args.extend_from_slice(&0u32.to_le_bytes());
+    args.extend_from_slice(&compressed);
+    args
+}
+
+#[test]
+fn submit_runs_off_thread_and_drains() {
+    let _g = LOCK.lock();
+    completion::clear();
+    let payload = b"hello castrum tasks".repeat(64);
+    assert!(super::submit_op(
+        OP_GZIP_DECOMPRESS,
+        gzip_args(&payload),
+        0x1001
+    ));
+    let (status, body) = wait_for(0x1001);
+    assert_eq!(status, STATUS_OK);
+    assert_eq!(body, payload);
+}
+
+#[test]
+fn a_slice_submit_reads_the_payload_in_place() {
+    let _g = LOCK.lock();
+    completion::clear();
+    // Zero-copy INPUT: only the 4-byte level header crosses the boundary; the
+    // payload pointer is read on the worker. The buffer must outlive the task,
+    // which is exactly the contract JS upholds by holding `Deferred.keep`.
+    let payload = b"zero-copy input payload".repeat(256);
+    let hdr = 6u32.to_le_bytes().to_vec();
+    assert!(super::submit_slice_op(
+        OP_GZIP_COMPRESS,
+        hdr,
+        payload.as_ptr() as usize,
+        payload.len(),
+        0x1009,
+    ));
+    let (status, body) = wait_for(0x1009);
+    assert_eq!(status, STATUS_OK);
+
+    let restored =
+        crate::payload::compress::gzip_decompress_bytes(&body, payload.len() + 1).unwrap();
+    assert_eq!(restored, payload);
+
+    // A null payload with a zero length is an empty input, not a crash.
+    completion::clear();
+    assert!(super::submit_slice_op(
+        OP_GZIP_COMPRESS,
+        6u32.to_le_bytes().to_vec(),
+        0,
+        0,
+        0x100A
+    ));
+    assert_eq!(wait_for(0x100A).0, STATUS_OK);
+}
+
+#[test]
+fn error_status_carries_a_message() {
+    let _g = LOCK.lock();
+    completion::clear();
+    // Too-short args → the op returns an error string, not a panic.
+    assert!(super::submit_op(OP_GZIP_DECOMPRESS, vec![], 0x1002));
+    let (status, body) = wait_for(0x1002);
+    assert_eq!(status, STATUS_ERROR);
+    assert!(String::from_utf8_lossy(&body).contains("too short"));
+}
+
+#[test]
+fn cancellation_is_acknowledged() {
+    let _g = LOCK.lock();
+    completion::clear();
+    let id = 0x1003;
+    assert!(ops::mark_cancelled(id));
+    ops::execute_guarded(OP_GZIP_DECOMPRESS, &gzip_args(b"x"), id);
+    let (status, _) = wait_for(id);
+    assert_eq!(status, STATUS_CANCELLED);
+}
+
+#[test]
+fn a_panicking_task_is_contained() {
+    let _g = LOCK.lock();
+    completion::clear();
+    assert!(super::submit_op(OP_TEST_PANIC, vec![], 0x1004));
+    let (status, body) = wait_for(0x1004);
+    assert_eq!(status, STATUS_ERROR);
+    assert!(String::from_utf8_lossy(&body).contains("panicked"));
+}
+
+#[test]
+fn drain_uses_the_needed_size_convention() {
+    let _g = LOCK.lock();
+    completion::clear();
+    completion::set_doorbell(0);
+    completion::push(Completion {
+        id: 7,
+        status: STATUS_OK,
+        body: vec![1, 2, 3],
+    });
+    let mut tiny = [0u8; 1];
+    let needed = completion::drain(&mut tiny);
+    assert_eq!(needed, 4 + 16 + 3);
+    // Nothing was consumed, so a right-sized retry still gets it.
+    let mut ok = vec![0u8; needed];
+    let written = completion::drain(&mut ok);
+    assert_eq!(written, needed);
+    let parsed = parse(&ok, written);
+    assert_eq!(parsed, vec![(7u64, STATUS_OK, vec![1u8, 2, 3])]);
+}
+
+static BELLS: AtomicU32 = AtomicU32::new(0);
+
+extern "C" fn bell() {
+    BELLS.fetch_add(1, Ordering::SeqCst);
+}
+
+#[test]
+fn doorbell_coalesces_a_batch() {
+    let _g = LOCK.lock();
+    completion::clear();
+    completion::set_doorbell(bell as *const () as usize);
+    BELLS.store(0, Ordering::SeqCst);
+    completion::push(Completion {
+        id: 1,
+        status: STATUS_OK,
+        body: vec![0],
+    });
+    completion::push(Completion {
+        id: 2,
+        status: STATUS_OK,
+        body: vec![0],
+    });
+    // Both pushes land inside one armed window → exactly one crossing.
+    assert_eq!(BELLS.load(Ordering::SeqCst), 1);
+    let mut buf = vec![0u8; 4096];
+    assert!(completion::drain(&mut buf) > 0);
+    // A push after the drain re-arms the bell.
+    completion::push(Completion {
+        id: 3,
+        status: STATUS_OK,
+        body: vec![0],
+    });
+    assert_eq!(BELLS.load(Ordering::SeqCst), 2);
+    completion::drain(&mut buf);
+    completion::set_doorbell(0);
+    completion::clear();
+}
+
+#[test]
+fn pool_starts_with_a_nonzero_thread_count() {
+    let _g = LOCK.lock();
+    runtime::init(None);
+    assert!(runtime::threads() >= 1);
+}

package/rust/test_support.rs

@@ -0,0 +1,71 @@
+// rust/test_support.rs — Shared helpers for Rust unit tests (`cargo test`).
+//
+// Only compiled when running tests. Each module's `#[cfg(test)] mod tests`
+// imports whatever it needs from here instead of redefining it.
+
+/// Build a packed header buffer:
+/// `[u16 count] repeated { [u16 name_len][name][u32 val_len][val] }`.
+pub(crate) fn pack_headers<'a, I>(pairs: I) -> Vec<u8>
+where
+    I: IntoIterator<Item = (&'a str, &'a str)>,
+{
+    let pairs: Vec<(&str, &str)> = pairs.into_iter().collect();
+    let mut out = Vec::new();
+    out.extend_from_slice(&(pairs.len() as u16).to_le_bytes());
+    for (name, value) in pairs {
+        out.extend_from_slice(&(name.len() as u16).to_le_bytes());
+        out.extend_from_slice(name.as_bytes());
+        out.extend_from_slice(&(value.len() as u32).to_le_bytes());
+        out.extend_from_slice(value.as_bytes());
+    }
+    out
+}
+
+/// Decode a packed pairs buffer:
+/// `[u32 count] repeated { [u32 key_len][key][u32 val_len][val] }`.
+pub(crate) fn decode_packed_pairs(packed: &[u8]) -> Vec<(Vec<u8>, Vec<u8>)> {
+    assert!(packed.len() >= 4, "packed buffer too short");
+    let count = u32::from_le_bytes([packed[0], packed[1], packed[2], packed[3]]) as usize;
+    let mut out = Vec::with_capacity(count);
+    let mut pos = 4usize;
+    for _ in 0..count {
+        let key_len = u32::from_le_bytes([
+            packed[pos],
+            packed[pos + 1],
+            packed[pos + 2],
+            packed[pos + 3],
+        ]) as usize;
+        pos += 4;
+        let key = packed[pos..pos + key_len].to_vec();
+        pos += key_len;
+        let val_len = u32::from_le_bytes([
+            packed[pos],
+            packed[pos + 1],
+            packed[pos + 2],
+            packed[pos + 3],
+        ]) as usize;
+        pos += 4;
+        let val = packed[pos..pos + val_len].to_vec();
+        pos += val_len;
+        out.push((key, val));
+    }
+    out
+}
+
+/// Deterministic xorshift PRNG so fuzz-style tests are reproducible.
+pub(crate) struct Rng(pub u64);
+
+impl Rng {
+    pub fn next(&mut self) -> u64 {
+        let mut x = self.0;
+        x ^= x << 13;
+        x ^= x >> 7;
+        x ^= x << 17;
+        self.0 = x;
+        x
+    }
+
+    pub fn bytes(&mut self, len: usize) -> Vec<u8> {
+        (0..len).map(|_| self.next() as u8).collect()
+    }
+}