honker 0.3.2 → 0.5.0

data/ext/honker/honker-core/src/shm_watcher.rs

@@ -1,7 +1,8 @@
 //! Optional `-shm` fast path (feature = `shm-fast-path`).
 //!
 //! **Experimental.** Weaker correctness contract than the polling
-//! backend, in exchange for sub-millisecond wake latency.
+//! backend, in exchange for slightly lower CPU per tick. Not lower
+//! latency — see "What this backend is actually worth" below.
 //!
 //! # Contract
 //!
@@ -28,25 +29,60 @@
 //!   is read with bounded positional reads instead of mmap so SQLite file
 //!   churn cannot SIGBUS the host process.
 //!
+//! - **`-shm` descriptors are opened once and never closed early.** SQLite
+//!   locks `-shm`, and on POSIX closing any descriptor for an inode drops
+//!   every lock the *process* holds on it. See the registry below and
+//!   issue #80. This is why the backend does not simply `File::open` where
+//!   it needs a read.
+//!
+//! # What this backend is actually worth
+//!
+//! Less than its name suggests, and you should know that before enabling
+//! it. The original design mapped `-shm` and read `iChange` as a load,
+//! which was ~2000x cheaper than `PRAGMA data_version`. PR #43 replaced
+//! that mapping with bounded positional reads, citing SIGBUS risk.
+//!
+//! That risk was overstated for *this* read. SQLite's only shrink of
+//! `-shm` truncates it to 3 bytes, not 0 — deliberately — and `iChange`
+//! sits at offset 8, inside the zero-filled partial page that POSIX
+//! guarantees is readable. Only whole pages past the end of the object
+//! fault, and this module never touches those. The SIGBUS actually seen
+//! in CI came from *SQLite's own* mapping, which spans regions at 32 KiB
+//! and beyond, and it happened because this crate was dropping SQLite's
+//! DMS lock — issue #80, fixed by the registry above.
+//!
+//! The bounded read stays anyway: it costs ~1 us, it removes the need to
+//! reason about page boundaries at all, and restoring the mapping would
+//! not help. A bounded read is a syscall (~1.2 us here versus ~2.3 us for
+//! `PRAGMA data_version` on macOS/arm64), but both backends then sleep
+//! 1 ms, so **wake latency is identical**. The mapping would only pay off
+//! paired with a much tighter poll interval — and that trade is already
+//! available on the polling backend via `WatcherConfig::poll_interval`,
+//! without a second backend. Prefer polling unless you have measured a
+//! reason not to.
+//!
 //! Tests assert that wakes fire with sub-millisecond latency in WAL
 //! mode. If a test fails, the backend is broken — not "fall back to
 //! polling and pretend it worked".
 
 use crate::stat_identity;
 use rusqlite::{Connection, OpenFlags};
+use std::collections::HashMap;
 use std::fs::File;
-use std::io::{Read, Seek, SeekFrom};
-use std::path::PathBuf;
-use std::sync::Arc;
+use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
 use std::time::{Duration, Instant};
 
 const WALINDEX_MAX_VERSION: u32 = 3_007_000;
 const ICHANGE_OFFSET: usize = 8;
-/// Same cadence as the polling backend. Shm reads are nearly free; the
-/// win over polling is "PRAGMA -> memory load" (~3.5 us -> ns), not
-/// "1 ms -> 100 us". Going faster would just burn extra sleep syscalls
-/// for latency nobody can perceive.
+/// Same cadence as the polling backend. The win over polling is CPU per
+/// tick, not latency — both sleep 1 ms, so wake latency is identical.
+/// Measured on macOS/arm64 against SQLite 3.51.3: `pread` of the header
+/// is ~1.2 us versus ~2.3 us for `PRAGMA data_version`. That is a much
+/// smaller margin than the original mmap design promised, because a
+/// bounded read is a syscall and a mapped load was not. See the module
+/// docs for why the mapping had to go.
 const POLL_INTERVAL_MS: u64 = 1;
 /// Cadence for the dead-man's switch (db / -shm replacement detection).
 /// Same wall-clock interval as the polling and kernel backends. Tracked
@@ -54,6 +90,181 @@ const POLL_INTERVAL_MS: u64 = 1;
 /// up to ~15 ms.
 const IDENTITY_CHECK_INTERVAL: Duration = Duration::from_millis(100);
 
+// ---------------------------------------------------------------------
+// `-shm` descriptor registry (issue #80)
+// ---------------------------------------------------------------------
+//
+// SQLite takes POSIX advisory locks on `-shm` (the WAL-index locks and
+// the DMS byte). On POSIX, `close()` of *any* descriptor for an inode
+// releases *every* lock the calling process holds on it — including
+// locks belonging to unrelated SQLite connections in the same process.
+// SQLite's `unixInodeInfo` deferred-close list only defers closes of
+// descriptors SQLite itself opened, so it cannot protect us.
+//
+// So this module must never close a `-shm` descriptor while a connection
+// in this process might still hold locks on that inode. Three call sites
+// used to do exactly that: `probe()` on every `honker.open()`, the
+// identity-change reopen, and the watcher's own shutdown.
+//
+// The rule enforced here:
+//
+//   * open each `-shm` inode at most once per process, and share it;
+//   * never close a descriptor whose inode still has a name;
+//   * reclaim descriptors once `st_nlink == 0`, which proves the inode is
+//     unreferenced. SQLite only unlinks `-shm` while holding an EXCLUSIVE
+//     lock on the database file — i.e. when no connection anywhere is
+//     using that WAL — so at that point there is no lock left to drop.
+//
+// That bounds retention to one descriptor per *live* watched database
+// rather than leaking one per WAL generation.
+
+/// How many `-shm` descriptors this process will retain before giving up.
+/// Only reachable if inodes are churning faster than they can be reclaimed;
+/// failing loudly beats leaking descriptors without limit.
+#[cfg(unix)]
+const MAX_RETAINED_SHM_FDS: usize = 256;
+
+#[cfg(unix)]
+#[derive(Default)]
+struct ShmFdRegistry {
+    /// Current descriptor per `(dev, ino)`, shared by every watcher on it.
+    live: HashMap<(u64, u64), Arc<File>>,
+    /// Descriptors we could not file under a free key (lost an open race).
+    /// Held, not closed, until reclaimable.
+    extra: Vec<Arc<File>>,
+}
+
+#[cfg(unix)]
+fn shm_registry() -> &'static Mutex<ShmFdRegistry> {
+    static REGISTRY: OnceLock<Mutex<ShmFdRegistry>> = OnceLock::new();
+    REGISTRY.get_or_init(|| Mutex::new(ShmFdRegistry::default()))
+}
+
+/// `st_nlink` for an already-open file. `0` means the inode has no
+/// remaining directory entry, so nothing can lock it any more.
+#[cfg(unix)]
+fn link_count(file: &File) -> Option<u64> {
+    use std::os::unix::fs::MetadataExt;
+    file.metadata().ok().map(|m| m.nlink())
+}
+
+#[cfg(unix)]
+impl ShmFdRegistry {
+    /// Drop every descriptor whose inode is provably unreferenced and that
+    /// no watcher still holds. Cheap: one `fstat` per retained descriptor,
+    /// run only on acquire.
+    fn reclaim_unlinked(&mut self) {
+        self.live
+            .retain(|_, fd| Arc::strong_count(fd) > 1 || link_count(fd) != Some(0));
+        self.extra
+            .retain(|fd| Arc::strong_count(fd) > 1 || link_count(fd) != Some(0));
+    }
+
+    fn retained(&self) -> usize {
+        self.live.len() + self.extra.len()
+    }
+}
+
+/// Get a shared descriptor for `path`, opening it only if this process
+/// does not already hold one for that inode.
+///
+/// The `stat`-before-`open` step is not an optimization — it is the whole
+/// point. Opening a second descriptor just to discover we already had one
+/// would mean closing it, and that close is the bug.
+#[cfg(unix)]
+fn acquire_shm_fd(path: &Path) -> std::io::Result<Arc<File>> {
+    let existing_id = stat_identity(path).ok();
+    let mut reg = shm_registry().lock().unwrap_or_else(|e| e.into_inner());
+    reg.reclaim_unlinked();
+
+    if let Some(id) = existing_id
+        && let Some(fd) = reg.live.get(&id)
+    {
+        return Ok(Arc::clone(fd));
+    }
+
+    if reg.retained() >= MAX_RETAINED_SHM_FDS {
+        return Err(std::io::Error::other(format!(
+            "shm-fast-path is holding {MAX_RETAINED_SHM_FDS} -shm descriptors it \
+             cannot safely close; refusing to open more. Closing them would \
+             release this process's SQLite WAL-index locks (issue #80)."
+        )));
+    }
+
+    let file = Arc::new(File::open(path)?);
+    // Re-identify from the descriptor: `path` may have been replaced
+    // between the stat above and this open.
+    let id = match stat_identity_of(&file) {
+        Some(id) => id,
+        None => {
+            reg.extra.push(Arc::clone(&file));
+            return Ok(file);
+        }
+    };
+    match reg.live.entry(id) {
+        std::collections::hash_map::Entry::Occupied(slot) => {
+            // Raced with another thread. Keep ours alive rather than
+            // closing it, and hand back the descriptor already on file.
+            let winner = Arc::clone(slot.get());
+            reg.extra.push(file);
+            Ok(winner)
+        }
+        std::collections::hash_map::Entry::Vacant(slot) => {
+            slot.insert(Arc::clone(&file));
+            Ok(file)
+        }
+    }
+}
+
+/// `(dev, ino)` of an open file, matching [`crate::stat_identity`]'s shape.
+#[cfg(unix)]
+fn stat_identity_of(file: &File) -> Option<(u64, u64)> {
+    use std::os::unix::fs::MetadataExt;
+    let m = file.metadata().ok()?;
+    Some((m.dev(), m.ino()))
+}
+
+/// Windows has no POSIX advisory locks — closing a handle cannot release
+/// another connection's lock — so the retention machinery above is not
+/// needed and would only keep handles alive on a live `-shm`.
+#[cfg(not(unix))]
+fn acquire_shm_fd(path: &Path) -> std::io::Result<Arc<File>> {
+    File::open(path).map(Arc::new)
+}
+
+/// A `-shm` descriptor, the 12-byte WAL-index header read from it, and
+/// that file's `(dev, ino)` at the time of the read.
+type ShmHeaderSnapshot = (Arc<File>, [u8; 12], (u64, u64));
+
+/// Positional read of the WAL-index header. One syscall, and — unlike a
+/// mapping — a file that shrinks underneath us yields `UnexpectedEof`
+/// instead of SIGBUS. That protection came from PR #43 and must stay.
+fn read_wal_index_header(file: &File) -> std::io::Result<[u8; 12]> {
+    let mut header = [0_u8; 12];
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::FileExt;
+        file.read_exact_at(&mut header, 0)?;
+    }
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::FileExt;
+        let mut done = 0;
+        while done < header.len() {
+            match file.seek_read(&mut header[done..], done as u64)? {
+                0 => {
+                    return Err(std::io::Error::new(
+                        std::io::ErrorKind::UnexpectedEof,
+                        "-shm shorter than the WAL index header",
+                    ));
+                }
+                n => done += n,
+            }
+        }
+    }
+    Ok(header)
+}
+
 pub(crate) fn run_shm_fast_path_loop<F>(
     db_path: PathBuf,
     on_change: F,
@@ -118,7 +329,7 @@ pub(crate) fn run_shm_fast_path_loop<F>(
 
     while !stop.load(Ordering::Acquire) {
         std::thread::sleep(Duration::from_millis(POLL_INTERVAL_MS));
-        let current = match read_wal_index_header(&mut f) {
+        let current = match read_wal_index_header(&f) {
             Ok(header) => read_ichange_from_header(&header),
             Err(e) => {
                 if let Some((new_file, new_header, new_id)) = reopen_shm_header(&shm_path) {
@@ -164,13 +375,6 @@ pub(crate) fn run_shm_fast_path_loop<F>(
     }
 }
 
-fn read_wal_index_header(file: &mut File) -> std::io::Result<[u8; 12]> {
-    let mut header = [0_u8; 12];
-    file.seek(SeekFrom::Start(0))?;
-    file.read_exact(&mut header)?;
-    Ok(header)
-}
-
 fn read_ichange_from_header(header: &[u8; 12]) -> u32 {
     u32::from_ne_bytes(
         header[ICHANGE_OFFSET..ICHANGE_OFFSET + 4]
@@ -179,9 +383,16 @@ fn read_ichange_from_header(header: &[u8; 12]) -> u32 {
     )
 }
 
-fn reopen_shm_header(path: &std::path::Path) -> Option<(File, [u8; 12], (u64, u64))> {
-    let mut file = File::open(path).ok()?;
-    let header = read_wal_index_header(&mut file).ok()?;
+/// Re-acquire the current `-shm` descriptor and re-read its header.
+///
+/// Goes through [`acquire_shm_fd`], so the descriptor this replaces is
+/// retained by the registry rather than closed. Closing it here would
+/// release the WAL-index locks of every SQLite connection in this
+/// process — the identity-change path was one of the three sites that
+/// did exactly that before issue #80.
+fn reopen_shm_header(path: &std::path::Path) -> Option<ShmHeaderSnapshot> {
+    let file = acquire_shm_fd(path).ok()?;
+    let header = read_wal_index_header(&file).ok()?;
     let id = stat_identity(path).ok()?;
     Some((file, header, id))
 }
@@ -189,7 +400,7 @@ fn reopen_shm_header(path: &std::path::Path) -> Option<(File, [u8; 12], (u64, u6
 fn wait_for_initial_shm_header(
     path: &std::path::Path,
     stop: &AtomicBool,
-) -> Option<(File, [u8; 12], (u64, u64))> {
+) -> Option<ShmHeaderSnapshot> {
     for _ in 0..200 {
         if stop.load(Ordering::Acquire) {
             return None;
@@ -236,10 +447,14 @@ pub(crate) fn probe(db_path: &std::path::Path) -> Result<(), String> {
         return Err("shm-fast-path requires little-endian platform".into());
     }
     let shm = format!("{}-shm", db_path.display());
-    let mut f = File::open(&shm)
+    // Acquire through the registry, never `File::open` + drop. `probe`
+    // runs at `honker.open()` time, *after* the caller's writer connection
+    // has already created -wal/-shm, so a bare open+close here released
+    // this process's SQLite WAL-index locks on every single open.
+    let f = acquire_shm_fd(std::path::Path::new(&shm))
         .map_err(|e| format!("-shm unavailable ({e}). WAL mode + open connection required."))?;
     let header =
-        read_wal_index_header(&mut f).map_err(|e| format!("-shm too small or unreadable: {e}"))?;
+        read_wal_index_header(&f).map_err(|e| format!("-shm too small or unreadable: {e}"))?;
     let iv = u32::from_ne_bytes(header[0..4].try_into().unwrap());
     if iv != WALINDEX_MAX_VERSION {
         return Err(format!(

data/ext/honker/honker-extension/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "honker-extension"
-version = "0.2.5"
+version = "0.5.0"
 edition = "2024"
 description = "SQLite loadable extension for Honker. Adds honker_* SQL functions (queues, streams, scheduler, pub/sub) to any SQLite client."
 license = "MIT OR Apache-2.0"
@@ -23,14 +23,15 @@ crate-type = ["cdylib"]
 # Using both `path` and `version` lets Cargo publish this crate to
 # crates.io referencing the real honker-core = "0.2" while still
 # using the in-tree source for local builds.
-honker-core = { path = "../honker-core", version = "0.2.5", default-features = false }
+honker-core = { path = "../honker-core", version = "0.5.0", default-features = false }
 # "loadable_extension" feature makes rusqlite usable from inside a
 # sqlite3_extension_init entry point.
-rusqlite = { version = "0.39.0", features = ["functions", "hooks", "loadable_extension"] }
+rusqlite = { version = "0.40.1", features = ["functions", "hooks", "loadable_extension"] }
 
 [features]
 default = []
 kernel-watcher = ["honker-core/kernel-watcher"]
 shm-fast-path = ["honker-core/shm-fast-path"]
 
+
 [workspace]

data/ext/honker/honker-extension/src/lib.rs

@@ -108,7 +108,7 @@ fn attach_watcher_sql_functions(conn: &Connection) -> Result<()> {
         |ctx| {
             let db_path: String = ctx.get(0)?;
             let backend: Option<String> = ctx.get(1)?;
-            let poll_interval_ms: Option<i64> = ctx.get(2)?;
+            let poll_interval_ms: Option<i64> = honker_core::arg_opt_i64(ctx, 2)?;
             let poll_interval_ms = poll_interval_ms.map(|ms| ms.max(0) as u64);
             let handle = open_watcher_handle(&db_path, backend.as_deref(), poll_interval_ms)
                 .map_err(|e| {
@@ -124,8 +124,8 @@ fn attach_watcher_sql_functions(conn: &Connection) -> Result<()> {
         2,
         FunctionFlags::SQLITE_UTF8,
         |ctx| {
-            let id: i64 = ctx.get(0)?;
-            let timeout_ms: i64 = ctx.get(1)?;
+            let id: i64 = honker_core::arg_i64(ctx, 0)?;
+            let timeout_ms: i64 = honker_core::arg_i64(ctx, 1)?;
             let Some(handle) = SQL_WATCHERS.lock().unwrap().remove(&(id as u64)) else {
                 return Ok(-1);
             };
@@ -149,7 +149,7 @@ fn attach_watcher_sql_functions(conn: &Connection) -> Result<()> {
         1,
         FunctionFlags::SQLITE_UTF8,
         |ctx| {
-            let id: i64 = ctx.get(0)?;
+            let id: i64 = honker_core::arg_i64(ctx, 0)?;
             if let Some(handle) = SQL_WATCHERS.lock().unwrap().remove(&(id as u64)) {
                 handle.shared.unsubscribe(handle.sub_id);
                 let _ = handle.shared.close();
@@ -363,17 +363,15 @@ pub unsafe extern "C" fn honker_watcher_wait(
     if handle.is_null() {
         return -1;
     }
-    match catch_unwind(AssertUnwindSafe(|| {
+    catch_unwind(AssertUnwindSafe(|| {
         let handle = unsafe { &mut *handle };
         match handle.rx.recv_timeout(Duration::from_millis(timeout_ms)) {
             Ok(()) => 1,
             Err(RecvTimeoutError::Timeout) => 0,
             Err(RecvTimeoutError::Disconnected) => -1,
         }
-    })) {
-        Ok(code) => code,
-        Err(_) => -2,
-    }
+    }))
+    .unwrap_or(-2)
 }
 
 /// Close a watcher opened by `honker_watcher_open`.

data/lib/honker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Honker
-  VERSION = "0.3.2"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: honker
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Russell Romney