ktstr/flock/
primitives.rs

1//! Kernel-syscall wrappers for `flock(2)` acquire/release.
2//!
3//! Five entry points, each gated through
4//! [`super::fs_filter::reject_remote_fs`] so a misconfigured lockfile
5//! path on NFS / CIFS / SMB2 / CephFS / AFS / FUSE surfaces actionably
6//! at open time rather than silently returning an unserialized fd:
7//!
8//!  - [`materialize`] — create the lockfile inode without acquiring
9//!    a lock. Used by the DISCOVER phase of
10//!    `acquire_llc_plan` so the snapshot pass has a target inode
11//!    for the subsequent `/proc/locks` match without contending
12//!    with live acquirers.
13//!  - [`try_flock`] — non-blocking acquire. Returns `Ok(None)` on
14//!    `EWOULDBLOCK` so the caller can decide whether to retry, poll,
15//!    or surface contention.
16//!  - [`try_flock_with_witness`] — the same non-blocking acquire while
17//!    retaining the still-open writable fd on contention. Admission
18//!    callers may use that witness to order its `IN_CLOSE_WRITE` after
19//!    publishing their blocked state, avoiding an unnecessary UNKNOWN
20//!    observation and re-probe.
21//!  - `probe_flock_existing_read_only` — test-only. Non-creating,
22//!    read-only observation of an existing lockfile. Its fd closes with
23//!    `IN_CLOSE_NOWRITE`, so a resource-release watcher can ignore
24//!    observation traffic; production observers open the file read-only
25//!    themselves for the same reason.
26//!  - [`block_flock`] — blocking acquire. Parks the calling thread
27//!    in the kernel until the lock is available. Used after
28//!    [`try_flock`] returns `None` for callers that want to wait
29//!    indefinitely; callers with a deadline use
30//!    [`super::acquire::acquire_flock_with_timeout`] instead.
31//!
32//! The creating/writable entry points open with
33//! `O_CREAT | O_RDWR | O_CLOEXEC | 0o666` so the resulting fd matches
34//! the rest of the crate's lockfile contract:
35//!
36//!  - `O_CLOEXEC` keeps the lock from leaking across `exec(2)` into
37//!    spawned subprocesses (cargo subcommands, build pipeline,
38//!    initramfs compressor) where the parent's `OwnedFd::drop`
39//!    would not release a child-held flock.
40//!  - 0o666 mode matches a peer first-acquire so the file's owner
41//!    and permissions don't depend on creation order.
42
43use anyhow::{Context, Result};
44use std::marker::PhantomData;
45use std::os::fd::{AsRawFd, FromRawFd, OwnedFd, RawFd};
46use std::path::Path;
47use std::rc::Rc;
48use std::sync::atomic::{AtomicBool, AtomicI32, AtomicU32, AtomicUsize, Ordering};
49use std::sync::{Arc, Mutex};
50use std::thread::JoinHandle;
51
52use super::FlockMode;
53use super::fs_filter::reject_remote_fs;
54
55/// Open a lockfile with the crate-wide flock contract: refuses
56/// remote filesystems via [`reject_remote_fs`], then opens with
57/// `O_CREAT | O_RDWR | O_CLOEXEC | 0o666`. The three module entry
58/// points ([`materialize`], [`try_flock_with_witness`] / [`try_flock`],
59/// and [`block_flock`]) share this open shape; centralizing it here
60/// means a future flag change (or an addition to the remote-fs
61/// deny-list) lands in one place instead of drifting across call sites.
62///
63/// `O_CLOEXEC` is mandatory: a leaked fd across `exec(2)` (cargo
64/// subcommand, build-pipeline subprocess, initramfs compressor)
65/// would keep the lock alive in the child after the parent's
66/// `OwnedFd::drop`, producing phantom holders the next acquirer
67/// would blame on the wrong pid.
68///
69/// 0o666 mode matches a peer first-acquire so the file's owner and
70/// permissions don't depend on creation order.
71fn open_lockfile(path: &Path) -> Result<OwnedFd> {
72    use rustix::fs::{Mode, OFlags, open};
73
74    reject_remote_fs(path)?;
75    open(
76        path,
77        OFlags::CREATE | OFlags::RDWR | OFlags::CLOEXEC,
78        Mode::from_raw_mode(0o666),
79    )
80    .map_err(|e| anyhow::anyhow!("open {}: {e}", path.display()))
81}
82
83/// Result of a nonblocking flock attempt that preserves the opened fd in
84/// either case.
85///
86/// A contended fd owns no flock: the kernel rejected the requested operation
87/// with `EWOULDBLOCK`. Keeping that writable fd open is nevertheless useful to
88/// admission protocols. They may publish the corresponding blocked state
89/// first, then drop the witness so its `IN_CLOSE_WRITE` avoids an intervening
90/// UNKNOWN state and re-probe. Correctness does not depend on retaining it when
91/// the admission model durably records pending UNKNOWN resources.
92#[derive(Debug)]
93pub(crate) enum TryFlockOutcome {
94    /// The fd owns the requested flock until its last open-file-description
95    /// reference closes.
96    Acquired(OwnedFd),
97    /// The fd remains open but owns no flock.
98    Contended(OwnedFd),
99}
100
101/// Issue the common nonblocking flock operation against an already-open fd.
102fn try_flock_fd(path: &Path, fd: OwnedFd, mode: FlockMode) -> Result<TryFlockOutcome> {
103    use rustix::fs::{FlockOperation, flock};
104
105    let op = match mode {
106        FlockMode::Exclusive => FlockOperation::NonBlockingLockExclusive,
107        FlockMode::Shared => FlockOperation::NonBlockingLockShared,
108    };
109    match flock(&fd, op) {
110        Ok(()) => Ok(TryFlockOutcome::Acquired(fd)),
111        Err(e) if e == rustix::io::Errno::WOULDBLOCK => Ok(TryFlockOutcome::Contended(fd)),
112        Err(e) => anyhow::bail!("flock {}: {e}", path.display()),
113    }
114}
115
116/// Ensure the lockfile exists on disk without acquiring a lock.
117/// Used by the DISCOVER phase of `acquire_llc_plan` (see
118/// `discover_llc_snapshots` in `crate::vmm::host_topology`): the
119/// snapshot pass needs every per-LLC lockfile's inode to exist so a
120/// subsequent `/proc/locks` match has a target, but DISCOVER itself
121/// must not contend with peer acquires.
122///
123/// Opens through [`open_lockfile`] so the resulting inode and fd
124/// mode match what a first-time acquirer would create. Immediately
125/// closes the fd — `OwnedFd::drop` releases the open-file
126/// description and (since no flock was ever taken on this fd)
127/// cannot release a lock held by a peer fd.
128pub(crate) fn materialize<P: AsRef<Path>>(path: P) -> Result<()> {
129    let fd = open_lockfile(path.as_ref())?;
130    drop(fd);
131    Ok(())
132}
133
134/// Open a lockfile read-write and attempt a nonblocking flock without dropping
135/// the fd on contention.
136///
137/// This is the evidence-preserving form of [`try_flock`]. Both variants create
138/// a missing lockfile with the crate-wide `O_CREAT | O_RDWR | O_CLOEXEC`
139/// contract. The only difference is that this function returns
140/// [`TryFlockOutcome::Contended`] with the writable fd still open, allowing a
141/// caller to order its eventual close after a cross-process state publication
142/// when doing so avoids a conservative UNKNOWN re-probe.
143pub(crate) fn try_flock_with_witness<P: AsRef<Path>>(
144    path: P,
145    mode: FlockMode,
146) -> Result<TryFlockOutcome> {
147    let path = path.as_ref();
148    let fd = open_lockfile(path)?;
149    try_flock_fd(path, fd, mode)
150}
151
152/// Observe an existing lockfile with a read-only, nonblocking flock attempt.
153///
154/// Returns `Ok(None)` if the path does not exist and never creates it. An
155/// existing path returns the same acquired/contended outcome as
156/// [`try_flock_with_witness`], but the fd was opened `O_RDONLY | O_CLOEXEC`.
157/// Dropping either outcome therefore emits `IN_CLOSE_NOWRITE`, not
158/// `IN_CLOSE_WRITE`; coordinator watches interested in real holder releases can
159/// omit observation traffic at the kernel filter.
160///
161/// An `Acquired` result is an observational proof flock. A caller may retain it
162/// through publication of the proven state so that state remains true at the
163/// publication boundary, then drop it; it should not use this read-only probe
164/// as a long-lived resource reservation.
165#[cfg(test)]
166pub(crate) fn probe_flock_existing_read_only<P: AsRef<Path>>(
167    path: P,
168    mode: FlockMode,
169) -> Result<Option<TryFlockOutcome>> {
170    use rustix::fs::{Mode, OFlags, open};
171
172    let path = path.as_ref();
173    reject_remote_fs(path)?;
174    let fd = match open(path, OFlags::RDONLY | OFlags::CLOEXEC, Mode::empty()) {
175        Ok(fd) => fd,
176        Err(e) if e == rustix::io::Errno::NOENT => return Ok(None),
177        Err(e) => return Err(anyhow::anyhow!("open existing {}: {e}", path.display())),
178    };
179    try_flock_fd(path, fd, mode).map(Some)
180}
181
182/// Open a lock file and attempt `flock` with `LOCK_NB`.
183///
184/// Creates the file with mode 0o666 if absent. Returns
185/// `Ok(Some(fd))` on successful acquire, `Ok(None)` on
186/// `EWOULDBLOCK` (peer already holds an incompatible lock), and
187/// propagates other errors. The returned fd owns the open-file
188/// description; dropping it closes the fd AND releases the kernel
189/// flock (the kernel releases `flock(2)` only when the last fd
190/// referring to its OFD closes — `OwnedFd::drop` is what makes that
191/// work).
192///
193/// `O_CLOEXEC` is mandatory: a leaked fd across `exec(2)` (cargo
194/// subcommand, build-pipeline subprocess, initramfs compressor) would
195/// keep the lock alive in the child process after the parent's
196/// `OwnedFd::drop` runs, producing phantom holders the next acquirer
197/// would blame on the wrong pid.
198///
199/// Calls `super::fs_filter::reject_remote_fs` before the open to
200/// fail-fast on NFS / CIFS / SMB2 / CEPH / AFS / FUSE — see the
201/// module-level rationale.
202///
203/// Accepts any `AsRef<Path>` so `&str`, `&Path`, `&PathBuf`, and
204/// `String` callers all work without string-ifying round trips. LLC
205/// lockfile paths are built as `String` via `format!` and cache
206/// lockfile paths are built as `PathBuf` via `Path::join` — both
207/// pass straight through.
208pub fn try_flock<P: AsRef<Path>>(path: P, mode: FlockMode) -> Result<Option<OwnedFd>> {
209    match try_flock_with_witness(path, mode)? {
210        TryFlockOutcome::Acquired(fd) => Ok(Some(fd)),
211        TryFlockOutcome::Contended(witness) => {
212            // Preserve the historical Option API: callers that do not
213            // participate in publication ordering intentionally discard the
214            // contended writable witness immediately.
215            drop(witness);
216            Ok(None)
217        }
218    }
219}
220
221/// Blocking variant of [`try_flock`]. Opens the lockfile (creating
222/// it if absent), then issues a blocking `flock(2)` that parks the
223/// caller in the kernel until the lock is available. Use after
224/// [`try_flock`] returns `None` to wait for a live peer to finish.
225pub fn block_flock<P: AsRef<Path>>(path: P, mode: FlockMode) -> Result<OwnedFd> {
226    use rustix::fs::{FlockOperation, flock};
227
228    let path = path.as_ref();
229    let fd = open_lockfile(path)?;
230    let op = match mode {
231        FlockMode::Exclusive => FlockOperation::LockExclusive,
232        FlockMode::Shared => FlockOperation::LockShared,
233    };
234    flock(&fd, op)
235        .map_err(|errno| std::io::Error::from_raw_os_error(errno.raw_os_error()))
236        .with_context(|| format!("flock (blocking) {}", path.display()))?;
237    Ok(fd)
238}
239
240/// RT signal used to interrupt a deadline-bounded blocking `flock(2)`
241/// ([`block_flock_deadline`]). `SIGRTMIN+4`: `SIGRTMIN` itself is the
242/// vCPU kick (`crate::vmm::vcpu::vcpu_signal`); +4 leaves headroom for
243/// future vCPU-adjacent signals without colliding. The handler is a
244/// no-op — the entire point is the `EINTR` the delivery forces out of
245/// the blocked `flock`.
246fn flock_deadline_signal() -> libc::c_int {
247    libc::SIGRTMIN() + 4
248}
249
250/// Cached signal number for async-signal-safe wake delivery.
251///
252/// On glibc `SIGRTMIN()` is a function call, not a compile-time constant.
253/// Resolve it while installing the handler in normal context so
254/// [`wake_interruptible_flock_waiter`] only performs atomic operations and
255/// async-signal-safe syscalls.
256static FLOCK_WAKE_SIGNAL: AtomicI32 = AtomicI32::new(0);
257
258/// Install the no-op handler for [`flock_deadline_signal`] exactly once,
259/// process-wide.
260///
261/// `sa_flags` deliberately omits `SA_RESTART`: both deadline ticks and an
262/// explicit interrupt wake must force a blocked `flock(2)` / `poll(2)` back
263/// into normal Rust context. Delivery is thread-directed, so unrelated threads
264/// never observe the wake signal.
265fn install_flock_deadline_handler() {
266    static INSTALL: std::sync::Once = std::sync::Once::new();
267    INSTALL.call_once(|| {
268        extern "C" fn noop(_: libc::c_int) {}
269        unsafe {
270            let signal = flock_deadline_signal();
271            let mut sa: libc::sigaction = std::mem::zeroed();
272            sa.sa_sigaction = noop as *const () as usize;
273            sa.sa_flags = 0; // no SA_RESTART — EINTR is load-bearing.
274            libc::sigemptyset(&mut sa.sa_mask);
275            let rc = libc::sigaction(signal, &sa, std::ptr::null_mut());
276            assert_eq!(
277                rc,
278                0,
279                "install_flock_deadline_handler: sigaction(SIGRTMIN+4) failed: {} — \
280                 deadline-bounded flock waits would park forever",
281                std::io::Error::last_os_error(),
282            );
283            FLOCK_WAKE_SIGNAL.store(signal, Ordering::SeqCst);
284        }
285    });
286}
287
288const NO_INTERRUPTIBLE_WAITER: u32 = 0;
289const CLOSING_INTERRUPTIBLE_WAITER: u32 = u32::MAX;
290const NO_BROKER_EVENTFD: RawFd = -1;
291const CLOSING_BROKER_EVENTFD: RawFd = -2;
292const INTERRUPT_WAKE_RETRY: std::time::Duration = std::time::Duration::from_millis(2);
293
294/// The current cancellation-aware registry ticket or coordinator.
295///
296/// The public identity is a generation token, not the Linux TID. A retry
297/// queued for an old waiter can therefore never signal a later registration
298/// that happens to run on the same thread. TID is published before the live
299/// generation and cleared before that generation returns to zero.
300static INTERRUPTIBLE_WAITER_ID: AtomicU32 = AtomicU32::new(NO_INTERRUPTIBLE_WAITER);
301static INTERRUPTIBLE_WAITER_TID: AtomicI32 = AtomicI32::new(0);
302static NEXT_INTERRUPTIBLE_WAITER_ID: AtomicU32 = AtomicU32::new(1);
303
304/// Broker iterations that passed the generation check and may still load/use
305/// the registered TID. Waiter teardown changes the generation to CLOSING and
306/// drains this count before blocking and draining the private RT signal.
307static INTERRUPTIBLE_BROKER_READERS: AtomicUsize = AtomicUsize::new(0);
308
309/// Signal-handler writers that may have loaded either the waiter generation or
310/// broker eventfd. Both waiter teardown and broker shutdown hide their
311/// respective object and drain this count before allowing reuse/close.
312static INTERRUPTIBLE_HANDLER_WRITERS: AtomicUsize = AtomicUsize::new(0);
313
314/// Eventfd handoff from the async handler to the normal-context broker.
315static INTERRUPTIBLE_BROKER_EVENTFD: AtomicI32 = AtomicI32::new(NO_BROKER_EVENTFD);
316static INTERRUPTIBLE_BROKER_REQUEST: AtomicU32 = AtomicU32::new(NO_INTERRUPTIBLE_WAITER);
317#[cfg(test)]
318static INTERRUPTIBLE_BROKER_SIGNAL_COUNT: AtomicUsize = AtomicUsize::new(0);
319#[cfg(test)]
320static INTERRUPTIBLE_BROKER_TID: AtomicU32 = AtomicU32::new(0);
321
322struct InterruptibleFlockBroker {
323    eventfd: OwnedFd,
324    stopping: Arc<AtomicBool>,
325    thread: JoinHandle<()>,
326}
327
328struct InterruptibleFlockBrokerState {
329    active: Option<InterruptibleFlockBroker>,
330    retired: Vec<JoinHandle<()>>,
331}
332
333static INTERRUPTIBLE_BROKER: Mutex<InterruptibleFlockBrokerState> =
334    Mutex::new(InterruptibleFlockBrokerState {
335        active: None,
336        retired: Vec::new(),
337    });
338
339fn broker_state() -> std::sync::MutexGuard<'static, InterruptibleFlockBrokerState> {
340    INTERRUPTIBLE_BROKER
341        .lock()
342        .unwrap_or_else(|poisoned| poisoned.into_inner())
343}
344
345/// Start the normal-context broker used to wake cancellation-aware flock
346/// waiters.
347///
348/// Lifecycle ownership belongs to cargo-ktstr: start immediately before
349/// entering its cleanup-owning phase and stop after all reservation state has
350/// dropped. The broker is restartable after a matching stop, which also keeps
351/// unit tests isolated.
352pub fn start_interruptible_flock_broker() -> Result<()> {
353    let mut state = broker_state();
354    // A normal cargo-ktstr process owns one broker epoch and exits after
355    // stopping it. Tests may deliberately restart the broker; join retired
356    // generations here, before publishing any new request/eventfd state, so
357    // an old reader can never consume a later generation's request.
358    for retired in state.retired.drain(..) {
359        if retired.join().is_err() {
360            anyhow::bail!("retired interruptible flock broker thread panicked");
361        }
362    }
363    if state.active.is_some() {
364        anyhow::bail!("interruptible flock broker is already running");
365    }
366    if INTERRUPTIBLE_WAITER_ID.load(Ordering::SeqCst) != NO_INTERRUPTIBLE_WAITER {
367        anyhow::bail!("cannot start interruptible flock broker with a live waiter");
368    }
369
370    // SAFETY: eventfd returns a new owned descriptor on success.
371    let raw_fd = unsafe { libc::eventfd(0, libc::EFD_CLOEXEC | libc::EFD_NONBLOCK) };
372    if raw_fd < 0 {
373        anyhow::bail!(
374            "create interruptible flock broker eventfd: {}",
375            std::io::Error::last_os_error(),
376        );
377    }
378    let eventfd = unsafe { OwnedFd::from_raw_fd(raw_fd) };
379
380    // Prime the exact libc write entry used by the signal handler while in
381    // normal context, then drain the probe before making the fd visible.
382    let one = 1_u64;
383    let wrote = unsafe {
384        libc::write(
385            raw_fd,
386            (&one as *const u64).cast(),
387            std::mem::size_of::<u64>(),
388        )
389    };
390    if wrote != std::mem::size_of::<u64>() as isize {
391        anyhow::bail!(
392            "prime interruptible flock broker eventfd write: {}",
393            std::io::Error::last_os_error(),
394        );
395    }
396    let mut drained = 0_u64;
397    let read = unsafe {
398        libc::read(
399            raw_fd,
400            (&mut drained as *mut u64).cast(),
401            std::mem::size_of::<u64>(),
402        )
403    };
404    if read != std::mem::size_of::<u64>() as isize || drained != one {
405        anyhow::bail!(
406            "drain interruptible flock broker eventfd prime: {}",
407            std::io::Error::last_os_error(),
408        );
409    }
410
411    INTERRUPTIBLE_BROKER_REQUEST.store(NO_INTERRUPTIBLE_WAITER, Ordering::SeqCst);
412    #[cfg(test)]
413    INTERRUPTIBLE_BROKER_SIGNAL_COUNT.store(0, Ordering::SeqCst);
414    let broker_eventfd = eventfd
415        .try_clone()
416        .map_err(|error| anyhow::anyhow!("clone interruptible flock broker eventfd: {error}"))?;
417    let stopping = Arc::new(AtomicBool::new(false));
418    let broker_stopping = Arc::clone(&stopping);
419    let thread = std::thread::Builder::new()
420        .name("ktstr-flock-wake".into())
421        .spawn(move || interruptible_flock_broker_loop(broker_eventfd, broker_stopping))
422        .map_err(|error| anyhow::anyhow!("spawn interruptible flock broker: {error}"))?;
423
424    // Publish only after the broker thread exists and owns its read loop.
425    INTERRUPTIBLE_BROKER_EVENTFD.store(raw_fd, Ordering::SeqCst);
426    state.active = Some(InterruptibleFlockBroker {
427        eventfd,
428        stopping,
429        thread,
430    });
431    Ok(())
432}
433
434/// Stop the interruptible-flock broker without waiting for its thread to run.
435///
436/// Hiding the eventfd and draining handler writers before the owned wake/close
437/// ensures an async handler can never write through a recycled fd number. The
438/// broker owns a duplicate eventfd and a generation-local stop flag, so it can
439/// finish asynchronously even when the host scheduler has starved that one
440/// thread. A later explicit restart joins retired generations before publishing
441/// new global request state.
442pub fn stop_interruptible_flock_broker() {
443    let mut state = broker_state();
444    let Some(broker) = state.active.take() else {
445        return;
446    };
447
448    let raw_fd = broker.eventfd.as_raw_fd();
449    let hidden = INTERRUPTIBLE_BROKER_EVENTFD.compare_exchange(
450        raw_fd,
451        CLOSING_BROKER_EVENTFD,
452        Ordering::SeqCst,
453        Ordering::SeqCst,
454    );
455    assert_eq!(
456        hidden,
457        Ok(raw_fd),
458        "interruptible flock broker eventfd changed before stop",
459    );
460    while INTERRUPTIBLE_HANDLER_WRITERS.load(Ordering::SeqCst) != 0 {
461        std::hint::spin_loop();
462    }
463
464    broker.stopping.store(true, Ordering::SeqCst);
465    // Wake the broker through the still-owned fd after handlers can no longer
466    // load it. Its duplicate keeps the eventfd object alive until the broker
467    // observes this generation's stop flag and exits.
468    let one = 1_u64;
469    unsafe {
470        libc::write(
471            raw_fd,
472            (&one as *const u64).cast(),
473            std::mem::size_of::<u64>(),
474        );
475    }
476    drop(broker.eventfd);
477    INTERRUPTIBLE_BROKER_REQUEST.store(NO_INTERRUPTIBLE_WAITER, Ordering::SeqCst);
478    INTERRUPTIBLE_BROKER_EVENTFD.store(NO_BROKER_EVENTFD, Ordering::SeqCst);
479    state.retired.push(broker.thread);
480}
481
482fn interruptible_flock_broker_loop(eventfd: OwnedFd, stopping: Arc<AtomicBool>) {
483    #[cfg(test)]
484    {
485        // SAFETY: `SYS_gettid` has no pointer arguments.
486        let tid = unsafe { libc::syscall(libc::SYS_gettid) };
487        assert!(tid > 0 && tid <= u32::MAX as libc::c_long);
488        INTERRUPTIBLE_BROKER_TID.store(tid as u32, Ordering::SeqCst);
489    }
490    let raw_fd = eventfd.as_raw_fd();
491    loop {
492        let mut pollfd = libc::pollfd {
493            fd: raw_fd,
494            events: libc::POLLIN,
495            revents: 0,
496        };
497        let ready = unsafe { libc::poll(&mut pollfd, 1, -1) };
498        if ready < 0 {
499            if std::io::Error::last_os_error().raw_os_error() == Some(libc::EINTR) {
500                continue;
501            }
502            std::thread::yield_now();
503            continue;
504        }
505
506        drain_interruptible_broker_eventfd(raw_fd);
507        if stopping.load(Ordering::SeqCst) {
508            break;
509        }
510
511        let waiter_id =
512            INTERRUPTIBLE_BROKER_REQUEST.swap(NO_INTERRUPTIBLE_WAITER, Ordering::SeqCst);
513        if waiter_id == NO_INTERRUPTIBLE_WAITER || waiter_id == CLOSING_INTERRUPTIBLE_WAITER {
514            continue;
515        }
516
517        // Re-fire only after cancellation was handed to the broker. Healthy
518        // queue contention therefore retains one FIFO flock request, while a
519        // signal that landed just before syscall entry cannot strand it.
520        loop {
521            if stopping.load(Ordering::SeqCst) || !broker_signal_waiter_if_live(waiter_id) {
522                break;
523            }
524            std::thread::sleep(INTERRUPT_WAKE_RETRY);
525        }
526    }
527    #[cfg(test)]
528    INTERRUPTIBLE_BROKER_TID.store(0, Ordering::SeqCst);
529}
530
531fn drain_interruptible_broker_eventfd(eventfd: RawFd) {
532    loop {
533        let mut value = 0_u64;
534        let read = unsafe {
535            libc::read(
536                eventfd,
537                (&mut value as *mut u64).cast(),
538                std::mem::size_of::<u64>(),
539            )
540        };
541        if read == std::mem::size_of::<u64>() as isize {
542            continue;
543        }
544        if read < 0 && std::io::Error::last_os_error().raw_os_error() == Some(libc::EINTR) {
545            continue;
546        }
547        break;
548    }
549}
550
551fn broker_signal_waiter_if_live(waiter_id: u32) -> bool {
552    INTERRUPTIBLE_BROKER_READERS.fetch_add(1, Ordering::SeqCst);
553    let live = INTERRUPTIBLE_WAITER_ID.load(Ordering::SeqCst) == waiter_id;
554    if live {
555        let tid = INTERRUPTIBLE_WAITER_TID.load(Ordering::SeqCst);
556        let signal = FLOCK_WAKE_SIGNAL.load(Ordering::SeqCst);
557        if tid > 0 && signal > 0 {
558            unsafe {
559                libc::syscall(libc::SYS_tgkill, libc::getpid(), tid, signal);
560            }
561            #[cfg(test)]
562            INTERRUPTIBLE_BROKER_SIGNAL_COUNT.fetch_add(1, Ordering::SeqCst);
563        }
564    }
565    INTERRUPTIBLE_BROKER_READERS.fetch_sub(1, Ordering::SeqCst);
566    live
567}
568
569/// Current cancellation-aware flock waiter generation, or zero when none is
570/// registered.
571///
572/// This atomic-only query is safe to call from a signal handler.
573pub fn interruptible_flock_waiter_id() -> u32 {
574    let waiter_id = INTERRUPTIBLE_WAITER_ID.load(Ordering::SeqCst);
575    if waiter_id == CLOSING_INTERRUPTIBLE_WAITER {
576        NO_INTERRUPTIBLE_WAITER
577    } else {
578        waiter_id
579    }
580}
581
582#[cfg(test)]
583pub(crate) fn interruptible_flock_broker_signal_count() -> usize {
584    INTERRUPTIBLE_BROKER_SIGNAL_COUNT.load(Ordering::SeqCst)
585}
586
587#[cfg(test)]
588pub(crate) fn interruptible_flock_broker_tid() -> u32 {
589    INTERRUPTIBLE_BROKER_TID.load(Ordering::SeqCst)
590}
591
592/// Hand cancellation of an exact waiter generation to the broker.
593///
594/// The signal-handler path performs only lock-free atomics and one nonblocking
595/// eventfd write. The caller must publish its cancellation flag first.
596pub fn wake_interruptible_flock_waiter(waiter_id: u32) {
597    if waiter_id == NO_INTERRUPTIBLE_WAITER || waiter_id == CLOSING_INTERRUPTIBLE_WAITER {
598        return;
599    }
600
601    INTERRUPTIBLE_HANDLER_WRITERS.fetch_add(1, Ordering::SeqCst);
602    if INTERRUPTIBLE_WAITER_ID.load(Ordering::SeqCst) == waiter_id {
603        let eventfd = INTERRUPTIBLE_BROKER_EVENTFD.load(Ordering::SeqCst);
604        if eventfd >= 0 {
605            INTERRUPTIBLE_BROKER_REQUEST.store(waiter_id, Ordering::SeqCst);
606            let one = 1_u64;
607            unsafe {
608                libc::write(
609                    eventfd,
610                    (&one as *const u64).cast(),
611                    std::mem::size_of::<u64>(),
612                );
613            }
614        }
615    }
616    INTERRUPTIBLE_HANDLER_WRITERS.fetch_sub(1, Ordering::SeqCst);
617}
618
619fn next_interruptible_waiter_id() -> u32 {
620    loop {
621        let waiter_id = NEXT_INTERRUPTIBLE_WAITER_ID.fetch_add(1, Ordering::SeqCst);
622        if waiter_id != NO_INTERRUPTIBLE_WAITER && waiter_id != CLOSING_INTERRUPTIBLE_WAITER {
623            return waiter_id;
624        }
625    }
626}
627
628/// RAII registration for one cancellation-aware registry ticket/coordinator.
629///
630/// The broker targets this registration's Linux TID only while its generation
631/// remains live. This value is deliberately `!Send`: its saved signal-mask
632/// state must be restored on the registering thread.
633pub(crate) struct InterruptibleFlockWaiter {
634    waiter_id: u32,
635    wake_was_blocked: bool,
636    _not_send: PhantomData<Rc<()>>,
637}
638
639impl InterruptibleFlockWaiter {
640    pub(crate) fn register() -> Result<Self> {
641        if INTERRUPTIBLE_BROKER_EVENTFD.load(Ordering::SeqCst) < 0 {
642            anyhow::bail!("interruptible flock broker is not running");
643        }
644        install_flock_deadline_handler();
645        let signal = FLOCK_WAKE_SIGNAL.load(Ordering::SeqCst);
646        let tid = unsafe { libc::syscall(libc::SYS_gettid) as libc::pid_t };
647
648        if INTERRUPTIBLE_WAITER_ID
649            .compare_exchange(
650                NO_INTERRUPTIBLE_WAITER,
651                CLOSING_INTERRUPTIBLE_WAITER,
652                Ordering::SeqCst,
653                Ordering::SeqCst,
654            )
655            .is_err()
656        {
657            anyhow::bail!("another interruptible flock waiter is already registered");
658        }
659
660        let mut wake_set: libc::sigset_t = unsafe { std::mem::zeroed() };
661        let mut previous_mask: libc::sigset_t = unsafe { std::mem::zeroed() };
662        let mask_rc = unsafe {
663            libc::sigemptyset(&mut wake_set);
664            libc::sigaddset(&mut wake_set, signal);
665            libc::pthread_sigmask(libc::SIG_UNBLOCK, &wake_set, &mut previous_mask)
666        };
667        if mask_rc != 0 {
668            INTERRUPTIBLE_WAITER_ID.store(NO_INTERRUPTIBLE_WAITER, Ordering::SeqCst);
669            return Err(anyhow::anyhow!(
670                "unblock interruptible flock wake signal: {}",
671                std::io::Error::from_raw_os_error(mask_rc),
672            ));
673        }
674        let wake_was_blocked = unsafe { libc::sigismember(&previous_mask, signal) == 1 };
675        let waiter_id = next_interruptible_waiter_id();
676
677        // TID becomes visible before the generation that authorizes readers to
678        // use it.
679        INTERRUPTIBLE_WAITER_TID.store(tid, Ordering::SeqCst);
680        INTERRUPTIBLE_WAITER_ID.store(waiter_id, Ordering::SeqCst);
681
682        Ok(Self {
683            waiter_id,
684            wake_was_blocked,
685            _not_send: PhantomData,
686        })
687    }
688}
689
690impl Drop for InterruptibleFlockWaiter {
691    fn drop(&mut self) {
692        let transitioned = INTERRUPTIBLE_WAITER_ID.compare_exchange(
693            self.waiter_id,
694            CLOSING_INTERRUPTIBLE_WAITER,
695            Ordering::SeqCst,
696            Ordering::SeqCst,
697        );
698        assert_eq!(
699            transitioned,
700            Ok(self.waiter_id),
701            "interruptible flock waiter registration changed before drop",
702        );
703
704        while INTERRUPTIBLE_HANDLER_WRITERS.load(Ordering::SeqCst) != 0
705            || INTERRUPTIBLE_BROKER_READERS.load(Ordering::SeqCst) != 0
706        {
707            std::hint::spin_loop();
708        }
709
710        // No new broker reader can pass the generation check after CLOSING.
711        // Block and drain a signal already sent by an old reader before
712        // allowing either the TID or generation slot to be reused.
713        unsafe {
714            let signal = FLOCK_WAKE_SIGNAL.load(Ordering::SeqCst);
715            let mut wake_set: libc::sigset_t = std::mem::zeroed();
716            libc::sigemptyset(&mut wake_set);
717            libc::sigaddset(&mut wake_set, signal);
718            libc::pthread_sigmask(libc::SIG_BLOCK, &wake_set, std::ptr::null_mut());
719            let zero = libc::timespec {
720                tv_sec: 0,
721                tv_nsec: 0,
722            };
723            loop {
724                let drained = libc::sigtimedwait(&wake_set, std::ptr::null_mut(), &zero);
725                if drained == signal {
726                    continue;
727                }
728                assert!(
729                    drained < 0,
730                    "sigtimedwait returned unexpected signal {drained} while \
731                     draining private wake signal {signal}",
732                );
733                let error = std::io::Error::last_os_error();
734                match error.raw_os_error() {
735                    // No private RT signal remains pending on this thread.
736                    Some(libc::EAGAIN) => break,
737                    // An unrelated unblocked signal ran while draining. Retry
738                    // until EAGAIN so an old wake cannot escape into a later
739                    // same-thread registration.
740                    Some(libc::EINTR) => continue,
741                    _ => panic!("drain interruptible flock wake signal: {error}"),
742                }
743            }
744
745            INTERRUPTIBLE_WAITER_TID.store(0, Ordering::SeqCst);
746            INTERRUPTIBLE_WAITER_ID.store(NO_INTERRUPTIBLE_WAITER, Ordering::SeqCst);
747            if !self.wake_was_blocked {
748                libc::pthread_sigmask(libc::SIG_UNBLOCK, &wake_set, std::ptr::null_mut());
749            }
750        }
751    }
752}
753
754/// RAII POSIX per-thread interval timer that delivers
755/// [`flock_deadline_signal`] to the CREATING thread. Armed with a
756/// one-shot expiry at the deadline plus a periodic re-fire, so a
757/// signal that lands in the race window between the deadline check
758/// and the next blocking `flock` entry cannot strand the waiter —
759/// the next interval tick interrupts it again.
760struct DeadlineTimer {
761    id: libc::timer_t,
762}
763
764impl DeadlineTimer {
765    /// Create and arm a timer targeted at the calling thread: first
766    /// fire at `tick` (clamped to the remaining deadline budget),
767    /// re-firing every `tick` after.
768    fn arm(deadline: std::time::Instant, tick: std::time::Duration) -> Result<Self> {
769        install_flock_deadline_handler();
770        let remaining = deadline
771            .saturating_duration_since(std::time::Instant::now())
772            .min(tick)
773            .max(std::time::Duration::from_millis(1));
774        unsafe {
775            let mut sev: libc::sigevent = std::mem::zeroed();
776            sev.sigev_notify = libc::SIGEV_THREAD_ID;
777            sev.sigev_signo = flock_deadline_signal();
778            sev.sigev_notify_thread_id = libc::gettid();
779            let mut id: libc::timer_t = std::mem::zeroed();
780            if libc::timer_create(libc::CLOCK_MONOTONIC, &mut sev, &mut id) != 0 {
781                anyhow::bail!(
782                    "timer_create for deadline-bounded flock: {}",
783                    std::io::Error::last_os_error()
784                );
785            }
786            let spec = libc::itimerspec {
787                it_value: libc::timespec {
788                    tv_sec: remaining.as_secs() as libc::time_t,
789                    tv_nsec: remaining.subsec_nanos() as libc::c_long,
790                },
791                // Periodic re-fire closes the check-then-block race:
792                // if a fire lands between the clock check and flock
793                // entry, the next tick still interrupts.
794                it_interval: libc::timespec {
795                    tv_sec: tick.as_secs() as libc::time_t,
796                    tv_nsec: tick.subsec_nanos() as libc::c_long,
797                },
798            };
799            if libc::timer_settime(id, 0, &spec, std::ptr::null_mut()) != 0 {
800                let e = std::io::Error::last_os_error();
801                libc::timer_delete(id);
802                anyhow::bail!("timer_settime for deadline-bounded flock: {e}");
803            }
804            Ok(DeadlineTimer { id })
805        }
806    }
807}
808
809impl Drop for DeadlineTimer {
810    fn drop(&mut self) {
811        // SAFETY: `id` came from a successful timer_create and is
812        // deleted exactly once (Drop).
813        unsafe {
814            libc::timer_delete(self.id);
815        }
816    }
817}
818
819/// Outcome of one [`block_flock_step`] blocking cycle.
820#[derive(Debug)]
821pub enum FlockWait {
822    /// Lock granted before the deadline; the fd holds it (RAII).
823    Granted(OwnedFd),
824    /// The periodic tick fired before the deadline: the caller gets
825    /// control back to re-evaluate (re-plan, re-scan alternatives)
826    /// and decide whether to call the step again. The kernel
827    /// wait-queue position is released with the step's fd.
828    Tick,
829    /// The deadline passed while blocked.
830    DeadlineExpired,
831}
832
833/// One deadline-bounded BLOCKING `flock(2)` cycle with a periodic
834/// re-evaluation tick.
835///
836/// Parks the calling thread in the kernel's per-inode flock wait
837/// queue — the wake-latency primitive the polling loops lacked: the
838/// kernel wakes the waiter at release time, so a freed lock is
839/// picked up in microseconds, not at the next poll interval.
840///
841/// Returns:
842///  - [`FlockWait::Granted`] when the lock is granted,
843///  - [`FlockWait::Tick`] when `tick` elapses first (caller
844///    re-evaluates live state — e.g. a coordinator re-scanning for a
845///    fully-free alternative target — then typically calls again),
846///  - [`FlockWait::DeadlineExpired`] when `deadline` passes,
847///  - `Err` on open / unexpected-errno failures.
848///
849/// Mechanism: a thread-targeted `CLOCK_MONOTONIC` POSIX timer
850/// (`DeadlineTimer`) delivers `SIGRTMIN+4` (no-op handler, no
851/// `SA_RESTART`) to this thread every `tick` (clamped to the
852/// remaining deadline budget), forcing the blocked `flock` to return
853/// `EINTR`; the step maps that to `Tick` or `DeadlineExpired` by the
854/// clock. The interval re-fire means a signal landing in the gap
855/// between arming and blocking cannot strand the waiter.
856pub fn block_flock_step<P: AsRef<Path>>(
857    path: P,
858    mode: FlockMode,
859    deadline: std::time::Instant,
860    tick: std::time::Duration,
861) -> Result<FlockWait> {
862    use rustix::fs::{FlockOperation, flock};
863
864    if std::time::Instant::now() >= deadline {
865        return Ok(FlockWait::DeadlineExpired);
866    }
867    let path = path.as_ref();
868    let fd = open_lockfile(path)?;
869    let op = match mode {
870        FlockMode::Exclusive => FlockOperation::LockExclusive,
871        FlockMode::Shared => FlockOperation::LockShared,
872    };
873    let _timer = DeadlineTimer::arm(deadline, tick)?;
874    match flock(&fd, op) {
875        Ok(()) => Ok(FlockWait::Granted(fd)),
876        Err(e) if e == rustix::io::Errno::INTR => {
877            if std::time::Instant::now() >= deadline {
878                Ok(FlockWait::DeadlineExpired)
879            } else {
880                Ok(FlockWait::Tick)
881            }
882        }
883        Err(e) => anyhow::bail!("flock (blocking, deadline) {}: {e}", path.display()),
884    }
885}
886
887/// Deadline-bounded BLOCKING `flock(2)` with no tick observation:
888/// loops [`block_flock_step`] until granted or the deadline expires.
889/// Used where the caller has nothing to re-evaluate mid-wait — e.g.
890/// a contended acquirer parking on the acquisition-queue ticket.
891///
892/// Returns `Ok(Some(fd))` when granted before `deadline`, `Ok(None)`
893/// on expiry, `Err` on open / unexpected-errno failures.
894pub fn block_flock_deadline<P: AsRef<Path>>(
895    path: P,
896    mode: FlockMode,
897    deadline: std::time::Instant,
898) -> Result<Option<OwnedFd>> {
899    let path = path.as_ref();
900    loop {
901        match block_flock_step(path, mode, deadline, std::time::Duration::from_millis(500))? {
902            FlockWait::Granted(fd) => return Ok(Some(fd)),
903            FlockWait::Tick => continue,
904            FlockWait::DeadlineExpired => return Ok(None),
905        }
906    }
907}
908
909#[cfg(test)]
910mod tests {
911    use super::*;
912
913    fn fd_flags(fd: &OwnedFd) -> libc::c_int {
914        use std::os::fd::AsRawFd;
915
916        // SAFETY: `fd` is live for the duration of the accessor and F_GETFD
917        // neither mutates nor assumes ownership of it.
918        let flags = unsafe { libc::fcntl(fd.as_raw_fd(), libc::F_GETFD) };
919        assert!(
920            flags >= 0,
921            "fcntl F_GETFD must succeed on a live fd; got errno={}",
922            std::io::Error::last_os_error(),
923        );
924        flags
925    }
926
927    /// [`try_flock`] sets `O_CLOEXEC` on the returned fd. Earlier
928    /// revisions missed this flag, which leaked flock-held fds
929    /// through `execve` into child processes — the child inherited
930    /// the lock, broke assumptions about RAII scope, and
931    /// manifested as phantom holders in `/proc/locks` long after
932    /// the parent had dropped its guard.
933    ///
934    /// Verifies the bit directly via `fcntl(F_GETFD)` rather than
935    /// asserting via a side-effect (forking an exec'd child is
936    /// noisier and harder to match). Failure mode: if the bit is
937    /// cleared by a future refactor that re-opens the fd without
938    /// re-applying O_CLOEXEC, this test fails the build.
939    #[test]
940    fn try_flock_sets_cloexec_on_returned_fd() {
941        use std::os::fd::AsRawFd;
942        use tempfile::TempDir;
943
944        let tmp = TempDir::new().expect("tempdir");
945        let path = tmp.path().join("cloexec.lock");
946        let fd = try_flock(&path, FlockMode::Exclusive)
947            .expect("try_flock must succeed on fresh tempfile")
948            .expect("EX must acquire on clean pool");
949
950        // SAFETY: fd is a valid OwnedFd — fcntl F_GETFD is a pure
951        // accessor, no concurrent modification, no ownership move.
952        let flags = unsafe { libc::fcntl(fd.as_raw_fd(), libc::F_GETFD) };
953        assert!(
954            flags >= 0,
955            "fcntl F_GETFD must succeed on our fd; got errno={}",
956            std::io::Error::last_os_error(),
957        );
958        assert_eq!(
959            flags & libc::FD_CLOEXEC,
960            libc::FD_CLOEXEC,
961            "FD_CLOEXEC must be set on try_flock-returned fd; \
962             flags=0x{flags:x}. Without it, exec'd children \
963             inherit the flock and produce phantom holders.",
964        );
965
966        drop(fd);
967    }
968
969    /// The evidence-preserving acquire keeps a real O_RDWR fd alive after
970    /// EWOULDBLOCK, with CLOEXEC set, but that witness owns no flock. Releasing
971    /// the real holder while the witness stays open must therefore let a third
972    /// fd acquire immediately. Dropping the witness cannot release the third
973    /// fd's independent flock.
974    #[test]
975    fn contended_witness_is_writable_cloexec_and_owns_no_flock() {
976        use std::os::fd::AsRawFd;
977        use tempfile::TempDir;
978
979        let tmp = TempDir::new().expect("tempdir");
980        let path = tmp.path().join("witness.lock");
981        let peer = try_flock(&path, FlockMode::Exclusive)
982            .expect("open peer")
983            .expect("peer EX on fresh file");
984        let witness =
985            match try_flock_with_witness(&path, FlockMode::Exclusive).expect("contended probe") {
986                TryFlockOutcome::Contended(fd) => fd,
987                TryFlockOutcome::Acquired(_) => panic!("peer EX must force a contended witness"),
988            };
989
990        assert_eq!(
991            fd_flags(&witness) & libc::FD_CLOEXEC,
992            libc::FD_CLOEXEC,
993            "a retained witness must not leak through exec",
994        );
995        // SAFETY: witness is a live O_RDWR fd. Writing one byte demonstrates
996        // the access mode directly without changing fd ownership.
997        let byte = b"x";
998        let written = unsafe {
999            libc::write(
1000                witness.as_raw_fd(),
1001                byte.as_ptr().cast::<libc::c_void>(),
1002                byte.len(),
1003            )
1004        };
1005        assert_eq!(
1006            written,
1007            byte.len() as libc::ssize_t,
1008            "the contended witness must remain open and writable: {}",
1009            std::io::Error::last_os_error(),
1010        );
1011
1012        drop(peer);
1013        let successor = try_flock(&path, FlockMode::Exclusive)
1014            .expect("successor probe")
1015            .expect("an open contended witness owns no flock");
1016
1017        drop(witness);
1018        assert!(
1019            try_flock(&path, FlockMode::Exclusive)
1020                .expect("probe against successor")
1021                .is_none(),
1022            "dropping a non-owning witness must not release the successor's flock",
1023        );
1024        drop(successor);
1025    }
1026
1027    /// A read-only observation never creates a missing lockfile. On an
1028    /// existing contended inode it returns a CLOEXEC O_RDONLY witness, which is
1029    /// the flag-level guarantee that its close is IN_CLOSE_NOWRITE and cannot
1030    /// masquerade as a resource-holder release.
1031    #[test]
1032    fn read_only_existing_probe_does_not_create_and_uses_read_only_cloexec_fd() {
1033        use std::os::fd::AsRawFd;
1034        use tempfile::TempDir;
1035
1036        let tmp = TempDir::new().expect("tempdir");
1037        let path = tmp.path().join("observe.lock");
1038        assert!(
1039            probe_flock_existing_read_only(&path, FlockMode::Exclusive)
1040                .expect("missing observation")
1041                .is_none(),
1042            "a missing existing-only probe must report no inode",
1043        );
1044        assert!(
1045            !path.exists(),
1046            "a read-only existing-file probe must never create the lockfile",
1047        );
1048
1049        let peer = try_flock(&path, FlockMode::Exclusive)
1050            .expect("open peer")
1051            .expect("peer EX on fresh file");
1052        let witness = match probe_flock_existing_read_only(&path, FlockMode::Exclusive)
1053            .expect("existing observation")
1054            .expect("peer materialized the inode")
1055        {
1056            TryFlockOutcome::Contended(fd) => fd,
1057            TryFlockOutcome::Acquired(_) => panic!("peer EX must force read-only contention"),
1058        };
1059        assert_eq!(
1060            fd_flags(&witness) & libc::FD_CLOEXEC,
1061            libc::FD_CLOEXEC,
1062            "read-only observation fd must not leak through exec",
1063        );
1064        // SAFETY: F_GETFL is a read-only query on a live fd.
1065        let status = unsafe { libc::fcntl(witness.as_raw_fd(), libc::F_GETFL) };
1066        assert!(
1067            status >= 0,
1068            "F_GETFL failed: {}",
1069            std::io::Error::last_os_error()
1070        );
1071        assert_eq!(
1072            status & libc::O_ACCMODE,
1073            libc::O_RDONLY,
1074            "observation fd must be O_RDONLY so close is IN_CLOSE_NOWRITE",
1075        );
1076
1077        drop(peer);
1078        let successor = try_flock(&path, FlockMode::Exclusive)
1079            .expect("successor probe")
1080            .expect("read-only contended witness owns no flock");
1081        drop(witness);
1082        drop(successor);
1083    }
1084
1085    /// Linux permits an exclusive flock on an O_RDONLY descriptor. The
1086    /// admission observer relies on that property to prove a free existing
1087    /// resource without opening it writable (and therefore without emitting
1088    /// IN_CLOSE_WRITE when the proof fd is dropped).
1089    #[test]
1090    fn read_only_existing_probe_acquires_exclusive_on_free_local_inode() {
1091        use tempfile::TempDir;
1092
1093        let tmp = TempDir::new().expect("tempdir");
1094        let path = tmp.path().join("read-only-exclusive.lock");
1095        materialize(&path).expect("materialize existing local inode");
1096
1097        let proof = probe_flock_existing_read_only(&path, FlockMode::Exclusive)
1098            .expect("read-only exclusive probe")
1099            .expect("materialized inode must exist");
1100        match proof {
1101            TryFlockOutcome::Acquired(fd) => drop(fd),
1102            TryFlockOutcome::Contended(_) => {
1103                panic!("a free local inode must grant EX through an O_RDONLY fd")
1104            }
1105        }
1106    }
1107
1108    /// Pin the flock compatibility matrix used when admission falls back to
1109    /// read-only observation of LLC availability:
1110    ///
1111    /// - a live SH holder admits another SH proof but rejects EX;
1112    /// - a live EX holder rejects both SH and EX.
1113    ///
1114    /// Each probe uses its own open-file description, so the result exercises
1115    /// kernel compatibility rather than recursive locking on one fd.
1116    #[test]
1117    fn read_only_existing_probe_matches_shared_exclusive_llc_matrix() {
1118        use tempfile::TempDir;
1119
1120        let tmp = TempDir::new().expect("tempdir");
1121        let path = tmp.path().join("read-only-matrix.lock");
1122
1123        let shared_peer = try_flock(&path, FlockMode::Shared)
1124            .expect("open shared peer")
1125            .expect("first SH must acquire");
1126        let shared_proof = probe_flock_existing_read_only(&path, FlockMode::Shared)
1127            .expect("read-only SH probe")
1128            .expect("shared peer materialized the inode");
1129        let shared_proof = match shared_proof {
1130            TryFlockOutcome::Acquired(fd) => fd,
1131            TryFlockOutcome::Contended(_) => {
1132                panic!("SH must remain compatible with a peer SH holder")
1133            }
1134        };
1135        match probe_flock_existing_read_only(&path, FlockMode::Exclusive)
1136            .expect("read-only EX probe against SH")
1137            .expect("inode exists")
1138        {
1139            TryFlockOutcome::Contended(fd) => drop(fd),
1140            TryFlockOutcome::Acquired(_) => {
1141                panic!("EX must conflict with live SH holders")
1142            }
1143        }
1144        drop(shared_proof);
1145        drop(shared_peer);
1146
1147        let exclusive_peer = try_flock(&path, FlockMode::Exclusive)
1148            .expect("open exclusive peer")
1149            .expect("EX must acquire after every SH proof drops");
1150        for mode in [FlockMode::Shared, FlockMode::Exclusive] {
1151            match probe_flock_existing_read_only(&path, mode)
1152                .expect("read-only probe against EX")
1153                .expect("inode exists")
1154            {
1155                TryFlockOutcome::Contended(fd) => drop(fd),
1156                TryFlockOutcome::Acquired(_) => {
1157                    panic!("{mode:?} must conflict with a live EX holder")
1158                }
1159            }
1160        }
1161        drop(exclusive_peer);
1162    }
1163
1164    /// `block_flock_step` tri-state contract: while a peer holds
1165    /// `LOCK_EX`, a step with a short tick returns `Tick` (the
1166    /// thread-targeted timer interrupted the blocked flock via EINTR —
1167    /// this is the empirical pin for the SIGRTMIN+4 deadline
1168    /// machinery), a step whose deadline lapses returns
1169    /// `DeadlineExpired`, and once the peer releases, a step returns
1170    /// `Granted` carrying the lock.
1171    #[test]
1172    fn block_flock_step_tick_expiry_and_grant() {
1173        use tempfile::TempDir;
1174        let tmp = TempDir::new().expect("tempdir");
1175        let path = tmp.path().join("step.lock");
1176        let peer = try_flock(&path, FlockMode::Exclusive)
1177            .expect("open")
1178            .expect("peer EX on fresh file");
1179
1180        // Tick: deadline far, tick near — the timer must interrupt
1181        // the blocked flock rather than leaving it parked.
1182        let start = std::time::Instant::now();
1183        let step = block_flock_step(
1184            &path,
1185            FlockMode::Exclusive,
1186            std::time::Instant::now() + std::time::Duration::from_secs(30),
1187            std::time::Duration::from_millis(150),
1188        )
1189        .expect("step must not error");
1190        assert!(
1191            matches!(step, FlockWait::Tick),
1192            "near tick + far deadline must interrupt as Tick; got {step:?}",
1193        );
1194        assert!(
1195            start.elapsed() < std::time::Duration::from_secs(5),
1196            "the tick must fire near its interval, not hang; elapsed={:?}",
1197            start.elapsed(),
1198        );
1199
1200        // DeadlineExpired: deadline nearer than the tick.
1201        let step = block_flock_step(
1202            &path,
1203            FlockMode::Exclusive,
1204            std::time::Instant::now() + std::time::Duration::from_millis(150),
1205            std::time::Duration::from_secs(30),
1206        )
1207        .expect("step must not error");
1208        assert!(
1209            matches!(step, FlockWait::DeadlineExpired),
1210            "lapsed deadline must report DeadlineExpired; got {step:?}",
1211        );
1212
1213        // Granted: kernel wakeup when the peer releases mid-block.
1214        let releaser = std::thread::spawn(move || {
1215            std::thread::sleep(std::time::Duration::from_millis(200));
1216            drop(peer);
1217        });
1218        let start = std::time::Instant::now();
1219        let step = block_flock_step(
1220            &path,
1221            FlockMode::Exclusive,
1222            std::time::Instant::now() + std::time::Duration::from_secs(30),
1223            std::time::Duration::from_secs(30),
1224        )
1225        .expect("step must not error");
1226        releaser.join().expect("releaser");
1227        assert!(
1228            matches!(step, FlockWait::Granted(_)),
1229            "release must grant the blocked step via kernel wakeup; got {step:?}",
1230        );
1231        assert!(
1232            start.elapsed() >= std::time::Duration::from_millis(150),
1233            "grant must come from the release, not an instant win; elapsed={:?}",
1234            start.elapsed(),
1235        );
1236    }
1237
1238    /// `block_flock_deadline` wraps the step loop: bounded `None` on a
1239    /// never-released peer, `Some(fd)` when the peer releases within
1240    /// the deadline.
1241    #[test]
1242    fn block_flock_deadline_bounds_and_grants() {
1243        use tempfile::TempDir;
1244        let tmp = TempDir::new().expect("tempdir");
1245        let path = tmp.path().join("deadline.lock");
1246        let peer = try_flock(&path, FlockMode::Exclusive)
1247            .expect("open")
1248            .expect("peer EX on fresh file");
1249
1250        let got = block_flock_deadline(
1251            &path,
1252            FlockMode::Exclusive,
1253            std::time::Instant::now() + std::time::Duration::from_millis(250),
1254        )
1255        .expect("must not error");
1256        assert!(got.is_none(), "held lock past the deadline must yield None");
1257
1258        let releaser = std::thread::spawn(move || {
1259            std::thread::sleep(std::time::Duration::from_millis(150));
1260            drop(peer);
1261        });
1262        let got = block_flock_deadline(
1263            &path,
1264            FlockMode::Exclusive,
1265            std::time::Instant::now() + std::time::Duration::from_secs(30),
1266        )
1267        .expect("must not error");
1268        releaser.join().expect("releaser");
1269        assert!(got.is_some(), "release within the deadline must grant");
1270    }
1271}