pigeonhole-db 1.1.0

data/vendor/shm/Cargo.toml

@@ -0,0 +1,24 @@
+# Generated by `rake gem:source` (crates/ruby/rakelib/source_gem.rake): a vendored copy of crates/shm
+
+[dependencies.pigeonhole-format]
+path = "../format"
+version = "=2.0.0"
+[dependencies.pigeonhole-io]
+path = "../io"
+version = "=2.0.0"
+[lints.rust.unexpected_cfgs]
+check-cfg = ["cfg(loom)", "cfg(engine_loom)", "cfg(io_loom)", "cfg(pigeonhole_sim)"]
+level = "warn"
+[package]
+authors = ["Matt Tanous <matt.tanous@hey.com>"]
+categories = ["database-implementations", "data-structures"]
+description = "Shared-memory region and multi-process reader protocol for Pigeonhole."
+edition = "2024"
+keywords = ["database", "wide-column", "embedded", "lsm", "bigtable"]
+license = "MIT"
+name = "pigeonhole-shm"
+readme = "README.md"
+repository = "https://github.com/CodingAnarchy/pigeonhole"
+rust-version = "1.96"
+version = "2.0.0"
+[target."cfg(unix)"]

data/vendor/shm/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Tanous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/vendor/shm/README.md

@@ -0,0 +1,5 @@
+# pigeonhole-shm
+
+Shared-memory region and multi-process reader protocol for Pigeonhole.
+
+This is an internal crate of [Pigeonhole](https://github.com/CodingAnarchy/pigeonhole). Most users want the [`pigeonhole`](https://crates.io/crates/pigeonhole) crate. It makes **no stability promise of its own** (D282): `pigeonhole` pins it exactly, and any release may change it incompatibly, under a new major version of this crate. Depend on `pigeonhole` instead.

data/vendor/shm/src/lib.rs

@@ -0,0 +1,427 @@
+//! Shared-memory region and multi-process reader protocol for Pigeonhole.
+//!
+//! The region (layout in `FORMAT.md` §11) holds the header and writer generation, each
+//! shard's published watermark, the current view (tablet map plus memtable roots), the
+//! reader-slot table, and one memtable arena per shard. This crate owns the layout, the
+//! lifecycle (create, attach, rebuild, remove), the locks on the main file's lock page, and
+//! the reader protocol. What goes inside the arenas belongs to `pigeonhole-memtable`.
+//!
+//! All shared fields are accessed through [`SharedRegion`](pigeonhole_io::SharedRegion) atomics, so this crate needs no
+//! `unsafe`. [`ShmRegion::in_memory`] is the heap-backed mock for engine tests.
+//!
+//! # Lifecycle
+//!
+//! Every process opens the main file **for writing** (even readers, which still write
+//! nothing: byte-range locks that are exclusive, such as the shm-init byte and the
+//! presence-byte upgrade at close, need a writable handle; decision D36).
+//!
+//! - The writer takes the [`WriterLock`], then calls [`ShmRegion::open`] with
+//!   [`Role::Writer`], then takes [`Presence`], all on the same handle (decision D37). The
+//!   open always builds a region under a new [`Generation`]: it creates the new region, marks
+//!   the old one abandoned, records the new generation in the directory region and removes
+//!   the old region's name. It takes the presence byte shared itself before publishing, so
+//!   the later [`Presence::acquire`] only returns the guard.
+//! - A reader takes [`Presence`], opens with [`Role::Reader`], claims a [`ReaderSlot`] and
+//!   pins before each snapshot. When [`ShmRegion::is_stale`] reports that a new writer built
+//!   a new generation, it calls [`ShmRegion::reattach`], re-claims a slot and re-pins.
+//! - At close, the process that can [`Presence::try_become_last`] calls [`ShmRegion::remove`].
+//!
+//! ```
+//! use pigeonhole_format::shm::ViewRecord;
+//! use pigeonhole_io::sim::SimVfs;
+//! use pigeonhole_io::{OpenOptions, ProcessId, Vfs};
+//! use pigeonhole_shm::{ShmConfig, ShmRegion};
+//!
+//! let mut config = ShmConfig::new(2);
+//! config.arena_bytes = 2 << 20;
+//! config.view_buffer_bytes = 64 << 10;
+//! let shm = ShmRegion::in_memory([7; 16], &config);
+//!
+//! // Writer side: a group of three commits on shard 0. Under the writer's allocator lock
+//! // (here, one thread), the group's hold is stored before the mirror passes it (FORMAT
+//! // §11.3, D300).
+//! let first = shm.next_seqno(); // the writer's own allocator, mirrored here
+//! shm.publish_pending(0, first);
+//! shm.advance_next_seqno(first + 3);
+//! // ... apply the group ...
+//! shm.publish_pending(0, u64::MAX);
+//! assert_eq!(shm.visible_seqno(), first + 2);
+//!
+//! shm.publish_view(&ViewRecord { view_version: 1, ..Default::default() }).unwrap();
+//!
+//! // Reader side: claim a slot (its liveness lock held through the reader's handle on the
+//! // database file), pin, then read through the pinned view.
+//! let vfs = SimVfs::new(1);
+//! let file = vfs.open("/db".as_ref(), OpenOptions::read_write_create()).unwrap();
+//! let slot = shm
+//!     .claim_reader_slot_locked(ProcessId { pid: 42, start_time: 1 }, &file)
+//!     .unwrap();
+//! slot.pin(shm.visible_seqno(), shm.view_version());
+//! let view = shm.read_view().unwrap();
+//! assert_eq!(view.view_version, 1);
+//! assert_eq!(shm.oldest_reader_pin(), Some((first + 2, 1)));
+//! drop(slot);
+//! assert_eq!(shm.oldest_reader_pin(), None);
+//! ```
+//!
+//! Part of [Pigeonhole](https://github.com/CodingAnarchy/pigeonhole). See the crate README.
+#![forbid(unsafe_code)]
+
+// The region's atomics are native-endian while FORMAT.md fixes its integers as
+// little-endian; refuse to build where the two differ (decision D56).
+#[cfg(not(target_endian = "little"))]
+compile_error!("pigeonhole-shm supports little-endian targets only (FORMAT.md §11)");
+
+mod lock;
+mod region;
+
+use std::fmt;
+use std::sync::Arc;
+use std::sync::atomic::AtomicBool;
+
+use pigeonhole_format::{Seqno, ShmLayoutVersion};
+use pigeonhole_io::{FileRef, ProcessId};
+
+pub use region::{FeedMarksView, RowEpochTable, ShmRegion};
+
+/// Result alias for this crate.
+pub type Result<T, E = Error> = std::result::Result<T, E>;
+
+/// Shared-memory errors.
+#[derive(Debug)]
+#[non_exhaustive]
+pub enum Error {
+    /// The underlying OS call failed.
+    Io(pigeonhole_io::Error),
+    /// Another process holds the writer lock.
+    WriterLocked,
+    /// A live region has a different layout version.
+    VersionMismatch {
+        /// Version in the region.
+        found: u32,
+        /// Version this build uses.
+        expected: u32,
+    },
+    /// The region belongs to another database or its header is invalid.
+    Corrupt(&'static str),
+    /// Every reader slot is taken.
+    NoReaderSlot,
+    /// The region could not be allocated at the requested size.
+    Unavailable,
+    /// The encoded view does not fit in a view buffer. The writer refuses the change that
+    /// would grow it (for example a tablet split) instead of publishing a truncated view.
+    ViewTooLarge {
+        /// Encoded view length.
+        needed: usize,
+        /// View buffer length.
+        capacity: usize,
+    },
+    /// This mapping was replaced by a newer generation; call [`ShmRegion::reattach`].
+    Stale,
+    /// [`ShmRegion::publish_view`] was given a view version at or below the published one.
+    /// Versions are strictly increasing (readers pin by version) and 0 means "no view".
+    ViewVersionNotNewer {
+        /// The version currently published.
+        published: u64,
+        /// The version offered.
+        offered: u64,
+    },
+    /// An [`ShmConfig`] field is out of range (see [`ShmConfig::validate`]).
+    InvalidConfig(&'static str),
+    /// A reader found no writer's region to attach to: no writer has built one, or the
+    /// generation the directory names is gone (its writer closed and no process maps it;
+    /// on Windows a closed writer's mapping disappears at once, #844).
+    NoWriter,
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Error::Io(e) => write!(f, "shared memory: {e}"),
+            Error::WriterLocked => f.write_str("another process holds the writer lock"),
+            Error::VersionMismatch { found, expected } => write!(
+                f,
+                "shared-memory layout version {found} differs from this build's {expected}"
+            ),
+            Error::Corrupt(what) => write!(f, "shared-memory region is invalid: {what}"),
+            Error::NoReaderSlot => f.write_str("every reader slot is taken"),
+            Error::Unavailable => {
+                f.write_str("the shared-memory region could not be allocated at the requested size")
+            }
+            Error::ViewTooLarge { needed, capacity } => write!(
+                f,
+                "encoded view ({needed} bytes) does not fit the view buffer ({capacity} bytes)"
+            ),
+            Error::Stale => {
+                f.write_str("this mapping was replaced by a newer generation; re-attach")
+            }
+            Error::ViewVersionNotNewer { published, offered } => write!(
+                f,
+                "view version {offered} is not newer than the published version {published}"
+            ),
+            Error::InvalidConfig(what) => write!(f, "invalid shared-memory configuration: {what}"),
+            Error::NoWriter => f.write_str("no writer is running: a reader process attaches to a running writer's shared memory; open the reader again once a writer runs"),
+        }
+    }
+}
+
+impl std::error::Error for Error {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Error::Io(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+impl From<pigeonhole_io::Error> for Error {
+    fn from(e: pigeonhole_io::Error) -> Self {
+        Self::Io(e)
+    }
+}
+
+impl From<pigeonhole_format::Error> for Error {
+    /// A header or view that fails to decode. A layout version other than this build's is
+    /// [`Error::VersionMismatch`]; everything else is [`Error::Corrupt`].
+    fn from(e: pigeonhole_format::Error) -> Self {
+        match e {
+            pigeonhole_format::Error::UnsupportedVersion { found, .. } => Error::VersionMismatch {
+                found,
+                expected: ShmLayoutVersion::CURRENT.0,
+            },
+            pigeonhole_format::Error::Truncated { what }
+            | pigeonhole_format::Error::BadMagic { what }
+            | pigeonhole_format::Error::Checksum { what }
+            | pigeonhole_format::Error::Corrupt { what } => Error::Corrupt(what),
+            _ => Error::Corrupt("shared-memory structure"),
+        }
+    }
+}
+
+/// Region generation: bumped each time a writer (re)builds the region, and part of the
+/// region's name. The directory region records the current one; readers re-attach when it
+/// changes.
+///
+/// ```
+/// use pigeonhole_shm::Generation;
+///
+/// assert!(Generation(1) < Generation(2));
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Generation(pub u64);
+
+/// The most row-epoch slots a region takes (128 MiB of table).
+pub const MAX_ROW_EPOCH_SLOTS: u32 = 1 << 24;
+
+/// Region sizing and placement.
+///
+/// ```
+/// use pigeonhole_shm::ShmConfig;
+///
+/// let config = ShmConfig::new(8);
+/// assert_eq!(config.shards, 8);
+/// assert_eq!(config.arena_bytes, 64 << 20);
+/// assert_eq!(config.reader_slots, 128);
+/// assert_eq!(config.view_buffer_bytes, 4 << 20);
+/// assert_eq!(config.first_seqno, 1);
+/// assert!(config.dir.is_none());
+/// assert!(config.validate().is_ok());
+/// assert!(ShmConfig::new(0).validate().is_err());
+/// ```
+#[derive(Debug, Clone)]
+#[non_exhaustive]
+pub struct ShmConfig {
+    /// Shards (arenas and watermark lines).
+    pub shards: u32,
+    /// Bytes per shard arena (default 64 MiB; rounded up to 2 MiB).
+    pub arena_bytes: u64,
+    /// Reader slots (default 128). Each is 64 bytes, and the slot area is padded up to the
+    /// arenas' 2 MiB alignment, so the default costs no space.
+    pub reader_slots: u32,
+    /// Bytes per view buffer (default 4 MiB). Must hold the encoded view: about
+    /// `40 + 2 * key bytes` per tablet plus 24 per memtable.
+    pub view_buffer_bytes: u32,
+    /// Directory for a file-backed region instead of the default memory-backed one.
+    pub dir: Option<std::path::PathBuf>,
+    /// The first seqno a region built with this config hands out (default 1). A writer
+    /// passes the seqno ceiling it recovered, so visible seqnos never go backwards across a
+    /// writer restart (ICR 0002). Values below 1 are raised to 1: 0 means "none" in reader
+    /// slots.
+    pub first_seqno: Seqno,
+    /// Row-epoch slots (D281): the row caches' write watermarks, shared by the writer and
+    /// every reader process, 8 bytes each. A power of two (default 2^18, 2 MiB). Fewer
+    /// slots only make rows share them more (false row-cache misses, never a wrong row).
+    pub row_epoch_slots: u32,
+    /// Whether the writer raises the row-epoch slots (its row cache is on, D281): recorded in
+    /// the header (`ROW_EPOCHS_MAINTAINED`), and a reader process caches rows only when it
+    /// is set. Default `true`.
+    pub row_epochs_maintained: bool,
+}
+
+impl ShmConfig {
+    /// Defaults for `shards` shards.
+    pub fn new(shards: u32) -> Self {
+        Self {
+            shards,
+            arena_bytes: 64 << 20,
+            reader_slots: 128,
+            view_buffer_bytes: 4 << 20,
+            dir: None,
+            first_seqno: 1,
+            row_epoch_slots: 1 << 18,
+            row_epochs_maintained: true,
+        }
+    }
+
+    /// Checks the ranges a region can be built from: at least one shard, at least one
+    /// reader slot, and a view buffer that holds at least a view header (32 bytes).
+    pub fn validate(&self) -> Result<()> {
+        if self.shards == 0 {
+            return Err(Error::InvalidConfig("shards must be at least 1"));
+        }
+        if self.reader_slots == 0 {
+            return Err(Error::InvalidConfig("reader_slots must be at least 1"));
+        }
+        if self.view_buffer_bytes < 32 {
+            return Err(Error::InvalidConfig(
+                "view_buffer_bytes must be at least 32 (one view header)",
+            ));
+        }
+        if !self.row_epoch_slots.is_power_of_two() || self.row_epoch_slots > MAX_ROW_EPOCH_SLOTS {
+            return Err(Error::InvalidConfig(
+                "row_epoch_slots must be a power of two, at most 2^24",
+            ));
+        }
+        Ok(())
+    }
+}
+
+/// The writer lock: the exclusive lock on the writer byte of the lock page. Held for the life
+/// of the writer; released on drop.
+///
+/// ```
+/// use std::path::Path;
+/// use pigeonhole_io::sim::SimVfs;
+/// use pigeonhole_io::{OpenOptions, Vfs};
+/// use pigeonhole_shm::{Error, WriterLock};
+///
+/// let vfs = SimVfs::new(1);
+/// let file = vfs.open(Path::new("/db/data.phdb"), OpenOptions::read_write_create()).unwrap();
+/// let other = vfs.open(Path::new("/db/data.phdb"), OpenOptions::read_write_create()).unwrap();
+///
+/// let lock = WriterLock::acquire(&file).unwrap();
+/// assert!(matches!(WriterLock::acquire(&other), Err(Error::WriterLocked)));
+/// drop(lock);
+/// assert!(WriterLock::acquire(&other).is_ok());
+/// ```
+#[derive(Debug)]
+pub struct WriterLock {
+    file: FileRef,
+    /// The process that took it ([`pigeonhole_io::sys::process_id`]): a forked child's copy
+    /// releases nothing (on Linux it shares the parent's open file description, so its
+    /// unlock would release the parent's lock).
+    held_in: u32,
+}
+
+/// The shared presence lock every open process holds on the presence byte.
+///
+/// ```
+/// use std::path::Path;
+/// use pigeonhole_io::sim::SimVfs;
+/// use pigeonhole_io::{OpenOptions, Vfs};
+/// use pigeonhole_shm::Presence;
+///
+/// let vfs = SimVfs::new(1);
+/// let file = vfs.open(Path::new("/db/data.phdb"), OpenOptions::read_write_create()).unwrap();
+/// let other = vfs.open(Path::new("/db/data.phdb"), OpenOptions::read_write_create()).unwrap();
+///
+/// let mine = Presence::acquire(&file).unwrap();
+/// let theirs = Presence::acquire(&other).unwrap();
+/// assert!(!mine.try_become_last().unwrap(), "another process is present");
+/// drop(theirs);
+/// assert!(mine.try_become_last().unwrap(), "now the last one: clean up");
+/// ```
+#[derive(Debug)]
+pub struct Presence {
+    file: FileRef,
+    /// As [`WriterLock`]'s: a forked child's copy releases nothing and is never "last".
+    held_in: u32,
+}
+
+/// How the calling process uses the region.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Role {
+    /// The writer: creates the region if absent, rebuilds it under a new generation if it
+    /// was left by a dead writer.
+    Writer,
+    /// A reader: attaches to an existing region; waits for `state == ready`.
+    Reader,
+}
+
+/// One reader process's slot. Released on drop.
+///
+/// ```
+/// use pigeonhole_io::sim::SimVfs;
+/// use pigeonhole_io::{OpenOptions, ProcessId, Vfs};
+/// use pigeonhole_shm::{ShmConfig, ShmRegion};
+///
+/// let mut config = ShmConfig::new(1);
+/// config.arena_bytes = 2 << 20;
+/// config.reader_slots = 1;
+/// let shm = ShmRegion::in_memory([1; 16], &config);
+/// // The reader's handle on the database file holds the slot's liveness lock.
+/// let vfs = SimVfs::new(1);
+/// let file = vfs.open("/db".as_ref(), OpenOptions::read_write_create()).unwrap();
+/// let me = ProcessId { pid: 7, start_time: 1 };
+///
+/// let slot = shm.claim_reader_slot_locked(me, &file).unwrap();
+/// assert_eq!(slot.index(), 0);
+/// assert!(shm.claim_reader_slot_locked(me, &file).is_err(), "one slot, already taken");
+/// assert_eq!(slot.pin(10, 0), (10, 0));
+/// assert_eq!(shm.oldest_reader_pin(), Some((10, 0)));
+/// slot.unpin();
+/// assert_eq!(shm.oldest_reader_pin(), None);
+/// ```
+#[derive(Debug)]
+pub struct ReaderSlot {
+    region: Arc<region::Inner>,
+    index: u32,
+    /// The process that claimed it: the slot is this handle's only while its owner fields
+    /// still name this process.
+    owner: ProcessId,
+    /// The database file handle holding the slot's liveness lock (layout 3,
+    /// [`ShmRegion::claim_reader_slot_locked`]), released after the slot is freed.
+    lock: FileRef,
+    /// Set by [`ReaderSlot::abandon`]: the handle no longer owns the slot and leaves it
+    /// alone. Shared with every [`SlotOwnership`] taken from this handle.
+    abandoned: Arc<AtomicBool>,
+    /// The id of the process that claimed the slot ([`pigeonhole_io::sys::process_id`]). In
+    /// any other process (a forked child's copy of the handle) the handle is inert, as if
+    /// abandoned, without releasing anything: the slot, its pins and (on Linux, where a
+    /// child shares the parent's open file description) its lock are the parent's.
+    claimed_in: u32,
+}
+
+/// Whether a [`ReaderSlot`] still belongs to the handle that claimed it, checkable without
+/// the slot (a live snapshot keeps one: [`ReaderSlot::ownership`]).
+#[derive(Debug, Clone)]
+pub struct SlotOwnership {
+    region: Arc<region::Inner>,
+    index: u32,
+    owner: ProcessId,
+    abandoned: Arc<AtomicBool>,
+    claimed_in: u32,
+}
+
+impl SlotOwnership {
+    /// Whether the slot is still claimed by its owner: not free, with the owner's pid and
+    /// start time. False once the writer judged the owner dead and freed the slot (and
+    /// possibly another reader took it), or once its handle abandoned it
+    /// ([`ReaderSlot::abandon`]), and always in a forked child: reads through the slot's
+    /// pins are then unprotected.
+    pub fn is_current(&self) -> bool {
+        !self.abandoned.load(std::sync::atomic::Ordering::Acquire)
+            && pigeonhole_io::sys::process_id() == self.claimed_in
+            && self.region.slot_owned_by(self.index, self.owner)
+    }
+}

data/vendor/shm/src/lock.rs

@@ -0,0 +1,153 @@
+//! The three lock-page bytes (FORMAT §8.3, decisions D3 and D21): writer, presence and
+//! shm-init. Locks never block; a conflicting holder fails the call at once.
+
+use pigeonhole_io::{ErrorKind, FileRef, LockMode};
+
+use crate::{Error, Presence, Result, WriterLock};
+
+/// Writer byte: exclusive by the one writer.
+pub(crate) const WRITER_BYTE: u64 = 8192;
+/// Presence byte: shared by every process with the database open.
+pub(crate) const PRESENCE_BYTE: u64 = 8193;
+/// Shm-init byte: exclusive while a process creates, validates or rebuilds the region.
+pub(crate) const SHM_INIT_BYTE: u64 = 8194;
+
+impl WriterLock {
+    /// Takes the writer byte; fails at once with [`Error::WriterLocked`].
+    pub fn acquire(file: &FileRef) -> Result<WriterLock> {
+        match file.lock(WRITER_BYTE, LockMode::Exclusive) {
+            Ok(()) => Ok(WriterLock {
+                file: file.clone(),
+                held_in: pigeonhole_io::sys::process_id(),
+            }),
+            Err(e) if e.kind == ErrorKind::Locked => Err(Error::WriterLocked),
+            Err(e) => Err(e.into()),
+        }
+    }
+}
+
+impl Drop for WriterLock {
+    fn drop(&mut self) {
+        if pigeonhole_io::sys::process_id() == self.held_in {
+            let _ = self.file.unlock(WRITER_BYTE);
+        }
+    }
+}
+
+impl Presence {
+    /// Takes the presence byte shared.
+    pub fn acquire(file: &FileRef) -> Result<Presence> {
+        file.lock(PRESENCE_BYTE, LockMode::Shared)?;
+        Ok(Presence {
+            file: file.clone(),
+            held_in: pigeonhole_io::sys::process_id(),
+        })
+    }
+
+    /// Tries to upgrade to exclusive. Success means this is the last process: it may
+    /// checkpoint, remove the WAL files and remove the region. Releases on drop either way.
+    ///
+    /// The upgrade needs a handle opened for writing; on a read-only handle it fails with
+    /// `Unsupported` (decision D36).
+    ///
+    /// **Two processes closing at once** (#150 item 4.7) would each fail the upgrade while
+    /// the other still holds its shared byte, and neither would clean up. So after a failed
+    /// upgrade this releases its shared byte and retries the exclusive lock a few times, a
+    /// little later each time: the other closer, doing the same, has released its byte, and
+    /// one of the two gets it. Cleanup is idempotent (the region and the WAL files may
+    /// already be gone), so a second closer that also gets the byte later is harmless. A
+    /// process that stays open keeps its shared byte, and every retry fails. After `false`
+    /// this handle no longer holds the presence byte. In a forked child (a process other
+    /// than the one that acquired it) this is `false` at once and touches no lock.
+    pub fn try_become_last(&self) -> Result<bool> {
+        // A forked child's copy is never the last one: the byte is the parent's.
+        if pigeonhole_io::sys::process_id() != self.held_in {
+            return Ok(false);
+        }
+        match self.file.lock(PRESENCE_BYTE, LockMode::Exclusive) {
+            Ok(()) => return Ok(true),
+            Err(e) if e.kind == ErrorKind::Locked => {}
+            Err(e) => return Err(e.into()),
+        }
+        self.file.unlock(PRESENCE_BYTE)?;
+        for delay_ms in LAST_RETRY_DELAYS_MS {
+            std::thread::sleep(std::time::Duration::from_millis(delay_ms));
+            match self.file.lock(PRESENCE_BYTE, LockMode::Exclusive) {
+                Ok(()) => return Ok(true),
+                Err(e) if e.kind == ErrorKind::Locked => {}
+                Err(e) => return Err(e.into()),
+            }
+        }
+        Ok(false)
+    }
+}
+
+/// The waits between `try_become_last`'s retries after its first upgrade failed: about 15 ms
+/// in all, longer than a closing process takes from its own failed upgrade to its retry.
+const LAST_RETRY_DELAYS_MS: [u64; 4] = [1, 2, 4, 8];
+
+impl Drop for Presence {
+    fn drop(&mut self) {
+        if pigeonhole_io::sys::process_id() == self.held_in {
+            let _ = self.file.unlock(PRESENCE_BYTE);
+        }
+    }
+}
+
+/// The shm-init byte, held exclusive for the duration of a create, validate or rebuild.
+/// Released on drop.
+pub(crate) struct ShmInit {
+    file: FileRef,
+}
+
+/// How often and how long to retry the shm-init byte. Another process holds it only while
+/// building or validating a region, which takes milliseconds.
+const INIT_RETRIES: u32 = 200;
+const INIT_RETRY_DELAY: std::time::Duration = std::time::Duration::from_millis(5);
+
+impl ShmInit {
+    /// Takes the shm-init byte, retrying briefly while another process holds it.
+    pub(crate) fn acquire(file: &FileRef) -> Result<Self> {
+        let mut attempts = 0;
+        loop {
+            match file.lock(SHM_INIT_BYTE, LockMode::Exclusive) {
+                Ok(()) => return Ok(Self { file: file.clone() }),
+                Err(e) if e.kind == ErrorKind::Locked && attempts < INIT_RETRIES => {
+                    attempts += 1;
+                    std::thread::sleep(INIT_RETRY_DELAY);
+                }
+                Err(e) => return Err(e.into()),
+            }
+        }
+    }
+}
+
+impl Drop for ShmInit {
+    fn drop(&mut self) {
+        let _ = self.file.unlock(SHM_INIT_BYTE);
+    }
+}
+
+/// Whether no other process has the database open: tries to take the presence byte
+/// exclusively through `file`. On success the byte is left **shared**: the caller is now
+/// present, as it is while `file` stays open. `Locked` means another process is present; any
+/// other failure (for example a read-only handle, which cannot try) is returned.
+///
+/// The caller must not already hold the presence byte on `file`: on Windows an upgrade from
+/// shared is not atomic and can lose the shared lock (decision D37). The writer's open
+/// sequence guarantees this by calling `ShmRegion::open` before `Presence::acquire`.
+pub(crate) fn alone(file: &FileRef) -> Result<bool> {
+    match file.lock(PRESENCE_BYTE, LockMode::Exclusive) {
+        Ok(()) => {
+            file.lock(PRESENCE_BYTE, LockMode::Shared)?;
+            Ok(true)
+        }
+        Err(e) if e.kind == ErrorKind::Locked => Ok(false),
+        Err(e) => Err(e.into()),
+    }
+}
+
+/// Takes the presence byte shared through `file` (a no-op if this handle already holds it).
+pub(crate) fn present(file: &FileRef) -> Result<()> {
+    Ok(file.lock(PRESENCE_BYTE, LockMode::Shared)?)
+}