1use 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
55fn 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#[derive(Debug)]
93pub(crate) enum TryFlockOutcome {
94 Acquired(OwnedFd),
97 Contended(OwnedFd),
99}
100
101fn 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
116pub(crate) fn materialize<P: AsRef<Path>>(path: P) -> Result<()> {
129 let fd = open_lockfile(path.as_ref())?;
130 drop(fd);
131 Ok(())
132}
133
134pub(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#[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
182pub 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 drop(witness);
216 Ok(None)
217 }
218 }
219}
220
221pub 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
240fn flock_deadline_signal() -> libc::c_int {
247 libc::SIGRTMIN() + 4
248}
249
250static FLOCK_WAKE_SIGNAL: AtomicI32 = AtomicI32::new(0);
257
258fn 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; 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
294static 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
304static INTERRUPTIBLE_BROKER_READERS: AtomicUsize = AtomicUsize::new(0);
308
309static INTERRUPTIBLE_HANDLER_WRITERS: AtomicUsize = AtomicUsize::new(0);
313
314static 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
345pub fn start_interruptible_flock_broker() -> Result<()> {
353 let mut state = broker_state();
354 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 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 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 INTERRUPTIBLE_BROKER_EVENTFD.store(raw_fd, Ordering::SeqCst);
426 state.active = Some(InterruptibleFlockBroker {
427 eventfd,
428 stopping,
429 thread,
430 });
431 Ok(())
432}
433
434pub 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 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 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 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
569pub 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
592pub 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
628pub(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 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 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 Some(libc::EAGAIN) => break,
737 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
754struct DeadlineTimer {
761 id: libc::timer_t,
762}
763
764impl DeadlineTimer {
765 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 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 unsafe {
814 libc::timer_delete(self.id);
815 }
816 }
817}
818
819#[derive(Debug)]
821pub enum FlockWait {
822 Granted(OwnedFd),
824 Tick,
829 DeadlineExpired,
831}
832
833pub 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
887pub 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 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 #[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 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 #[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 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 #[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 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 #[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 #[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 #[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 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 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 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 #[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}