Struct PidfileLock 

pub struct PidfileLock { /* private fields */ }

RAII handle holding an exclusive OFD-level flock on sqryd.lock.

Construct via acquire_pidfile_lock (normal start) or PidfileLock::adopt (grandchild after --detach FD inheritance).

Drop behaviour

PidfileOwnership	Unlinks pidfile?	Calls unlock()?
WriteOwner	yes	yes
Handoff	no	no (M-2 fix)
Adopted	yes	yes

Handoff closes the parent’s File handle (decrementing the OFD reference count) WITHOUT calling flock(LOCK_UN). This is intentional: LOCK_UN on a shared OFD releases the lock for ALL processes sharing that OFD — including the grandchild — which would break the singleton guarantee.

Drop MUST NOT panic — all cleanup uses let _ = ....

Implementations

impl PidfileLock

pub fn pidfile_path(&self) -> &PathBuf

Returns the path to the pidfile (sqryd.pid).

pub fn lockfile_path(&self) -> &PathBuf

Returns the path to the lockfile (sqryd.lock).

pub fn ownership(&self) -> PidfileOwnership

Returns the current ownership state.

pub fn as_raw_fd(&self) -> RawFd

Returns the raw OS file descriptor for the underlying lock file.

This is used by the --detach parent path in sqry_daemon::entrypoint to obtain the FD that must be passed to the grandchild process via SQRYD_LOCK_FD so the grandchild can call PidfileLock::adopt.

The returned FD is owned by this PidfileLock; the caller MUST NOT close it and MUST NOT use it after this lock is dropped.

pub fn hand_off_to_adopter(&mut self)

Transition from WriteOwner to Handoff.

Called by the parent process in the --detach path after the grandchild has signalled ready via the self-pipe. After this call the parent’s Drop will release the flock but not unlink the pidfile — the grandchild’s Adopted drop owns that responsibility.

Panics if the current state is not WriteOwner — calling this on a Handoff or Adopted handle is always a programming error and must be caught in both debug and release builds to prevent incorrect drop behaviour (skipping required pidfile unlink).

pub fn write_pid(&self, pid: u32) -> DaemonResult<()>

Write the current process’s PID (decimal + newline) to the pidfile atomically (tmp + rename).

This is called by:

• The foreground / run_start path immediately after acquire_pidfile_lock succeeds.
• The grandchild in the --detach path after PidfileLock::adopt to overwrite the parent’s PID with the grandchild’s PID.

The pidfile is created with mode 0644 (world-readable so that diagnostic tools can read it without elevated privileges).

pub unsafe fn adopt(fd: RawFd, pidfile: PathBuf, lockfile: PathBuf) -> Self

Wrap an already-locked FD inherited across fork+exec into a PidfileLock with ownership = Adopted.

Safety

The caller MUST ensure:

1. fd is a valid, open file descriptor in the current process.
2. fd is the target of an active OFD-level exclusive flock (typically inherited across fork+exec with FD_CLOEXEC cleared).
3. No other PidfileLock in this process owns fd.
4. The caller MUST NOT close fd separately — dropping the returned PidfileLock will close it (and release the flock) via the File destructor.

Violating any of these invariants is undefined behaviour (double-free, double-close, or stale-lock ABA).

Trait Implementations

impl Debug for PidfileLock

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for PidfileLock

fn drop(&mut self)

Release the flock and, when appropriate, unlink the pidfile.

Drop MUST NOT panic — every operation is wrapped in let _ = ....

Handoff and OFD-level flock invariant (M-2 fix)

In the --detach double-fork path the parent transitions to Handoff after the grandchild signals ready. The grandchild inherits the same OFD (open file description) via FD inheritance across fork+exec.

flock(LOCK_UN) operates at the OFD level: it releases the lock for every FD in every process that shares the same OFD. Calling unlock() in the Handoff drop would therefore release the grandchild’s lock too, breaking the singleton guarantee.

The correct behaviour is to close the parent’s FD without explicitly unlocking it. Closing a single FD that shares an OFD with another process’s FD is safe: the kernel decrements the OFD reference count but keeps the lock alive as long as any process still holds an open FD on that OFD. The lock remains held until the grandchild closes its inherited FD (which happens in Adopted drop).